245 lines
9.0 KiB
Markdown
245 lines
9.0 KiB
Markdown
# Notificaciones email automáticas — alertas y recordatorios (2026-04-26)
|
||
|
||
Cron diario 8:30 AM (America/Mexico_City) que envía dos tipos de email a
|
||
los responsables del despacho:
|
||
|
||
1. **Alertas fiscales nuevas**: una vez por alerta detectada (no se repite).
|
||
2. **Recordatorios próximos a vencer**: en 3 ventanas (3 días, 1 día, mismo día).
|
||
|
||
Cierra el pendiente histórico "notificaciones email automáticas de
|
||
alertas/recordatorios" que estaba en CLAUDE.md "Problemas conocidos".
|
||
|
||
---
|
||
|
||
## 1. Modelo de notificación elegido (Option B)
|
||
|
||
Después de evaluar 3 opciones (digest diario / por evento / híbrido) el
|
||
owner eligió **Option B — por evento**: notificar cuando algo se activa
|
||
por primera vez. Para alertas significa una sola email por (alerta_id,
|
||
contribuyente_id) en toda la vida; para recordatorios significa hasta tres
|
||
emails (uno por ventana) por recordatorio.
|
||
|
||
### Por qué no digest diario
|
||
|
||
El owner prefiere relevancia temporal sobre consolidación. Una alerta
|
||
nueva debe gatillar email; no esperar al "siguiente lunes" como hace
|
||
`weekly-update.job.ts`.
|
||
|
||
### Por qué no real-time (vs daily 8:30 AM)
|
||
|
||
Real-time requiere hooks en `generarAlertasAutomaticas` que se ejecuta on
|
||
each `/alertas` page load. Costoso. El cron diario captura el mismo set
|
||
de alertas con UX equivalente (el usuario no esperaba inmediatez sub-hora
|
||
para una alerta fiscal). Los recordatorios siempre se evalúan en función
|
||
de `fecha_limite ± días`, así que un cron al día es suficiente.
|
||
|
||
---
|
||
|
||
## 2. Esquema de datos (BD tenant)
|
||
|
||
### Migración 039 — `alertas_notificadas`
|
||
|
||
```sql
|
||
CREATE TABLE alertas_notificadas (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
alerta_id TEXT NOT NULL,
|
||
contribuyente_id UUID,
|
||
notified_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
resuelta_at TIMESTAMPTZ
|
||
);
|
||
|
||
CREATE UNIQUE INDEX uniq_alertas_notif
|
||
ON alertas_notificadas (alerta_id, COALESCE(contribuyente_id::text, ''));
|
||
```
|
||
|
||
- `alerta_id` es el `id` que retorna `generarAlertasAutomaticas` (e.g.,
|
||
`'lista-negra-propia'`, `'discrepancia-regimen'`).
|
||
- `contribuyente_id` puede ser NULL si la alerta es tenant-level. El
|
||
UNIQUE compuesto con `COALESCE(... ::text, '')` permite la combinación
|
||
porque NULL no participa en UNIQUE de columna sola.
|
||
- `resuelta_at` se setea cuando una alerta previamente notificada deja
|
||
de aparecer en la corrida actual del cron. Solo informativo — no
|
||
genera email.
|
||
|
||
### Migración 040 — columnas en `recordatorios`
|
||
|
||
```sql
|
||
ALTER TABLE recordatorios
|
||
ADD COLUMN email_3d_at TIMESTAMPTZ,
|
||
ADD COLUMN email_1d_at TIMESTAMPTZ,
|
||
ADD COLUMN email_0d_at TIMESTAMPTZ;
|
||
```
|
||
|
||
Cada columna se setea cuando el cron envía el email para esa ventana.
|
||
Si el usuario edita `fecha_limite` después de un envío, las columnas
|
||
previas siguen marcadas — no se re-notifica para ventanas ya enviadas.
|
||
Decisión MVP simple y predecible.
|
||
|
||
---
|
||
|
||
## 3. Flujo del cron
|
||
|
||
`apps/api/src/jobs/notifications.job.ts` corre `30 8 * * *` America/Mexico_City:
|
||
|
||
```
|
||
runNotifications()
|
||
├─ FOR each tenant active:
|
||
│ ├─ runNotificationsForTenant(tenantId)
|
||
│ │ ├─ Promise.all:
|
||
│ │ │ ├─ processNewAlertas(pool, tenantId, ctx)
|
||
│ │ │ └─ processProximosRecordatorios(pool, tenantId, ctx)
|
||
│ │ └─ try/catch por proceso (un error no bloquea el otro)
|
||
│ └─ try/catch por tenant
|
||
└─ Logea resumen final
|
||
```
|
||
|
||
### `processNewAlertas`
|
||
|
||
Para cada contribuyente activo:
|
||
|
||
1. `generarAlertasAutomaticas(pool, tenantId, contribuyenteId)` → lista
|
||
de alertas activas (no persistidas).
|
||
2. Por cada alerta: `INSERT INTO alertas_notificadas ... ON CONFLICT DO
|
||
NOTHING RETURNING id`. Si retorna fila → era nueva, agregar a batch.
|
||
3. Marcar `resuelta_at = NOW()` para alertas previamente notificadas
|
||
que NO están activas hoy (`alerta_id <> ALL($activos)`).
|
||
4. Si hay alertas nuevas → resolver destinatarios y enviar email
|
||
batched (1 email con todas las alertas nuevas del contribuyente).
|
||
|
||
### `processProximosRecordatorios`
|
||
|
||
Para cada ventana `['3d', '1d', '0d']`:
|
||
|
||
1. Buscar recordatorios donde `completado = false`,
|
||
`fecha_limite = CURRENT_DATE + diasVentana`, y `email_Xd_at IS NULL`.
|
||
2. Por cada recordatorio: resolver destinatarios, enviar email,
|
||
`UPDATE email_Xd_at = NOW()`.
|
||
|
||
---
|
||
|
||
## 4. Resolución de destinatarios
|
||
|
||
### Alertas (contribuyente-específicas)
|
||
|
||
Conjunto = unión de:
|
||
|
||
- `entidades_gestionadas.supervisor_user_id` del contribuyente.
|
||
- `carteras.auxiliar_user_id` de carteras donde aparece el contribuyente
|
||
(vía `cartera_entidades`).
|
||
- `cliente_accesos.user_id` para ese contribuyente.
|
||
|
||
El owner del tenant queda incluido **solo si es supervisor de ese
|
||
contribuyente** (no se agrega por ser owner). Dedupe natural vía `Set<userId>`.
|
||
|
||
### Recordatorios (tenant-level, no atados a contribuyente)
|
||
|
||
- **Privado**: solo el `creado_por`.
|
||
- **Público**:
|
||
- Clientes con cualquier acceso (`cliente_accesos.user_id`).
|
||
- Auxiliares de cualquier cartera (`carteras.auxiliar_user_id`).
|
||
- **Si no hay auxiliares en absoluto**: agregar supervisores
|
||
(`entidades_gestionadas.supervisor_user_id` ∪ `carteras.supervisor_user_id`).
|
||
- **Si owner es supervisor y no hay auxiliares**: owner queda incluido
|
||
vía la lista de supervisores (intersección).
|
||
|
||
### Dedupe por usuario, no por email
|
||
|
||
Si el mismo user aparece como supervisor + auxiliar + cliente, el `Set`
|
||
sobre userId garantiza un solo email. El email se resuelve después con
|
||
`prisma.user.findMany({ where: { id: { in: userIds }, active: true } })`.
|
||
|
||
---
|
||
|
||
## 5. Templates email
|
||
|
||
### `alertas-nuevas.ts`
|
||
|
||
Header con conteo total + breakdown por nivel (alta/media/baja con
|
||
badges de color SAT-style). Lista de items con borde izquierdo del color
|
||
del nivel. Botón "Ver alertas en el sistema" → `${FRONTEND_URL}/alertas`.
|
||
|
||
Footer aclaratorio: "Estas alertas ya fueron registradas — solo te
|
||
avisaremos cuando aparezcan nuevas, no se repetirá esta notificación si
|
||
la misma alerta sigue activa."
|
||
|
||
### `recordatorio-proximo.ts`
|
||
|
||
Subject incluye prefijo según ventana: `🗓 / ⚠️ / ⏰` + label "en 3 días"
|
||
/ "mañana" / "HOY". Body resalta `fecha_limite` con color del nivel de
|
||
urgencia (azul/amarillo/rojo). Link → `${FRONTEND_URL}/calendario`.
|
||
|
||
---
|
||
|
||
## 6. Archivos creados/modificados
|
||
|
||
```
|
||
apps/api/src/migrations/tenant/039_alertas_notificadas.sql [+]
|
||
apps/api/src/migrations/tenant/040_recordatorios_email_notif.sql [+]
|
||
apps/api/src/services/email/templates/alertas-nuevas.ts [+]
|
||
apps/api/src/services/email/templates/recordatorio-proximo.ts [+]
|
||
apps/api/src/services/email/email.service.ts [~] +sendAlertasNuevas, +sendRecordatorioProximo
|
||
apps/api/src/services/notifications.service.ts [+]
|
||
apps/api/src/jobs/notifications.job.ts [+]
|
||
apps/api/src/index.ts [~] +startNotificationsJob (prod-only)
|
||
```
|
||
|
||
Migraciones aplicadas a 3 tenants existentes:
|
||
`horux_despacho_mo3nhzvl_1xheu`, `horux_despacho_mo3ni6u8_b9vgg`
|
||
(Patito), `horux_despacho_mo7je8bz_vdopr` (Zorro).
|
||
|
||
---
|
||
|
||
## 7. Operación
|
||
|
||
### Activación
|
||
|
||
- **Producción**: el cron arranca automáticamente en `index.ts` cuando
|
||
`NODE_ENV === 'production'`. SMTP debe estar configurado en `.env`
|
||
(`SMTP_HOST/PORT/USER/PASS/FROM`).
|
||
- **Dev**: cron OMITIDO. Disparo manual:
|
||
|
||
```ts
|
||
import { runNotificationsForTenant } from './jobs/notifications.job.js';
|
||
await runNotificationsForTenant('<tenantId>');
|
||
```
|
||
|
||
Para probar sin SMTP real, los emails se loguean a consola (transport
|
||
detecta SMTP_USER vacío y entra en modo "log only").
|
||
|
||
### Disparo manual desde admin
|
||
|
||
`runNotifications()` y `runNotificationsForTenant(tenantId)` están
|
||
exportados — se pueden cablear a un endpoint admin futuro tipo
|
||
`POST /admin/notifications/run` para forzar un envío.
|
||
|
||
### Trazabilidad
|
||
|
||
- Tabla `alertas_notificadas` queda como log permanente (con
|
||
`notified_at` + `resuelta_at`). Útil para auditar "¿se envió email
|
||
cuando apareció esta alerta?".
|
||
- Recordatorios: las 3 columnas `email_Xd_at` documentan cuáles ventanas
|
||
se enviaron.
|
||
|
||
---
|
||
|
||
## 8. Pendientes / mejoras posibles
|
||
|
||
- **Notificación de resolución**: hoy `resuelta_at` se setea en silencio.
|
||
Si el owner quiere "buena noticia: la alerta de lista negra desapareció"
|
||
agregar template `alerta-resuelta.ts` y disparar email cuando
|
||
`rowCount > 0` en el UPDATE de resolved.
|
||
- **Re-notificación tras resolución**: hoy MVP "una sola vez en la vida".
|
||
Si una alerta se resuelve y vuelve a activarse, no re-notifica. Cambio
|
||
pequeño: `DELETE alertas_notificadas WHERE resuelta_at IS NOT NULL AND
|
||
resuelta_at < NOW() - INTERVAL '30 days'` antes del INSERT permitiría
|
||
re-notificación tras 30 días.
|
||
- **Preferencias por usuario**: hoy el destinatario no puede opt-out de
|
||
notificaciones específicas. Tabla `user_notification_preferences` con
|
||
flags por categoría sería útil cuando aparezca el primer "demasiados
|
||
emails" de un cliente.
|
||
- **Endpoint admin de disparo manual**: cablear `runNotifications()` a
|
||
`POST /admin/notifications/run` para QA/debug.
|
||
- **Histórico de emails enviados**: audit-log entry por cada email
|
||
enviado (cuántos a quién) para soporte cuando un usuario diga "no me
|
||
llegó nada".
|