netgescon-day0/skill-netgescon/directives/gestione-posta-imap-webmail-protocollo.md

Direttiva: Gestione Posta IMAP, Webmail Gmail-Style e Protocollo Comunicazioni

1. Obiettivo

Questa direttiva formalizza la gestione omnicanale delle comunicazioni e della posta (Ordinaria e PEC) in NetGescon:

1. Configurazione IMAP Multi-Casella per Stabile: salvataggio dei parametri di connessione (host, porta, crittografia, username, password cifrata/gestita, cartella) nella configurazione avanzata dello stabile.
2. Archiviazione Locale dei file .EML e Allegati: scaricamento e conservazione deterministica del messaggio sorgente integro in storage/app/private/amministratori/{cod_adm}/stabili/{cod_stabile}/posta_{tipo}/{anno}/{msg_id}.eml ed estrazione sicura degli allegati.
3. Ingestion & Matching su DB Relazionale: creazione del record in communication_messages con auto-matching dell'Unità Immobiliare di riferimento tramite riscontro dell'email del mittente con i contatti censiti per l'unità.
4. Interfacce Webmail Stile Gmail:
   • PostaOrdinariaWebmail (/admin-filament/comunicazioni/posta-ordinaria)
   • PostaPecWebmail (/admin-filament/comunicazioni/posta-pec)
   • Layout Gmail con cartelle (In arrivo, Speciali, Inviati, Allegati), barra di ricerca debounce, pill allegati, creazione ticket 1-click, composizione modale e anteprima allegati / documenti integrata.
5. Scheda Unità (unita-immobiliare) - Tab Comunicazioni & Protocollo:
   • Aggregazione multi-sorgente: estratti conto inviati (protoc_ec), circolari/lettere (corrisp_inviata) e messaggi email/PEC (communication_messages).
   • Ordinamento cronologico decrescente rigoroso basato su Unix timestamp (Carbon::parse()).
   • Modal di anteprima visiva rapida di PDF, immagini e testi allegati ai documenti di protocollo.
6. Gestione Fornitori e Ditte Inter-Stabili:
   • Fornitore Nethome SAS (10055221005) configurato e collegato trasversalmente per compensi e fatturazione.
   • Allineamento del codice mnemonico cod_stabile ereditato da Stabili.mdb visibile e indicizzato nell'anagrafica stabili.

2. Architettura File e Namespace

• app/Services/Posta/EmlParser.php: Parser puro PHP per decodifica MIME, multipart, headers e allegati.
• app/Services/Posta/ImapClient.php: Client socket puro PHP SSL/TLS IMAP (porta 993) senza dipendenze binarie libc-client.
• app/Services/Posta/ImapMailboxService.php: Servizio di sincronizzazione, archiviazione .eml e associazione stabile/unità/ticket.
• app/Console/Commands/FetchMailboxesCommand.php: Comando CLI php artisan gescon:fetch-mail.
• app/Filament/Pages/Posta/PostaOrdinariaWebmail.php: Blade Webmail Posta Ordinaria.
• app/Filament/Pages/Posta/PostaPecWebmail.php: Blade Webmail Posta Certificata PEC.
• resources/views/filament/pages/posta/webmail.blade.php: Vista Blade responsive stile Gmail.
• tests/Feature/PostaImapWebmailAndProtocolloTest.php: Suite di test Pest dedicata.