Esecuzione dei Piani

Esegui piani di manutenzione manualmente o automaticamente, visualizza l'anteprima dei risultati e monitora la cronologia delle esecuzioni.

A cosa serve

Guidare il tecnico passo dopo passo durante l'intervento.
Catturare evidenza (foto, firma, lettura) alla chiusura.
Riportare consumi di ricambi e tempo reale impiegato.

Come funziona

L'app mobile carica l'ordine, mostra la checklist dei passi, permette di allegare evidenza e registra i consumi. La chiusura sincronizza con il backend in tempo reale (o batch in modalità offline).

Esecuzione manuale

Puoi eseguire qualsiasi piano di manutenzione immediatamente dalla dashboard, senza attendere che lo scheduler lo attivi.

Vai a Manutenzione > Piani.
Seleziona il piano che desideri eseguire.
Clicca su Esegui.

Quando esegui un piano manualmente:

Viene creata un'attivita con tutti i parametri configurati nel piano.
Vengono inviate le notifiche configurate (email e/o WhatsApp).
Vengono aggiornati last_executed_at e execution_count del piano.
Per i piani a calendario, viene ricalcolato next_due_at.
Per i piani a contatore, current_counter si resetta a zero.

L'esecuzione manuale funziona indipendentemente dallo stato enabled del piano. Puoi eseguire un piano disabilitato.

Anteprima (dry run)

Prima di eseguire un piano, puoi visualizzare esattamente cosa succederebbe senza creare alcuna attivita ne inviare notifiche.

L'anteprima mostra:

Campo	Descrizione
task_title	Titolo che avrebbe l'attivita generata
task_priority	Priorita assegnata
task_due_date	Data di scadenza calcolata
assigned_to_name	Nome della persona assegnata
asset_name	Nome dell'asset collegato
checklist_items	Numero di elementi nella lista di verifica
notifications	Canali e destinatari delle notifiche
next_due_after_execution	Prossima data di esecuzione dopo l'esecuzione
execution_count_after	Numero di esecuzione risultante

L'anteprima e completamente sicura: non modifica alcun dato ne invia alcuna comunicazione.

Notifica di prova

Puoi verificare che le notifiche siano configurate correttamente senza eseguire il piano:

Seleziona il piano.
Clicca su Prova Notifica.

Il sistema invia una notifica di prova con il prefisso [TEST] nel titolo. Questo permette di verificare:

Che l'account email sia attivo e possa inviare.
Che il numero WhatsApp sia connesso.
Che la persona assegnata abbia dati di contatto validi.

La prova di notifica richiede che il piano abbia almeno un canale configurato (email o WhatsApp) e una persona assegnata.

Cronologia delle esecuzioni

Ogni piano mantiene una cronologia completa di tutte le attivita che ha generato.

La cronologia mostra:

Campo	Descrizione
task_code	Codice unico dell'attivita (es: MAN-001)
title	Titolo dell'attivita
status	Stato attuale (todo, in_progress, done, ecc.)
priority	Priorita assegnata
created_at	Data di creazione
due_date	Data di scadenza

La cronologia e paginata e ordinata per data di creazione decrescente.

Tracciamento risultati notifiche

Ogni attivita generata da un piano registra il risultato delle notifiche inviate:

{
  "notification_results": {
    "email": { "sent": true, "to": "tecnico@azienda.com" },
    "whatsapp": { "sent": false, "error": "Numero non connesso" }
  }
}

Questo permette di tracciare esattamente quali notifiche sono state inviate con successo e quali sono fallite, senza influire sulla creazione dell'attivita.

Esecuzione automatica via Cloud Scheduler

Il sistema verifica automaticamente i piani in scadenza ogni ora attraverso un endpoint interno:

POST /internal/check-maintenance-due

Questo endpoint e protetto da un segreto HMAC (X-Scheduler-Secret) e viene invocato da Google Cloud Scheduler.

Flusso di esecuzione automatica

Cloud Scheduler invoca l'endpoint interno ogni ora.
Il sistema scopre tutti i tenant registrati.
Per ogni tenant, cerca piani con enabled: true, trigger: calendar, e next_due_at <= adesso.
Ogni piano in scadenza viene eseguito, creando l'attivita e inviando le notifiche.
Un meccanismo di claim atomico previene esecuzioni duplicate in ambienti multi-istanza.

Se l'esecuzione di un piano fallisce, il sistema ripristina la data next_due_at in modo che il piano venga ritentato nel ciclo successivo.

Protezione di idempotenza

Il sistema utilizza un meccanismo di claim atomico per prevenire esecuzioni duplicate:

Prima di eseguire, avanza next_due_at al futuro in modo atomico.
Se un'altra istanza ha gia reclamato il piano, il claim fallisce e viene saltato.
Se l'esecuzione fallisce, next_due_at viene ripristinato al valore originale.

Incremento del contatore

Per i piani basati su contatore, puoi incrementare il valore del contatore manualmente o tramite integrazione:

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

La risposta mostra lo stato attuale:

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

Quando il contatore raggiunge o supera la soglia, il piano viene eseguito automaticamente:

{
  "plan_id": "abc123",
  "current_counter": 0,
  "threshold": 500,
  "triggered": true,
  "task": {
    "task_id": "...",
    "task_code": "MAN-015",
    "title": "Sostituzione filtri — Pompa Principale"
  }
}

L'incremento e atomico per prevenire condizioni di concorrenza in ambienti concorrenti.

Benefici chiave

Checklist guidata passo dopo passo — meno errori.
Modalità offline con sync automatico al riconnettersi.
Evidenza strutturata: foto + firma + lettura.
Report consumo ricambi per ordine.
Tempo reale di intervento catturato automaticamente.

Esecuzione dei Piani

In questa pagina