Saltar al contenido principal

TEC-002 — Colas de Trabajo con BullMQ

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

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​

RFEntregable
RF-TEC-002-01Procesamiento asíncrono de las operaciones pesadas mediante colas
RF-TEC-002-02Gestión de las colas con BullMQ
RF-TEC-002-03Encolar la generación de reportes programados y el envío de notificaciones
RF-TEC-002-04Consultar el estado de los trabajos y reintentar los fallidos

⚙️ Arquitectura​

ColasService es una fachada con dos caminos:

  • BullMQ (si COLAS_ENABLED=true y 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.

ColaTrabajoProcesador
reportesgenerar-reporteGenera el archivo, registra el historial, envía el correo y actualiza la próxima ejecución
notificacionesentregar-notificacionEntrega 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/reintentar y POST /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. tsc y 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.