Ejecución de Planes

¿Para qué sirve?

• Guiar al técnico paso a paso durante la intervención.
• Capturar evidencia (foto, firma, lectura) al cierre.
• Reportar consumos de repuestos y tiempo real invertido.

¿Cómo funciona?

La app móvil carga la orden, muestra la checklist de pasos, permite adjuntar evidencia y registra consumos. El cierre sincroniza con el backend en tiempo real (o batch en modo offline).

Ejecución manual

Puedes ejecutar cualquier plan de mantenimiento inmediatamente desde el dashboard, sin esperar a que el scheduler lo dispare.

1. Ve a Mantenimiento > Planes.
2. Selecciona el plan que deseas ejecutar.
3. Haz clic en Ejecutar.

Al ejecutar un plan manualmente:

• Se crea una tarea con todos los parametros configurados en el plan.
• Se envian las notificaciones configuradas (email y/o WhatsApp).
• Se actualiza last_executed_at y execution_count del plan.
• Para planes de calendario, se recalcula next_due_at.
• Para planes de contador, se reinicia current_counter a cero.

Previsualizacion (dry run)

Antes de ejecutar un plan, puedes previsualizar exactamente que pasaria sin crear ninguna tarea ni enviar notificaciones.

La previsualizacion muestra:

Notificación de prueba

Puedes verificar que las notificaciones estan correctamente configuradas sin ejecutar el plan:

1. Selecciona el plan.
2. Haz clic en Probar Notificación.

El sistema envia una notificación de prueba con el prefijo [TEST] en el titulo. Esto permite verificar:

• Que la cuenta de email esta activa y puede enviar.
• Que el numero de WhatsApp esta conectado.
• Que la persona asignada tiene datos de contacto validos.

Historial de ejecución

Cada plan mantiene un historial completo de todas las tareas que ha generado.

El historial muestra:

El historial esta paginado y ordenado por fecha de creacion descendente.

Resultados de notificación

Cada tarea generada por un plan registra el resultado de las notificaciones enviadas:

{
  "notification_results": {
    "email": { "sent": true, "to": "tecnico@empresa.com" },
    "whatsapp": { "sent": false, "error": "Number not connected" }
  }
}

Esto permite rastrear exactamente que notificaciones se enviaron con exito y cuales fallaron, sin afectar la creacion de la tarea.

Ejecución automatica via Cloud Scheduler

El sistema verifica automáticamente los planes pendientes cada hora a traves de un endpoint interno:

POST /internal/check-maintenance-due

Este endpoint esta protegido por un secreto HMAC (X-Scheduler-Secret) y es invocado por Google Cloud Scheduler.

Flujo de ejecución automatica

1. Cloud Scheduler invoca el endpoint interno cada hora.
2. El sistema descubre todos los tenants registrados.
3. Para cada tenant, busca planes con enabled: true, trigger: calendar, y next_due_at <= ahora.
4. Ejecuta cada plan pendiente creando la tarea y enviando notificaciones.
5. Usa un claim atomico para evitar ejecuciones duplicadas en entornos con multiples instancias.

Proteccion de idempotencia

El sistema usa un mecanismo de claim atomico para prevenir ejecuciones duplicadas:

1. Antes de ejecutar, avanza next_due_at al futuro atomicamente.
2. Si otra instancia ya reclamo el plan, el claim falla y se salta.
3. Si la ejecución falla, se revierte next_due_at al valor original.

Incremento de contador

Para planes basados en contador, puedes incrementar el valor del contador manualmente o via integración:

POST /api/v1/maintenance/{plan_id}/increment-counter
{
  "value": 10
}

La respuesta indica el estado actual:

{
  "plan_id": "abc123",
  "current_counter": 490,
  "threshold": 500,
  "triggered": false,
  "task": null
}

Cuándo el contador alcanza o supera el umbral, el plan se ejecuta automáticamente:

{
  "plan_id": "abc123",
  "current_counter": 0,
  "threshold": 500,
  "triggered": true,
  "task": {
    "task_id": "...",
    "task_code": "MAN-015",
    "title": "Cambio de filtros — Bomba Principal"
  }
}

Beneficios clave

• Checklist guiada paso a paso — menos errores.
• Modo offline con sync automático al reconectar.
• Evidencia estructurada: foto + firma + lectura.
• Reporte de consumo de repuestos por orden.
• Tiempo real de intervención capturado automáticamente.