Saltar al contenido principal

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.

TablaFinalidad
usersCuentas del studio manager y de los instructores (credenciales de acceso)
clientsClientes que reservan clases a través de la app móvil
instructorsPerfil uno a uno vinculado a una fila de users
class_templatesDefinición reutilizable de una clase (Yoga, HIIT, Pilates…)
scheduled_classesUna ocurrencia concreta de un tipo de clase en una fecha/hora
bookingsLa reserva de un cliente para una clase programada
checkinsRegistro de asistencia confirmada para una reserva
waitlistEntrada en la cola cuando una clase está completa
membershipsLa membresía activa o el bono de créditos de un cliente
membership_typesPlantilla para planes recurrentes o bonos de créditos
paymentsRegistros de pago (Stripe o manual)
locationsSede física del estudio (V1: siempre id=1)
studio_settingsFila singleton con la configuración del estudio
consent_logEventos de consentimiento del RGPD
email_templatesCuerpos de correos transaccionales personalizados
email_event_assignmentsAsocia eventos del ciclo de vida a plantillas personalizadas
smart_listsConsultas 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 funcionalidadTablas
Citas (reservas 1:1)appointments, appointment_services, appointment_service_locations, instructor_availability
Venta al por menor / POSproducts, product_sales, product_sale_items
Tarjetas regalogift_cards, gift_card_redemptions
Códigos promocionalespromo_codes, promo_code_usages
Facturacióninvoices
Automatizaciones de marketingmarketing_automations, marketing_automation_enrollments
Segmentación por etiquetas y smart liststags, client_tags, auto_tag_rules
Descargos de responsabilidadwaivers, waiver_signatures
Mensajería SMSsms_templates, sms_event_assignments
Personal y nóminaroles, 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 appnotification_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:

ÍndiceColumnasPatrón de consulta
idx_booking_class_statusscheduled_class_id, statusTodas las reservas confirmadas de una clase
idx_booking_client_statusclient_id, statusHistorial de reservas de un cliente
idx_membership_client_statusclient_id, statusBúsqueda de la membresía activa de un cliente
idx_class_starts_at_location_statusstarts_at, location_id, statusConsultas de calendario por rango de fechas