TEC-002 — Colas de Trabajo con BullMQ
Implementación de la mejora TEC-002 (Colas de Trabajo), dentro de 6.1 Rendimiento y Escalabilidad. Las dos operaciones más pesadas del módulo dejan de ejecutarse en línea y pasan a procesarse en segundo plano, con visibilidad y reintentos.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-TEC-002-01 | Procesamiento asíncrono de las operaciones pesadas mediante colas |
| RF-TEC-002-02 | Gestión de las colas con BullMQ |
| RF-TEC-002-03 | Encolar la generación de reportes programados y el envío de notificaciones |
| RF-TEC-002-04 | Consultar el estado de los trabajos y reintentar los fallidos |
⚙️ Arquitectura
ColasService es una fachada con dos caminos:
- BullMQ (si
COLAS_ENABLED=truey Redis disponible): el trabajo se publica en la cola y se procesa en segundo plano. - Ejecución en línea: si las colas no están disponibles, se ejecuta el respaldo que pasa el dominio, con la misma lógica que el procesador. Sin Redis, el trabajo se hace igual; solo deja de ser asíncrono.
Los procesadores viven en su dominio (reportes), no en el módulo de colas: common
aporta la infraestructura y la API, y los dominios dependen de él.
| Cola | Trabajo | Procesador |
|---|---|---|
reportes | generar-reporte | Genera el archivo, registra el historial, envía el correo y actualiza la próxima ejecución |
notificaciones | entregar-notificacion | Entrega la alerta por sus canales y graba el resultado en la alerta |
🔄 Reintentos
Cada trabajo reintenta hasta 3 veces con backoff exponencial (5 s base) y, además, se puede reintentar a mano desde la API o desde la página de trabajos.
🔍 Panel de trabajos
- API (Administrador):
GET /api/colas/estado,GET /api/colas/trabajos,GET /api/colas/trabajos/:cola/:id,POST /api/colas/trabajos/:cola/:id/reintentaryPOST /api/colas/reintentar-fallidos. - Página
/trabajos: estado de las colas por estado, tabla de trabajos con filtros y botón de reintento. Si las colas no están disponibles, lo declara en lugar de fallar.
⚙️ Configuración
COLAS_ENABLED=true # requiere Redis
BULL_PREFIX=ccf
BULL_INTENTOS=3
BULL_BACKOFF_MS=5000
BULL_REMOVE_ON_COMPLETE=1000
BULL_REMOVE_ON_FAIL=5000
La conexión reutiliza REDIS_URL / REDIS_HOST / REDIS_PORT / REDIS_PASSWORD /
REDIS_DB de TEC-001. COLAS_ENABLED es false por defecto: sin Redis, todo se
ejecuta en línea y la aplicación arranca sin infraestructura.
✅ Verificación
- 435 pruebas en 44 suites, 0 fallos en la API; 33 pruebas en 8 suites, 0 fallos en
el frontend.
tscy ESLint limpios en lo añadido. - Pruebas nuevas: configuración, fachada de colas (encolado, degradación, consulta, reintento), ambos procesadores, el cableado de alertas y una prueba de integración de DI del módulo en modo degradado.
- Página de trabajos con pruebas de render (datos, modo degradado y error).
Nota: se usó bullmq v4 porque v5/v6 exigen redis>=5 como peer opcional y el
proyecto usa redis@4.7.1 (TEC-001). @nestjs/bullmq se fijó en v11 (CommonJS), ya que la
v12 es ESM-only y rompe el transform de Jest y el require de un proyecto CJS.
