# MODULO FE UNIFICATO PER SOGGETTI ## Scopo Definire un modulo unico per la gestione delle fatture elettroniche ricevute, con regole comuni di parsing e aggancio dati, ma con archivi separati e attivazione distinta per soggetto. ## Principio operativo - Il motore FE e unico: parsing XML/P7M, deduplica, aggancio anagrafico, estrazione righe e seriali. - Cambia il soggetto che richiede il modulo: amministratore oppure fornitore. - Cambia anche il contenitore archivio dei file sorgente, per evitare mescolanze tra archivi amministratore/stabile e archivi fornitore. ## Regole di identificazione FE ### Cedente / prestatore - Chiave primaria: P.IVA del fornitore emittente. - Fallback: codice fiscale del fornitore. ### Destinatario / cliente che riceve la FE - Chiave primaria: P.IVA destinatario. - Altri identificativi ammessi: codice fiscale destinatario, codice destinatario SDI, PEC destinatario. ## Soggetti supportati ### Amministratore - Archivio FE: area amministratore/stabile gia esistente. - Sorgenti base: upload manuale. - Sorgente aggiuntiva: Cassetto Fiscale solo se abilitato da contratto/licenza. - Flag attuale contratto: `amministratori.fe_cassetto_enabled`. ### Fornitore - Archivio FE: area dedicata fornitore. - Path canonico: `fornitori//fe/ricevute/stabili//inbox/`. - Sorgenti configurabili: upload manuale, PEC, Cassetto Fiscale, altro gestionale. - Flag modulo: `fornitori.fe_features.invoice_import.enabled`. - Sorgenti abilitate: `fornitori.fe_features.invoice_import.sources`. ## Separazione archivi - Il pannello amministratore continua a salvare nei path storici dello stabile. - Il pannello fornitore salva i file FE solo nel proprio archivio dedicato. - L import FE resta universale ma il file store sorgente resta distinto per soggetto. ## Estrazione seriali da FE - I seriali vengono estratti dal modulo catalogo/seriali FE quando la descrizione riga contiene identificatori compatibili. - I seriali FE vengono salvati con `source_reference = fe:`. - Questo consente ricerca prodotto e risalita immediata alla FE origine. ## Pipeline operativa fornitore La pipeline operativa da adottare per i fornitori e questa: 1. FE -> acquisizione dati fornitore. 2. Aggancio o creazione automatica di anagrafica unica (`rubrica_universale`) e scheda `fornitori`. 3. Importazione prodotti nel catalogo interno unificato. 4. Importazione e aggancio seriali alle schede prodotto. ### Acquisizione automatica fornitore da FE - Quando l import FE trova un fornitore non ancora censito per l amministratore, il motore puo creare automaticamente: - la voce in anagrafica unica `rubrica_universale`; - la scheda `fornitori` collegata alla rubrica; - i dati base di contatto e pagamento trovati nella FE. - La FE resta quindi il primo punto di ingresso per costruire una scheda fornitore completa e riusabile. ### Importazione prodotti - L import prodotti si appoggia al catalogo unificato `products` con identificativi separati in `product_identifiers` e offerte in `product_offers`. - I codici FE e listino vengono conservati come identificativi, privilegiando quando possibile il vero codice fornitore. - I fornitori master con alias storici devono leggere il catalogo usando la scope aggregata `catalogScopeSupplierIds()`. ### Importazione seriali - I seriali restano trasversali al prodotto ma con provenienza tracciata. - Da FE: `source_reference = fe:`. - Da assistenza o altre sorgenti: `source` e `source_reference` dedicati. ## FOCELDA come modello base catalogo - Per il catalogo prodotti base, FOCELDA e oggi il modello piu ricco tra i listini gestiti. - Il suo CSV porta: - `Marca` come radice naturale dei filtri; - gerarchia `Linea > Gruppo > Famiglia`; - `EAN` utile sia per ricerche mirate interne sia per confronti Amazon; - link pagina prodotto e link immagini; - materiale utile all internalizzazione di immagini e documenti. - Per questo motivo il modello FOCELDA va considerato base per: - tassonomia filtri prodotto; - ricerca per EAN; - ingestione multi-immagine; - collegamento a PDF e risorse produttore. ### Aggiornamento remoto FOCELDA - La scheda fornitore puo salvare un `catalog_import.remote_csv_url`. - Questo permette di scaricare e aggiornare il listino direttamente dal link remoto del fornitore senza passaggi manuali sul file locale. - I link fornitore restano interni al gestionale e non vanno esposti nelle viste pubbliche. ## Stato attuale implementato - Separazione archivio FE fornitore completata. - Base del modulo unico FE per soggetto completata. - Gating sorgenti FE lato UI completato: - amministratore: upload manuale sempre disponibile, Cassetto Fiscale solo se attivo; - fornitore: modulo attivabile/disattivabile e sorgenti configurabili da scheda fornitore. ## Procedure operative ### Attivare FE su fornitore 1. Aprire la scheda fornitore. 2. Entrare in Impostazioni FE. 3. Attivare Modulo FE fornitore attivo. 4. Selezionare le sorgenti ammesse. 5. Salvare. ### Attivare Cassetto Fiscale su amministratore 1. Super Admin configura il servizio Cassetto Fiscale. 2. Abilitare il flag contratto/licenza per l amministratore. 3. Il pannello FE mostra automaticamente le azioni Cassetto Fiscale. ### Controllare scarichi e copertura Cassetto - Nella pagina `admin-filament/contabilita/fatture-ricevute`, tab Scarichi da Cassetto Fiscale, il riepilogo mostra per anno: totale dichiarato dal Cassetto, file XML/P7M nel pacchetto, FE presenti in archivio locale, righe Lista AdE e differenza da verificare. - Ogni trimestre puo essere visto in modalita Schede oppure Tabella desktop. Entrambe mostrano stato, conteggi e barra di avanzamento; la tabella usa meglio lo spazio FHD, mentre le schede restano piu adatte a schermi piccoli. - Durante lo scarico il log passa da `queued` a `started/downloaded/importing/ok` e aggiorna importate, duplicate ed errori. - Un trimestre diventa `COMPLETO` solo quando l'archivio FE locale copre il massimo tra riepilogo Cassetto, file scaricati e Lista AdE distinta. Se il pacchetto e lavorato ma l'archivio locale e inferiore, resta `VERIFICA` e il pulsante diventa `Ricontrolla` per forzare un nuovo controllo senza saltare il periodo. - Se `amministratori.fe_cassetto_enabled` e spento, la pagina mostra un avviso rosso e i pulsanti di scarico sono disabilitati; lo storico locale resta consultabile. ## Note KB - Il KB deve distinguere sempre tra: - motore FE universale; - attivazione per soggetto; - archivio separato per soggetto; - sorgenti abilitate per soggetto. - Per il flusso fornitore il KB deve ricordare anche la sequenza operativa canonica: - FE -> anagrafica unica e scheda fornitore; - catalogo prodotti; - seriali; - asset interni e listino remoto quando disponibili.