KARATE CLUB

Como Administrador del club
Quiero definir cuotas por alumno o grupo y registrar cobros manualmente
Para controlar la morosidad y tener un registro de pagos sin necesidad de pasarela de pago

1. Descripción Funcional

El sistema debe permitir definir cuotas (mensual, trimestral, anual) y registrar manualmente los pagos recibidos. No incluye pasarela de pago en Fase 1 debido al bajo volumen de transacciones y modelo de contacto directo del club.

El sistema debe generar recordatorios de cuotas pendientes y permitir consultar el estado de pagos de cada alumno.

1. Criterios de Aceptación (Gherkin)

```gherkin
Feature: Gestión de cuotas y cobros
Como administrador del club
Quiero gestionar cuotas y registrar cobros
Para controlar los pagos del club

Scenario: Definir cuota mensual para un alumno
    Dado que accedo a la ficha de un alumno
    Cuando selecciono "Nueva Cuota" 
    Y configuro:
    | Concepto | Cuota mensual |
    | Importe | 50.00 € |
    | Periodicidad | Mensual |
    | Fecha inicio | 01/09/2025 |
    Y pulso "Guardar" 
    Entonces el sistema debe crear la cuota
    Y debe generar automáticamente los recibos mensuales

Scenario: Registrar pago en efectivo
    Dado que un alumno tiene una cuota pendiente de septiembre
    Cuando accedo a sus cuotas
    Y selecciono la cuota pendiente
    Y pulso "Registrar pago" 
    Y completo:
    | Fecha de pago | 05/09/2025 |
    | Método | Efectivo |
    | Importe | 50.00 € |
    Y pulso "Guardar" 
    Entonces el estado debe cambiar a "Pagado" 
    Y debe actualizarse la fecha de último pago

Scenario: Listado de morosos
    Dado que existen 50 alumnos con cuotas
    Y 8 tienen cuotas pendientes de más de 30 días
    Cuando accedo al módulo "Cuotas pendientes" 
    Entonces debo ver los 8 alumnos con morosidad
    Y deben ordenarse por antigüedad de deuda
    Y debe mostrarse el importe total adeudado

Scenario: Generación de recordatorio de pago
    Dado que un alumno tiene cuota pendiente
    Cuando selecciono "Enviar recordatorio" 
    Entonces el sistema debe generar plantilla de email
    Y debe incluir: Alumno, concepto, importe, fecha vencimiento
    Y debe permitir copiar o enviar el mensaje

Scenario: Aplicar descuento a cuota
    Dado que un alumno tiene hermanos en el club
    Cuando creo su cuota mensual
    Y aplico descuento "Hermanos 20%" 
    Entonces el importe debe ser 40.00 € en lugar de 50.00 €
    Y debe registrarse el motivo del descuento
```

1. Modelo de Datos

1. Tabla: Cuotas (Configuración)
   Campos obligatorios:
   - alumno_id (FK alumnos)
   - concepto (string: "Cuota mensual", "Cuota trimestral", etc.)
   - importe (decimal 10,2)
   - periodicidad (enum: mensual, trimestral, anual, único)
   - fecha_inicio (date)
   - estado (activo/inactivo)

Campos opcionales:
- descuento_porcentaje (decimal)
- descuento_motivo (text)
- observaciones (text)

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

1. Tabla: Pagos (Registros de cobro)
   Campos obligatorios:
   - cuota_id (FK cuotas)
   - alumno_id (FK alumnos)
   - concepto (string)
   - importe (decimal 10,2)
   - fecha_vencimiento (date)
   - fecha_pago (date, null si pendiente)
   - estado (enum: pendiente, pagado, parcial)
   - metodo_pago (enum: efectivo, transferencia, tarjeta, otro)

Campos opcionales:
- referencia (string: número de transferencia, etc.)
- observaciones (text)

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

1. Validaciones

1. El importe debe ser mayor que 0
2. La fecha de pago no puede ser futura
3. El importe pagado no puede superar el importe de la cuota
4. La periodicidad debe ser válida (mensual/trimestral/anual/único)
5. El descuento no puede ser mayor del 100%
6. La fecha de inicio debe ser válida

1. Interfaz de Usuario

1. Dashboard de Cuotas
   - Contadores:
   - Total cobrado este mes
   - Cuotas pendientes (importe)
   - Número de morosos
   - Previsión próximo mes
   - Listado de alumnos con estado de cuotas
   - Filtros: Estado (pagado/pendiente), Centro, Mes
   - Botón: "Enviar recordatorios masivos"

1. Ficha de Cuotas del Alumno
   - Cuota configurada: Concepto, importe, periodicidad
   - Historial de pagos: Tabla con fecha, concepto, importe, método, estado
   - Próximas cuotas: Vencimientos futuros
   - Botones: "Nuevo pago", "Modificar cuota", "Enviar recordatorio"

1. Formulario de Registro de Pago
   - Fecha de pago (date picker)
   - Método de pago (select)
   - Importe (con validación)
   - Referencia (opcional)
   - Observaciones
   - Botones: "Guardar", "Cancelar"

1. Funcionalidades Automáticas

1. Generación automática de recibos: Al crear cuota mensual, genera recibos para los próximos 12 meses
2. Alertas de morosidad: Dashboard muestra alumnos con >30 días de retraso
3. Plantillas de email: Generación automática de recordatorios personalizados

1. Definition of Done (DoD)

- [ ] Modelos Cuota y Pago creados en Supabase
- [ ] Relaciones con Alumno configuradas
- [ ] API CRUD para cuotas y pagos
- [ ] Generación automática de recibos periódicos
- [ ] Dashboard con contadores implementado
- [ ] Listado de cuotas con filtros funcionando
- [ ] Formulario de nueva cuota con validaciones
- [ ] Formulario de registro de pago
- [ ] Cálculo automático de descuentos
- [ ] Historial de pagos en ficha de alumno
- [ ] Listado de morosos (>30 días)
- [ ] Generación de plantillas de recordatorio
- [ ] Exportación a Excel/CSV
- [ ] Tests unitarios, integración y E2E pasando
- [ ] JSDoc completo
- [ ] Responsive en todos los dispositivos

1. Pruebas Principales

Funcionales: Crear cuota, registrar pago, aplicar descuento, generar recordatorios, listado morosos
Validación: Importes, fechas, descuentos, métodos de pago
Automáticos: Generación recibos periódicos, alertas morosidad
Integración: Estado cuotas en ficha alumno, contadores dashboard

1. Estimación

Story Points: 8
Horas estimadas: 13-21 horas

1. Dependencias

- Gestión de alumnos completada
- Sistema de plantillas de email

1. Referencias

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