KARATE CLUB

1. Historia de Usuario

Como Administrador del club
Quiero gestionar completamente los datos de los alumnos (crear, consultar, actualizar y eliminar)
Para mantener actualizado el censo del club y tener toda la información necesaria de cada alumno

1. Descripción Funcional

El sistema debe permitir al administrador realizar todas las operaciones CRUD sobre los alumnos del club. Cada alumno debe tener un perfil completo con sus datos personales, información del tutor/responsable, nivel técnico (cinturón/grado) y centro al que pertenece.

La gestión de alumnos es la base fundamental del sistema, ya que todos los demás módulos (asistencia, licencias, cuotas, eventos) dependen de tener un registro correcto de los alumnos.

1. Criterios de Aceptación (Gherkin)

```gherkin
Feature: Gestión de alumnos
Como administrador del club
Quiero gestionar los datos de los alumnos
Para mantener el censo actualizado

Scenario: Alta de nuevo alumno con datos completos
    Dado que accedo al módulo de alumnos como administrador
    Cuando selecciono "Nuevo Alumno" 
    Y completo el formulario con:
    | Campo | Valor |
    | Nombre | Juan |
    | Apellidos | García López |
    | Fecha de nacimiento | 15/03/2010 |
    | Nombre del tutor | María López |
    | Teléfono del tutor | 666123456 |
    | Email del tutor | maria.lopez@email.com |
    | Cinturón/Grado | Cinturón Blanco |
    | Centro | Dojo Central |
    Y adjunto el documento de autorización (PDF)
    Y pulso "Guardar" 
    Entonces el sistema debe crear el alumno
    Y debe mostrar mensaje "Alumno creado correctamente" 
    Y el alumno debe aparecer en el listado de alumnos

Scenario: Búsqueda rápida de alumno por nombre
    Dado que existen 50 alumnos registrados
    Cuando escribo "Gar" en el campo de búsqueda
    Entonces el sistema debe mostrar solo los alumnos con "Gar" en nombre o apellidos
    Y debe mostrarse en menos de 1 segundo

Scenario: Edición de datos de alumno existente
    Dado que visualizo la ficha del alumno "Juan García" 
    Cuando pulso "Editar" 
    Y modifico el cinturón a "Cinturón Amarillo" 
    Y modifico el teléfono del tutor a "666999888" 
    Y pulso "Guardar" 
    Entonces los cambios deben guardarse correctamente
    Y debe actualizarse la fecha de "última modificación" 
    Y debe registrarse quién realizó el cambio

Scenario: Baja de alumno con confirmación
    Dado que visualizo la ficha del alumno "Pedro Martínez" 
    Cuando pulso "Dar de baja" 
    Entonces el sistema debe mostrar confirmación "¿Estás seguro de dar de baja a Pedro Martínez?" 
    Cuando confirmo la acción
    Entonces el alumno debe marcarse como "Inactivo" 
    Y no debe aparecer en listados por defecto
    Y su historial debe conservarse (RGPD - derecho al olvido pendiente de implementar)

Scenario: Listado de alumnos con filtros
    Dado que existen alumnos de varios centros y grados
    Cuando accedo al listado de alumnos
    Y filtro por "Centro: Dojo Central" y "Cinturón: Amarillo" 
    Entonces solo debo ver alumnos del Dojo Central con cinturón amarillo
    Y el conteo debe ser correcto

Scenario: Visualización de ficha completa de alumno
    Dado que selecciono un alumno del listado
    Cuando accedo a su ficha
    Entonces debo ver:
      - Datos personales completos
      - Foto del alumno (si existe)
      - Documentos adjuntos
      - Historial de asistencia (resumen)
      - Estado de licencia federativa
      - Estado de cuotas (pendientes/pagadas)
      - Resultados en competiciones
```

1. Campos Obligatorios del Alumno

- Nombre (string, max 100 caracteres)
- Apellidos (string, max 150 caracteres)
- Fecha de nacimiento (date, validar edad razonable: 4-100 años)
- Nombre del tutor/responsable (string, max 150 caracteres)
- Teléfono de contacto (string, validar formato español)
- Email de contacto (string, validar formato email)
- Cinturón/Grado (select de lista predefinida)
- Centro (select de centros existentes)

1. Campos Opcionales

- Foto del alumno (imagen, max 5MB)
- Documentos de autorización (PDFs, max 10MB total)
- Observaciones médicas (text, información sensible - encriptada)
- Notas adicionales (text)

1. Campos Automáticos (Sistema)

- ID (auto-incremental)
- Fecha de alta (timestamp automático)
- Fecha de última modificación (timestamp automático)
- Creado por (user_id del admin)
- Modificado por (user_id del último que editó)
- Estado (activo/inactivo)

1. Validaciones

1. Nombre y apellidos no pueden estar vacíos
2. Fecha de nacimiento debe ser válida y el alumno debe tener entre 4 y 100 años
3. El email debe tener formato válido
4. El teléfono debe tener formato español válido (+34 XXX XXX XXX o 9 dígitos)
5. No se puede dar de alta dos alumnos con mismo nombre, apellidos y fecha de nacimiento (detectar duplicados)
6. Los documentos adjuntos solo pueden ser PDF, PNG, JPG (max 10MB total)

1. Interfaz de Usuario

1. Listado de Alumnos
   - Tabla paginada (25 alumnos por página)
   - Columnas: Foto (thumbnail), Nombre completo, Edad, Cinturón, Centro, Estado licencia, Estado cuotas
   - Búsqueda rápida por nombre/apellidos
   - Filtros: Centro, Cinturón, Estado (activo/inactivo)
   - Botón "Nuevo Alumno" (principal, destacado)
   - Exportar a Excel/CSV

1. Formulario de Alta/Edición
   - Diseño limpio, dividido en secciones:
   1. Datos del alumno: Nombre, apellidos, fecha nacimiento, foto
   2. Datos del tutor: Nombre, teléfono, email
   3. Datos del club: Centro, cinturón, fecha de alta
   4. Documentos: Subida de autorizaciones
   5. Observaciones: Notas médicas y adicionales
   - Validación en tiempo real
   - Botones: "Guardar", "Guardar y crear otro", "Cancelar"

1. Ficha del Alumno
   - Vista detallada con pestañas:
   1. Datos personales
   2. Asistencia (resumen + link a histórico)
   3. Licencias
   4. Cuotas y pagos
   5. Competiciones
   6. Documentos
   - Botones de acción: "Editar", "Dar de baja", "Imprimir ficha"

1. Definition of Done (DoD)

- [ ] Modelo de datos de Alumno creado en Supabase con todos los campos
- [ ] API CRUD completa implementada y probada
- [ ] Interfaz de listado de alumnos funcionando con paginación y búsqueda
- [ ] Formulario de alta de alumno con todas las validaciones
- [ ] Formulario de edición de alumno funcionando
- [ ] Funcionalidad de baja de alumno implementada
- [ ] Subida y gestión de documentos adjuntos funcionando (Supabase Storage)
- [ ] Filtros de listado funcionando correctamente
- [ ] Vista de ficha completa del alumno implementada
- [ ] Tests unitarios de validaciones pasando
- [ ] Tests de integración de API CRUD pasando
- [ ] Tests E2E del flujo completo (crear, editar, buscar, dar de baja)
- [ ] Documentación técnica (JSDoc en funciones)
- [ ] Responsive: funciona en desktop, tablet y móvil
- [ ] Accesibilidad: formularios accesibles con teclado y screen readers
- [ ] Auditoría: se registran created_by y updated_by correctamente

1. Pruebas a Realizar

1. Pruebas Funcionales
   1. Crear alumno con datos mínimos requeridos
   2. Crear alumno con todos los campos opcionales
   3. Intentar crear alumno sin campos obligatorios (debe fallar)
   4. Intentar crear alumno duplicado (debe advertir)
   5. Editar datos de alumno y verificar persistencia
   6. Subir documentos PDF y verificar descarga
   7. Buscar alumno por nombre parcial
   8. Filtrar por centro y cinturón simultáneamente
   9. Dar de baja alumno y verificar que no aparece en listado
   10. Verificar que alumno inactivo conserva su historial

1. Pruebas de Validación
   1. Email con formato inválido (debe rechazar)
   2. Teléfono con formato inválido (debe rechazar)
   3. Fecha de nacimiento futura (debe rechazar)
   4. Fecha de nacimiento hace más de 100 años (debe rechazar)
   5. Archivo adjunto mayor de 10MB (debe rechazar)
   6. Archivo adjunto con extensión no permitida (.exe) (debe rechazar)

1. Pruebas de Seguridad
   1. Solo usuarios con rol Admin pueden crear/editar/eliminar alumnos
   2. Los datos sensibles (observaciones médicas) están encriptados en BD
   3. Los documentos adjuntos no son accesibles sin autenticación
   4. No se puede acceder a datos de alumnos de otros centros (si aplica multi-tenant futuro)

1. Pruebas de Rendimiento
   1. Listado de 200 alumnos carga en menos de 2 segundos
   2. Búsqueda sobre 200 alumnos responde en menos de 1 segundo
   3. Subida de documento de 5MB completa en menos de 10 segundos

1. Estimación

Story Points: 13
Horas estimadas: 21-34 horas

1. Dependencias

- Configuración de Supabase (base de datos + storage)
- Sistema de autenticación implementado
- Configuración de roles (Admin, Instructor, Familia)

1. Notas Técnicas

- Usar Supabase Storage para almacenar fotos y documentos
- Encriptar campos sensibles (observaciones médicas) usando AES-256
- Implementar soft delete para las bajas (marcar como inactivo, no borrar físicamente)
- Indexar campos de búsqueda frecuente (nombre, apellidos, centro)
- Cachear lista de centros y cinturones disponibles

1. Referencias

- SPECS/SPEC_FUNCIONAL.md: RF-001
- SPECS/HISTORIAS_USUARIO[PBI].md: Historia de Admin #1