KARATE CLUB » KARA CLUB - WEB

1. Objetivo

Implementar el módulo completo de gestión de alumnos con interfaz web responsive y todas las funcionalidades CRUD.

1. Descripción Técnica

Desarrollar las vistas, componentes, API routes y lógica para la gestión de alumnos. Incluye listado con filtros, formularios de alta/edición, ficha detallada y subida de archivos.

1. Componentes a Desarrollar

1. 1. Páginas (App Router)
   - [ ] `/app/alumnos/page.tsx` - Listado de alumnos
   - [ ] `/app/alumnos/nuevo/page.tsx` - Alta de alumno
   - [ ] `/app/alumnos/[id]/page.tsx` - Ficha del alumno
   - [ ] `/app/alumnos/[id]/editar/page.tsx` - Edición de alumno

1. 2. Componentes
   - [ ] `AlumnosList.tsx` - Tabla paginada con filtros
   - [ ] `AlumnoCard.tsx` - Tarjeta de alumno (vista móvil)
   - [ ] `AlumnoForm.tsx` - Formulario de alta/edición
   - [ ] `AlumnoFilters.tsx` - Filtros (centro, cinturón, estado)
   - [ ] `AlumnoFicha.tsx` - Vista detallada con pestañas
   - [ ] `AlumnoAvatar.tsx` - Foto del alumno con placeholder
   - [ ] `DocumentUpload.tsx` - Subida de documentos

1. 3. Servicios/API
   - [ ] `/app/api/alumnos/route.ts` - GET (listar), POST (crear)
   - [ ] `/app/api/alumnos/[id]/route.ts` - GET, PUT, DELETE
   - [ ] `/app/api/alumnos/[id]/upload/route.ts` - POST (subir foto/documentos)
   - [ ] `lib/alumnos.service.ts` - Lógica de negocio
   - [ ] `lib/validations/alumno.schema.ts` - Validaciones con Zod

1. 4. Hooks Personalizados
   - [ ] `useAlumnos()` - Lista de alumnos con filtros
   - [ ] `useAlumno(id)` - Alumno individual
   - [ ] `useCreateAlumno()` - Crear alumno
   - [ ] `useUpdateAlumno()` - Actualizar alumno
   - [ ] `useDeleteAlumno()` - Eliminar alumno

1. 5. Types
   - [ ] `types/alumno.ts` - Interfaces de Alumno, AlumnoFormData, AlumnoFilters

1. Funcionalidades Detalladas

1. Listado de Alumnos
   - Tabla responsive (desktop) y cards (móvil)
   - Paginación (25 por página)
   - Búsqueda en tiempo real (nombre, apellidos)
   - Filtros: Centro, Cinturón, Estado (activo/inactivo)
   - Columnas: Foto, Nombre completo, Edad, Centro, Cinturón, Estado licencia, Estado cuotas
   - Acciones: Ver, Editar, Eliminar
   - Botón flotante "Nuevo Alumno"
   - Exportar a Excel/CSV

1. Formulario de Alta/Edición
   - Validación en tiempo real (Zod + React Hook Form)
   - Secciones colapsables:
   1. Datos del alumno
   2. Datos del tutor
   3. Datos del club
   4. Documentos
   5. Observaciones
   - Subida de foto con preview
   - Subida de documentos (autorizaciones PDF)
   - Detección de duplicados antes de guardar
   - Guardado con feedback visual

1. Ficha del Alumno
   - Pestañas:
   1. Datos personales
   2. Asistencia (integración futura)
   3. Licencias (integración futura)
   4. Cuotas (integración futura)
   5. Competiciones (integración futura)
   6. Documentos
   - Botones: Editar, Dar de baja, Imprimir ficha
   - Badges visuales: Estado licencia, Estado cuotas

1. Criterios de Aceptación

- ✅ Listado de alumnos carga y muestra correctamente
- ✅ Búsqueda y filtros funcionan en tiempo real
- ✅ Formulario de alta con todas las validaciones
- ✅ Subida de foto y documentos funciona (Supabase Storage)
- ✅ Edición de alumno actualiza correctamente
- ✅ Baja de alumno (soft delete) funciona
- ✅ Ficha de alumno muestra todos los datos
- ✅ Detección de duplicados funciona
- ✅ Responsive en desktop, tablet y móvil
- ✅ Tests unitarios de componentes pasando
- ✅ Tests E2E del flujo completo pasando

1. Dependencias

- PBI #1927 (Historia de Usuario: Gestión de alumnos)
- Esquema de BD implementado
- Configuración de Supabase Storage

1. Estimación

Horas: 21-34h

1. Referencias

Relacionado con: PBI #1927, RF-001