Programacion y Reportes

Configura reportes programados de mantenimiento, integra con Cloud Scheduler y gestiona pausas de planes con registro de auditoria.

Reportes programados

Puedes configurar reportes automaticos que se generan y entregan periodicamente con informacion de tus planes de mantenimiento.

Crear un reporte programado

Ve a Mantenimiento > Reportes Programados.
Haz clic en Nuevo Reporte.
Configura los parametros:

Campo	Requerido	Descripcion
Nombre	Si	Nombre descriptivo del reporte (max 200 caracteres)
Frecuencia	Si	daily, weekly o monthly
Formato	No	PDF (default) o Excel
Canal de entrega	No	email (default) o whatsapp
Destinatarios	No	Lista de emails o numeros de telefono
Hora	No	Hora UTC de ejecucion (0-23, default: 8)
Dia de la semana	No	Solo para frecuencia weekly (0=lunes a 6=domingo)
Dia del mes	No	Solo para frecuencia monthly (1-28)
Habilitado	No	Activa o desactiva el reporte

Frecuencias disponibles

Frecuencia	Ejecucion
daily	Todos los dias a la hora configurada
weekly	El dia de la semana configurado a la hora configurada
monthly	El dia del mes configurado a la hora configurada

La hora de ejecucion esta en UTC. Ajusta segun tu zona horaria local.

Presets de branding

Los reportes programados pueden usar un preset de branding guardado para mantener una identidad visual consistente:

Campo del branding	Descripcion
company_name	Nombre de la empresa en el encabezado
logo_url	URL del logo (PNG/JPG)
header_lines	Lineas adicionales en el encabezado (division, telefono, etc.)
header_bg_color	Color de fondo del encabezado (hex, ej: #003366)
footer_text	Texto del pie de pagina
accent_color	Color de acento para tablas y elementos destacados
font_family	Familia de fuente: Courier, Helvetica o Times

Para vincular un branding a un reporte programado, usa el campo branding_id:

{
  "name": "Reporte Semanal de Mantenimiento",
  "frequency": "weekly",
  "format": "pdf",
  "branding_id": "branding_abc123",
  "day_of_week": 0,
  "hour": 8
}

El branding se resuelve en cada ejecucion del reporte. Si actualizas el preset de branding, los reportes futuros reflejaran los cambios automaticamente.

Integracion con Cloud Scheduler

Los reportes programados se ejecutan a traves de un endpoint interno invocado por Google Cloud Scheduler:

POST /internal/run-scheduled-reports

Flujo de ejecucion

Cloud Scheduler invoca el endpoint a intervalos regulares.
El sistema revisa todos los reportes habilitados de todos los tenants.
Para cada reporte, verifica si es el momento de ejecutarlo segun su frecuencia y hora configurada.
Genera el reporte en el formato especificado (PDF o Excel).
Entrega el reporte al canal configurado (email o WhatsApp).
Actualiza last_run_at y calcula next_run_at.

Seguridad del endpoint

El endpoint interno esta protegido por:

HMAC Secret — El header X-Scheduler-Secret debe coincidir con el secreto configurado.
Sin JWT — No requiere autenticacion de usuario, solo el secreto del scheduler.

El endpoint interno no es accesible para usuarios finales. Solo debe ser invocado por Cloud Scheduler con el secreto correcto.

Pausar y reanudar planes

Puedes pausar temporalmente un plan de mantenimiento sin eliminarlo. La pausa deshabilita la ejecucion automatica y registra la accion en el trail de auditoria.

Pausar un plan

Selecciona el plan desde Mantenimiento > Planes.
Haz clic en Pausar.
Opcionalmente, ingresa un motivo (max 500 caracteres).

Al pausar un plan:

Accion	Detalle
`paused` se establece en `true`	Marca el plan como pausado
`enabled` se establece en `false`	Previene la ejecucion automatica
`paused_at` se registra	Timestamp de cuando se pauso
`paused_by` se registra	ID del usuario que pauso
`pause_reason` se almacena	Motivo opcional proporcionado
Entrada de auditoria creada	Se registra la accion "pause" con el motivo

Reanudar un plan

Selecciona el plan pausado.
Haz clic en Reanudar.

Al reanudar un plan:

Accion	Detalle
`paused` se establece en `false`	Desmarca la pausa
`enabled` se establece en `true`	Reactiva la ejecucion automatica
`next_due_at` se recalcula	La proxima ejecucion se calcula desde ahora, no desde la fecha original
Campos de pausa se limpian	`paused_at`, `paused_by`, `pause_reason` se eliminan
Entrada de auditoria creada	Se registra la accion "resume"

Al reanudar un plan, la proxima fecha de ejecucion se recalcula desde el momento actual. El tiempo que el plan estuvo pausado no cuenta como tiempo transcurrido.

Trail de auditoria

Todas las acciones de pausa y reanudacion quedan registradas en el trail de auditoria inmutable:

{
  "action": "pause",
  "resource_type": "maintenance_plan",
  "resource_id": "plan_abc123",
  "actor": "user_xyz",
  "actor_type": "user",
  "details": { "reason": "Equipo en reparacion mayor" },
  "timestamp": "2026-03-25T10:30:00Z"
}

Esto permite rastrear quien pauso o reanudo un plan, cuando y por que.

Proteccion de idempotencia

El sistema incluye multiples mecanismos para garantizar que los planes no se ejecuten de forma duplicada:

Mecanismo	Descripcion
Claim atomico	Antes de ejecutar un plan, avanza `next_due_at` al futuro atomicamente. Si otra instancia ya lo reclamo, se salta
Rollback en fallo	Si la ejecucion falla, se revierte `next_due_at` al valor original para reintentar en el proximo ciclo
Semaforo de concurrencia	Maximo 5 tenants procesados en paralelo para evitar sobrecarga
HMAC del scheduler	El endpoint interno solo acepta requests con el secreto correcto

En entornos con multiples instancias del servicio, el claim atomico garantiza que cada plan se ejecute exactamente una vez por ciclo.

Ejecucion manual de reportes

Ademas de la ejecucion automatica, puedes generar cualquier reporte programado inmediatamente:

Ve a Mantenimiento > Reportes Programados.
Selecciona el reporte.
Haz clic en Ejecutar Ahora.

La ejecucion manual actualiza last_run_at pero no modifica next_run_at. El reporte se entrega inmediatamente al canal configurado.

Programacion y Reportes

En esta página