Documentación del Sistema

Appearance

Fase 1: MVP con Polling ​

← Índice General | Fase 2 SSE →

Objetivo de la Fase ​

Implementar el sistema de background jobs mínimo viable usando polling como mecanismo de actualización. El worker procesará jobs de forma asíncrona mientras el frontend consulta periódicamente el estado.

Entregables principales:

  • Infraestructura de base de datos (tablas, DTOs, models)
  • Job dispatcher y worker CLI con polling
  • HTTP endpoints para gestión de jobs
  • Integración con frontend React (hook con polling)
  • Testing integral end-to-end

Subfases ​

1.1 Infraestructura Base ​

Tareas: 4 tarjetas Estimación: 14 horas Objetivo: Crear migraciones, DTOs y models para background_jobs y notifications

Tareas principales:

  • Migración background_jobs (4h)
  • Migración notifications (3h)
  • DTOs BackgroundJob y Notification (3h)
  • Models BackgroundJobModel y NotificationModel (4h)

1.2 Job Dispatcher ​

Tareas: 5 tarjetas Estimación: 18 horas Objetivo: Implementar dispatcher, worker CLI, runner y handlers

Tareas principales:

  • JobDispatcher (4h)
  • Script CLI worker (3h)
  • JobRunner (4h)
  • JobHandlerInterface (2h)
  • BatchInvoicingJobHandler (5h)

Dependencias: Requiere completar Fase 1.1

1.3 HTTP Endpoints + Polling ​

Tareas: 5 tarjetas Estimación: 15 horas Objetivo: Exponer API REST y crear hook React con polling

Tareas principales:

  • JobController (4h)
  • Rutas /jobs (2h)
  • Hook useBackgroundJob frontend (4h)
  • Integración FacturacionBatchController (3h)
  • Feature flag enable_background_jobs (2h)

Dependencias: Requiere completar Fase 1.2

1.4 Testing Integral MVP ​

Tareas: 1 tarjeta Estimación: 8 horas Objetivo: Tests end-to-end, multi-tenancy, performance, concurrency

Tareas principales:

  • Tests end-to-end completos (8h)
    • Dispatch → worker → status actualizado
    • Multi-tenancy (schema isolation)
    • Performance (100 jobs paralelos)
    • Concurrency (race conditions)
    • Migrations (rollback)
    • Coverage >= 85%

Dependencias: Requiere completar Fases 1.1-1.3

Dependencias entre Subfases ​

1.1 Infraestructura
    ↓
1.2 Job Dispatcher
    ↓
1.3 HTTP Endpoints + Polling
    ↓
1.4 Testing Integral

Secuencia recomendada:

  1. Completar 1.1 completo
  2. Completar 1.2 completo
  3. Completar 1.3 completo
  4. Ejecutar 1.4 (validación integral)

Estimación Total de la Fase ​

Total de tarjetas: 15 tarjetas Total de horas: ~55 horas Duración estimada (1 dev full-time): 7 días laborables Duración estimada (1 dev part-time 50%): 14 días laborables

Criterios de Completitud ​

La Fase 1 se considera completa cuando:

  • [ ] Todas las migraciones ejecutadas y validadas
  • [ ] Worker CLI funcional con polling cada 5s
  • [ ] Al menos 1 handler implementado (BatchInvoicing)
  • [ ] API REST completa con auth JWT
  • [ ] Hook React useBackgroundJob con polling automático
  • [ ] Feature flag implementado y documentado
  • [ ] Tests end-to-end passing
  • [ ] Coverage >= 85%
  • [ ] Multi-tenancy validado (schemas no se interfieren)
  • [ ] Performance validada (100 jobs < 100s latencia)

Notas Técnicas ​

Arquitectura del Worker (Polling) ​

┌──────────────┐
│   Frontend   │ ──── HTTP GET /jobs/:id (cada 2s) ───┐
└──────────────┘                                       │
                                                       ▼
┌──────────────┐                              ┌─────────────┐
│ POST /jobs   │ ─────► JobDispatcher ──────► │ background_ │
│ (dispatch)   │         ↓ INSERT             │   jobs      │
└──────────────┘         schema=suc0001       │   table     │
                                              └─────────────┘
                                                       ▲
                                                       │
┌──────────────┐         SELECT pending       ┌───────┴─────┐
│ bin/worker   │ ◄────── (polling cada 5s) ───┤  JobRunner  │
│     CLI      │ ────────► UPDATE status      └─────────────┘
└──────────────┘           (completed/failed)

Multi-Tenancy ​

Cada job tiene columna schema para aislar por tenant:

  • Worker filtra: WHERE schema = :schema AND status = 'pending'
  • Frontend envía X-Schema header en requests
  • JobDispatcher valida schema contra JWT payload

Feature Flag ​

php
// constants.php
define('ENABLE_BACKGROUND_JOBS', getenv('ENABLE_BACKGROUND_JOBS') === 'true');

// FacturacionBatchController
if (ENABLE_BACKGROUND_JOBS) {
    $jobId = $jobDispatcher->dispatch(BatchInvoicingJobHandler::class, $payload, $schema);
    return new JsonResponse(['jobId' => $jobId]);
} else {
    exec('php bin/batch-invoicing.php ' . $payload);
}

← Índice General | Fase 2 SSE →