Ottimizzazione e comunicazione tra Gmail e Google Drive

Realizza un progetto completo, riutilizzabile e installabile da utenti diversi in Google Apps Script che integri Gmail, Google Drive e Google Sheets per organizzare automaticamente email, allegati e file caricati manualmente. REQUISITO FONDAMENTALE Il codice non deve contenere dati personali o valori specifici dell’utente: niente indirizzi email, nomi di clienti/aziende, ID di cartelle Drive, percorsi personali, mittenti predefiniti o nomi fissi delle categorie. Tutte le impostazioni devono essere modificabili senza intervenire sul codice tramite: 1. un foglio Google “Configurazione”; 2. una funzione guidata setup(); 3. PropertiesService; 4. tabelle di regole configurabili. OBIETTIVI Il sistema deve: - salvare automaticamente gli allegati Gmail in Drive; - riprodurre in Drive l’alberatura delle etichette Gmail; - organizzare file e cartelle caricati manualmente; - classificare allegati senza etichetta; - organizzare prudentemente la Inbox; - distinguere email concluse, da gestire e programmate; - evitare duplicati, sovrascritture e perdite; - funzionare tramite trigger anche con il computer spento. CONFIGURAZIONE INIZIALE setup() deve consentire di impostare: - cartella Drive principale; - cartella tecnica; - cartella provvisoria/non classificati; - frequenza dei controlli; - massimo messaggi/file per esecuzione; - data iniziale dell’importazione storica; - modalità conservativa o speculare; - comportamento dei casi dubbi; - regole per mittenti, domini, oggetto, testo e file. Se non viene scelta una root, crea automaticamente una cartella dedicata in “Il mio Drive”. Non incorporare ID nel codice. FOGLIO CONFIGURAZIONE Crea almeno le schede: - Impostazioni - Regole Gmail - Regole Drive - Errori - Allegati - Attività “Regole Gmail” deve contenere almeno: mittente esatto, dominio, regex, parole oggetto, parole testo, azione, etichetta destinazione, mantenimento/rimozione Inbox, priorità, eccezioni, attiva/disattiva. Azioni supportate: - lascia invariata; - applica etichetta; - applica etichetta e archivia; - mantieni in Inbox come attività; - sposta nel Cestino; - segnala per revisione; - proponi disiscrizione. “Regole Drive” deve contenere almeno: nome/regex file, MIME type, parole chiave, eventuale mittente collegato, percorso destinazione, priorità, soglia di confidenza, attiva/disattiva. SINCRONIZZAZIONE GMAIL → DRIVE Usa Gmail Advanced API v1 e lavora sui singoli messaggi, non solo sulle conversazioni. Per ogni messaggio: - considera le etichette personali realmente applicate; - ignora Spam, Cestino e Bozze; - rileva gli allegati reali; - escludi firme, loghi e immagini inline/incorporate; - assegna un nome sicuro agli allegati senza nome; - conserva metadati: messageId, attachment/part ID, mittente, data, oggetto e nome originale; - conserva fisicamente un solo originale tecnico; - crea shortcut/collegamenti nelle cartelle corrispondenti alle etichette. Un’etichetta Gmail come: Categoria/Cliente/Progetto deve produrre in Drive: Categoria → Cliente → Progetto Gli allegati senza etichette personali devono andare nella cartella provvisoria configurata. DEDUPLICAZIONE Non deduplicare mai solo in base al nome. Usa almeno: - Gmail message ID; - attachment ID o MIME part ID; - SHA-256; - dimensione; - marker tecnico/indice associato al file Drive. Lo stesso allegato deve essere conservato fisicamente una sola volta anche se associato a più etichette, usando collegamenti dove necessario. IMPORTAZIONE STORICA E SINCRONIZZAZIONE INCREMENTALE Importa progressivamente Gmail dalla data configurata. Implementa: - batch; - checkpoint persistenti; - continuazioni automatiche; - Gmail History API; - recupero quando historyId è scaduto; - gestione page token non validi; - retry con exponential backoff; - registro persistente degli errori; - rispetto dei limiti di esecuzione/quota; - LockService; - ripresa automatica dopo interruzioni. Ogni operazione deve essere idempotente: rieseguire una funzione non deve duplicare o corrompere dati. CLASSIFICAZIONE SENZA ETICHETTA Per elementi non classificati analizza: - mittente e destinatari; - oggetto; - snippet/anteprima; - nomi allegati; - etichette esistenti; - regole configurate. Se la corrispondenza supera la soglia configurata: - crea l’etichetta Gmail se manca; - applicala al messaggio; - crea/sposta il collegamento Drive; - aggiorna l’indice. In caso di parità di priorità, regole in conflitto o confidenza insufficiente, non decidere arbitrariamente: lascia l’elemento tra i non classificati e segnala la revisione. GESTIONE FILE CARICATI MANUALMENTE IN DRIVE Controlla periodicamente la root configurata. Escludi: - cartelle tecniche; - shortcut; - file già gestiti dallo script; - cartelle protette definite dall’utente; - elementi già indicizzati. Per classificare usa, quando disponibili: - nome ed estensione; - MIME type; - descrizione; - porzione del contenuto testuale; - hash; - regole Drive; - corrispondenze con allegati già indicizzati. Se la destinazione è sicura, sposta l’originale senza crearne copie e conservando ID, cronologia, permessi e link condivisi. Non eliminare file. Registra lo spostamento in modo che sia reversibile con rollback. GESTIONE INBOX La gestione deve essere configurabile e prudente. Prevedi almeno: - transazione/ordine; - newsletter; - notifica automatica; - comunicazione personale; - attività da svolgere; - attività programmata; - caso dubbio. Default: - casi dubbi: restano in Inbox; - richieste operative: possono ricevere etichetta e restare in Inbox; - comunicazioni chiaramente concluse: possono essere archiviate; - newsletter certamente promozionali: possono essere spostate nel Cestino solo se una regola lo consente; - nessuna cancellazione definitiva. Proteggi sempre da archiviazione/cestino automatici, salvo regole esplicite e sicure: - messaggi con stella; - messaggi importanti; - sicurezza/accessi; - pagamenti e ricevute; - documenti amministrativi; - conversazioni a cui l’utente ha risposto; - messaggi con allegati potenzialmente sensibili. REGOLE MITTENTI E NEWSLETTER Non inserire mittenti predefiniti. Le regole devono supportare: - indirizzo esatto; - dominio; - mittente + oggetto; - regex; - priorità; - eccezioni. Qualunque azione di “eliminazione” deve significare esclusivamente spostamento nel Cestino, mai eliminazione definitiva. DISISCRIZIONE NEWSLETTER Riconosci solo meccanismi ufficiali: - List-Unsubscribe; - List-Unsubscribe-Post: List-Unsubscribe=One-Click; - meccanismi ufficiali equivalenti esposti da Gmail/API. Non aprire automaticamente link generici nel corpo. Default: 1. identifica la newsletter; 2. registrala in un report; 3. proponi la disiscrizione; 4. eseguila solo dopo conferma esplicita dell’utente. Non confondere comunicazioni promozionali con sicurezza, amministrazione o transazioni dello stesso servizio. GESTIONE ATTIVITÀ Usa la Inbox come stato predefinito “da gestire”. Consenti etichette personalizzabili equivalenti a: - Attività/Da fare - Attività/In corso - Attività/Programmate - Attività/Completate Un’email archiviata non è automaticamente completata se possiede ancora un’etichetta di attività aperta. Non inventare scadenze. Considera “programmata” un’attività solo se esiste una data esplicita nel messaggio, nel foglio Configurazione o, se integrato e autorizzato, nel calendario. TRIGGER Crea trigger separati e configurabili per: - sync Gmail–Drive; - manutenzione Drive; - classificazione non classificati; - organizzazione Inbox; - continuazione backfill storico; - retry delle esecuzioni saltate. Non creare trigger duplicati. Se LockService segnala un’altra esecuzione attiva, termina in sicurezza e pianifica un nuovo tentativo senza moltiplicare trigger. FUNZIONI PUBBLICHE MINIME Implementa almeno: setup() creaConfigurazione() dryRun() syncGmailAttachments() continueHistoricalBackfill() classificaSenzaEtichetta() archiviaFileRoot() manutenzioneDrive() organizzaInbox() installaTrigger() rimuoviTriggerDuplicati() verificaPermessi() stato() rollback() dryRun() deve effettuare una ricognizione in sola lettura e mostrare chiaramente cosa verrebbe modificato senza spostare file, creare/rimuovere etichette, archiviare o cestinare messaggi, creare shortcut operative o modificare dati. stato() deve mostrare almeno: - avanzamento importazione storica; - ultima sincronizzazione; - errori recenti; - elementi in attesa; - file non classificati; - email da riesaminare; - trigger installati; - attività aperte. MANIFEST E PERMESSI Genera appsscript.json con runtime V8, timezone configurabile, Gmail Advanced Service v1, logging Cloud/Stackdriver e solo gli OAuth scope realmente necessari per Gmail, Drive, Sheets e ScriptApp. Documenta chiaramente come abilitare i servizi avanzati richiesti. SICUREZZA E ROBUSTEZZA Il progetto deve: - essere idempotente; - non eliminare definitivamente email/file; - non sovrascrivere file; - non duplicare cartelle, shortcut o trigger; - prevenire formula injection nei fogli; - sanificare nomi cartella/file e proteggere nomi tecnici; - registrare operazioni, errori e decisioni; - supportare rollback degli spostamenti Drive; - lasciare invariati i casi ambigui; - chiedere conferma per azioni esterne come disiscrizioni; - usare LockService; - gestire eccezioni, quote, timeout e retry senza perdita di stato. INSTALLAZIONE SICURA Il primo avvio deve seguire questa sequenza: 1. installazione codice; 2. autorizzazione API; 3. setup(); 4. creazione Configurazione; 5. ricognizione in sola lettura; 6. dryRun(); 7. report delle operazioni proposte; 8. eventuale modifica delle regole; 9. nuovo dry-run; 10. attivazione volontaria dei trigger; 11. sincronizzazione reale. Non modificare Gmail o Drive automaticamente durante il primo setup prima che l’utente abbia potuto controllare il dry-run. OUTPUT RICHIESTO Fornisci: 1. progetto Apps Script completo e funzionante, suddiviso in più file .gs se utile; 2. appsscript.json; 3. ISTRUZIONI.md; 4. struttura/modello del foglio Configurazione; 5. test automatici o funzioni di test ripetibili; 6. procedura di installazione; 7. procedura dry-run; 8. procedura rollback; 9. guida semplice per utenti non tecnici. Non usare pseudocodice, TODO o funzioni vuote. Tutte le funzioni dichiarate devono essere implementate realmente. Commenta il codice nei punti critici e indica eventuali limiti tecnici delle API Google invece di simulare funzionalità non disponibili.