REP-008 — Alertas Inteligentes
Implementación de la mejora REP-008 (Alertas Inteligentes), dentro de 4.2 Analítica Avanzada: el sistema deja de tener una sola alerta con todo cableado en el código y pasa a tener un motor de reglas donde el usuario define qué se vigila, con qué umbral, con qué severidad y por dónde se le avisa, con historial de cada alerta y de su atención.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-REP-008-01 | Reglas configurables: métrica + operador + umbral, sobre un catálogo cerrado de 10 métricas |
| RF-REP-008-02 | Emisión automática: scheduler cada 10 minutos, evaluación manual por regla y masiva |
| RF-REP-008-03 | Canales por alerta: notificación en el sistema y correo, entregados de forma independiente |
| RF-REP-008-04 | Historial: valor observado, umbral, canales entregados/fallidos y estado de atención |
🔒 Por qué un catálogo cerrado y no expresiones libres
El camino fácil habría sido guardar condiciones como expresiones evaluadas o SQL editable. Se descartó: una configuración que se ejecuta es un vector de ataque, y además produce reglas imposibles de validar en la interfaz.
En su lugar, cada regla es «métrica · operador · umbral» sobre un catálogo que vive en el backend. Al elegir la métrica, la UI ofrece solo los operadores que admite y pide únicamente sus parámetros. No se puede componer una regla que el servidor vaya a rechazar.
🧮 Las 10 métricas, alimentadas por lo que ya existe
Ninguna métrica reimplementa una consulta: cada una reutiliza el servicio que ya resuelve ese dato (REP-001, REP-005, REP-006, INV-002, INV-005, INV-006). Si la definición de «stock bajo» o de «consumo» cambia en su dominio, la alerta cambia con ella.
Con los datos reales del sistema: 12 unidades por vencer, 33 productos con stock bajo, 33 agotados, 3 en punto de reorden, $566.000 de inventario, 5 solicitudes pendientes, 3 estancadas, 172 productos sin movimiento y 20 conteos sin cerrar.
🚫 Lo que el motor se niega a hacer
Si una métrica no se puede resolver, el sistema no emite alerta: registra el motivo y
sigue. En la verificación real, desviacion_consumo no tenía período anterior comparable y el
motor lo declaró en lugar de devolver un cero que habría disparado una alerta falsa. Una alerta
inventada es peor que ninguna.
🔁 Anti-repetición
Sin ella, una condición que persiste generaría una alerta cada pasada y el historial se volvería ilegible. Cada regla tiene un cooldown por regla + entidad: dentro del plazo se cuenta la detección («detectada 3×») sin volver a avisar; pasado el plazo, si el problema sigue, vuelve a avisar — un problema no resuelto merece insistencia.
📡 Entrega desacoplada por canal
web (notificación persistida de REP-003 + emisión en vivo) y email (el servicio de correo de
REP-004). Cada canal se entrega de forma independiente: si el SMTP está caído, la notificación
en el sistema sale igual y el fallo queda registrado en canales_fallidos. Añadir WhatsApp o SMS
será añadir una estrategia, sin tocar el motor.
Y la alerta se registra aunque fallen todos los canales: el historial cuenta que la condición se cumplió, no que el correo salió.
🔗 INV-004 no se reescribe: se integra
La alerta de vencimiento ya existía. En lugar de tener dos motores en paralelo, el seeder declara
una regla del sistema sobre la métrica productos_por_vencer y el servicio de INV-004 sigue
siendo su proveedor. Así el historial de REP-008 cubre también esas alertas, y el cron de INV-004
se conserva sin tocar lo ya probado.
Junto a ella se siembran tres reglas más (stock bajo, reposición requerida, solicitudes estancadas). Son del sistema: no se eliminan, se desactivan.
✅ Verificación
Backend: tsc EXIT 0 · 416 pruebas en verde (48 nuevas) · migración 029 aplicada ·
npm run seed completo.
Contra la base real: 24 de 24 contrastes OK, ejercitando el motor a través del contenedor real de Nest. Las cuatro reglas sembradas dispararon, se creó una alerta por regla y se entregaron por web con su notificación persistida. Reevaluar de inmediato silencia en lugar de duplicar.
Frontend: tsc EXIT 0 · next lint sin warnings · 30 pruebas en verde (8 nuevas).
Un hallazgo que la verificación destapó
La primera pasada reportó el canal web como fallido. No era el motor: el gateway de
notificaciones tocaba this.server sin comprobar que estuviera inicializado, y fuera de un proceso
con WebSocket eso lanzaba. Se corrigió en dos niveles —el gateway omite la emisión en vivo sin
fallar, y el canal web se considera entregado por la persistencia de la notificación, no por el
emit— y la verificación pasó a reportar entregados=[web] fallidos=[]. La verificación contra
datos reales encontró un fallo que las pruebas unitarias no veían.
📚 Documentación
Requerimiento cubierto: REP-008 (Fase 3, Impacto Alto) — los 4 RF implementados y verificados.
