Schéma de base de données
Agon utilise SQLite (mode WAL) comme base de données locale. Toutes les valeurs datetime sont stockées en UTC (sans fuseau horaire).
Diagramme entité-relation
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"
Tables principales
Le diagramme ci-dessus montre le schéma d'origine pour la planification, les abonnements et les paiements. Les fonctionnalités ajoutées par la suite ont leurs propres tables, résumées ci-dessous plutôt que représentées dans le diagramme.
| Table | Rôle |
|---|---|
users | Comptes du studio manager et des instructeurs (identifiants de connexion) |
clients | Clients qui réservent des cours via l'application mobile |
instructors | Profil associé un-à-un à une ligne users |
class_templates | Définition réutilisable d'un cours (Yoga, HIIT, Pilates…) |
scheduled_classes | Une occurrence précise d'un type de cours à une date/heure donnée |
bookings | La réservation d'un client pour un cours planifié |
checkins | Enregistrement de présence confirmée pour une réservation |
waitlist | Entrée dans la file d'attente quand un cours est complet |
memberships | L'abonnement actif ou le carnet de crédits d'un client |
membership_types | Modèle pour les abonnements récurrents ou les carnets de crédits |
payments | Enregistrements de paiement (Stripe ou manuel) |
locations | Site physique du studio (V1 : toujours id=1) |
studio_settings | Ligne singleton contenant la configuration du studio |
consent_log | Événements de consentement RGPD |
email_templates | Corps des e-mails transactionnels personnalisés |
email_event_assignments | Associe les événements du cycle de vie à des modèles personnalisés |
smart_lists | Requêtes de filtrage client enregistrées pour un ciblage de messages |
Autres tables (ajoutées par des fonctionnalités ultérieures)
Celles-ci ne faisaient pas partie du diagramme d'origine ci-dessus ; chacune appartient à une fonctionnalité lancée après le schéma initial.
| Domaine fonctionnel | Tables |
|---|---|
| Rendez-vous (réservations 1:1) | appointments, appointment_services, appointment_service_locations, instructor_availability |
| Vente au détail / POS | products, product_sales, product_sale_items |
| Cartes cadeaux | gift_cards, gift_card_redemptions |
| Codes promo | promo_codes, promo_code_usages |
| Facturation | invoices |
| Automatisations marketing | marketing_automations, marketing_automation_enrollments |
| Ciblage par tags et smart lists | tags, client_tags, auto_tag_rules |
| Décharges | waivers, waiver_signatures |
| Messagerie SMS | sms_templates, sms_event_assignments |
| Personnel et paie | roles, staff_pay_components, payroll_runs, payroll_line_items |
| Facturation Stripe (abonnements récurrents) | stripe_customers, stripe_prices, stripe_checkout_sessions, stripe_subscriptions, stripe_webhook_events — en plus de la colonne memberships.stripe_subscription_id indiquée ci-dessus |
| Notifications push/in-app | notification_log |
| Migration (voir Vue d'ensemble de la migration) | migration_job |
Il existe aussi ai_usage_log et ai_response_cache (journalisation des requêtes et mise en cache des réponses de l'Assistant IA), mais elles sont volontairement exclues des deux tableaux ci-dessus — ce sont des données opérationnelles/internes plutôt que des données métier du studio, et leur forme exacte est plus susceptible de changer au fil de l'évolution de l'Assistant IA.
Notes de conception
Datetime en UTC sans fuseau horaire
Toutes les colonnes DateTime stockent des valeurs UTC sans information de fuseau horaire. La couche applicative compare toujours avec utcnow() de app.utils. N'insérez jamais de datetime avec fuseau horaire dans la base de données.
Convention location_id
Chaque entité métier porte un location_id (par défaut 1). Le site 1 (Main Studio) est créé lors de la migration. Cette colonne est le point d'ancrage pour la prise en charge multi-sites de la V2 — aucune modification de schéma n'est nécessaire.
Suppression douce vs définitive
- Suppression douce (status/is_active) : clients, instructeurs, types de cours, types d'abonnement, réservations, abonnements, cours planifiés.
- Suppression définitive : uniquement sur demande explicite de suppression RGPD. Les données personnelles sont anonymisées sur place ; les lignes d'historique de réservations/paiements sont conservées à des fins d'audit.
Voir ARCHITECTURE.md dans le code source pour la stratégie complète de suppression et les règles de cascade.
Index composites
Les schémas de requêtes critiques en performance sont couverts par des index composites :
| Index | Colonnes | Schéma de requête |
|---|---|---|
idx_booking_class_status | scheduled_class_id, status | Toutes les réservations confirmées pour un cours |
idx_booking_client_status | client_id, status | Historique des réservations d'un client |
idx_membership_client_status | client_id, status | Recherche de l'abonnement actif d'un client |
idx_class_starts_at_location_status | starts_at, location_id, status | Requêtes de calendrier par plage de dates |