KARATE CLUB

Como Monitor del club
Quiero pasar lista de forma rápida en cada sesión
Para registrar la asistencia de los alumnos con flujo de "dos clics"

1. Descripción Funcional

El sistema debe permitir a los monitores realizar el pase de lista de manera rápida y eficiente. La interfaz debe estar optimizada para uso en tablet/móvil durante las clases. Cada sesión tiene su registro de asistencia independiente.

Esta es una funcionalidad crítica de uso diario, por eso tiene prioridad ALTA y debe tener una experiencia de usuario excelente (flujo "dos clics").

1. Criterios de Aceptación (Gherkin)

```gherkin
Feature: Control de asistencia
Como monitor
Quiero pasar lista rápidamente
Para registrar la asistencia diaria

Scenario: Pase de lista de sesión con flujo rápido
    Dado que soy monitor
    Y tengo una clase del grupo "Infantil" a las 18:00
    Cuando accedo a "Pasar lista" 
    Entonces el sistema debe mostrar todos los alumnos del grupo
    Y cada alumno debe tener botones: ✓ Presente | ✗ Ausente | ⚠ Justificada
    Cuando marco a 15 alumnos como presentes
    Y marco a 2 como ausentes
    Y pulso "Guardar asistencia" 
    Entonces debe registrarse la sesión completa
    Y debe mostrarse "Asistencia guardada correctamente"

Scenario: Marcar asistencia con un solo toque (dos clics)
    Dado que estoy pasando lista
    Cuando pulso una vez sobre "Juan García" 
    Entonces debe marcarse automáticamente como "Presente" (verde)
    Cuando pulso de nuevo
    Entonces debe cambiar a "Ausente" (rojo)
    Cuando pulso de nuevo
    Entonces debe cambiar a "Justificada" (amarillo)

Scenario: Historial de asistencia por alumno
    Dado que visualizo la ficha de un alumno
    Cuando accedo a la pestaña "Asistencia" 
    Entonces debo ver calendario con su historial
    Y debe mostrar estadísticas:
      - Total sesiones
      - Asistencias (porcentaje)
      - Ausencias (porcentaje)
      - Justificadas (porcentaje)

Scenario: Alertar alumno con muchas ausencias
    Dado que un alumno tiene 5 ausencias no justificadas en el mes
    Cuando el sistema ejecuta el proceso de alertas
    Entonces debe notificar al administrador
    Y debe sugerir "Contactar con la familia"

Scenario: Ver asistencia de una sesión pasada
    Dado que soy monitor
    Cuando accedo a "Historial de sesiones" 
    Y selecciono la clase del 15/10/2025
    Entonces debo ver la lista de asistencia de ese día
    Y debe indicar quién pasó lista
    Y debe permitir editar si es necesario
```

1. Modelo de Datos

1. Tabla: Sesiones (Clases realizadas)
   Campos obligatorios:
   - fecha (date)
   - hora_inicio (time)
   - hora_fin (time)
   - grupo (string: "Infantil", "Juvenil", "Adultos", etc.)
   - centro_id (FK centros)
   - instructor_id (FK users)
   - estado (enum: programada, realizada, cancelada)

Automáticos: id, created_at, updated_at, created_by

1. Tabla: Asistencias
   Campos obligatorios:
   - sesion_id (FK sesiones)
   - alumno_id (FK alumnos)
   - estado (enum: presente, ausente, justificada)
   - fecha (date, denormalizado para queries rápidas)

Campos opcionales:
- observaciones (text, ej: "Llegó tarde")

Automáticos: id, created_at, updated_at, created_by

1. Validaciones

1. No se puede pasar lista de una sesión futura
2. No se puede duplicar asistencia (misma sesión + alumno)
3. Solo monitores y admins pueden pasar lista
4. La sesión debe estar en estado "realizada" para guardar asistencia

1. Interfaz de Usuario

1. Vista Principal: Pasar Lista (Optimizada para Tablet/Móvil)
   - Selector de sesión: Fecha + Hora + Grupo
   - Botón destacado: "Iniciar pase de lista"
   - Lista de alumnos:
   - Foto (thumbnail pequeño)
   - Nombre completo
   - Botones grandes táctiles: ✓ ✗ ⚠
   - Estado actual con color de fondo (verde/rojo/amarillo)
   - Contador en tiempo real: "15/17 presentes"
   - Botones inferiores fijos:
   - "Marcar todos presentes" (acción rápida)
   - "Guardar asistencia"
   - "Cancelar"

1. Vista: Historial de Sesiones (Admin/Monitor)
   - Tabla de sesiones:
   - Fecha, hora, grupo, monitor, total alumnos, presentes
   - Filtros: Fecha, grupo, centro, monitor
   - Acciones por sesión: "Ver detalle", "Editar asistencia"

1. Pestaña de Asistencia (en Ficha de Alumno)
   - Estadísticas generales:
   - Total sesiones: 48
   - Asistencias: 42 (87.5%)
   - Ausencias: 4 (8.3%)
   - Justificadas: 2 (4.2%)
   - Calendario visual (tipo heatmap):
   - Verde: presente
   - Rojo: ausente
   - Amarillo: justificada
   - Gris: sin clase
   - Tabla detallada (últimas 20 sesiones):
   - Fecha, hora, grupo, estado, observaciones

1. Flujo "Dos Clics" (Requisito Clave)

El objetivo es que el monitor pueda pasar lista de 20 alumnos en menos de 1 minuto:

1. Clic 1: Acceder a "Pasar lista" → Sistema carga automáticamente la próxima sesión
2. Clic 2-N: Un toque por alumno para marcar presente (por defecto)
3. Clic final: "Guardar asistencia"

Optimizaciones:
- Por defecto, todos aparecen como "No marcado"
- Un toque = Presente (caso más común)
- Toques adicionales alternan: Presente → Ausente → Justificada → No marcado
- Botón "Marcar todos presentes" para agilizar cuando casi todos asisten

1. Definition of Done (DoD)

- [ ] Modelos Sesión y Asistencia en Supabase
- [ ] API CRUD para sesiones y asistencias
- [ ] Interfaz de pase de lista optimizada para táctil
- [ ] Flujo de "un toque" para marcar asistencia funcionando
- [ ] Botón "Marcar todos presentes" implementado
- [ ] Contador en tiempo real de asistentes
- [ ] Guardado de sesión completa
- [ ] Historial de sesiones con filtros
- [ ] Vista de detalle de sesión pasada
- [ ] Edición de asistencia de sesión pasada
- [ ] Pestaña de asistencia en ficha de alumno
- [ ] Estadísticas de asistencia por alumno
- [ ] Calendario visual (heatmap) de asistencia
- [ ] Sistema de alertas por ausencias recurrentes
- [ ] Tests unitarios, integración y E2E pasando
- [ ] JSDoc completo
- [ ] Responsive y optimizado para tablet/móvil (crítico)
- [ ] Test de usabilidad: pasar lista de 20 alumnos en <1 minuto

1. Pruebas Principales

Funcionales: Pasar lista, editar sesión pasada, historial, estadísticas
Usabilidad: Flujo de dos clics, marcar todos presentes, uso en tablet
Validación: Duplicados, sesiones futuras, permisos
Rendimiento: Cargar lista de 30 alumnos en <1 segundo
Alertas: Notificación por ausencias recurrentes

1. Estimación

Story Points: 8
Horas estimadas: 13-21 horas

1. Dependencias

- Gestión de alumnos completada
- Sistema de autenticación y roles (Monitor)

1. Referencias

Relacionado con: RF-005 (SPEC_FUNCIONAL.md), Historia Monitor #1 (HISTORIAS_USUARIO[PBI].md)