Gesti-n-Reservas-Naturcalabacera/docs/superpowers/specs/2026-06-15-configuracion-destinatarios-notificaciones-design.md

# Configuración de destinatarios de notificaciones — Diseño

**Fecha:** 2026-06-15
**Estado:** Aprobado para implementación (pendiente revisión final del spec)

---

## 1. Problema

Hoy, "quién recibe cada correo" se define con variables de entorno en Dokploy
(`NOTIFICATION_EMAIL_TENERIFFA`, `NOTIFICATION_EMAIL_NATUR`,
`NOTIFICATION_EMAIL_POOL_HEATING`). Esto es:

- **Rígido**: cualquier cambio exige editar Dokploy y redeplegar.
- **Invisible**: el cliente no ve ni controla a quién llega cada cosa.
- **Frágil/inseguro**: nada impide mandar información completa (datos del cliente) a
  un destinatario que solo debería recibir información reducida (Teneriffa, por
  acuerdo de privacidad).

## 2. Objetivo

Mover la configuración de destinatarios a la base de datos y gestionarla desde una
**pantalla nueva dentro de la app** (solo admin). El motor de envío deja de leer las
env vars y lee esta configuración.

**Regla dura de privacidad:** a un destinatario marcado como "reducida" es
**imposible** enviarle la versión completa, por diseño del modelo.

### No-objetivos

- No se rediseña el formato visual de los emails: **las plantillas HTML actuales se
  conservan tal cual** (es justo lo que al cliente le gusta).
- No se añade gestión de plantillas desde la UI (las plantillas siguen en disco).

## 3. Modelo de datos (Supabase, schema `natur_reservas`)

> **CRÍTICO:** todo el SQL se cualifica con `natur_reservas.` (instancia Supabase
> compartida; `public` es otro proyecto). Ver CLAUDE.md §1.

### Tabla `natur_reservas.notification_groups`

Un grupo de destinatarios con un nivel de información fijo.

| Columna | Tipo | Notas |
|---|---|---|
| `id` | uuid PK | `gen_random_uuid()` |
| `name` | text NOT NULL | Ej. "Teneriffa", "Naturcalabacera (Admin)", "Limpieza" |
| `level` | text NOT NULL | `CHECK (level IN ('reducida','completa'))`, default `'completa'` |
| `emails` | text[] NOT NULL | default `'{}'`; lista de correos del grupo |
| `enabled` | boolean NOT NULL | default `true` |
| `created_at` | timestamptz | default `now()` |
| `updated_at` | timestamptz | default `now()` |

### Tabla `natur_reservas.notification_scenario_recipients`

Qué grupos recibe cada escenario (relación N:M escenario ↔ grupo).

| Columna | Tipo | Notas |
|---|---|---|
| `id` | uuid PK | `gen_random_uuid()` |
| `scenario` | text NOT NULL | Igual que `event_type` (ver §5) |
| `group_id` | uuid NOT NULL | `REFERENCES natur_reservas.notification_groups(id) ON DELETE CASCADE` |
| `created_at` | timestamptz | default `now()` |
| — | — | `UNIQUE (scenario, group_id)` |

### RLS

Solo `admin` gestiona ambas tablas (mismo patrón que `notification_events` en la
migración 009: política `FOR ALL` con `get_user_role() = 'admin'`). El backend usa la
`service_role` key, que bypasea RLS.

### Migración

Archivo nuevo `supabase/migrations/012_notification_config.sql` que crea las dos
tablas, RLS y la **semilla** del §6.

## 4. Motor de envío (backend)

`apps/api/src/events/handler.ts` deja de leer `env.NOTIFICATION_EMAIL_*`. En su lugar,
una función nueva resuelve destinatarios desde la BD por escenario:

```
resolveRecipients(scenario) ->
  SELECT g.level, g.emails
  FROM natur_reservas.notification_scenario_recipients r
  JOIN natur_reservas.notification_groups g ON g.id = r.group_id
  WHERE r.scenario = $scenario AND g.enabled = true
```

Reglas de uso:

- **Escenarios de reserva con doble versión** (`created`, `updated`, `cancelled`):
  - Emails de grupos `level = 'reducida'` → se envía la **plantilla reducida**
    (`renderTeneriffaMinimal`). Un envío con todos esos emails en `to`.
  - Emails de grupos `level = 'completa'` → se envía la **plantilla completa**
    (`natur-crud.html`). Un envío con todos esos emails en `to`.
  - Si una de las dos listas está vacía, ese envío simplemente no ocurre.
- **Escenarios de plantilla única** (`invoice_second_notice`, `pool_heating_notice`):
  - Se juntan todos los emails de todos los grupos asignados (sin importar nivel,
    porque la plantilla es fija) → un envío con la plantilla del escenario.
- Si un escenario no tiene grupos asignados, **no se envía nada** y se registra en log
  (`console.warn`) para diagnóstico.

El resto del flujo (render de plantilla, `sendEmail` → webhook n8n → Gmail) **no
cambia**. El webhook y el formato siguen igual.

### Compatibilidad con env vars

Tras esta migración, `NOTIFICATION_EMAIL_TENERIFFA/_NATUR/_POOL_HEATING` dejan de
usarse. Se eliminan del `required()` en `apps/api/src/config/env.ts` para que la app no
dependa de ellas. (Se pueden retirar también de Dokploy, pero no es necesario.)

## 5. Escenarios (mapa de `event_type` → plantilla)

| Escenario (`event_type`) | Disparo | Plantilla(s) | Doble versión |
|---|---|---|---|
| `reservation.created` | Inmediato (al guardar) | reducida + completa | Sí |
| `reservation.updated` | Inmediato (solo si cambian fechas/horas) | reducida + completa | Sí |
| `reservation.cancelled` | Inmediato | reducida + completa | Sí |
| `reservation.invoice_second_notice` | Programado 10 días antes | `invoice-10d` | No |
| `reservation.pool_heating_notice` | Programado 48h antes | `pool-heating-48h` | No |

> El correo de check-in 24h (`reservation.reminder_24h`) ya fue eliminado del sistema
> en una iteración previa.

## 6. Semilla inicial

**Grupos:**

| name | level | emails |
|---|---|---|
| Teneriffa | `reducida` | `uwe.dotschkis@teneriffa2000.de`, `j.reichstein@teneriffa2000.de` |
| Naturcalabacera (Admin) | `completa` | `administracion@naturcalabacera.com` |
| Limpieza | `completa` | `limpieza.naturcalabacera@gmail.com` *(placeholder editable)* |

**Asignación escenario → grupos:**

| Escenario | Teneriffa | Admin | Limpieza |
|---|---|---|---|
| `reservation.created` | ✅ | ✅ | — |
| `reservation.updated` | ✅ | ✅ | — |
| `reservation.cancelled` | ✅ | ✅ | — |
| `reservation.invoice_second_notice` | — | ✅ | — |
| `reservation.pool_heating_notice` | — | — | ✅ |

(El email de Limpieza y la posible copia de piscina para Admin se ajustan desde la
pantalla una vez montada.)

## 7. Pantalla (frontend)

Nueva vista **"Notificaciones"**, accesible **solo para rol `admin`**.

- **Navegación:** añadir entrada en `Sidebar.tsx` y `MobileNavigation.tsx`
  (`requires: 'admin'`), y el render condicional en `App.tsx`
  (`currentView === 'notifications' && isAdmin`).
- **Componente** `apps/web/src/components/NotificationSettings.tsx` con hook
  `useNotificationConfig` que lee/escribe las dos tablas vía el cliente Supabase
  (schema `natur_reservas`), siguiendo el patrón de `useReservations` /
  `UserManagement`.
- **Bloque 1 — Grupos:** lista editable de grupos. Por grupo: nombre, selector de
  nivel (`reducida`/`completa`), chips de emails (añadir/quitar), activar/desactivar,
  borrar. Botón "+ Nuevo grupo".
- **Bloque 2 — Asignación:** por cada escenario, chips de los grupos; click para
  activar/desactivar qué grupos lo reciben.
- **Guardar:** persiste cambios (upsert de grupos y de asignaciones).
- **Estética:** Tailwind, modo oscuro, paleta de la app (emerald/amber/slate),
  iconos `lucide-react`, toasts `sonner`. Coherente con `SettingsPage` /
  `UserManagement`.

## 8. Botón "Enviar prueba"

Por cada escenario, un botón que dispara ese correo **con datos ficticios** sin crear
reservas reales.

- **Endpoint** nuevo `POST /api/notifications/test-scenario` (protegido, admin):
  `{ scenario, testEmail? }`.
- Construye una `Reservation` ficticia coherente con el escenario y llama al mismo
  `handleNotificationEvent`, de modo que la prueba usa **exactamente** la misma lógica
  y plantillas que el envío real.
- Destinatario: si `testEmail` viene, se envía solo a ese; si no, a los destinatarios
  configurados del escenario (prueba realista de entrega).
- El asunto/encabezado de prueba se marca visualmente como tal (p. ej. prefijo
  `[PRUEBA]`) para no confundir con un aviso real.

## 9. Riesgo conocido a verificar en implementación

Esta pantalla resuelve **a quién** y **con qué formato** llega cada correo, pero **no**
garantiza por sí sola que los correos de reserva (CRUD) se disparen en producción.

Patrón observado durante el diagnóstico: los correos de **jobs** (segunda factura;
prueba manual de piscina) llegan, mientras que los **CRUD disparados desde el
navegador** (`App.tsx` → `POST /api/notifications/reservation-event`) estaban en duda.
El `notifyApi` del frontend es "fire-and-forget" con errores silenciados
(`App.tsx:236-239`) y depende de `VITE_API_URL` (build) y de `WEB_ORIGIN`/CORS
(`index.ts:11-14`).

**Tarea explícita del plan:** verificar que el frontend de producción alcanza el
backend (valores reales de `VITE_API_URL` y `WEB_ORIGIN`, ver una llamada a
`reservation-event` en DevTools/Network). Si esa vía está rota, ninguna configuración
de destinatarios hará que salgan los correos de reserva. Considerar, si procede, dejar
de silenciar el error en `notifyApi` (al menos un `console.error` / toast) para que el
fallo sea visible.

## 10. Pruebas

- **Backend:** test unitario de `resolveRecipients` (separación por nivel; escenario
  sin grupos → sin envío; plantilla correcta por nivel).
- **Regla de privacidad:** test que verifica que un grupo `reducida` nunca recibe la
  plantilla completa, en ninguno de los escenarios de doble versión.
- **Manual:** botón "Enviar prueba" de cada escenario contra el webhook real,
  comprobando entrega y formato (continuidad del método que veníamos usando).