netgescon-day0/docs/manuals/MODULO-FE-UNIFICATO-SOGGETTI.md

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/<codice_univoco>/fe/ricevute/stabili/<stabile>/inbox/<Y/m>.
• 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:<id_fattura_elettronica>.
• 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:<id>.
• 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.