Guida utente

Le parole che userai

Le schermate di questa guida usano un tour di esempio con dati fittizi (Vertigo Tour 2027) e account demo tm@sound-demo.it / produzione@sound-demo.it. Schermate aggiornate al 2026-10-25 18:16.

02Account e profili

Ci sono due ruoli. L'amministratore vede tutti i tour, li crea, collega Gmail e invita le persone. L'utente vede e lavora solo sui tour che gli sono stati assegnati. Non esiste una registrazione libera: si entra solo con un invito.

2.1 · Primo avvio: creare l'account amministratore

Al primissimo avvio il tool non ha account e mostra questa pagina. Si usa una volta sola, da chi installa il tool: appena esiste un account la pagina si chiude e da lì in poi si entra solo con un invito.

1. 1La tua email: sarà il nome utente.
2. 2Una password di almeno 8 caratteri.
3. 3La stessa password, per conferma.
4. 4Crea amministratore: entri subito e arrivi alla pagina Tour.

2.2 · Invitare una persona (amministratore)

1. Nella barra laterale apri Amministrazione›Utenti e accessi.
2. Nel riquadro Invita una persona scrivi l'email del collega e spunta i tour a cui deve accedere.
3. Premi Crea link di registrazione, copia il link e mandalo alla persona (mail, WhatsApp…).

1. 1Email della persona. Consigliata: così solo quell'indirizzo potrà usare il link.
2. 2I tour che la persona potrà vedere. Puoi cambiarli anche dopo.
3. 3Crea link di registrazione.

1. 1Il link personale. Vale una sola volta, per 7 giorni, e non viene più mostrato.
2. 2Copia e invialo. Se lo perdi: revocalo (in «Link in attesa») e creane un altro.

2.3 · Creare il proprio profilo dal link (utente invitato)

1. Apri il link ricevuto (va bene da computer, tablet o telefono).
2. L'email è già compilata se l'amministratore l'ha indicata. Scegli una password (almeno 8 caratteri) e ripetila.
3. Premi Crea account ed entra: vedrai subito i tour che ti sono stati assegnati.

1. 1Email (bloccata se l'invito è nominativo).
2. 2Scegli la password.
3. 3Ripetila.
4. 4Crea account ed entra.

1. 1Apri per entrare nel tour.
2. 2Il tuo account e il pulsante Esci.

Se dopo la registrazione vedi «Nessun tour assegnato», l'account funziona ma l'amministratore non ti ha ancora dato accesso a un tour: chiedigli di spuntarlo in Utenti e accessi.

2.4 · Accedere

1. 1Email del tuo account.
2. 2Password.
3. 3Accedi. La sessione resta aperta 7 giorni su quel browser.

Dopo 5 tentativi sbagliati di fila l'accesso per quell'email si blocca per un minuto.

2.5 · Password dimenticata, account da gestire

Non c'è un «password dimenticata» automatico: l'amministratore crea un link nuova password e te lo manda. Dalla stessa tabella gestisce tutti gli account.

1. 1I tour a cui l'utente ha accesso: spunta o togli…
2. 2…e premi Salva accessi.
3. 3Link nuova password: crea un link (una volta, 7 giorni) per reimpostarla.
4. 4Rendi amministratore / togli il ruolo.
5. 5Disattiva: la persona non può più entrare (si può riattivare).

Amministratore chiuso fuori? Se nessun amministratore riesce più a entrare, chi gestisce il server del tool può crearne o reimpostarne uno (python tools/create_admin.py tua@email.it).

03I tour

Ogni tour ha i suoi messaggi, task, grafo, date e tourbook, e la sua etichetta Gmail. Si gestiscono dalla pagina Tutti i tour · nuovo sotto il nome del tour nella barra laterale.

1. 1Nome del tour, es. «Fuori Rotta Tour 2026».
2. 2Etichetta Gmail del tour. Vuota = TOUR/<nome del tour> (vedi Collegare Gmail).
3. 3Crea e apri: crea il tour e ti porta nei suoi Task attivi.

1. 1Il tour aperto in questa scheda. Il menu a tendina cambia tour solo in questa scheda.
2. 2Apri il tour.
3. 3Apri in nuova scheda: puoi lavorare su due tour in parallelo, uno per scheda.
4. 4Modifica: rinomina, cambia etichetta Gmail, Archivia (sparisce dal menu ma i dati restano).
5. 5Periodo del tour e etichetta Gmail in uso.

04L'interfaccia

Tutte le pagine hanno la stessa struttura: a sinistra il tour e il menu, in alto il titolo della pagina e il tuo account.

1. 1Il tour su cui stai lavorando e il link alla pagina Tour.
2. 2Il menu: Operativo, Inbox, Grafo, Calendario, Viste rapide, Aiuto e (solo admin) Amministrazione.
3. 3Riepilogo della pagina (qui: task aperti e incongruenze).
4. 4Il tuo account (admin se amministratore) e Esci.
5. 5L'impronta CO₂ del tour: clic per il dettaglio.
6. 6Scansiona risposte e Approva tutti i pending (vedi Task attivi).
7. 7Le incongruenze trovate tra i messaggi: clic per espandere.
8. 8Un task: la barra colorata a sinistra è l'urgenza.

05Assistente della guida

Un assistente a cui chiedere in linguaggio naturale come si usa il TM Tool: «come invito un collega?», «dove scarico il tourbook in Word?», «si può collegare WhatsApp?». Risponde in base a questa guida.

1. 1Il pannello si apre dal pulsante Chiedi all'assistente, in basso a destra in ogni pagina dopo l'accesso.
2. 2La conversazione: risposte brevi, con i passaggi da seguire e il rimando alla sezione della guida.
3. 3Nuova chat: ricomincia da zero (l'assistente dimentica le domande precedenti).
4. 4Scrivi la domanda e premi Invio (Maiusc+Invio per andare a capo).

• Ricorda la conversazione: puoi fare domande di seguito («e se il link è scaduto?»). Sa anche in che pagina sei, quindi puoi chiedere «a cosa serve questo pulsante?» nominandolo.
• Sa cosa si può fare e cosa no: se una funzione non esiste ancora te lo dice (vedi Cosa si può fare), invece di inventarla.
• Non vede i dati dei tuoi tour (task, persone, hotel) e non fa azioni al posto tuo: spiega come farle. Per sapere «dove dorme Marta» usa le Viste rapide.
• Può sbagliare: per le operazioni delicate (reset, accessi, Gmail) verifica sempre nella sezione della guida che ti indica.
• È disponibile solo dopo l'accesso. Se risponde «non è ancora configurato» o «non risponde», avvisa chi gestisce il tool.

06Carica messaggi

Tutto ciò che entra nel tool passa da qui. Ogni messaggio viene letto dall'AI, che ne estrae persone, date, hotel, treni, diete e pass e crea i task corrispondenti nel tour indicato.

1. 1Gmail: legge solo le mail con l'etichetta del tour (vedi Collegare Gmail).
2. 2Tipo fonte: scegli che cosa stai caricando prima di selezionare i file.
3. 3File singoli o multipli: clic e scegli uno o più file (Ctrl/⌘+clic per sceglierne più di uno).
4. 4Cartella intera: carica tutti i file di una cartella.
5. 5Nota manuale: scrivi o detta un'informazione ricevuta a voce.
6. 6Aggiungi nota: la nota segue lo stesso percorso di un messaggio.

Dopo il caricamento si apre una pagina di avanzamento: ogni file richiede da qualche secondo a un minuto. Non ricaricare e non ricliccare: il tool blocca già i doppi invii. Un file già caricato nello stesso tour viene riconosciuto e saltato («File già processato»).

La nota manuale e la dettatura

Per le informazioni senza un messaggio da caricare (telefonata, riunione, backstage). Scrivi cosa ti è stato detto, ad esempio «Il fonico mi ha detto per telefono che il check-in dell'hotel a Bologna slitta al 22». Il task creato resta evidenziato in azzurro come Inserito a mano finché non lo confermi.

Il pulsante Detta trascrive la voce: in Chrome, Edge e Safari il testo compare mentre parli; negli altri browser registri, premi Ferma e il testo arriva poco dopo (la trascrizione la fa il server del tool, non un servizio esterno). La prima volta il browser chiede il permesso per il microfono: clicca Consenti. Controlla sempre il testo prima di premere «Aggiungi nota».

07Task attivi e bozze

La pagina di lavoro. I task aperti sono divisi per urgenza (alta media bassa), poi vengono quelli in attesa di risposta.

1. 1Urgenza e tipo di task (alloggio, biglietto_treno, catering, pass…).
2. 2Scrivi al fornitore: bozza di richiesta a chi deve fare la cosa (hotel, agenzia, catering).
3. 3Rispondi al mittente: bozza di risposta a chi ha scritto il messaggio («ricevuto, ci pensiamo noi»).
4. 4Prenota assistita (solo alloggi, treni, voli, auto): vedi Prenotazione assistita.
5. 5Approva e invia: genera la bozza e la segna subito come inviata, senza revisione. Non spedisce nulla: serve quando la invii comunque tu (Vedi bozza › Apri in Gmail).
6. 6Conferma nel grafo: l'informazione è già certa, scrivila tra i fatti del tour.
7. 7Modifica: correggi descrizione, dati estratti e scadenza prima di confermare.
8. 8Annulla task: scarta un task inutile o duplicato (non entra nel grafo).
9. 9seleziona: per le azioni su più task insieme.

Il ciclo di vita di un task

Le bozze: controlli tu, invii tu

Il tool non invia mai nulla da solo. Ogni bozza si apre già compilata nel programma giusto, la rileggi e premi Invia lì.

1. 1Tipo di bozza: richiesta al fornitore, risposta via email o via WhatsApp.
2. 2Il testo proposto, con oggetto e destinatario se noti.
3. 3Apri in Gmail: apre una nuova mail con destinatario, oggetto e testo già scritti.
4. 4Inviata ✓: premilo dopo aver inviato davvero. Una richiesta passa «in attesa risposta», un avviso chiude il task.
5. 5Scarta: elimina la bozza (puoi generarne un'altra).

Se il testo non va bene, premi Scarta e rigenera, oppure correggilo direttamente in Gmail prima di inviare. Se usi più account Google, Gmail si apre su quello indicato in GMAIL_ACCOUNT nel file .env.

Aspettare e registrare le risposte

1. 1Simula risposta fornitore: in fase di prova crea una risposta finta (positiva o negativa) per vedere il ciclo completo.
2. 2Vedi bozza: rileggi cosa era stato inviato.
3. 3chiudi a mano: la conferma è arrivata per altra via (es. al telefono).

Il pulsante Scansiona risposte in alto legge le risposte arrivate: se il fornitore conferma, i dati confermati (hotel, date, numero di prenotazione…) diventano un fatto nel grafo e il task si chiude; se rifiuta, il task torna da fare. Al termine compare il riepilogo di cosa è stato registrato.

Azioni su più task

1. 1Approva selezionati: genera e segna come inviate le bozze dei task selezionati.
2. 2Chiudi selezionati: li segna come fatti.
3. 3Approva tutti i pending: lo stesso per tutti i task da fare del tour. Chiede conferma.

Attenzione: «Approva» (singolo, selezionati o tutti) non invia mail o messaggi: genera le bozze e fa avanzare lo stato dei task come se fossero state inviate. Le richieste vanno comunque spedite da Gmail o WhatsApp (pulsante Vedi bozza sul task).

Paracadute: «Approva tutti i pending» salta sempre i task delicati, che restano da rivedere a mano: importi da 500 € in su, modifiche di prenotazioni esistenti (con numero di conferma), pagamenti, bonifici e fatture.

Incongruenze

1. 1Cosa non torna e tra quali informazioni.
2. 2Ignora quando hai verificato. Per correggere usa Modifica sul task o Correggi sul fatto.

Correggere un task

1. 1Descrizione del task.
2. 2Scadenza (opzionale).
3. 3Salva correzioni: questa versione è quella che finirà nel grafo alla conferma.

Nei campi estratti (persone, date, città…) separa più nomi con la virgola. Correggere qui, prima della conferma, evita fatti sbagliati nel tourbook.

08Prenotazione assistita

Per alloggi, treni, voli e auto il tool può aprire il sito di prenotazione e compilare per te i campi che conosce (stazioni, città, persone). Scelta finale e pagamento li fai sempre tu sul sito.

1. 1Il passo in cui ti trovi.
2. 2I siti disponibili per quel tipo di task: clic per aprirlo e iniziare la compilazione.

1. Premi Prenota assistita sul task e scegli il sito.
2. Il sito si apre nel tuo Chrome con i dati compilati. Le date spesso vanno inserite a mano: i calendari dei siti non si lasciano compilare.
3. Scegli l'offerta e completa il pagamento sul sito, come faresti normalmente.
4. Torna nel tool e registra l'esito (Registra → grafo): la prenotazione diventa un fatto confermato.

Funzione opzionale: richiede un componente aggiuntivo (Chrome con un'estensione di supporto) configurato da chi gestisce il tool. Se manca, i pulsanti segnalano «non raggiungibile» e tutto il resto funziona normalmente.

09Fatti confermati e tourbook

Il grafo contiene solo ciò che una persona ha confermato. Da qui si correggono i dati e si generano i documenti del tour.

1. 1Tourbook grafo: tutti i fatti in una pagina stampabile.
2. 2Genera Tourbook Professionale: il tourbook completo, scaricabile in Word ed Excel.
3. 3Totale CO₂ del tour e dettaglio.
4. 4Un fatto: tipo, dati e collegamenti (persone, hotel, città), chi l'ha confermato e quando.
5. 5Correggi il fatto.
6. 6Rimuovi il fatto dal grafo (chiede conferma).

1. 1Salva correzione: sostituisce il fatto (il precedente resta nello storico) e ricalcola subito CO₂ e pasti.
2. 2Aggiungi come fatto in più: se una registrazione copre due cose (es. «Firenze e Torino»), correggi questa con la prima e aggiungi l'altra.

Per il calcolo della CO₂ servono città riconoscibili, una per campo («Firenze», non «Firenze e Torino»).

Tourbook grafo

1. 1Stampa / Salva PDF: nella finestra di stampa scegli «Salva come PDF».

Tourbook professionale

Il documento da dare alla crew: travel party, itinerario, documenti, trasporti, merci, alloggi, pasti e diete, avvisi, info pratiche, guida per città, checklist, CO₂ e controlli sui dati. I dati vengono dal grafo; le parti generali (info pratiche, città) le scrive l'AI. La generazione richiede di solito un minuto, al massimo 2–3: non chiudere la pagina.

1. 1Stampa / Salva PDF.
2. 2Scarica Word: file .docx modificabile.
3. 3Scarica Excel: file .xlsx con le tabelle.
4. 4Rigenera testi: rifà le parti scritte dall'AI (altrimenti vengono riusate finché i dati del tour non cambiano).

Le sezioni con bordo tratteggiato si possono correggere direttamente nella pagina prima di stampare. Word ed Excel contengono i dati generati, non le correzioni fatte nella pagina: correggi nel file scaricato.

10Calendario e daily

1. 1Clic su una data per il dettaglio del giorno.
2. 2Scegli il periodo…
3. 3…e apri il Report periodo stampabile, giorno per giorno.

1. 1Stampa Daily: il daily sheet del giorno, da stampare o salvare in PDF.
2. 2Torna al calendario.

Il dettaglio del giorno raccoglie i task, gli spostamenti e chi dorme in hotel quella notte. Le date si popolano da sole man mano che i messaggi le citano.

11Viste rapide

Tabelle pronte per rispondere al volo a «dove dorme X?», «chi è celiaco?», «quando parte il bilico?».

1. 1Le viste rapide nel menu: Roster, Alloggi, Spostamenti, Pass, Diete, Trasporti pesanti.
2. 2Clic su un nome per il profilo della persona.

1. 1Tourbook personale: il programma di quella persona (viaggi, hotel, pass), da stampare o mandare.

12Impronta CO₂

Una stima delle emissioni del tour calcolata dai fatti confermati: spostamenti, notti in hotel, trasporti pesanti e pasti dello staff.

Le voci n/d mancano di un dato (città non riconosciuta, km o tonnellate assenti): correggi il fatto e il totale si aggiorna subito. Le assunzioni usate per i pasti sono elencate sotto la tabella.

13Amministrazione

Solo per amministratori: Utenti e accessi (descritto sopra) e il reset dei dati.

1. 1Solo il tour aperto: cancella messaggi, task, date e fatti di quel tour. Gli altri restano.
2. 2Tutto il database: come ripartire dal primo avvio (gli account restano, senza tour).
3. 3Per confermare digita la parola indicata e premi Azzera.

Il reset è irreversibile e non crea backup. Se i dati servono, chiedi prima un backup a chi gestisce il server del tool.

14Collegare Gmail ed etichetta TOUR

Il tool legge da Gmail solo le mail con l'etichetta del tour, in sola lettura: non può inviare, modificare né cancellare nulla. La configurazione si fa una volta sola, dall'amministratore (circa 15 minuti).

14.1 · Creare le credenziali in Google Cloud

1. Vai su console.cloud.google.com con l'account Google della casella del tour e crea un progetto: menu progetti in alto › Nuovo progetto › nome, es. tm-tool › Crea.
2. Attiva la Gmail API: API e servizi›Libreria › cerca «Gmail API» › Abilita.
3. Configura la schermata di consenso: API e servizi›Schermata di consenso OAuth › tipo Esterno › nome dell'app (es. «TM Tool») e la tua email come contatto.
4. In Utenti di test aggiungi l'indirizzo Gmail che il tool leggerà. Finché l'app è in modalità «Test» solo questi utenti possono autorizzarla.
5. In Accesso ai dati›Aggiungi o rimuovi ambiti aggiungi solo …/auth/gmail.readonly (lettura).
6. Crea le credenziali: Credenziali›Crea credenziali›ID client OAuth › tipo di applicazione App desktop › Crea. Copia l'ID client e il Client secret.

Google cambia spesso i nomi dei menu della console: se una voce non corrisponde, cercala nella barra di ricerca in alto («Gmail API», «Schermata di consenso», «Credenziali»).

14.2 · Inserirle nel tool

Chi gestisce il server del tool le inserisce nel file di configurazione .env:

GMAIL_CLIENT_ID=123456789-xxxx.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-xxxxxxxx
GMAIL_ACCOUNT=casella.tour@gmail.com

Poi il tool va riavviato. Il file .env non va mai condiviso: contiene le chiavi.

14.3 · Creare l'etichetta del tour in Gmail

L'etichetta dice al tool quali mail riguardano il tour. Ogni tour ha la sua, così le mail di un tour non finiscono in un altro. Il nome lo trovi nella pagina Tour («Gmail: …» sulla scheda del tour): se non l'hai cambiato è TOUR/<nome del tour>, cioè un'etichetta TOUR con dentro una sotto-etichetta per ogni tour.

1. In Gmail, nella colonna di sinistra, scorri fino a Etichette e premi + (Crea nuova etichetta). Nome: TOUR › Crea.
2. Premi di nuovo +, scrivi il nome del tour esattamente come nel tool (es. Vertigo Tour 2027), spunta Nidifica l'etichetta sotto e scegli TOUR › Crea. Il risultato è TOUR/Vertigo Tour 2027.
3. Applica l'etichetta alle mail del tour: selezionale › icona etichetta 🏷 › spunta l'etichetta del tour › Applica.
4. Consigliato — un filtro automatico: nella barra di ricerca di Gmail apri le opzioni (icona a destra), indica mittenti o parole del tour (es. @agenzia-viaggi.it, «Vertigo») › Crea filtro › spunta Applica l'etichetta e scegli quella del tour (anche Applica il filtro anche alle conversazioni corrispondenti per le mail già arrivate) › Crea filtro.

Il tool confronta il nome dell'etichetta senza distinguere maiuscole e minuscole, ma deve corrispondere per il resto: stessi spazi, stessa barra /. Se preferisci un nome diverso, scrivilo nella pagina Tour › Modifica › Label Gmail.

14.4 · Autorizzare e sincronizzare

Entra come amministratore e apri Inbox›Carica messaggi.

1. 1Autorizza Gmail: si apre la pagina di Google. Scegli l'account, conferma l'accesso in lettura e torni nel tool.

Google può avvisare che «l'app non è verificata»: è normale per un'app in modalità Test creata da te. Clicca Avanzate › Vai a TM Tool.

1. 1Facoltativo: leggi solo le mail da una data in poi (formato AAAA/MM/GG).
2. 2Sincronizza Gmail: importa le mail nuove con l'etichetta del tour aperto.

• Ogni sincronizzazione importa al massimo 15 mail nuove (ognuna richiede qualche chiamata all'AI): se ce ne sono di più, premi di nuovo.
• Le mail già importate vengono saltate; quelle senza etichetta non vengono mai lette, nemmeno se stanno nella stessa conversazione.
• Gli allegati delle mail non vengono letti: scaricali e caricali come PDF o immagine.
• Finché l'app Google è in modalità Test l'autorizzazione scade dopo 7 giorni: se compare «token scaduto», premi di nuovo Autorizza Gmail.

15WhatsApp

Oggi WhatsApp entra nel tool caricando le chat esportate, e le risposte partono da WhatsApp con un clic. Quando sarà attivo il numero WhatsApp del tour, i messaggi arriveranno da soli: sotto trovi cosa serve per prepararlo.

15.1 · Oggi: esportare una chat e caricarla

1. Nel tool apri Carica messaggi, scegli Tipo fonte: WhatsApp e carica il .txt.
2. Vocali, foto e PDF arrivati in chat: salvali e caricali con il tipo Audio, Immagine o PDF. Uno screenshot della chat va benissimo come immagine.
3. Aggiornamenti della stessa chat: un file identico viene riconosciuto e saltato, ma una nuova esportazione contiene anche i messaggi vecchi e verrebbe riletta tutta, creando task doppi. Per aggiornare, apri il .txt, tieni solo i messaggi dopo l'ultimo caricamento, salvalo come nuovo file e carica quello. Eventuali doppioni si scartano con Annulla task.

15.2 · Rispondere su WhatsApp

Quando un task nasce da una chat, Rispondi al mittente prepara una risposta adatta a WhatsApp.

1. 1La bozza è indicata come «Risposta al mittente · WhatsApp».
2. 2Apri in WhatsApp: si apre WhatsApp (app o web) con il testo già scritto. Scegli tu la chat o il gruppo e invia: non serve conoscere il numero.
3. 3Inviata ✓ dopo l'invio.

15.3 · Domani: il numero WhatsApp del tour

È previsto un numero dedicato, gestito da un assistente («Jessica, l'assistente di produzione») sulla piattaforma Karacal. Avrà due usi:

• Chat privata: il tour manager o la crew scrivono un'informazione («Fabio è celiaco», «sposta il treno di Marta al 21») e l'assistente conferma in una riga cosa ha annotato. Non prenota, non conferma e non inventa nulla: annota soltanto.
• Gruppi del tour: il numero è membro dei gruppi e legge in silenzio; risponde solo se viene nominato.

I messaggi raccolti entreranno nel tool come fonte WhatsApp, esattamente come una chat esportata, e diventeranno task con lo stesso percorso.

Stato attuale: il numero non è ancora disponibile e la sincronizzazione automatica nel tool non è ancora attiva. Fino ad allora usa l'esportazione della chat (15.1). Nessuna parte del tool va cambiata da te: quando il collegamento sarà pronto comparirà in Carica messaggi.

Checklist per quando arriva il numero

1. Un numero dedicato, non quello personale di nessuno, in grado di ricevere l'SMS o la chiamata di verifica. Un numero già attivo nell'app WhatsApp normale di solito va prima disattivato lì, perché la piattaforma business lo possa usare.
2. Configurazione dell'assistente su Karacal: Configurazione Jessica-WhatsApp con il prompt e le impostazioni del runbook docs/KARACAL_SETUP.md § 10 (internet e download disattivati, nessuno strumento, nessun output strutturato).
3. Prova in Chats prima di collegare il numero: incolla sample_inbox/12_whatsapp_fontana_dieta.txt (deve confermare solo «celiaco / niente glutine»), scrivi «sposta il treno al 21» (deve chiedere di chi e quale treno), chiedi «hai prenotato l'hotel a Napoli?» (deve dire che gira la richiesta alla produzione).
4. Deployment: Karacal › Deployment › Nuovo deployment › tipo WhatsApp, nome e configurazione Jessica-WhatsApp, poi collega il numero seguendo la procedura di Karacal.
5. Aggiungi il numero ai gruppi del tour e salvalo in rubrica a crew e fornitori con un nome riconoscibile (es. «Produzione — Vertigo»).
6. Avvisa i partecipanti che il numero legge i messaggi del gruppo per la produzione: è una questione di correttezza e di privacy.

16Cosa si può fare (e cosa non ancora)

Un riepilogo per rispondere in fretta alla domanda «il TM Tool lo fa?».

17Problemi frequenti