151 lines
10 KiB
Markdown
Executable File
151 lines
10 KiB
Markdown
Executable File
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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
|