Reportes Programados

Los Reportes Programados son el mismo reporte que armás en Reportes, pero ejecutándose solo: cada lunes, cada día a las 8am, el primero del mes. Se generan en PDF o Excel, se envían por email o WhatsApp a la lista que definas y el historial de ejecuciones queda auditable.

Resumen ejecutivo

El cambio de juego: el reporte semanal de mantenimiento llega al buzón del gerente sin que nadie se acuerde de generarlo.

¿Para qué sirve?

• Reportes de mantenimiento recurrentes — semanal para gerencia, mensual para dirección.
• Facturas consolidadas para clientes de servicio de mantenimiento.
• Dashboards de KPIs que un supervisor imprime en las reuniones de lunes.
• Auditorías internas — snapshot mensual del estado de la planta para archivo compliance.

¿Cómo funciona?

flowchart LR
  S[Cloud Scheduler<br/>cada 15 min] --> C{Hay reporte<br/>due?}
  C -- sí --> G[Genera PDF/Excel<br/>con branding_id]
  G --> D{canal}
  D -- email --> E[Postmark SMTP]
  D -- whatsapp --> W[Evolution API]
  G --> H[Registrar<br/>ejecución]
  C -- no --> W1[esperar]

El job run-scheduled-reports (Cloud Scheduler cada 15 min) recorre la colección de reportes programados activos y evalúa si cada uno está due (según frecuencia + hora + día) y no corrió ya en ese período. Si sí, genera el archivo con la estructura definida, aplica el branding y lo entrega.

Cada ejecución deja registro en _scheduled_report_executions con:

• timestamp
• tamaño del archivo generado
• estado (ok / delivery_failed / generation_failed)
• destinatarios efectivos
• signed URL del PDF/Excel en GCS

Parámetros de configuración

¿Cómo usarlo?

Crear un reporte programado

1. Ir a Datos → Reportes Programados → Nuevo.
2. Ponerle nombre ("Mantenimiento semanal — Planta Norte").
3. Elegir la frecuencia (semanal, lunes a las 7am UTC = 4am CDMX).
4. Elegir el canal de entrega y seleccionar la cuenta/numero (cuenta verificada de email o número WhatsApp conectado).
5. Agregar los destinatarios (emails o teléfonos separados por coma).
6. Seleccionar el branding guardado (o dejar vacío para usar el default).
7. Definir la estructura del reporte — mismo editor de bloques que los reportes on-demand.
8. Guardar y activar.

El próximo lunes a las 7am UTC el sistema genera el PDF y lo manda.

Ejecutar manualmente (sin esperar)

Durante el setup es útil probar la ejecución antes de activar:

1. En el detalle del reporte programado, clic en Ejecutar ahora.
2. El job se dispara inmediatamente. El PDF/Excel se genera y se entrega a los destinatarios listados.
3. La ejecución queda registrada en el historial como triggered_by=manual.

Esto no altera el calendario de la próxima ejecución automática.

Endpoints REST

POST   /api/v1/scheduled-reports                   # crear
GET    /api/v1/scheduled-reports                   # listar
GET    /api/v1/scheduled-reports/{id}              # detalle
PATCH  /api/v1/scheduled-reports/{id}              # actualizar
DELETE /api/v1/scheduled-reports/{id}              # borrar
POST   /api/v1/scheduled-reports/{id}/execute      # ejecutar manualmente
GET    /api/v1/scheduled-reports/{id}/executions   # historial
GET    /api/v1/scheduled-reports/{id}/executions/{exec_id}  # ejecución específica

Casos de uso

1 · Reporte semanal de mantenimiento (planta manufacturera). Frecuencia weekly, lunes 7am UTC (4am local). PDF con 8 bloques: header con logo de la planta, tabla de tareas de la semana pasada, tabla de alarmas críticas, KPIs (disponibilidad, MTTR, MTBF). Destinatarios: 3 emails del equipo de dirección. Llega antes de que empiecen la reunión de lunes, sin trabajo humano.

2 · Reporte mensual para cliente externo (proveedor de servicio). Frecuencia monthly, día 5 a las 14:00 UTC. PDF con branding del cliente (logo + colores + footer "Confidencial"). Tabla de intervenciones del mes pasado con tiempos, técnico asignado y costo. El cliente recibe su reporte ejecutivo sin pedirlo. Se cobra el servicio el mismo día.

3 · Reporte diario de cumplimiento HACCP (food safety). Frecuencia daily, 6am UTC. Canal WhatsApp al grupo de supervisores. PDF compacto con las lecturas del día anterior: temperaturas de cámaras frías, alarmas de rango fuera, acciones correctivas pendientes. Cumple la obligación documental sin que nadie tenga que acordarse.

Limitaciones y supuestos

• Resolución mínima de ejecución: 15 minutos. Un reporte con hour=8 puede dispararse entre 08:00 y 08:15 UTC.
• day_of_month está limitado a 1-28. No hay soporte para "último día del mes"; si necesitás eso, programá el día 28 con una nota en el reporte.
• Si la cuenta de email o el número WhatsApp de entrega se desactiva, la ejecución falla silenciosa (queda en el historial como delivery_failed). El reporte no se reintenta automáticamente — hay que re-ejecutar manualmente tras arreglar la conexión.
• No hay ejecución condicional: el reporte se genera aunque no haya datos nuevos. Si querés ejecutar "solo si hay alarmas críticas este mes", eso es un agente de WhatsApp con una herramienta de generación de reportes, no un reporte programado.
• Los PDFs generados ocupan espacio en GCS. Los tenants con muchos reportes programados + muchas ejecuciones pueden acumular almacenamiento; la política de retención se configura per-tenant.

Beneficios clave

• Reportes recurrentes en 0 minutos humanos → liberás al coordinador de tareas repetitivas.
• Historial completo de ejecuciones para auditoría (qué se generó, cuándo, a quién, con qué tamaño).
• Branding corporativo aplicado consistente — cambia el logo en un lugar y todos los próximos reportes lo usan.
• Misma estructura de bloques que los reportes on-demand — no hay doble trabajo si ya tenías un template.
• Entrega confiable vía Postmark (email) o Evolution API (WhatsApp) — sin colas de salida que se saturen.