Documentación del Sistema

Appearance

Background Jobs - Documentación Técnica Backend ​

Conceptual Foundation: Para entender los CONCEPTOS de background job processing y las decisiones arquitecturales, consulte Architecture: Background Jobs.

Descripción General ​

El Sistema de Tareas en Segundo Plano proporciona una infraestructura genérica para ejecutar operaciones de larga duración de forma asíncrona, liberando al usuario de esperar en el navegador y mejorando la experiencia de usuario para procesos pesados.

Propósito del Sistema ​

  • Ejecución asíncrona: Permitir que operaciones largas (> 30 segundos) se ejecuten en background
  • No bloqueo del navegador: Usuario recibe respuesta inmediata 202 Accepted
  • Notificaciones: Sistema notifica al usuario cuando el job termina (success/error)
  • Monitoreo: Usuarios pueden consultar el estado de sus jobs en progreso
  • Escalabilidad: Infraestructura preparada para evolucionar a sistemas de colas más robustos

Casos de Uso ​

  • Facturación masiva: Generar cientos de facturas en lote
  • Reportes pesados: Consolidación multi-schema con miles de registros
  • Importación de datos: Procesar archivos CSV/Excel grandes
  • Sincronización externa: Integración con APIs lentas (AFIP, bancos)
  • Operaciones masivas: Actualización/eliminación de múltiples registros
  • Generación de PDFs: Informes complejos con procesamiento pesado

Índice de Documentación ​

1. Arquitectura de Componentes ​

Estructura completa del sistema: Value Objects, Repositorios, Servicios, Handlers, Controllers, y CLI Workers. Describe la implementación de cada componente con sus responsabilidades, métodos principales y flujos de ejecución.

2. Base de Datos ​

Estructura de tablas PostgreSQL (background_jobs, notifications), índices, constraints, y función NOTIFY para SSE (Fase 2). Incluye justificación de multi-tenancy a nivel sucursal.

3. API Endpoints ​

Especificación completa de endpoints HTTP: despacho de jobs (POST), consulta de estado (GET), streaming SSE (Fase 2), y notificaciones. Incluye ejemplos de request/response, códigos de error y uso con curl/JavaScript.

4. Handlers: Implementación de Nuevos Jobs ​

Guía completa para agregar nuevos tipos de jobs: interface JobHandlerInterface, patrón wrapper, ejemplo completo de BatchInvoicingJobHandler, y guía paso a paso para registrar handlers personalizados.

5. Multi-Tenant (CRÍTICO) ​

CRÍTICO: Aislamiento por schema PostgreSQL. Flujo completo de propagación de schema desde frontend hasta worker CLI, configuración de ConnectionManager, testing de aislamiento, y troubleshooting de isolation issues.

6. Testing ​

Estrategia de testing completa: Unit tests con mocks (JobDispatcherTest, JobExecutorTest, HandlerTest), Integration tests con BD real (flujo end-to-end, multi-tenant isolation, error handling), y cobertura esperada.

7. Troubleshooting ​

Guía de diagnóstico y solución de problemas comunes: jobs stuck in "running", notificaciones que no llegan, multi-tenant isolation issues, performance degradation, worker crashes, y DOS protection.

8. Referencia de Código ​

Listado completo de archivos clave del sistema: ubicación de Value Objects, Interfaces, Repositorios, Servicios, Controllers, Handlers, Routes, CLI scripts, Migraciones, Configuración, Tests, y convenciones de nomenclatura.

Integración con Arquitectura Existente ​

5-Layer Architecture:

Routes + Validators → Controller → Service → [Background Job] → Handler → Service → Model → DB
                                        ↓
                                   CLI Worker

Patrón Wrapper:

  • Los handlers NO refactorizan servicios existentes
  • Los handlers envuelven (wrap) servicios existentes
  • Los handlers reconstruyen el request DTO y delegan al service original
  • CERO impacto en código legacy: se mantiene intacto

Fases de Implementación ​

Fase 1: MVP con Polling (ACTUAL) ​

  • ✅ exec() para lanzar workers
  • ✅ Polling HTTP para consultar estado
  • ✅ Notificaciones en BD
  • Simple, CERO dependencias externas

Fase 2: Real-Time con SSE + PostgreSQL NOTIFY ​

  • ✅ SSE para notificaciones en tiempo real
  • ✅ PostgreSQL NOTIFY trigger
  • ✅ Latencia mínima (~50-200ms)

Fase 3: Production Hardening ​

  • Worker pool (long-running processes)
  • Retry automático con exponential backoff
  • Metrics y monitoring

Fase 4: Scale con RabbitMQ (Opcional) ​

  • RabbitMQ para queue management
  • Workers distribuidos
  • Priority queues y delayed jobs

Referencias ​

ADRs Relacionados:

Documentación de Arquitectura:

Documentación Técnica:

Última Actualización: 2026-02-05 Versión: 1.0 (Fase 1 - MVP con Polling)