# Kings & Queens - Cobros por periodo

Este flujo reemplaza el modelo de horas como credito. La cuota se cobra por periodo mensual y las clases solo registran agenda/asistencia.

## Variables

Configurar en n8n o en el entorno del runner:

- `KQ_PB_URL`: URL interna o externa de PocketBase. Ejemplo: `http://eddos-kq-pocketbase:8090`
- `KQ_PB_ADMIN_EMAIL`: superuser de PocketBase
- `KQ_PB_ADMIN_PASSWORD`: password del superuser
- `KQ_TRANSFER_ALIAS`: alias de transferencia de Ale
- `KQ_TRANSFER_CBU`: CBU/CVU de transferencia

## Medios y monedas

Cada plan puede tener:

- `currency`: `ARS` o `USD`.
- `payment_method`: `cash`, `transfer` o `international`.

Uso recomendado:

- `cash`: efectivo, confirmacion manual en el panel de Ale.
- `transfer`: transferencia local argentina, con alias/CBU/CVU en instrucciones.
- `international`: estudiantes extranjeros o cobros en dolares; el mensaje indica coordinar el medio internacional con Ale.

## Workflows recomendados

### 1. Generar periodos

Schedule: dia 1 de cada mes, 08:00 Argentina.

Comando:

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs generate
```

Resultado:

- Crea un `billing_periods` por alumno con plan activo.
- Crea un `payment_orders` con referencia unica.
- Hereda moneda y medio de pago desde el plan del alumno.
- No acredita horas ni descuenta clases.
- Despues de generar, se puede ejecutar el recordatorio del dia 1.

### 2. Recordatorio de pago del dia 1

Schedule: dia 1 de cada mes, 09:00 Argentina.

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs reminder-payment
```

El comando devuelve JSON con `reminders[]`. n8n debe iterar esa lista y mandar cada `message` al `phone` del alumno por Evolution/WhatsApp. Al mismo tiempo marca `payment_reminder_sent_at`, asi no repite el aviso.

### 3. Recordatorio de vencimiento del dia 9

Schedule: dia 9 de cada mes, 09:00 Argentina.

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs reminder-due
```

Solo incluye alumnos cuyo periodo sigue pendiente. Si Ale marco el pago manualmente antes del 9, no sale mensaje.

### 4. Recargo desde el dia 11

Schedule: diario desde el dia 11, 09:00 Argentina.

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs late-fee
```

Aplica una sola vez el `late_fee_amount` configurado en el plan del alumno, actualiza el importe de la cuota y la orden de pago.

### 5. Marcar vencidos

Schedule: diario, 09:05 Argentina.

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs overdue
```

### 6. Cerrar periodos

Schedule: dia 1 de cada mes, 09:00 Argentina, despues de generar el nuevo periodo.

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_periods.mjs close
```

## Confirmacion de pago

El camino principal ahora es manual: Ale entra al panel, abre el alumno y toca `Confirmar pago`.

La app actualiza:

- `payment_orders.status = "approved"`
- `payment_orders.approved_at = now`
- `billing_periods.status = "paid"`
- `payment_events` con `provider = "manual"` y status `matched`

Al quedar `paid`, los recordatorios del dia 9 y el recargo del dia 11 lo saltean.

## Validacion automatica opcional

Si mas adelante se vuelve a transferencia automatizada o PSP, el proveedor debe actualizar los mismos campos. Si el monto o referencia no coinciden, guardar `payment_events.status = "review"` y no marcar el periodo como pagado.

El webhook de banco/PSP puede llamar este comando pasando el JSON del evento por stdin:

```bash
node /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/scripts/billing_payment_event.mjs
```

Contrato minimo del payload:

```json
{
  "provider": "transfer",
  "provider_event_id": "movimiento-unico-123",
  "amount": 50000,
  "reference": "KQ-MARIA-PEREZ-2026-05"
}
```

El script detecta duplicados por `provider_event_id`, matchea contra orden pendiente por monto y referencia, crea `payment_events`, aprueba la orden y marca el periodo como `paid`.