Guida all'uso della dashboard

1. Cosa fa questa dashboard

Aiuta a pianificare le visite tecniche dei tecnici 626 nei prossimi giorni. Recupera dal CRM Facile626 i sopralluoghi pendenti, calcola la rotta più efficiente per ciascun tecnico considerando l'orario di lavoro, la pausa pranzo e i tempi di guida con traffico, contatta i clienti via WhatsApp per fissare gli appuntamenti, e mostra il risultato sulla mappa.

Il flusso di lavoro è in quattro fasi (le prime tre sono i passi normali; la quarta gestisce le casistiche residue):

1. Fase 1 — Sync dati: aggiorna tecnici, sopralluoghi, appuntamenti e indisponibilità dal CRM.
2. Fase 2 — Pianificazione: calcola le rotte ottimali per ciascun tecnico e crea le proposte di appuntamento.
3. Fase 3 — Outreach WhatsApp: invia ai clienti il template di consenso (pulsante OK), poi il messaggio coi dettagli (SI / NO entro le 23:00), gestisce conferme, alternative e casi di slot non più disponibile.
4. Fase 4 — Gestione code: tre flussi automatici di servizio a orari diversi. Timeout alle 07:00 (mette in retry chi non risponde da 24h), Retry sender alle 08:00 (rinvia il template di reminder ai clienti riprogrammati), Hole filling alle 09:00 (riempie i buchi nelle agende fino a max 5 tappe/giorno usando i sopralluoghi rimasti in coda).

C'è anche una Fase 5 — endpoint REST per il gestionale — usata solo dal sistema CRM, non dalla dashboard.

2. Come lanciare le fasi (dalla home)

Nella pagina Overview trovi il pannello "Lancio fasi"con tre card: Fase 1, Fase 2, Fase 3. Procedi sempre nell'ordine.

1. Lancia Fase 1 (sync dati). Doppio click di conferma. Dura circa 2 minuti; il bottone resta in stato "In esecuzione…".
2. Quando vedi ✓ ok sulla card Fase 1, lancia Fase 2(calcolo rotte). Dura circa 5 secondi.
3. Quando vedi ✓ ok anche sulla Fase 2, vai su Mappa Rotteper controllare le tappe pianificate.
4. Lancia Fase 3 (Outreach WhatsApp) solo quando vuoi che i clienti ricevano la proposta di appuntamento. Il bottone è arancione e ti ricorda che manderà un messaggio reale.

3. Leggere la mappa rotte

Vai su Mappa Rotte, scegli un tecnico e una data, poi clicca Carica rotta.

Vedrai:

• 🏠 Casa del tecnico — punto di partenza al mattino e di rientro la sera
• Tappe numerate sulla mappa nell'ordine in cui il tecnico le visiterà (numerazione ricalcolata in base agli orari reali, non solo all'ordine di inserimento)
• Linea blu piena = strada reale calcolata da Google con traffico medio
• Linea grigia tratteggiata (raro) = la rotta Google non è disponibile per quel giorno; mostriamo una linea retta come fallback
• In alto a destra: numero tappe, distribuzione per stato, km totali, ore di guida
• Sotto la mappa: lista tappe con orario di arrivo, durata, stato, eventuale badge pernottamento

4. Cosa significano gli stati delle tappe

I colori e le etichette sulla mappa e in lista riflettono lo stato reale del cliente:

5. Quando lanciare le fasi

• Ogni mattina, una sola volta: lancia Fase 1 per portarti i nuovi sopralluoghi e appuntamenti del CRM.
• Subito dopo: lancia Fase 2 per ricalcolare le rotte sulla base dei dati appena sincronizzati.
• Durante il giorno, se entrano nuove richieste: ripeti i due passi.
• Dopo le 18: di solito non serve, ma puoi rilanciare se hai nuovi dati per il giorno dopo.

6. Cosa fare se qualcosa non torna

• La card Fase 1 / Fase 2 mostra ✗ errore: rileggi l'orario dell'ultimo run, attendi 1 minuto e riprova. Se l'errore persiste, contatta l'assistenza tecnica.
• Sulla mappa non vedo tappe per un tecnico: prima conferma di aver lanciato Fase 2 oggi (vedi la sezione Lancio fasi). Se Fase 2 è ok ma la mappa è vuota, è normale che alcuni tecnici non abbiano lavoro in alcune date.
• Una tappa appare due volte stesso giorno per lo stesso cliente: ogni cliente compare al massimo una volta per giornata-tecnico. Se per qualche motivo ci fossero entrambe una versione "Pianificata" e una "Confermata" per lo stesso sopralluogo, viene mostrata solo quella Confermata (il sistema deduplica automaticamente). Sopralluoghi diversi dello stesso cliente (es. primo controllo + sopralluogo periodico) hanno #numero diverso e restano legittimamente distinti.
• Vedo la dicitura "pernottamento": il tecnico tornerebbe a casa troppo tardi quel giorno (oltre il cutoff serale, default 20:00). Resta nei pressi dell'ultima tappa e ricomincia di lì il mattino dopo. Il numero massimo di pernottamenti per tecnico è gestito dalla "Configurazione tecnici" sopra (default 4 al mese, modificabile per singolo tecnico).
• Banner rosso "Conflitto di orario" sulla mappa: due tappe della stessa giornata-tecnico si sovrappongono nel tempo. Vedi §3 per il dettaglio su come si risolve.

7. Perché l'ordine delle tappe a volte sembra strano

Capita di vedere una rotta che sembra meno efficiente — per esempio: il tecnico va in una zona, poi in una zona lontana, poi torna vicino a casa. La tentazione è dire "ma se le due tappe vicine a casa le faceva consecutive...". Quasi sempre il calcolo dimostra il contrario.

Esempio reale: casa in zona A, due tappe in zona A (vicine), due tappe in zona B (lontane). Confronto:

• Sequenza ottimale (sistema): Casa → A1 → B1 → B2 → A2 → Casa. Si fa una sola "puntata" verso B; A2 viene raccolta sulla via del rientro.
• Sequenza intuitiva (errata): Casa → A1 → A2 → B1 → B2 → Casa. Si fanno DUE viaggi pieni A↔B andata e ritorno.

Tipicamente la sequenza ottimale fa 8-15 km in meno. È il classico "commesso viaggiatore": a colpo d'occhio non si vede, ma sui chilometri totali la differenza c'è e si accumula. Se in una rotta specifica vedi qualcosa che ti sembra molto assurdo (più di 20km in più rispetto alla tua intuizione), segnalalo: c'è qualcosa che il sistema non sa.

8. Pernottamenti: quando e come

Il sistema decide automaticamente che un tecnico deve pernottare quando, nella giornata pianificata, il rientro a casa sarebbe troppo tardi rispetto al suo cutoff serale (default 20:00, configurabile per tecnico). Tipicamente succede in due scenari:

• Sopralluogo isolato a 200+ km da casa: andata, lavoro, ritorno = oltre 12 ore. Il tecnico pernotta vicino al cliente.
• Cluster di sopralluoghi in zona remota: 3-4 lavori in val Pusteria o in Carnia → trasferta di 2 giorni con pernottamento intermedio.

Per generare scenari di pernottamento realistici, configura sopra la sezione "Configurazione tecnici" quali tecnici accettano trasferte (raggio > 150 km) e a quale ora rifiutano il rientro (cutoff < 20). Esempio: tecnico A con raggio 250 km e cutoff 19 lavorerà occasionalmente fuori-zona generando overnight; tecnico B con valori di default resterà sempre vicino casa.

Sulla mappa vedrai un banner arancione sopra la mappa quando una giornata ha pernottamento, più un badge "pernottamento"sull'ultima tappa di quel giorno.

9. Fase 3 — Outreach WhatsApp ai clienti

La Fase 3 manda automaticamente i messaggi WhatsApp ai clienti pianificati (status "Pianificata") e gestisce le loro risposte in due step:

1. Primo template di consenso (vi_contatteremo): "Facile626 desidera contattarla per fissare un sopralluogo. Premi OK per ricevere i dettagli." Pulsante: OK.
2. Dopo OK, il sistema invia un secondo messaggio (testo libero, S.20.17) con i dettagli completi: data, ora, indirizzo, durata, firma Facile626 e richiesta di risposta entro le 23:00. Il cliente risponde digitando o premendo il bottone SI oppure NO.

Da qui i percorsi possibili:

• SI → la tappa diventa Confermata. Il cliente riceve un messaggio di conferma (S.20.20) con dettagli + numero Customer Care 0432 44982 + policy 48h di preavviso per modifiche.
• NO → il sistema propone automaticamente una data alternativapresa dalla coda di alternative pianificate (sempre con SI/NO entro le 23:00). Se non ci sono più alternative (= 3° NO consecutivo: originale + 2 alternative rifiutate), parte il messaggio di escalation: "al momento non abbiamo altre date disponibili, sarà ricontattato dal nostro Customer Care al 0432 44982" e il sopralluogo passa in stato "escalation" per gestione manuale. In parallelo il sistema chiama il vostro endpoint di Customer Care GET /ai_tecnici/set_doesnt_answer?id_tasks=…(l'URL completo è in app_settings.customer_care_escalation_webhook_url) passando in concatenazione tutti i task id del sopralluogo, così l'ufficio sa immediatamente chi richiamare. Dopo 5 giorni (configurabile viaapp_settings.escalation_auto_reset_days) i sopralluoghi in escalation vengono automaticamente riportati a in_coda dalla Fase 1, in modo che tornino disponibili per nuove proposte automatiche. È possibile anche fare un reset manuale di un singolo cliente via endpointPOST /api/admin/reset-escalation con body{ "inspection_id": "…" }.
• Conferma cliente registrata su F626: dopo ogni SI/conferma il sistema chiama il vostro endpointGET /ai_tecnici/set_made_appointment?id_task=…&reason=…(URL in app_settings.customer_care_made_appointment_webhook_url), una volta per ciascun task del sopralluogo (così bundle RSPP+HACCP vengono registrati entrambi).
• Slot non più disponibile (S.20.16) → se tra la proposta e la conferma del cliente lo slot è stato occupato da un altro cliente o si è creato un overlap temporale, il sistema risponde automaticamente: "l'appuntamento non è più disponibile, in alternativa le proponiamo [data alternativa]". Il cliente decide SI/NO sulla nuova proposta.
• Nessuna risposta entro 24h → la Fase 4 Timeout (ore 7:00) mette in "attesa_retry" e la Fase 4 Retry sender (ore 8:00) rinvia il template di reminder. Dopo 3 tentativi senza risposta → escalation.

La Fase 3 parte automaticamente alle 8:30 del mattino ogni giorno. Non serve un pulsante — le risposte dei clienti popolano la dashboard man mano che arrivano.

Come provarla: usa il Test plan qui sopra (passi 7→10). Il passo 8 ti permette anche di simulare lo scenario "slot occupato" senza dover orchestrare un conflitto reale tra clienti.

10. Fase 4 — Tre flussi automatici

La Fase 4 è composta da tre flussi indipendenti che girano a orari diversi e gestiscono altrettanti scenari residui del ciclo di outreach. Per il cliente finale l'esperienza resta un'unica conversazione coerente; sotto sono workflow separati per chiarezza e affidabilità.

• 07:00 — Timeout: identifica i sopralluoghi in "soft_booking" con last_contact_at più vecchio di 24h. Se il cliente è periodico e ha ancora tentativi disponibili (max 3), passa in "attesa_retry". Se i tentativi sono esauriti, passa direttamente in "escalation" (gestione manuale).
• 08:00 — Retry sender: per i sopralluoghi in "attesa_retry" con prossimo_contatto = oggi, rinvia il template di reminder (reminder_no_risposta con pulsanti SI/NO e numero Customer Care 0432 44982) e li riporta in "soft_booking" in attesa di nuova risposta.
• 09:00 — Hole Filling: per ogni giornata-tecnico che ha meno di 4 tappe confermate o pianificate (e meno di 5 considerando l'overbooking del 30%), cerca sopralluoghi ancora in "in_coda" e li inserisce nei buchi liberi. Non manda WhatsApp direttamente: prepara nuove entry pending in daily_contact_planche la Fase 3 della mattina successiva raccoglierà.

Il numero massimo di tappe pianificate per giornata-tecnico è 5 (4 visite attese × 30% overbooking), in linea con un orario di lavoro 9:00-18:00 con pausa pranzo e tempi di viaggio realistici. Questo evita che Hole Filling riempia le giornate oltre la capacità reale di un tecnico.

Come provarli: usa il Test plan qui sopra (passi 11, 12, 13). Ogni test ha un proprio bottone "Setup" che predispone lo stato di Merlin (utente di test) e poi il bottone di lancio della fase specifica.

11. Glossario rapido

Sopralluogo

Visita tecnica programmata per un cliente specifico.

Tappa

Una singola visita all'interno della giornata di un tecnico.

Rotta

L'insieme delle tappe di un tecnico in un dato giorno, nell'ordine in cui le visiterà.

Pianificata (soft)

Tappa decisa dal sistema, in attesa di contattare il cliente o di sua risposta.

Confermata (hard)

Cliente ha risposto SI sul WhatsApp di proposta. Il sopralluogo è fissato e immutabile.

Soft booking

Slot riservato in modo "tentativo" (in attesa di conferma cliente). Più soft possono coesistere su stessa giornata grazie all'overbooking del 30%.

Hard booking

Slot confermato dal cliente. Il sistema non lo modifica più automaticamente.

Pernottamento

Il tecnico passa la notte fuori casa quando il rientro la sera richiederebbe troppo tempo (oltre il cutoff serale, default 20:00).

Slot occupato (S.20.16)

Lo slot proposto a un cliente non è più disponibile (capacità raggiunta o overlap con altra conferma). Il sistema gli manda automaticamente un messaggio di scuse + prima data alternativa.

Escalation

Stato in cui il sistema non riesce più a procedere autonomamente (es. alternative esaurite dopo 3 NO consecutivi, 3 retry falliti). Il cliente riceve un messaggio "sarà ricontattato dal Customer Care al 0432 44982", il sopralluogo passa in carico all'operatore e parte un webhook esterno al Customer Care di Facile626 col dettaglio del cliente da contattare.

Overbooking

Strategia che propone più appuntamenti di quelli che il tecnico può fare (di solito 30% in più), per compensare i rifiuti attesi. Max 5 tappe pianificate per giornata, 4 confermate.

Whitelist di test

Numero WhatsApp dedicato ai test. Durante la fase di rodaggio Fase 3 spedisce SOLO a questo numero; tutti gli altri clienti hanno il campo whatsapp svuotato per sicurezza.

12. Integrazione con il CRM Facile626 (webhook)

Il sistema dialoga con il CRM Facile626 in due direzioni: noi → loroper notificare gli eventi salienti del ciclo WhatsApp (conferme e "non risponde"), e loro → noi per rimettere manualmente in coda un cliente già contattato offline dal Customer Care.

12.1 Notifiche da noi verso F626

Vengono attivate automaticamente dalla Fase 3 / Fase 4 in due casi:

• Conferma cliente (dopo SI):GET https://cat-italia.facile626.it/ai_tecnici/set_made_appointment?id_task=<task_id>&reason=cliente_ha_confermato_via_whatsapp. Inviata una per ogni task_id del sopralluogo (RSPP + HACCP vengono entrambi registrati).
• Cliente non risponde / rifiuta (3° NO consecutivo, 3° timeout, finestra esaurita, primo cliente in timeout):GET https://cat-italia.facile626.it/ai_tecnici/set_doesnt_answer?id_tasks=<t1,t2,t3>. id_tasks è la concatenazione (csv) di tutti i task_id del sopralluogo.

Entrambi gli URL sono configurabili nel DB (app_settings.customer_care_escalation_webhook_urle customer_care_made_appointment_webhook_url). Se l'endpoint torna errore o va in timeout (10s), logghiamo ma non blocchiamo il flusso conversazionale del cliente.

12.2 Endpoint da noi esposto: reset manuale escalation

Quando il Customer Care chiude manualmente un caso (cliente ricontattato per telefono, appuntamento concordato a voce, ecc.) può rimettere il sopralluogo in coda chiamando il nostro endpoint:

POST https://<dashboard-host>/api/admin/reset-escalation
Content-Type: application/json

Body (uno tra i due):
  { "inspection_id": "2436997" }
  { "task_id": "2447844" }

Risposta:
  {
    "ok": true,
    "mode": "single",
    "reset_count": 1,
    "inspection_id": "2436997",
    "note": "Sopralluogo riportato a in_coda, sarà ripreso dalla prossima Fase 2"
  }

Sul valore di reset_count: indica quante righe sono state effettivamente aggiornate sul database. 1 = reset riuscito,0 = nessun sopralluogo in escalation con quell'id (eventualmente già in coda o id sbagliato). Il retry_count del sopralluogo viene azzerato lato DB, così il cliente riparte da zero tentativi.

12.3 Auto-reset programmato (5 giorni)

Indipendentemente dalla chiamata manuale, ogni esecuzione di Fase 1 (di norma 1 al giorno) rimette automaticamente in coda i sopralluoghi rimasti in escalation da più di 5 giorni (configurabile in app_settings.escalation_auto_reset_days). Lo scopo è che, anche se il Customer Care si dimentica di chiamare l'endpoint sopra, il cliente non resti bloccato nell'automazione per sempre.

12.4 I 3 step di rollout

L'uscita in produzione del sistema WhatsApp è strutturata come 3 step successivi, ognuno attivabile con un click dal pannello Modalità Outreach in cima a questa pagina. Li abbiamo chiamati Step e non Fase per evitare confusione con le Fasi 1-5 dei workflow N8N (Fase 1 sync, Fase 2 pianificazione, Fase 3 outreach, ecc.).

1. Step 1 — Test con numero di test (default attuale). Il sistema contatta esclusivamente il numero salvato come whitelist nella sezione "Numero di test". Tutti gli altri clienti sono filtrati prima della spedizione. Lo scopo è verificare:
   • che il template iniziale, il freeform con i dettagli e la conferma arrivino correttamente al numero di test;
   • che i webhook set_made_appointment e set_doesnt_answer verso il CRM F626 vengano registrati come atteso;
   • che lo stato del task (confermato / da ricontattare manualmente) cambi sul gestionale Facile626 quando il numero di test conferma o rifiuta sopra il limite di NO.
2. Step 2 — Deploy limitato (3 clienti reali). Il filtro del numero di test viene disattivato. Il sistema contatta i primi 3 clienti reali in coda. È la prima validazione in condizioni di produzione vera, con un volume controllato. Lo scopo è verificare:
   • che i 3 clienti ricevano effettivamente i template WhatsApp;
   • che le loro risposte (OK, SI, NO) vengano gestite correttamente lato nostro;
   • che i loro task sul gestionale F626 cambino stato a fronte di queste interazioni.
   Il passaggio richiede una conferma esplicita dal pannello.
3. Step 3 — Produzione piena. Nessun filtro, nessun limite. Il sistema contatta tutti i clienti pending al prossimo ciclo di Fase 3 outreach. Si attiva solo dopo che lo Step 2 è andato a buon fine sui 3 clienti reali e il Customer Care ha confermato che tutto è arrivato come ci si aspettava. Il passaggio richiede una doppia conferma.

Sotto il pannello con i 3 bottoni di fase trovi anche un riquadro "Controlli avanzati" con i due interruttori grezzi (whitelist e limite numerico), utile se ti serve una configurazione non-standard (es. limite a 10 o 20 clienti, oppure whitelist disattivata senza limite).