Zum Hauptinhalt springen

Datenbankschema

Agon verwendet SQLite (WAL-Modus) als lokale Datenbank. Alle Datetime-Werte werden in UTC (ohne Zeitzone) gespeichert.

Entity-Relationship-Diagramm​

erDiagram
users {
int id PK
string email UK
string password_hash
string full_name
string role
bool is_active
datetime created_at
datetime updated_at
}

clients {
int id PK
int location_id
string email UK
string password_hash
string full_name
string phone
date dob
string notes
string push_token
bool is_active
datetime created_at
datetime updated_at
}

instructors {
int id PK
int user_id FK
int location_id
string bio
string specialties
datetime created_at
datetime updated_at
}

class_templates {
int id PK
int location_id
string name
string description
int duration_minutes
int default_capacity
string color
int default_instructor_id FK
bool is_active
datetime created_at
datetime updated_at
}

scheduled_classes {
int id PK
int template_id FK
int instructor_id FK
int location_id
datetime starts_at
datetime ends_at
int capacity
string status
string meeting_url
datetime created_at
datetime updated_at
}

bookings {
int id PK
int client_id FK
int scheduled_class_id FK
int location_id
string status
datetime created_at
datetime updated_at
}

checkins {
int id PK
int booking_id FK
int client_id FK
int scheduled_class_id FK
int checked_in_by FK
string method
datetime checked_in_at
}

waitlist {
int id PK
int client_id FK
int scheduled_class_id FK
int position
string status
datetime expires_at
datetime created_at
datetime updated_at
}

membership_types {
int id PK
int location_id
string name
string type
float price
string currency
int credits
int duration_days
bool is_active
datetime created_at
datetime updated_at
}

memberships {
int id PK
int client_id FK
int membership_type_id FK
int location_id
string status
date starts_at
date expires_at
int credits_remaining
int credits_used
string stripe_subscription_id
datetime created_at
datetime updated_at
}

payments {
int id PK
int client_id FK
int membership_id FK
float amount
string currency
string status
string provider
string provider_payment_id
datetime paid_at
datetime created_at
datetime updated_at
}

locations {
int id PK
string name
string address
string phone
bool is_active
datetime created_at
datetime updated_at
}

studio_settings {
int id PK
string studio_name
string timezone
string currency
string stripe_public_key
string stripe_secret_key
string cloudflare_tunnel_token
int booking_cancellation_hours
bool waitlist_enabled
datetime created_at
datetime updated_at
}

consent_log {
int id PK
int client_id FK
string type
bool granted
string ip_address
datetime created_at
}

email_templates {
int id PK
string name
string subject
string body_html
string variables
bool is_active
datetime created_at
datetime updated_at
}

email_event_assignments {
int id PK
string event_type
int template_id FK
}

smart_lists {
int id PK
string name
string filters_json
datetime created_at
datetime updated_at
}

users ||--o{ instructors : "has profile"
clients ||--o{ bookings : "makes"
clients ||--o{ memberships : "holds"
clients ||--o{ waitlist : "joins"
clients ||--o{ payments : "makes"
clients ||--o{ consent_log : "logs"
scheduled_classes ||--o{ bookings : "receives"
scheduled_classes ||--o{ waitlist : "has"
scheduled_classes ||--o{ checkins : "records"
class_templates ||--o{ scheduled_classes : "spawns"
instructors ||--o{ scheduled_classes : "teaches"
instructors |o--o{ class_templates : "default for"
bookings ||--o| checkins : "has"
memberships ||--o{ payments : "paid via"
membership_types ||--o{ memberships : "defines"
email_templates |o--o{ email_event_assignments : "assigned to"

Wichtige Tabellen​

Das obige Diagramm zeigt das ursprüngliche Kern-Schema für Terminplanung, Mitgliedschaften und Zahlungen. Später hinzugekommene Funktionsbereiche haben eigene Tabellen, die unten zusammengefasst sind, statt im Diagramm dargestellt zu werden.

TabelleZweck
usersKonten von Studio-Manager und Kursleitern (Anmeldedaten)
clientsKunden, die über die mobile App Kurse buchen
instructors1:1-Profil, verknüpft mit einer users-Zeile
class_templatesWiederverwendbare Kursdefinition (Yoga, HIIT, Pilates…)
scheduled_classesEin konkretes Vorkommen eines Kurstyps zu einem bestimmten Datum/einer Uhrzeit
bookingsDie Buchung eines Kunden für einen geplanten Kurs
checkinsBestätigter Anwesenheitsnachweis für eine Buchung
waitlistWarteschlangeneintrag, wenn ein Kurs voll ist
membershipsDie aktive Mitgliedschaft oder das Credit-Paket eines Kunden
membership_typesVorlage für wiederkehrende Pläne oder Credit-Pakete
paymentsZahlungsdatensätze (Stripe oder manuell)
locationsPhysischer Studio-Standort (V1: immer id=1)
studio_settingsSingleton-Zeile mit der Studio-Konfiguration
consent_logDSGVO-Einwilligungsereignisse
email_templatesBenutzerdefinierte Inhalte transaktionaler E-Mails
email_event_assignmentsOrdnet Lebenszyklus-Ereignisse benutzerdefinierten Vorlagen zu
smart_listsGespeicherte Kundenfilter-Abfragen für gezielte Nachrichten

Weitere Tabellen (durch spätere Funktionen hinzugefügt)​

Diese waren nicht Teil des ursprünglichen Diagramms oben; jede gehört zu einem Funktionsbereich, der nach dem ursprünglichen Schema veröffentlicht wurde.

FunktionsbereichTabellen
Termine (1:1-Buchungen)appointments, appointment_services, appointment_service_locations, instructor_availability
Einzelhandel / POSproducts, product_sales, product_sale_items
Geschenkkartengift_cards, gift_card_redemptions
Rabattcodespromo_codes, promo_code_usages
Rechnungsstellunginvoices
Marketing-Automatisierungenmarketing_automations, marketing_automation_enrollments
Targeting über Tags & Smart Liststags, client_tags, auto_tag_rules
Haftungsfreistellungenwaivers, waiver_signatures
SMS-Nachrichtensms_templates, sms_event_assignments
Personal & Lohnabrechnungroles, staff_pay_components, payroll_runs, payroll_line_items
Stripe-Abrechnung (wiederkehrende Mitgliedschaften)stripe_customers, stripe_prices, stripe_checkout_sessions, stripe_subscriptions, stripe_webhook_events — zusätzlich zur oben gezeigten Spalte memberships.stripe_subscription_id
Push-/In-App-Benachrichtigungennotification_log
Migration (siehe Migrationsübersicht)migration_job

Es gibt außerdem ai_usage_log und ai_response_cache (Protokollierung von KI-Assistent-Anfragen und Zwischenspeicherung von Antworten), die aber bewusst aus beiden obigen Tabellen ausgelassen wurden — sie sind operative/interne Daten statt Geschäftsdaten des Studios, und ihre genaue Form wird sich mit der Weiterentwicklung des KI-Assistenten eher ändern.

Design-Hinweise​

UTC-Datetimes ohne Zeitzone​

Alle DateTime-Spalten speichern UTC-Werte ohne Zeitzoneninformation. Die Anwendungsebene vergleicht immer mit utcnow() aus app.utils. Füge niemals zeitzonenbehaftete Datetimes in die Datenbank ein.

location_id-Konvention​

Jede Geschäftsentität trägt ein location_id (Standard 1). Standort 1 (Main Studio) wird bei der Migration angelegt. Diese Spalte ist der Anknüpfungspunkt für die Mehr-Standort-Unterstützung in V2 — keine Schemaänderung nötig.

Soft Delete vs. Hard Delete​

  • Soft Delete (status/is_active): Kunden, Kursleiter, Kursvorlagen, Mitgliedschaftstypen, Buchungen, Mitgliedschaften, geplante Kurse.
  • Hard Delete: Nur auf ausdrückliche DSGVO-Löschanfrage. Personenbezogene Daten werden an Ort und Stelle anonymisiert; Buchungs-/Zahlungshistorien-Zeilen werden zu Prüfzwecken aufbewahrt.

Siehe ARCHITECTURE.md im Quellcode für die vollständige Löschstrategie und die Kaskadenregeln.

Zusammengesetzte Indizes​

Leistungskritische Abfragemuster werden durch zusammengesetzte Indizes abgedeckt:

IndexSpaltenAbfragemuster
idx_booking_class_statusscheduled_class_id, statusAlle bestätigten Buchungen für einen Kurs
idx_booking_client_statusclient_id, statusBuchungshistorie eines Kunden
idx_membership_client_statusclient_id, statusSuche nach der aktiven Mitgliedschaft eines Kunden
idx_class_starts_at_location_statusstarts_at, location_id, statusKalenderabfragen über einen Datumsbereich