Aller au contenu principal

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.

TableRôle
usersComptes du studio manager et des instructeurs (identifiants de connexion)
clientsClients qui réservent des cours via l'application mobile
instructorsProfil associé un-à-un à une ligne users
class_templatesDéfinition réutilisable d'un cours (Yoga, HIIT, Pilates…)
scheduled_classesUne occurrence précise d'un type de cours à une date/heure donnée
bookingsLa réservation d'un client pour un cours planifié
checkinsEnregistrement de présence confirmée pour une réservation
waitlistEntrée dans la file d'attente quand un cours est complet
membershipsL'abonnement actif ou le carnet de crédits d'un client
membership_typesModèle pour les abonnements récurrents ou les carnets de crédits
paymentsEnregistrements de paiement (Stripe ou manuel)
locationsSite physique du studio (V1 : toujours id=1)
studio_settingsLigne singleton contenant la configuration du studio
consent_logÉvénements de consentement RGPD
email_templatesCorps des e-mails transactionnels personnalisés
email_event_assignmentsAssocie les événements du cycle de vie à des modèles personnalisés
smart_listsRequê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 fonctionnelTables
Rendez-vous (réservations 1:1)appointments, appointment_services, appointment_service_locations, instructor_availability
Vente au détail / POSproducts, product_sales, product_sale_items
Cartes cadeauxgift_cards, gift_card_redemptions
Codes promopromo_codes, promo_code_usages
Facturationinvoices
Automatisations marketingmarketing_automations, marketing_automation_enrollments
Ciblage par tags et smart liststags, client_tags, auto_tag_rules
Déchargeswaivers, waiver_signatures
Messagerie SMSsms_templates, sms_event_assignments
Personnel et paieroles, 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-appnotification_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 :

IndexColonnesSchéma de requête
idx_booking_class_statusscheduled_class_id, statusToutes les réservations confirmées pour un cours
idx_booking_client_statusclient_id, statusHistorique des réservations d'un client
idx_membership_client_statusclient_id, statusRecherche de l'abonnement actif d'un client
idx_class_starts_at_location_statusstarts_at, location_id, statusRequêtes de calendrier par plage de dates