# 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///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 `//dbc/Fornitori.mdb`. La pagina `admin-filament/contabilita/prima-nota` espone l'azione `Aggiorna da legacy`, basata sul comando: ```bash php artisan gescon:sync-operazioni-prima-nota --stabile-id= --year= --tipo=all --dry ``` Regole operative: - le righe arrivano da `gescon_import.operazioni` e vengono sincronizzate in `contabilita_registrazioni` con `external_reference = OPERAZIONE_LEGACY:`; - 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=` - `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: ```bash 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