KARATE CLUB

Como Administrador del club
Quiero registrar y renovar las licencias federativas de los alumnos
Para cumplir con los requisitos de la federación y saber qué alumnos están al día con su licencia

1. Descripción Funcional

El sistema debe permitir gestionar las licencias federativas de cada alumno. Cada licencia tiene un número único, fecha de emisión y renovación anual (en enero). El sistema debe alertar sobre licencias próximas a caducar o caducadas.

Las licencias son requisito obligatorio para participar en competiciones oficiales y deben estar siempre actualizadas según normativa de la Federación Madrileña de Karate (FMK).

1. Criterios de Aceptación (Gherkin)

```gherkin
Feature: Gestión de licencias federativas
Como administrador del club
Quiero gestionar las licencias de los alumnos
Para cumplir con la federación

Scenario: Registro de nueva licencia federativa
    Dado que visualizo la ficha de un alumno sin licencia
    Cuando accedo a la pestaña "Licencias" 
    Y pulso "Nueva Licencia" 
    Y completo los datos:
    | Número de licencia | FMK-2025-12345 |
    | Fecha de emisión | 15/01/2025 |
    | Fecha de renovación | 31/01/2026 |
    Y adjunto el justificante en PDF
    Y pulso "Guardar" 
    Entonces la licencia debe quedar registrada
    Y el estado debe ser "Vigente" 
    Y debe mostrarse en la ficha del alumno

Scenario: Alerta de licencia próxima a caducar
    Dado que un alumno tiene licencia que caduca en 20 días
    Cuando el sistema ejecuta el proceso nocturno de alertas
    Entonces debe generar alerta "Licencia próxima a caducar" 
    Y debe mostrarse en el dashboard del admin
    Y debe enviarse email al tutor del alumno

Scenario: Renovación de licencia caducada
    Dado que un alumno tiene licencia caducada desde febrero
    Cuando accedo a su ficha de licencias
    Y pulso "Renovar Licencia" 
    Y completo el nuevo número "FMK-2026-12345" 
    Y la nueva fecha de renovación "31/01/2027" 
    Y adjunto el nuevo justificante
    Y pulso "Guardar" 
    Entonces debe crearse nuevo registro de licencia
    Y la licencia anterior debe marcarse como "Histórica" 
    Y la nueva licencia debe estar "Vigente"

Scenario: Listado de licencias caducadas
    Dado que existen 50 alumnos con licencias
    Y 8 tienen licencias caducadas
    Cuando accedo al módulo de licencias
    Y filtro por "Estado: Caducada" 
    Entonces debo ver solo los 8 alumnos con licencia caducada
    Y deben ordenarse por antigüedad de caducidad (más antiguas primero)

Scenario: Bloqueo de inscripción a competición sin licencia vigente
    Dado que un alumno tiene licencia caducada
    Cuando intento inscribirlo a una competición federada
    Entonces el sistema debe bloquear la inscripción
    Y debe mostrar mensaje "El alumno debe tener licencia vigente para competiciones federadas" 
```

1. Campos de la Licencia

1. Campos Obligatorios
   - Número de licencia (string, formato FMK-YYYY-XXXXX)
   - Alumno (relación con tabla alumnos)
   - Fecha de emisión (date)
   - Fecha de renovación (date, por defecto 31 de enero del año siguiente)
   - Estado (enum: vigente, caducada, pendiente_renovacion)

1. Campos Opcionales
   - Justificante (PDF, Supabase Storage)
   - Observaciones (text)

1. Campos Automáticos
   - ID, created_at, updated_at, created_by, updated_by

1. Validaciones

1. Número de licencia único en el sistema
2. Fecha de emisión no puede ser futura
3. Fecha de renovación posterior a emisión
4. Solo una licencia vigente por alumno
5. Formato: FMK-YYYY-XXXXX (regex)
6. Justificante PDF max 5MB

1. Estados Automáticos

- Vigente: Fecha actual < Fecha renovación
- Pendiente renovación: < 30 días para caducidad
- Caducada: Fecha actual >= Fecha renovación

Actualización automática mediante proceso nocturno (cron).

1. Interfaz de Usuario

1. Dashboard de Licencias
   - Contadores: Vigentes, Próximas a caducar, Caducadas, Sin licencia
   - Listado con filtros y búsqueda
   - Exportar Excel/CSV

1. Pestaña en Ficha de Alumno
   - Licencia actual con semáforo visual 🟢🟡🔴
   - Historial de licencias
   - Botones: Renovar, Descargar justificante

1. Alertas Automáticas
   - Dashboard: Licencias caducadas y próximas
   - Emails: 30 días antes, al caducar, resumen mensual admin

1. Definition of Done (DoD)

- [ ] Modelo Licencia en Supabase con relación a Alumno
- [ ] API CRUD completa y probada
- [ ] Lógica de estados automáticos implementada
- [ ] Proceso nocturno (cron) de actualización funcionando
- [ ] Dashboard con contadores implementado
- [ ] Formularios nueva licencia y renovación con validaciones
- [ ] Subida/descarga justificantes PDF funcionando
- [ ] Historial visible en ficha de alumno
- [ ] Sistema de alertas automáticas
- [ ] Emails automáticos configurados y probados
- [ ] Bloqueo inscripción sin licencia vigente
- [ ] Filtros, búsquedas y exportación funcionando
- [ ] Tests unitarios, integración y E2E pasando
- [ ] JSDoc completo
- [ ] Responsive en todos los dispositivos

1. Pruebas Principales

Funcionales: Crear, renovar, filtrar, alertas, bloqueo competiciones
Validación: Formatos, fechas, duplicados, tamaño archivos
Proceso automático: Cron actualización estados, envío emails
Integración: Bloqueo inscripciones, estado en ficha alumno

1. Estimación

Story Points: 8
Horas estimadas: 13-21 horas

1. Dependencias

- Gestión de alumnos completada
- Supabase Storage configurado
- Sistema cron jobs
- Sistema emails (Resend/Supabase)

1. Referencias

Relacionado con: RF-002 (SPEC_FUNCIONAL.md), Historia Admin #2 (HISTORIAS_USUARIO[PBI].md)