KARATE CLUB

Como Administrador y familias del club
Quiero ver un calendario de clases y eventos con posibilidad de inscripción
Para planificar la asistencia y gestionar eventos especiales (competiciones, cursos)

1. Descripción Funcional

El sistema debe mostrar un calendario mensual/semanal con las clases regulares y eventos especiales. Los usuarios pueden inscribirse a eventos con control de aforo. Los administradores gestionan el calendario completo.

1. Criterios de Aceptación (Gherkin)

```gherkin
Feature: Calendario de clases y eventos
Como usuario del club
Quiero ver y gestionar el calendario
Para planificar actividades

Scenario: Crear evento de competición
    Dado que soy administrador
    Cuando creo un nuevo evento:
    | Tipo | Competición |
    | Nombre | Campeonato Regional |
    | Fecha | 15/11/2025 |
    | Lugar | Polideportivo Sur |
    | Aforo | 30 |
    Y pulso "Guardar" 
    Entonces el evento debe aparecer en el calendario
    Y debe estar disponible para inscripción

Scenario: Inscripción a evento por familia
    Dado que soy usuario familia
    Y hay un curso de katas con 10 plazas libres
    Cuando selecciono el evento
    Y pulso "Inscribir a mi hijo" 
    Entonces debe confirmarse la inscripción
    Y debe reducirse el aforo disponible a 9
    Y debe enviarse email de confirmación

Scenario: Evento completo (aforo agotado)
    Dado que un curso tiene aforo de 20 alumnos
    Y ya hay 20 inscritos
    Cuando un usuario intenta inscribirse
    Entonces debe mostrarse "Evento completo" 
    Y el botón de inscripción debe estar deshabilitado

Scenario: Vista de calendario mensual
    Dado que accedo al calendario
    Cuando selecciono vista "Mes" 
    Entonces debo ver todos los eventos del mes
    Y las clases regulares deben aparecer en gris
    Y los eventos especiales en color destacado

Scenario: Cancelar inscripción a evento
    Dado que mi hijo está inscrito a un curso
    Cuando accedo al detalle del evento
    Y pulso "Cancelar inscripción" 
    Entonces debe confirmarse la cancelación
    Y debe liberarse una plaza
    Y debe enviarse email de confirmación
```

1. Modelo de Datos

1. Tabla: Eventos
   Campos obligatorios:
   - tipo (enum: clase_regular, competición, curso, examen, otro)
   - nombre (string)
   - descripción (text)
   - fecha_inicio (datetime)
   - fecha_fin (datetime)
   - lugar (string)
   - centro_id (FK centros)
   - aforo_maximo (int, 0 = sin límite)
   - instructor_id (FK users, opcional)
   - permite_inscripcion (boolean)

Campos opcionales:
- coste (decimal, si aplica)
- requisitos (text: "Licencia vigente", etc.)
- imagen (url Supabase Storage)

Automáticos: id, created_at, updated_at, created_by, updated_by

1. Tabla: Inscripciones
   Campos obligatorios:
   - evento_id (FK eventos)
   - alumno_id (FK alumnos)
   - usuario_id (FK users, quien inscribió)
   - estado (enum: confirmada, cancelada, en_espera)
   - fecha_inscripcion (timestamp)

Campos opcionales:
- observaciones (text)
- fecha_cancelacion (timestamp)

Automáticos: id, created_at, updated_at

1. Validaciones

1. Fecha inicio debe ser posterior a fecha actual (al crear)
2. Fecha fin debe ser posterior a fecha inicio
3. Aforo máximo debe ser >= 0
4. No se puede inscribir mismo alumno dos veces al mismo evento
5. No se puede inscribir si aforo completo
6. No se puede inscribir sin licencia vigente (si evento lo requiere)

1. Interfaz de Usuario

1. Calendario (Vista Pública: Admin, Instructor, Familia)
   - Vistas: Mes, Semana, Lista
   - Leyenda de colores:
   - Clases regulares (gris)
   - Competiciones (rojo)
   - Cursos (azul)
   - Exámenes (naranja)
   - Filtros: Tipo evento, Centro
   - Botón "Nuevo Evento" (solo Admin/Instructor)

1. Detalle de Evento
   - Información completa: nombre, fecha, lugar, descripción, aforo
   - Listado de inscritos (solo Admin/Instructor)
   - Botón "Inscribirse" (Familia, si hay plazas)
   - Botón "Cancelar inscripción" (Familia, si está inscrito)
   - Botones Admin: "Editar", "Cancelar evento", "Exportar listado"

1. Formulario de Evento (Admin/Instructor)
   - Tipo, nombre, descripción
   - Fecha inicio y fin (date/time pickers)
   - Lugar, centro
   - Aforo máximo (0 = sin límite)
   - Requisitos (checkbox: "Requiere licencia vigente")
   - Coste (opcional)
   - Imagen destacada
   - Botones: "Guardar", "Guardar y crear otro", "Cancelar"

1. Notificaciones

1. Email confirmación inscripción (a tutor del alumno)
2. Email cancelación inscripción (a tutor)
3. Email recordatorio (24h antes del evento, a todos los inscritos)
4. Alerta Admin cuando evento llega al 80% de aforo

1. Definition of Done (DoD)

- [ ] Modelos Evento e Inscripción en Supabase
- [ ] Relaciones correctamente configuradas
- [ ] API CRUD eventos e inscripciones
- [ ] Vista de calendario mensual y semanal
- [ ] Filtros por tipo y centro funcionando
- [ ] Detalle de evento con info completa
- [ ] Formulario de creación/edición de evento
- [ ] Lógica de inscripción con control de aforo
- [ ] Lógica de cancelación de inscripción
- [ ] Validación de requisitos (licencia vigente)
- [ ] Listado de inscritos para Admin/Instructor
- [ ] Emails de confirmación y recordatorio
- [ ] Exportación de listados
- [ ] Tests unitarios, integración y E2E pasando
- [ ] JSDoc completo
- [ ] Responsive: calendario usable en móvil

1. Pruebas Principales

Funcionales: Crear evento, inscribirse, cancelar inscripción, aforo completo, requisitos
Validación: Fechas, aforos, duplicados, licencia vigente
Notificaciones: Emails confirmación, recordatorio, alertas aforo
Integración: Inscripciones desde ficha alumno, bloqueo sin licencia

1. Estimación

Story Points: 13
Horas estimadas: 21-34 horas

1. Dependencias

- Gestión de alumnos completada
- Gestión de licencias (para validación)
- Sistema de emails

1. Referencias

Relacionado con: RF-004 (SPEC_FUNCIONAL.md), Historias Admin #4 y Familia #1-2 (HISTORIAS_USUARIO[PBI].md)