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.
| Tabelle | Zweck |
|---|---|
users | Konten von Studio-Manager und Kursleitern (Anmeldedaten) |
clients | Kunden, die über die mobile App Kurse buchen |
instructors | 1:1-Profil, verknüpft mit einer users-Zeile |
class_templates | Wiederverwendbare Kursdefinition (Yoga, HIIT, Pilates…) |
scheduled_classes | Ein konkretes Vorkommen eines Kurstyps zu einem bestimmten Datum/einer Uhrzeit |
bookings | Die Buchung eines Kunden für einen geplanten Kurs |
checkins | Bestätigter Anwesenheitsnachweis für eine Buchung |
waitlist | Warteschlangeneintrag, wenn ein Kurs voll ist |
memberships | Die aktive Mitgliedschaft oder das Credit-Paket eines Kunden |
membership_types | Vorlage für wiederkehrende Pläne oder Credit-Pakete |
payments | Zahlungsdatensätze (Stripe oder manuell) |
locations | Physischer Studio-Standort (V1: immer id=1) |
studio_settings | Singleton-Zeile mit der Studio-Konfiguration |
consent_log | DSGVO-Einwilligungsereignisse |
email_templates | Benutzerdefinierte Inhalte transaktionaler E-Mails |
email_event_assignments | Ordnet Lebenszyklus-Ereignisse benutzerdefinierten Vorlagen zu |
smart_lists | Gespeicherte 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.
| Funktionsbereich | Tabellen |
|---|---|
| Termine (1:1-Buchungen) | appointments, appointment_services, appointment_service_locations, instructor_availability |
| Einzelhandel / POS | products, product_sales, product_sale_items |
| Geschenkkarten | gift_cards, gift_card_redemptions |
| Rabattcodes | promo_codes, promo_code_usages |
| Rechnungsstellung | invoices |
| Marketing-Automatisierungen | marketing_automations, marketing_automation_enrollments |
| Targeting über Tags & Smart Lists | tags, client_tags, auto_tag_rules |
| Haftungsfreistellungen | waivers, waiver_signatures |
| SMS-Nachrichten | sms_templates, sms_event_assignments |
| Personal & Lohnabrechnung | roles, 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-Benachrichtigungen | notification_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:
| Index | Spalten | Abfragemuster |
|---|---|---|
idx_booking_class_status | scheduled_class_id, status | Alle bestätigten Buchungen für einen Kurs |
idx_booking_client_status | client_id, status | Buchungshistorie eines Kunden |
idx_membership_client_status | client_id, status | Suche nach der aktiven Mitgliedschaft eines Kunden |
idx_class_starts_at_location_status | starts_at, location_id, status | Kalenderabfragen über einen Datumsbereich |