KARATE CLUB » KARA CLUB - WEB

1. Objetivo

Diseñar e implementar el esquema completo de base de datos PostgreSQL en Supabase con todas las tablas, relaciones, índices y políticas RLS.

1. Descripción Técnica

Crear todas las tablas necesarias para el MVP con sus relaciones, constraints, triggers y políticas de seguridad Row Level Security (RLS). Este es un trabajo crítico y bloqueante para todo el desarrollo de features.

1. Tablas a Crear

1. 1. Tabla: users (extensión de Supabase Auth)
   ```sql
   -- Campos adicionales a auth.users
   - role (enum: admin, monitor, familia)
   - centro_id (FK centros, nullable para admin)
   - created_at, updated_at
   ```

1. 2. Tabla: centros
   ```sql
   - id (uuid, PK)
   - nombre (varchar 150, NOT NULL)
   - direccion (text, NOT NULL)
   - telefono (varchar 20)
   - email (varchar 100)
   - responsable (varchar 150)
   - observaciones (text)
   - created_at, updated_at, created_by, updated_by
   ```

1. 3. Tabla: alumnos
   ```sql
   - id (uuid, PK)
   - nombre (varchar 100, NOT NULL)
   - apellidos (varchar 150, NOT NULL)
   - fecha_nacimiento (date, NOT NULL)
   - nombre_tutor (varchar 150, NOT NULL)
   - telefono_tutor (varchar 20, NOT NULL)
   - email_tutor (varchar 100, NOT NULL)
   - cinturon (varchar 50, NOT NULL)
   - centro_id (FK centros, NOT NULL)
   - foto_url (text, nullable)
   - observaciones_medicas (text, nullable) -- ENCRYPTED
   - notas (text, nullable)
   - estado (enum: activo, inactivo)
   - created_at, updated_at, created_by, updated_by
   ```

1. 4. Tabla: licencias
   ```sql
   - id (uuid, PK)
   - alumno_id (FK alumnos, NOT NULL)
   - numero_licencia (varchar 50, UNIQUE, NOT NULL)
   - fecha_emision (date, NOT NULL)
   - fecha_renovacion (date, NOT NULL)
   - estado (enum: vigente, caducada, pendiente_renovacion)
   - justificante_url (text, nullable)
   - observaciones (text)
   - created_at, updated_at, created_by, updated_by
   ```

1. 5. Tabla: cuotas
   ```sql
   - id (uuid, PK)
   - alumno_id (FK alumnos, NOT NULL)
   - concepto (varchar 100, NOT NULL)
   - importe (decimal 10,2, NOT NULL)
   - periodicidad (enum: mensual, trimestral, anual, unico)
   - fecha_inicio (date, NOT NULL)
   - descuento_porcentaje (decimal 5,2, nullable)
   - descuento_motivo (text, nullable)
   - estado (enum: activo, inactivo)
   - observaciones (text)
   - created_at, updated_at, created_by, updated_by
   ```

1. 6. Tabla: pagos
   ```sql
   - id (uuid, PK)
   - cuota_id (FK cuotas, NOT NULL)
   - alumno_id (FK alumnos, NOT NULL)
   - concepto (varchar 100, NOT NULL)
   - importe (decimal 10,2, NOT NULL)
   - fecha_vencimiento (date, NOT NULL)
   - fecha_pago (date, nullable)
   - estado (enum: pendiente, pagado, parcial)
   - metodo_pago (enum: efectivo, transferencia, tarjeta, otro)
   - referencia (varchar 100, nullable)
   - observaciones (text)
   - created_at, updated_at, created_by, updated_by
   ```

1. 7. Tabla: eventos
   ```sql
   - id (uuid, PK)
   - tipo (enum: clase_regular, competicion, curso, examen, otro)
   - nombre (varchar 150, NOT NULL)
   - descripcion (text)
   - fecha_inicio (timestamp, NOT NULL)
   - fecha_fin (timestamp, NOT NULL)
   - lugar (varchar 150)
   - centro_id (FK centros, NOT NULL)
   - aforo_maximo (int, default 0)
   - instructor_id (FK users, nullable)
   - permite_inscripcion (boolean, default true)
   - coste (decimal 10,2, nullable)
   - requisitos (text)
   - imagen_url (text, nullable)
   - created_at, updated_at, created_by, updated_by
   ```

1. 8. Tabla: inscripciones
   ```sql
   - id (uuid, PK)
   - evento_id (FK eventos, NOT NULL)
   - alumno_id (FK alumnos, NOT NULL)
   - usuario_id (FK users, NOT NULL) -- quien inscribió
   - estado (enum: confirmada, cancelada, en_espera)
   - fecha_inscripcion (timestamp, NOT NULL)
   - fecha_cancelacion (timestamp, nullable)
   - observaciones (text)
   - created_at, updated_at
   - UNIQUE
   ```

1. 9. Tabla: sesiones
   ```sql
   - id (uuid, PK)
   - fecha (date, NOT NULL)
   - hora_inicio (time, NOT NULL)
   - hora_fin (time, NOT NULL)
   - grupo (varchar 50, NOT NULL)
   - centro_id (FK centros, NOT NULL)
   - instructor_id (FK users, NOT NULL)
   - estado (enum: programada, realizada, cancelada)
   - created_at, updated_at, created_by
   ```

1. 10. Tabla: asistencias
   ```sql
   - id (uuid, PK)
   - sesion_id (FK sesiones, NOT NULL)
   - alumno_id (FK alumnos, NOT NULL)
   - estado (enum: presente, ausente, justificada)
   - fecha (date, NOT NULL) -- denormalizado para queries rápidas
   - observaciones (text)
   - created_at, updated_at, created_by
   - UNIQUE
   ```

1. 11. Tabla: resultados_competiciones
   ```sql
   - id (uuid, PK)
   - alumno_id (FK alumnos, NOT NULL)
   - nombre_evento (varchar 150, NOT NULL)
   - fecha_evento (date, NOT NULL)
   - categoria (varchar 100, NOT NULL)
   - resultado (text, NOT NULL)
   - lugar_evento (varchar 150)
   - foto_url (text, nullable)
   - certificado_url (text, nullable)
   - observaciones (text)
   - created_at, updated_at, created_by, updated_by
   ```

1. 12. Tabla: plantillas_comunicacion
   ```sql
   - id (uuid, PK)
   - nombre (varchar 100, NOT NULL)
   - tipo (enum: email, whatsapp)
   - asunto (varchar 200, nullable) -- solo email
   - contenido (text, NOT NULL)
   - variables (jsonb) -- lista de variables disponibles
   - activa (boolean, default true)
   - created_at, updated_at, created_by, updated_by
   ```

1. Tareas de Implementación

1. 1. Crear Migraciones SQL
   - [ ] Escribir scripts SQL para cada tabla
   - [ ] Crear enums necesarios
   - [ ] Definir constraints (FK, UNIQUE, CHECK)
   - [ ] Crear índices para optimización

1. 2. Configurar Row Level Security (RLS)
   - [ ] Habilitar RLS en todas las tablas
   - [ ] Políticas para rol Admin (acceso total)
   - [ ] Políticas para rol Monitor (limitado a su centro)
   - [ ] Políticas para rol Familia (solo sus hijos)

1. 3. Crear Triggers
   - [ ] Trigger para updated_at automático
   - [ ] Trigger para actualización de estado de licencias
   - [ ] Trigger para generación de pagos periódicos (cuotas)

1. 4. Crear Funciones Stored
   - [ ] Función: generar_recibos_cuota_mensual()
   - [ ] Función: actualizar_estados_licencias()
   - [ ] Función: calcular_estadisticas_asistencia(alumno_id)

1. 5. Seeds de Datos
   - [ ] Script de datos iniciales (centros, plantillas)
   - [ ] Script de datos de prueba (alumnos, eventos, etc.)

1. 6. Documentación
   - [ ] Diagrama ER (Entity-Relationship)
   - [ ] Documentación de políticas RLS
   - [ ] Documentación de triggers y funciones

1. Criterios de Aceptación

- ✅ Todas las tablas creadas en Supabase
- ✅ Relaciones (Foreign Keys) correctamente configuradas
- ✅ Índices creados en campos de búsqueda frecuente
- ✅ RLS habilitado y políticas configuradas
- ✅ Triggers funcionando correctamente
- ✅ Tests de políticas RLS pasando
- ✅ Documentación del esquema completada
- ✅ Seeds de datos de prueba cargados

1. Estimación

Horas: 13-21h

1. Referencias

- CLAUDE.md: Sección "Database Schema Entities"
- SPECS/SPEC_FUNCIONAL.md: Requisitos funcionales RF-001 a RF-011