Documentación del Sistema

Appearance

Kanban: Sistema Background Jobs - Bautista ​

Total de tareas: 37 tarjetas Estimación total: ~124 horas (~15.5 días full-time / ~31 días part-time 50%)

Progress Tracker ​

Fase 1: MVP con Polling          [░░░░░░░░░░] 0/15 tareas (55h)
Fase 2: Real-Time con SSE        [░░░░░░░░░░] 0/6 tareas  (21h)
Fase 3: Production Hardening     [░░░░░░░░░░] 0/16 tareas (48h)
                                 ─────────────────────────
                                  0/37 tareas (124h)

Índice de Fases ​

Fase 1: MVP con Polling ​

Tareas: 15 tarjetas | Estimación: 55 horas | Duración: 7 días full-time

Sistema mínimo viable con worker polling, endpoints HTTP y hook React con actualización periódica.

Subfases:

Entregables principales:

  • Migraciones background_jobs y notifications
  • JobDispatcher y JobRunner
  • Worker CLI con polling
  • API REST (/jobs)
  • Hook useBackgroundJob (polling cada 2s)
  • BatchInvoicingJobHandler
  • Feature flag ENABLE_BACKGROUND_JOBS
  • Tests end-to-end >= 85% coverage

Fase 2: Real-Time con SSE ​

Tareas: 6 tarjetas | Estimación: 21 horas | Duración: 2.5-3 días full-time

Reemplazar polling con Server-Sent Events (SSE) para actualizaciones instantáneas usando PostgreSQL NOTIFY.

Subfases:

Entregables principales:

  • JobStreamController (SSE endpoint)
  • PostgreSQL NOTIFY en worker
  • Hook useJobStream con EventSource
  • Fallback a polling si SSE no disponible
  • Columna progress (0-100%)
  • Componente JobProgressBar
  • NOTIFY con progress updates

Fase 3: Production Hardening ​

Tareas: 16 tarjetas | Estimación: 48 horas | Duración: 6-7 días full-time

Preparación para producción: retry, monitoring, health checks, systemd y documentación completa.

Subfases:

Entregables principales:

  • Retry logic con exponential backoff
  • Cronjob cleanup stale jobs
  • Admin endpoints (/admin/jobs/failed)
  • Metrics endpoint (Prometheus format)
  • Health check endpoint
  • Logging estructurado JSON
  • Alert triggers (Slack/email)
  • Systemd service con auto-restart
  • CLAUDE.md actualizado
  • Documentación técnica completa
  • OpenAPI spec actualizado
  • CHANGELOG actualizado

Roadmap Visual ​

┌─────────────────────────────────────────────────────────────────┐
│                        FASE 1: MVP (59h)                        │
├─────────────────────────────────────────────────────────────────┤
│ 1.1 Infraestructura (14h)                                       │
│   ├─ Migración background_jobs                                  │
│   ├─ Migración notifications                                    │
│   ├─ DTOs                                                       │
│   └─ Models                                                     │
├─────────────────────────────────────────────────────────────────┤
│ 1.2 Job Dispatcher (18h)                                        │
│   ├─ JobDispatcher                                              │
│   ├─ Worker CLI (polling cada 5s)                               │
│   ├─ JobRunner                                                  │
│   ├─ JobHandlerInterface                                        │
│   └─ BatchInvoicingJobHandler                                   │
├─────────────────────────────────────────────────────────────────┤
│ 1.3 HTTP Endpoints (15h)                                        │
│   ├─ JobController                                              │
│   ├─ Rutas /jobs                                                │
│   ├─ useBackgroundJob (polling cada 2s)                         │
│   ├─ Integración FacturacionBatch                               │
│   └─ Feature flag                                               │
├─────────────────────────────────────────────────────────────────┤
│ 1.4 Testing Integral (8h)                                       │
│   └─ End-to-end, multi-tenancy, performance, concurrency        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     FASE 2: Real-Time (21h)                     │
├─────────────────────────────────────────────────────────────────┤
│ 2.1 SSE Endpoint (13h)                                          │
│   ├─ JobStreamController                                        │
│   ├─ PostgreSQL NOTIFY en worker                                │
│   └─ useJobStream (EventSource)                                 │
├─────────────────────────────────────────────────────────────────┤
│ 2.2 Progress Tracking (8h)                                      │
│   ├─ Columna progress                                           │
│   ├─ JobRunner actualiza progress                               │
│   └─ JobProgressBar UI                                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   FASE 3: Production (48h)                      │
├─────────────────────────────────────────────────────────────────┤
│ 3.1 Retry + Error Handling (14h)                                │
│   ├─ Columnas retry                                             │
│   ├─ Exponential backoff                                        │
│   ├─ Cleanup stale jobs                                         │
│   └─ Admin endpoints                                            │
├─────────────────────────────────────────────────────────────────┤
│ 3.2 Monitoring (14h)                                            │
│   ├─ Metrics (Prometheus)                                       │
│   ├─ Health checks                                              │
│   ├─ Logging estructurado                                       │
│   └─ Alert triggers                                             │
├─────────────────────────────────────────────────────────────────┤
│ 3.3 Systemd Service (5h)                                        │
│   ├─ Service file                                               │
│   ├─ Auto-restart                                               │
│   └─ Journalctl logs                                            │
├─────────────────────────────────────────────────────────────────┤
│ 3.4 Documentación (15h)                                         │
│   ├─ server/CLAUDE.md                                           │
│   ├─ docs/backend/background-jobs-system.md                     │
│   ├─ docs/architecture/background-jobs-architecture.md          │
│   ├─ OpenAPI                                                    │
│   └─ CHANGELOG                                                  │
└─────────────────────────────────────────────────────────────────┘

Estimaciones por Fase ​

FaseTareasHorasFull-timePart-time 50%
Fase 1: MVP con Polling1555h7 días14 días
Fase 2: Real-Time SSE621h2.5-3 días5-6 días
Fase 3: Production1648h6-7 días12-14 días
TOTAL37124h~15.5 días~31 días

Dependencias Críticas ​

Secuencia de Fases ​

Fase 1 completa
    ↓
Fase 2 completa
    ↓
Fase 3 completa

No se puede empezar Fase 2 sin completar Fase 1.No se puede empezar Fase 3 sin completar Fase 2.

Hitos de Validación ​

Hito 1 (post Fase 1):

  • [ ] Worker procesa jobs con polling
  • [ ] Frontend actualiza status cada 2s
  • [ ] Multi-tenancy validado
  • [ ] Tests >= 85% coverage

Hito 2 (post Fase 2):

  • [ ] SSE funciona con eventos en tiempo real
  • [ ] Fallback a polling si SSE falla
  • [ ] Progress bar actualiza 0-100%
  • [ ] Backward compatible con Fase 1

Hito 3 (post Fase 3):

  • [ ] Retry logic funciona con exponential backoff
  • [ ] Metrics endpoint retorna Prometheus format
  • [ ] Systemd service instalado y running
  • [ ] Documentación completa y revisada
  • [ ] Sistema production-ready

Criterios de Aceptación Global ​

El sistema completo se considera production-ready cuando:

Funcional ​

  • [ ] Jobs se dispatchen exitosamente
  • [ ] Worker procese jobs asíncronamente
  • [ ] Frontend reciba actualizaciones en tiempo real (SSE)
  • [ ] Progress tracking funcione 0-100%
  • [ ] Retry logic maneje fallos automáticamente
  • [ ] Failed jobs sean manejables desde admin UI

No Funcional ​

  • [ ] Multi-tenancy garantizado (schema isolation)
  • [ ] Performance: 100 jobs < 100s latencia total
  • [ ] Coverage tests >= 85%
  • [ ] Logs estructurados en JSON
  • [ ] Metrics disponibles para Prometheus
  • [ ] Health checks retornen status correcto
  • [ ] Systemd auto-restart funcione

Operacional ​

  • [ ] Systemd service habilitado e iniciado
  • [ ] Cleanup cronjob configurado
  • [ ] Alert triggers configurados
  • [ ] Documentación completa y sin dead links
  • [ ] OpenAPI spec actualizado
  • [ ] CHANGELOG actualizado con nueva versión

Notas Generales ​

Branch Naming Convention ​

  • feature/background-jobs-* - Features nuevas
  • test/background-jobs-* - Tests
  • docs/background-jobs-* - Documentación
  • Máximo 40 caracteres en branch name

Testing Strategy ​

  • Unit Tests: Mock dependencies (DB, services)
  • Integration Tests: Real PostgreSQL con migrations auto
  • End-to-End Tests: Completo dispatch → execution → status
  • Load Tests: 100+ concurrent jobs
  • Multi-Tenancy Tests: Schema isolation verificado

Deliverables Comunes ​

Cada tarjeta debe incluir:

  • [ ] Code implementation
  • [ ] Unit tests
  • [ ] Integration tests (si aplica)
  • [ ] Documentation / PHPDoc
  • [ ] No breaking changes (verificado)

Última actualización: 2025-02-05 Documento origen: /var/www/Bautista/docs/ai-work/kanban-background-jobs.md