Esquema de la base de datos
Agon usa SQLite (modo WAL) como base de datos local. Todos los valores datetime se almacenan en UTC (sin zona horaria).
Diagrama entidad-relación
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"
Tablas clave
El diagrama anterior muestra el esquema original de planificación, membresías y pagos. Las áreas de funcionalidad añadidas más tarde tienen sus propias tablas, resumidas abajo en lugar de dibujadas en el diagrama.
| Tabla | Finalidad |
|---|---|
users | Cuentas del studio manager y de los instructores (credenciales de acceso) |
clients | Clientes que reservan clases a través de la app móvil |
instructors | Perfil uno a uno vinculado a una fila de users |
class_templates | Definición reutilizable de una clase (Yoga, HIIT, Pilates…) |
scheduled_classes | Una ocurrencia concreta de un tipo de clase en una fecha/hora |
bookings | La reserva de un cliente para una clase programada |
checkins | Registro de asistencia confirmada para una reserva |
waitlist | Entrada en la cola cuando una clase está completa |
memberships | La membresía activa o el bono de créditos de un cliente |
membership_types | Plantilla para planes recurrentes o bonos de créditos |
payments | Registros de pago (Stripe o manual) |
locations | Sede física del estudio (V1: siempre id=1) |
studio_settings | Fila singleton con la configuración del estudio |
consent_log | Eventos de consentimiento del RGPD |
email_templates | Cuerpos de correos transaccionales personalizados |
email_event_assignments | Asocia eventos del ciclo de vida a plantillas personalizadas |
smart_lists | Consultas de filtrado de clientes guardadas para mensajes dirigidos |
Otras tablas (añadidas por funcionalidades posteriores)
Estas no formaban parte del diagrama original de arriba; cada una pertenece a un área de funcionalidad publicada después del esquema inicial.
| Área de funcionalidad | Tablas |
|---|---|
| Citas (reservas 1:1) | appointments, appointment_services, appointment_service_locations, instructor_availability |
| Venta al por menor / POS | products, product_sales, product_sale_items |
| Tarjetas regalo | gift_cards, gift_card_redemptions |
| Códigos promocionales | promo_codes, promo_code_usages |
| Facturación | invoices |
| Automatizaciones de marketing | marketing_automations, marketing_automation_enrollments |
| Segmentación por etiquetas y smart lists | tags, client_tags, auto_tag_rules |
| Descargos de responsabilidad | waivers, waiver_signatures |
| Mensajería SMS | sms_templates, sms_event_assignments |
| Personal y nómina | roles, staff_pay_components, payroll_runs, payroll_line_items |
| Facturación con Stripe (membresías recurrentes) | stripe_customers, stripe_prices, stripe_checkout_sessions, stripe_subscriptions, stripe_webhook_events — además de la columna memberships.stripe_subscription_id mostrada arriba |
| Notificaciones push/en la app | notification_log |
| Migración (ver Resumen de la migración) | migration_job |
También existen ai_usage_log y ai_response_cache (registro de peticiones y caché de respuestas del Asistente IA), pero se excluyen deliberadamente de las dos tablas anteriores — son datos operativos/internos, no datos de negocio del estudio, y su forma exacta es más probable que cambie a medida que evolucione el Asistente IA.
Notas de diseño
Datetimes en UTC sin zona horaria
Todas las columnas DateTime almacenan valores UTC sin información de zona horaria. La capa de aplicación siempre compara con utcnow() de app.utils. Nunca insertes datetimes con zona horaria en la base de datos.
Convención de location_id
Cada entidad de negocio lleva un location_id (por defecto 1). La sede 1 (Main Studio) se crea en el momento de la migración. Esta columna es el punto de apoyo para el soporte multisede de la V2 — no se necesita ningún cambio de esquema.
Eliminación suave frente a eliminación definitiva
- Eliminación suave (status/is_active): clientes, instructores, tipos de clase, tipos de membresía, reservas, membresías, clases programadas.
- Eliminación definitiva: solo ante una solicitud explícita de borrado por el RGPD. Los datos personales se anonimizan en el sitio; las filas de historial de reservas/pagos se conservan con fines de auditoría.
Consulta ARCHITECTURE.md en el código fuente para la estrategia completa de eliminación y las reglas de cascada.
Índices compuestos
Los patrones de consulta críticos para el rendimiento están cubiertos por índices compuestos:
| Índice | Columnas | Patrón de consulta |
|---|---|---|
idx_booking_class_status | scheduled_class_id, status | Todas las reservas confirmadas de una clase |
idx_booking_client_status | client_id, status | Historial de reservas de un cliente |
idx_membership_client_status | client_id, status | Búsqueda de la membresía activa de un cliente |
idx_class_starts_at_location_status | starts_at, location_id, status | Consultas de calendario por rango de fechas |