Documentación del Sistema

Appearance

Referencia de Código ​

◄ Anterior: Troubleshooting | Índice

Tabla de Contenidos ​

Archivos Clave ​

Value Objects ​

  • Core/ValueObjects/BackgroundJob.php
  • Core/ValueObjects/Notification.php
  • Core/ValueObjects/RetryResult.php

Interfaces ​

  • Core/Interfaces/JobHandlerInterface.php

Repositorios ​

  • Core/Repositories/JobRepository.php
  • Core/Repositories/NotificationRepository.php

Servicios ​

  • Core/Services/JobDispatcher.php
  • Core/Services/JobExecutor.php
  • Core/Services/JobHandlerRegistry.php
  • Core/Services/NotificationService.php
  • Core/Services/RetryStrategy.php
  • Core/Services/AlertService.php
  • Core/Services/HealthChecker.php
  • Core/Services/JobRetryService.php
  • Core/Services/AdminPermissionChecker.php

Controllers ​

  • Core/Controllers/JobController.php
  • Core/Controllers/JobStreamController.php
  • Core/Controllers/AdminJobController.php
  • Core/Controllers/MonitoringController.php

Handlers (Ejemplos) ​

  • Ventas/Handlers/BatchInvoicingJobHandler.php

Routes ​

  • Routes/Jobs/JobRoutes.php
  • Routes/Jobs/AdminJobRoutes.php

Middleware ​

  • Middleware/MetricsAuthMiddleware.php

Validators ​

  • Validators/Jobs/JobDispatchValidator.php

CLI ​

  • cli/background-worker.php
  • cli/bootstrap-cli.php
  • bin/ (scripts de mantenimiento)

Supervisor ​

  • supervisor/bautista-worker.conf.dist

Migraciones ​

  • migrations/migrations/system/ (3 archivos de migración)

Inyección de Dependencias ​

  • container/shared-definitions.php - Definiciones compartidas (JobExecutor, repositorios, etc.)
  • index.php - JobDispatcher registrado solo en contexto web

Tests ​

  • Tests/Unit/Core/JobDispatcherTest.php
  • Tests/Unit/Core/JobExecutorTest.php
  • Tests/Unit/Core/JobRepositoryTest.php
  • Tests/Integration/Core/BackgroundJobsFlowTest.php

Convenciones ​

Estados de Job ​

EstadoDescripciónTransiciones Permitidas
pendingJob creado o pendiente de reintento→ running
runningJob ejecutándose→ completed, pending (retry), failed
completedJob terminó exitosamente(final)
failedJob falló y agotó reintentos(final)

Reglas:

  • ✅ pending → running: Cuando worker inicia
  • ✅ running → completed: Cuando handler retorna sin exception
  • ✅ running → pending: Cuando handler lanza exception y retry_count < max_retries (self-dispatch retry)
  • ✅ running → failed: Cuando handler lanza exception y retry_count >= max_retries
  • ❌ completed → running: NUNCA (job no se re-ejecuta)
  • ❌ failed → pending: NUNCA (reintentos agotados; retry manual = crear nuevo job via admin endpoint)

Tipos de Notificación ​

TipoUsoColor UI
successJob completado exitosamenteVerde
errorJob fallóRojo
infoInformación general (ej: job iniciado)Azul

Convenciones de mensaje:

  • success: "Operación completada: {resumen del resultado}"
  • error: "Operación falló: {mensaje de error}"
  • info: "Operación iniciada: {descripción del job}"

Nomenclatura de Handlers ​

Patrón: {Module}{Operation}JobHandler

Ejemplos:

  • BatchInvoicingJobHandler - Facturación masiva
  • ReportGenerationJobHandler - Generación de reportes
  • DataImportJobHandler - Importación de datos
  • ExternalSyncJobHandler - Sincronización externa

Tipos de job (snake_case):

  • batch_invoicing
  • report_generation
  • data_import
  • external_sync

Logging ​

Formato structured logging:

php
$logger->info('Job dispatched', [
    'job_id' => $jobId,
    'job_type' => $type,
    'user_id' => $userId,
    'schema' => $schema,
]);

$logger->info('Job started', [
    'job_id' => $jobId,
    'job_type' => $job->type,
]);

$logger->info('Job completed', [
    'job_id' => $jobId,
    'job_type' => $job->type,
    'execution_time_seconds' => $job->getExecutionTime(),
]);

$logger->error('Job failed', [
    'job_id' => $jobId,
    'job_type' => $job->type,
    'error' => $job->error,
]);

Archivo de log: /logs/background-jobs.log

Log rotation:

bash
# /etc/logrotate.d/background-jobs
/var/log/background-jobs.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
}

Patterns Utilizados ​

Strategy Pattern ​

Uso: JobHandlerInterface

Permite agregar nuevos tipos de jobs sin modificar JobExecutor. Cada handler implementa la interface y se registra en el executor.

Beneficio: Open/Closed Principle - abierto a extensión, cerrado a modificación.

Repository Pattern ​

Uso: JobRepository, NotificationRepository

Abstrae el acceso a datos. Los servicios NO conocen detalles de SQL, solo operan con entidades.

Beneficio: Separación de concerns, fácil testing con mocks.

Value Objects ​

Uso: BackgroundJob, Notification

Entidades inmutables que representan conceptos de dominio con validación incorporada.

Beneficio: Type safety, domain model claro.

Wrapper Pattern ​

Uso: Handlers envuelven services existentes

Handler NO modifica service. Reconstruye DTOs y delega al service sin cambios.

Beneficio: CERO impacto en código legacy, rollback instantáneo con feature flag.

Referencias Externas ​

ADRs Relacionados ​

Documentación de Arquitectura ​

Documentación Externa ​

Comandos Útiles ​

Ejecutar Worker Manualmente ​

bash
php cli/background-worker.php {job_id}

Cleanup Jobs Antiguos ​

bash
php cli/cleanup-old-jobs.php

Cleanup Jobs Stale ​

bash
php cli/cleanup-stale-jobs.php

Verificar Jobs Pendientes ​

sql
SELECT COUNT(*) FROM background_jobs WHERE status = 'pending';

Verificar Jobs Running ​

sql
SELECT * FROM background_jobs WHERE status = 'running';

Verificar Notificaciones No Leídas ​

sql
SELECT COUNT(*) FROM notifications WHERE is_read = FALSE;

Feature Flags ​

Ubicación: container/shared-definitions.php (variables de entorno en .env)

php
return [
    'background_jobs' => [
        'enabled' => getenv('FEATURE_BACKGROUND_JOBS') === 'true',
        'max_pending_per_user' => (int) (getenv('MAX_PENDING_JOBS') ?: 10),
    ],
];

Variables de entorno:

  • FEATURE_BACKGROUND_JOBS: Activar/desactivar sistema (default: false)
  • MAX_PENDING_JOBS: Límite de jobs pendientes por usuario (default: 10)

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

◄ Anterior: Troubleshooting | Índice