Documentación del Sistema

Appearance

Sistema de Background Jobs - Documentación Completa ​

Sistema: Background Jobs (Tareas en Segundo Plano) Estado: En Planificación (Fase 1 próxima) Fecha: 2026-02-05

Descripción ​

Sistema genérico para ejecutar operaciones de larga duración de forma asíncrona, liberando al usuario de esperar en el navegador. Implementa ejecución en background con notificaciones, consulta de estado y monitoreo.

Casos de uso:

  • Facturación masiva (500+ facturas, 3-10 minutos)
  • Reportes consolidados multi-schema (2-5 minutos)
  • Importación de datos CSV/Excel (5-15 minutos)
  • Sincronización AFIP (2-8 minutos)

Estructura de Documentación ​

📐 Arquitectura y Decisiones ​

architecture.md (649 líneas)

  • Problema arquitectural
  • Solución seleccionada: SSE + PostgreSQL NOTIFY
  • Roadmap de implementación (4 fases)
  • Escalabilidad y migración a RabbitMQ
  • Patrones utilizados

adrs/ (5 ADRs)

  • ADR-001: Ejecución con exec() + CLI Worker
  • ADR-002: Tablas por Schema Multi-Tenant
  • ADR-003: Polling → SSE Progresivo
  • ADR-004: Wrapper Pattern (NO Refactoring)
  • ADR-005: Schema Isolation en Background (CRÍTICO)

🔧 Implementación Técnica ​

backend/ (9 archivos, 3,325 líneas)

  • Arquitectura de componentes (Value Objects, Services, Handlers, Controllers)
  • Base de datos (tablas, índices, constraints)
  • API endpoints (POST /jobs, GET /jobs/{id}, SSE)
  • Handlers (implementación de nuevos jobs)
  • Multi-tenant (CRÍTICO) - Schema isolation
  • Testing (Unit + Integration)
  • Troubleshooting
  • Referencia de código

📋 Tareas de Implementación ​

kanban/ (14 archivos, 37 tarjetas)

  • Fase 1: MVP con Polling (15 tarjetas, 55h, 2 semanas)
  • Fase 2: SSE Real-Time (6 tarjetas, 21h, 1 semana)
  • Fase 3: Production Hardening (16 tarjetas, 48h, 1.5 semanas)

Tecnologías ​

Stack:

  • PHP 8.2+ con exec() para lanzar workers CLI
  • PostgreSQL (storage + NOTIFY para real-time)
  • Server-Sent Events (SSE) para notificaciones
  • React/TypeScript frontend

Dependencias: CERO externas (solo PHP + PostgreSQL)

Fases de Implementación ​

Fase 1: MVP con Polling (2 semanas) ​

  • Ejecución asíncrona con exec()
  • Tabla background_jobs + notifications
  • HTTP polling cada 2-5 segundos
  • Handlers: BatchInvoicingJobHandler

Fase 2: SSE Real-Time (1 semana) ​

  • PostgreSQL NOTIFY/LISTEN
  • SSE endpoint con EventSource
  • Latencia < 200ms
  • Progress tracking

Fase 3: Production Hardening (1.5 semanas) ​

  • Retry con exponential backoff
  • Monitoring y health checks
  • Systemd service
  • Cleanup automático

Fase 4: Escalar con RabbitMQ (Futuro) ​

  • Cuando volumen > 500 jobs/día
  • Worker pool distribuido
  • Priority queues
  • Dead letter queue
TemaArchivo
¿Por qué esta solución?architecture.md
¿Cómo implementar?backend/README.md
¿Qué tareas hacer?kanban/README.md
¿Qué decidimos?adrs/README.md
¿Cómo testear multi-tenant?backend/05-multi-tenant.md
¿Problemas comunes?backend/07-troubleshooting.md

Métricas ​

Total documentación: 5,237 líneas

  • Arquitectura: 649 líneas
  • ADRs: 39.7 KB (5 decisiones)
  • Backend: 3,325 líneas (9 archivos)
  • Kanban: 37 tarjetas (124h estimadas)

Complejidad: Media Time to Market: 4-5 semanas Costo Infraestructura: $0/mes

Siguientes Pasos ​

  1. ✅ Documentación completa
  2. ⏳ Revisión y aprobación de arquitectura
  3. ⏳ Iniciar Fase 1.1: Infraestructura base
  4. ⏳ Seguir kanban/fase-1-mvp/

Última actualización: 2026-02-05