Documentación del Sistema

Appearance

Fase 1.3: HTTP Endpoints + Polling ​

← Anterior: 1.2 Dispatcher | Siguiente: 1.4 Testing →

Crear JobController ​

Archivo: */backend/background-jobs-system.md

Rama: feature/background-jobs-api

Fase: 1.3: HTTP Endpoints + Polling

Estimación: 4 horas

Dependencias: Crear clase JobDispatcher, Crear Models

Deliverables ​

  • [ ] Crear server/src/controller/modulo-background-jobs/JobController.php
    • [ ] POST /jobs (dispatch) → JobDispatcher
    • [ ] GET /jobs/:id (status) → BackgroundJobModel
    • [ ] GET /jobs?status=pending (list)
    • [ ] Request/Response DTOs
    • [ ] Auth middleware (JWT)
    • [ ] Schema validation
  • [ ] Exception handling y HTTP error codes
  • [ ] PHPDoc con ejemplos
  • [ ] Unit tests

Crear rutas /jobs en routes ​

Archivo: */backend/background-jobs-system.md

Rama: feature/background-jobs-api

Fase: 1.3: HTTP Endpoints + Polling

Estimación: 2 horas

Dependencias: Crear JobController

Deliverables ​

  • [ ] Crear server/src/Routes/BackgroundJobs/jobs.php
    • [ ] POST /jobs (validator middleware)
    • [ ] GET /jobs/:id
    • [ ] GET /jobs (query filters)
    • [ ] Middleware chain: auth, schema validation
  • [ ] Validadores Zod equivalentes
  • [ ] Tests de rutas

Frontend: Crear hook useBackgroundJob ​

Archivo: */frontend/background-jobs-system.md

Rama: feature/background-jobs-frontend

Fase: 1.3: HTTP Endpoints + Polling

Estimación: 4 horas

Dependencias: Crear rutas /jobs

Deliverables ​

  • [ ] Crear public/src/backgroundJobs/hooks/useBackgroundJob.ts
    • [ ] Polling automático cada 2 segundos
    • [ ] useQuery con retry exponencial
    • [ ] Estados: idle, dispatching, pending, completed, failed
    • [ ] Métodos: dispatch(handler, payload), cancel(), getStatus()
    • [ ] useEffect cleanup para detener polling
  • [ ] Tipos TypeScript completos
  • [ ] Tests unitarios con mock API
  • [ ] Tests de polling (falsos timers)

Integrar FacturacionBatchController con JobDispatcher ​

Archivo: */backend/background-jobs-system.md

Rama: feature/background-jobs-integration

Fase: 1.3: HTTP Endpoints + Polling

Estimación: 3 horas

Dependencias: Crear BatchInvoicingJobHandler, Crear JobController

Deliverables ​

  • [ ] Modificar server/src/controller/modulo-ventas/FacturacionBatchController.php
    • [ ] Reemplazar exec() con JobDispatcher->dispatch()
    • [ ] Retorna jobId en respuesta
    • [ ] Mantiene compatibilidad (retorna mismo schema)
  • [ ] Tests verificando que dispatch ocurre
  • [ ] Tests verificando que resultado es mismo
  • [ ] Documentar cambio (no breaking change)

Agregar feature flag enable_background_jobs ​

Archivo: */backend/background-jobs-system.md

Rama: feature/background-jobs-integration

Fase: 1.3: HTTP Endpoints + Polling

Estimación: 2 horas

Dependencias: Integrar FacturacionBatchController

Deliverables ​

  • [ ] Agregar ENABLE_BACKGROUND_JOBS = true en server/src/config/constants.php
  • [ ] Condicional en FacturacionBatchController: if flag → JobDispatcher, else → exec()
  • [ ] Agregar variable de entorno .env.example
  • [ ] Tests verificando ambos paths
  • [ ] Documentar en CLAUDE.md

← Anterior: 1.2 Dispatcher | Siguiente: 1.4 Testing →