Scheduler y batch

Objetivo

Documentar qué ejecuta sy-energy de forma automática, en qué orden, a qué hora y dónde deja su salida.

Audiencia

Soporte, infraestructura y desarrollo interno.

Estado documental

• Estado: Borrador
• Última actualización: 2026-08-02
• Owner: Pendiente
• SME requerido: soporte técnico / DevOps
• Fuente resumida: definición del scheduler en el código y configuración de cron del servidor.

Resumen operativo

sy-energy no usa cron directamente para cada tarea. El servidor ejecuta un solo cron cada minuto que llama al scheduler de Laravel, y el scheduler decide qué toca correr:

cron (cada minuto)  ──►  php artisan schedule:run  ──►  tareas del día

Esto tiene una consecuencia importante para el diagnóstico: si el cron se detiene, ninguna tarea automática corre y no hay error visible en la aplicación. Antes de investigar por qué falló una tarea concreta, verificar que el cron esté activo.

El cron vive en el repositorio server-configs, no en sy-energy. Hay una entrada por cada instancia de participante.

Tareas programadas

Todas en zona horaria America/Mexico_City.

Hora	Comando	Para qué	Log
05:00	queue:retry all	Reintenta los trabajos fallidos acumulados antes de arrancar la cadena del día.	ecd-sync.log
05:05	ecd:sync <fecha>	Descarga los Estados de Cuenta Diarios de CENACE.	ecd-sync.log
05:30	ecd:create_invoices	Crea los CFDI pendientes vía Factura.com.	cenace-process.log
05:45	ecd:upload_invoices_to_s3	Sube a S3 las facturas creadas hoy.	cenace-process.log
06:00	service:demand-sync	Sincroniza la demanda de los centros de carga.	service-process.log
06:45	ecd:upload_invoices	Encola la carga de las facturas al SIM.	cenace-process.log
Lunes 07:00	bot:queue --slug=bank-one	Primera etapa de referencia bancaria (FOP).	Sin log dedicado
08:15	ecd:invoices_status	Consulta en el SIM el estatus de las facturas cargadas.	cenace-process.log
08:30	bot:queue --slug=rea	Dispara el bot que descarga la REA.	cenace-process.log

Los logs viven en el directorio storage/logs de la instancia.

El desfase de 5 días en ecd:sync

La tarea de las 05:05 no sincroniza el día anterior: pide el ECD de hace 5 días.

No es un error de configuración. CENACE no publica el ECD de inmediato, y el desfase da margen para que el documento esté disponible.

Consecuencias prácticas:

• Un ECD faltante de ayer es normal; uno faltante de hace una semana no lo es.
• Al reprocesar manualmente, la fecha a usar es la fecha de operación, no la del día en que se ejecuta el comando.
• Un hueco en la publicación de CENACE se vuelve visible 5 días después.

Encadenamiento

Las tareas están espaciadas porque dependen unas de otras:

05:05  ecd:sync                  descarga el ECD
  │                              ↓ deja documentos pendientes de facturar
05:30  ecd:create_invoices       crea los CFDI
  │                              ↓ deja facturas creadas
05:45  ecd:upload_invoices_to_s3 las deposita en S3
  │                              ↓ archivos disponibles para el bot
06:45  ecd:upload_invoices       encola la carga al SIM
  │                              ↓ el bot sube y responde
08:15  ecd:invoices_status       verifica el resultado en el SIM

El margen entre tareas es el tiempo estimado para que los workers terminen la etapa previa. Si una etapa se retrasa, la siguiente corre igual y procesa menos elementos de los esperados — no falla, simplemente hace menos trabajo.

Por eso, cuando faltan facturas al final del día, la causa suele estar en una etapa anterior que no alcanzó a terminar, no en la última que corrió.

Ventana crítica

Entre las 05:00 y las 08:30 corre la cadena completa. En esa franja hay que evitar:

• despliegues;
• reinicio de workers de Supervisor;
• mantenimiento de base de datos;
• ejecución manual de los mismos comandos, por riesgo de procesamiento duplicado.

Qué revisar cada mañana

Ver el runbook de operación diaria para el procedimiento completo. En corto:

1. El cron del servidor está activo.
2. Los workers de Supervisor están arriba.
3. Los logs del día no reportan errores.
4. queue:failed no muestra acumulación de trabajos fallidos.

Batch fuera del scheduler

El scheduler cubre lo diario y lo semanal. Estos procesos no están programados y se ejecutan a mano:

Proceso	Cuándo
Ciclo mensual de facturación	Día 1 y día 4 de cada mes. Ver Ciclo mensual de facturación.
Recálculos de pass-through	Bajo demanda, ante correcciones o reliquidaciones.
Reproceso de un ECD puntual	Bajo demanda, cuando CENACE republica un documento.

Riesgos y gaps

• No hay alerta documentada cuando una tarea programada no corre o falla. Hoy la detección depende de revisar logs.
• bot:queue --slug=bank-one no escribe en un log dedicado, lo que dificulta verificar si corrió.
• Los tiempos entre tareas son fijos y no se ajustan al volumen del día; no está documentado qué pasa cuando una etapa tarda más que su ventana.
• Falta confirmar si el scheduler corre con los mismos horarios en todas las instancias de participante.

Próxima revisión

Tras la validación de soporte sobre alertamiento y tiempos reales de cada etapa.