Report Programmati

I Report Programmati sono lo stesso report che costruisci in Report ma che si eseguono da soli: ogni lunedì, ogni giorno alle 8, il primo del mese. Vengono generati in PDF o Excel, consegnati via email o WhatsApp alla lista definita, e la cronologia delle esecuzioni rimane tracciabile.

Riepilogo esecutivo

Il cambio di passo: il report settimanale di manutenzione arriva nella casella del manager senza che nessuno si ricordi di generarlo.

A cosa serve

• Report ricorrenti di manutenzione — settimanali per il management, mensili per la direzione.
• Fatturazione consolidata per clienti di servizio di manutenzione.
• Dashboard di KPI che il supervisore stampa per la riunione del lunedì.
• Audit interni — snapshot mensile dello stato dell'impianto per archivio compliance.

Come funziona

flowchart LR
  S[Cloud Scheduler<br/>ogni 15 min] --> C{Report<br/>due?}
  C -- sì --> G[Genera PDF/Excel<br/>con branding_id]
  G --> D{canale}
  D -- email --> E[Postmark SMTP]
  D -- whatsapp --> W[Evolution API]
  G --> H[Log<br/>esecuzione]
  C -- no --> W1[attesa]

Il job run-scheduled-reports (Cloud Scheduler ogni 15 min) scorre la collezione dei report programmati attivi e valuta se ognuno è due (frequenza + ora + giorno) e non è ancora partito in quella finestra. Se sì, genera il file con la struttura definita, applica il branding e lo consegna.

Ogni esecuzione viene loggata in _scheduled_report_executions con:

• timestamp
• dimensione del file generato
• stato (ok / delivery_failed / generation_failed)
• destinatari effettivi
• signed URL del PDF/Excel su GCS

Parametri di configurazione

Come usarlo

Creare un report programmato

1. Dati → Report Programmati → Nuovo.
2. Assegnare un nome ("Manutenzione settimanale — Impianto Nord").
3. Scegliere la frequenza (settimanale, lunedì alle 7 UTC = 8 in Italia).
4. Scegliere il canale di consegna e selezionare account/numero (account email verificato o numero WhatsApp connesso).
5. Aggiungere i destinatari (email o telefoni separati da virgola).
6. Selezionare il branding salvato (o lasciare vuoto per usare il default).
7. Definire la struttura del report — stesso editor a blocchi dei report on-demand.
8. Salvare e attivare.

Il prossimo lunedì alle 7 UTC il sistema genera il PDF e lo invia.

Esecuzione manuale (senza aspettare)

Durante il setup è utile provare l'esecuzione prima di attivare:

1. Nel dettaglio del report programmato, clic su Esegui ora.
2. Il job parte immediatamente. Il PDF/Excel viene generato e consegnato ai destinatari elencati.
3. L'esecuzione viene loggata come triggered_by=manual.

Questo non altera la prossima esecuzione programmata.

Endpoint REST

POST   /api/v1/scheduled-reports                   # creare
GET    /api/v1/scheduled-reports                   # elencare
GET    /api/v1/scheduled-reports/{id}              # dettaglio
PATCH  /api/v1/scheduled-reports/{id}              # aggiornare
DELETE /api/v1/scheduled-reports/{id}              # eliminare
POST   /api/v1/scheduled-reports/{id}/execute      # esecuzione manuale
GET    /api/v1/scheduled-reports/{id}/executions   # cronologia
GET    /api/v1/scheduled-reports/{id}/executions/{exec_id}

Casi d'uso

1 · Report settimanale di manutenzione (impianto manifatturiero). weekly, lunedì 7 UTC (8 ora locale). PDF con 8 blocchi: header con logo impianto, tabella delle attività della settimana scorsa, tabella di allarmi critici, KPI (disponibilità, MTTR, MTBF). Destinatari: 3 email del team di direzione. Arriva prima che inizi la riunione del lunedì, zero lavoro umano.

2 · Report mensile per cliente esterno (fornitore di servizi). monthly, giorno 5 alle 14:00 UTC. PDF con branding del cliente (logo + colori + footer "Confidenziale"). Tabella degli interventi del mese scorso con tempi, tecnico assegnato e costo. Il cliente riceve il report esecutivo senza chiederlo. Il servizio viene fatturato lo stesso giorno.

3 · Report giornaliero di compliance HACCP (food safety). daily, 6 UTC. Canale WhatsApp al gruppo dei supervisori. PDF compatto con le letture del giorno precedente: temperature delle celle frigorifere, allarmi fuori range, azioni correttive pendenti. Soddisfa l'obbligo documentale senza che nessuno debba ricordarsene.

Limiti e assunzioni

• Risoluzione minima di esecuzione: 15 minuti. Un report con hour=8 può partire tra le 08:00 e le 08:15 UTC.
• day_of_month è limitato a 1-28. Non c'è supporto per "ultimo giorno del mese"; se serve, programmare il giorno 28 con una nota nel report.
• Se l'account di consegna (email o numero WhatsApp) viene disabilitato, l'esecuzione fallisce in silenzio (loggata come delivery_failed). Il report non viene riprovato automaticamente — eseguire manualmente dopo aver risolto la connessione.
• Nessuna esecuzione condizionale: il report si genera anche se non ci sono dati nuovi. "Solo se ci sono allarmi critici questo mese" è un agente WhatsApp con tool di generazione report, non un report programmato.
• I PDF generati occupano spazio in GCS. I tenant con molti report programmati + molte esecuzioni possono accumulare spazio; la policy di retention è configurabile per tenant.

Vantaggi chiave

• Report ricorrenti in 0 minuti umani → liberi il coordinatore da lavoro ripetitivo.
• Cronologia completa delle esecuzioni per audit (cosa è stato generato, quando, a chi, con che dimensione).
• Branding aziendale coerente — cambi il logo in un posto e tutti i futuri report lo usano.
• Stessa struttura a blocchi dei report on-demand — nessun doppio lavoro se avevi già un template.
• Consegna affidabile via Postmark (email) o Evolution API (WhatsApp) — nessuna coda di uscita che si satura.