netgescon-day0/docs/INTEGRAZIONE-CONTABILE.md

Integrazione contabile operativa

Riconciliazione banca MPS

La pagina Contabilita > Casse e banche > Movimenti non e piu solo una vista di suggerimenti. La coda di riconciliazione ora puo chiudere due casi operativi direttamente dal movimento banca:

• Incasso affitto: il movimento positivo puo essere collegato a un canone aperto del modulo affitti. L'azione crea o completa il record in affitti_canoni_pagati e marca il movimento come riconciliato operativamente.
• Pagamento fornitore: il movimento negativo puo essere collegato a una fattura del modulo contabilita_fatture_fornitori. L'azione genera la prima nota del pagamento, collega il movimento alla fattura e aggiorna o apre la riga nel registro_ritenute_acconto quando la fattura ha ritenuta.

Regole applicate

• I canoni affitto vengono proposti in base a importo, data, inquilino e coerenza con il conto bancario associato all'affitto.
• Le fatture fornitore vengono proposte usando il netto da pagare quando presente, cosi il match resta coerente anche in presenza di ritenuta d'acconto.
• I movimenti riconciliati nel dominio operativo vengono marcati in match_data con un esito esplicito, cosi escono dalla coda anche quando non generano subito una registrazione contabile autonoma.

Base per moduli dichiarativi

Questa slice segue la direzione dei moduli dichiarativi:

• il modulo banca espone una coda operativa e i suoi candidati;
• il modulo affitti chiude i canoni nel proprio dominio senza duplicare logica nella UI;
• il modulo contabilita fornitore mantiene la responsabilita di prima nota, debito fornitore e registro RA.

La regola da mantenere nelle prossime slice e semplice: la pagina di regia riconosce il caso e delega la chiusura all'unita funzionale proprietaria del dominio.

Operazioni legacy GESCON verso Prima Nota

Sorgente autorevole legacy:

• root archivi: /mnt/gescon-archives/gescon
• anagrafiche stabili: /mnt/gescon-archives/gescon/dbc/Stabili.mdb
• fornitori globali legacy: /mnt/gescon-archives/gescon/dbc/Fornitori.mdb
• dati annuali stabile: /mnt/gescon-archives/gescon/<codice_stabile>/<cartella_anno>/singolo_anno.mdb

La pagina admin-filament/gescon/importazione-archivi deve usare sempre il root globale sopra come sorgente. La scelta dell'amministratore determina la destinazione NetGescon/studio, non deve modificare il path sorgente in /<codice_admin>/dbc/Fornitori.mdb.

La pagina admin-filament/contabilita/prima-nota espone l'azione Aggiorna da legacy, basata sul comando:

php artisan gescon:sync-operazioni-prima-nota --stabile-id=<id> --year=<YYYY> --tipo=all --dry

Regole operative:

• le righe arrivano da gescon_import.operazioni e vengono sincronizzate in contabilita_registrazioni con external_reference = OPERAZIONE_LEGACY:<id_operaz>;
• il comando importa solo righe scoperte sullo stabile (cod_stabile uguale a stabili.codice_stabile o stabili.cod_stabile); se non trova righe scoperte non importa record con cod_stabile nullo, per evitare contaminazioni tra stabili;
• operazioni.cod_spe viene risolto su voci_spesa.legacy_codice o voci_spesa.codice, preferendo la gestione contabile risolta;
• operazioni.cod_for viene risolto sul fornitore dell'amministratore usando prima fornitori.cod_forn, poi fornitori.old_id; questo evita il vecchio equivoco tra codice fornitore operativo e id legacy;
• quando possibile viene creata anche una riga contabilita_movimenti collegata alla registrazione, con voce_spesa_id e metadata legacy (id_operaz, cod_spe, cod_for, tabella, legacy_year).

Esempio verificato:

• per lo stabile 0021 (id=25, codici 0021/148) sono stati caricati da storage/app/amministratori/HWFGITXK/legacy/0021/0001/singolo_anno.mdb e 0003/singolo_anno.mdb complessivamente 309 record operazioni scoperte;
• il sync reale su 0021 ha prodotto 309 registrazioni Prima Nota legacy e 284 movimenti; 25 registrazioni non hanno movimento per importo nullo/non significativo;
• tutte le righe movimento create hanno voce_spesa_id valorizzata; 196 movimenti hanno anche fornitore risolto nei metadata, mentre 88 restano senza fornitore per cod_for=0 o codici non presenti nello scope amministratore;
• i codici fornitore non devono essere risolti pescando da altri amministratori: se cod_for manca nello scope corretto, resta da bonificare/importare nel tenant dell'amministratore;
• per lo stabile 0016 (id=17) il dry-run 2026 rileva 54 operazioni, 48 voci collegabili e 41 fornitori collegabili.

Questa sincronizzazione e una base di controllo: la partita doppia definitiva resta responsabilita della Prima Nota e dei servizi contabili dedicati, ma la provenienza legacy viene resa consultabile e riconciliabile nello stesso archivio operativo.

Runbook rapido: import Banca del Fucino su 0016

Questo runbook serve sia all'operatore sia alla mini AI banca/contabilita quando deve caricare estratti Excel legacy in Contabilita > Casse e banche > Movimenti.

Per lo stabile 0016 (GERMANICO 96) il conto corretto usato in questa sessione e:

• stabile_id=17
• conto_id=14
• legacy_cod_cassa=CCB
• iban=IT48W0312403203000000233378

Sorgente validata:

• cartella: /home/michele/netgescon/netgescon-day0/Miki-Bug-workspace/Banca/germanico 96
• formato reale: file .xls legacy Banca del Fucino
• parser da usare: flusso UI Excel XLS/XLSX

Esito validato in sessione:

• file letti correttamente dal parser Excel senza convertire in CSV
• importati 1935 movimenti reali su contabilita_movimenti_banca
• duplicati scartati automaticamente: 891
• copertura finale conto: 2022-02-03 -> 2026-06-03

Regole operative da mantenere:

• usare sempre il conto/cassa selezionato come ancora dell import, non il solo nome file
• non usare replace se i file sono estratti annuali o parziali sovrapposti; la deduplica applicativa via row_hash gestisce gia i doppioni naturali
• prima della riconciliazione verificare che il movimento banca sia collegabile a un incasso o a una scrittura di pagamento senza forzature
• le scritture legacy incassi e operazioni devono restare filtrate su slice annotate (legacy_year) quando esistono, ignorando i residui storici orfani

Indicazione per mini AI:

• prima legge questo runbook
• poi apre la pagina admin-filament/contabilita/casse-banche/movimenti
• seleziona conto_id=14
• usa formato Excel XLS/XLSX
• importa i file della cartella germanico 96
• controlla a fine import: numero righe, range date, duplicati scartati, movimenti non riconciliati rimasti in coda

Chiamata mini AI .202 per riconciliazione incassi

Il primo collaudo operativo deve essere read-only e basato sugli incassi reali gia importati da singolo_anno.mdb.incassi, non su scritture automatiche.

Configurazione NetGescon:

• MINI_AI_ENABLED=true
• MINI_AI_BASE_URL=http://192.168.0.202:8000
• MINI_AI_RECONCILIATION_PATH=/api/v1/reconciliation/incassi
• MINI_AI_TOKEN=<token se richiesto dalla macchina .202>
• MINI_AI_TIMEOUT=30

Flusso applicativo:

1. L HUB admin-filament/contabilita/incassi costruisce uno snapshot tramite IncassiHubReadService.
2. Priorita sorgenti: incassi_estratto_conto, poi gescon_import.in_da_ec, poi netgescon.incassi importati da singolo_anno.mdb.
3. Per il primo controllo su 0016, oggi la sorgente reale e netgescon.incassi (2102 righe disponibili sul dominio), con candidati movimento letti da contabilita_movimenti_banca.
4. Il pulsante Invia a mini AI o il comando artisan invia solo payload JSON read-only e salva richiesta/risposta in ai_requests.
5. L operatore deve confermare manualmente eventuali proposte prima di collegare incassi, movimenti bancari o scritture contabili.
6. Nel nuovo HUB operativo la gestione di competenza puo essere spostata manualmente sulla gestione chiusa immediatamente precedente quando la causale banca parla esplicitamente di saldo/conguaglio dell anno prima.
7. I riferimenti del pagante (Coord.Ordinante, Banca Ordinante, BIC, CRO) vanno esposti all operatore e memorizzati sul soggetto confermato per rafforzare i riconoscimenti futuri.
8. Il nominativo mostrato nel blocco C/I deve privilegiare la verita operativa della unita (unita_immobiliari.denominazione) e del condomin legacy prima del collegamento soggetti.old_id, che puo essere storicamente disallineato.
9. Le partite straordinarie aperte non vanno assorbite nel solo elenco ordinario: devono comparire in un bucket dedicato e restare imputabili fino a estinzione completa.
10. Il HUB incassi deve mostrare i parziali del dovuto per bucket (ordinarie, straordinarie), per gestione e il totale generale aperto del C/I; questi numeri sono il riferimento operativo per solleciti e riconciliazione storica.
11. Se un lavoro straordinario risulta presente nelle gestioni (lavori_straordinari) ma non ha righe residue materializzate per il C/I, la UI deve evidenziarlo come anomalia di import e non nasconderlo.
12. Quando la mini-AI propone allocations[], il workspace incassi deve poterle applicare alle rate manuali con un solo comando, cosi l operatore chiude la riconciliazione senza ricopiare i dettagli a mano.

Comandi di collaudo:

php artisan netgescon:mini-ai-incassi --codice-stabile=0016 --limit=2 --dry-run
php artisan netgescon:mini-ai-incassi --codice-stabile=0016 --limit=20

Payload atteso verso .202:

• task = reconcile_incassi_movimenti_bancari
• mode = read_only_suggestions
• snapshot.meta.source = netgescon.incassi per il primo controllo con singolo_anno.mdb.incassi
• risposta richiesta: JSON con summary, warnings, suggestions[]

La mini AI non deve mai scrivere direttamente nel gestionale: restituisce suggerimenti con confidence, suggested_incasso_id, suggested_movimento_id, suggested_action e reason.

Nota operativa stabile 0016:

• la coda incassi operativa lavora sui movimenti compresi nella finestra ordinaria aperta 2024-10-01 .. 2026-09-30
• le rate candidate lato AI e lato operatore restano entro 2024/25, 2025/26 e, quando necessario per competenza, 2023/24
• le straordinarie aperte del C/I selezionato restano visibili separatamente dal bucket ordinario, anche quando derivano da emissioni fuori dalla sola logica mensile ordinaria
• caso diagnostico noto 0016 / A-27: il ledger straordinario ricostruisce ATTO AeR, Ascensore, Facciata; Ripristino corr. semint. sc. A e segnalato come lavoro presente in gestione ma senza riga residua materializzata, quindi da verificare nel flusso di import delle spese straordinarie