# Passaggio di consegne - gestione documentale e import ex novo GESCON ## Stato di partenza Al `2026-05-27` la DEMO su `.157` e nuovamente utilizzabile per test reali. Chiusura problema accesso: - il blocco login non era dovuto alle credenziali; - il guasto reale era un passaggio da `https` a `http` durante il flusso web; - corretto questo punto, la DEMO puo tornare a essere usata per prove con utenti esterni. Conseguenza pratica: - la DEMO deve ora diventare ambiente di raccolta bug e osservazione del comportamento reale su dati inseriti da terzi; - i prossimi sviluppi vanno agganciati a questo uso concreto, non solo a prove isolate da sviluppatore. ## Obiettivo immediato Riprendere i primi due moduli su cui tornare a lavorare: 1. gestione documentale con modulo iniziale di carico documenti; 2. importazione ex novo da GESCON con test passo-passo su dati nuovi. ## Modulo 1 - carico documenti ### Scopo del test import Creare una sezione in cui registrare il materiale documentale che arriva, distinguendo almeno: - lotti o consegne ricevute; - cartelline/faldoni fisici da etichettare; - documenti gia digitali da caricare in archivio; - documenti cartacei da digitalizzare o classificare in un secondo passaggio. ### Primo perimetro funzionale Il primo rilascio non deve provare a risolvere tutto l archivio. Deve coprire almeno questi passaggi: 1. registrare una consegna documentale con data, provenienza, note e responsabile; 2. generare un elenco dei documenti o fascicoli presi in carico; 3. stampare etichette per faldoni e cartelline; 4. associare progressivamente i documenti digitali al loro contenitore logico; 5. lasciare tracciato cosa e stato solo ricevuto, cosa e stato etichettato e cosa e stato gia caricato nel sistema. ### Etichette gia da riusare Nel codice esistono gia riferimenti utili per la stampa DYMO: - formato `99014`; - formato `11354`; - controller di stampa/calibrazione gia presenti per il ramo documentale. Questa parte va riusata, non reinventata. Target pratico: - usare `99014` e `11354` per etichettare faldoni, cartelline e contenitori dei documenti ricevuti; - mantenere la possibilita di calibrazione stampa, perche sui driver DYMO ci sono gia state differenze pratiche da gestire. ### Dati minimi da gestire nel primo step - identificativo consegna; - stabile o soggetto di riferimento, se gia noto; - tipologia contenuto; - stato del lotto: ricevuto, da etichettare, etichettato, da caricare, caricato; - numero contenitori/documenti; - note operative e anomalie. ## Modulo 2 - import ex novo da GESCON ### Scopo operativo Fare una prova completa di importazione su dati nuovi, senza dare per scontato che la pipeline funzioni solo perche ha gia importato archivi storici in passato. L idea e: - inserire dati nuovi o usare un set nuovo di archivi GESCON; - importare passo passo; - osservare cosa succede in ogni step; - fermarsi sui bug reali che emergono da input concreti. ### Base tecnica gia presente Il progetto ha gia: - database staging `gescon_import`; - pagina Filament `ImportazioneArchivi`; - pipeline `gescon:import-full`; - import mirati e servizi di supporto per staging e sincronizzazione dominio; - mount legacy standard su `/mnt/gescon-archives/gescon`. ### Procedura da testare La prova iniziale deve restare disciplinata: 1. verificare `gescon_import` attivo e pulizia del contesto di test; 2. preparare il nuovo set di dati/archivi da importare; 3. caricare prima in staging; 4. verificare l esito intermedio prima di sincronizzare nel dominio; 5. eseguire poi i passaggi di sincronizzazione utili; 6. controllare subito cosa si e creato, cosa manca e cosa e incoerente; 7. trasformare ogni anomalia vera in bug tracciato o fix documentato. ### Stato operativo gia corretto sul ramo import stabile Sulla pagina `ImportazioneArchivi` il flusso di lavoro per il primo stabile e stato riallineato per lavorare nella stessa blade: - caricamento setup inline da `Stabili.mdb` o staging `gescon_import.stabili`; - creazione o aggiornamento dello stabile locale senza duplicazioni; - rimozione della cassa `CDL` e mantenimento della sola `CON`; - creazione/aggiornamento del conto bancario vero in `dati_bancari` usando `banca_principale` e `iban_principale` ma preservando `legacy_cod_cassa` reale da `Anagr_casse`; - prima gestione ordinaria configurabile inline con mesi rate e toggle riscaldamento; - import gestioni con mesi letti solo da `Stabili.mdb`, senza fallback ai dati rate del `singolo_anno.mdb`. Caso gia verificato: - stabile legacy `0026`; - banca principale `Monte dei Paschi di Siena` con IBAN `IT58P0103003203000001300987`; - una sola cassa locale `CON`; - conto bancario locale con `legacy_cod_cassa = CCB` e `numero_conto = CCB`; - una gestione ordinaria `2026` con mesi rate `[1,5,9]`. ### Validazione chiusa della prima base import su 0026 Verifiche concluse sul primo blocco fondamentale prima della contabilita: - `23` unita immobiliari importate; - `23` diritti di proprieta al `100%`; - `4` locazioni; - `8` tabelle millesimali; - `171` righe in `dettaglio_importi_tabella`; - `92` righe effettive in `dettaglio_millesimi`; - `46` voci spesa; - totale `importo_default = 15108.00`. Chiarimento sui soggetti: - il dominio collega `21` soggetti distinti, non `27`; - il dato e corretto perche il legacy contiene `23` righe proprietario e `4` righe inquilino ma non `27` persone uniche; - in `0026/0001` i proprietari distinti sono `18`, gli inquilini distinti sono `4`, con sovrapposizione tra almeno una anagrafica proprietario/inquilino. Chiarimento sui comproprietari: - la tabella `Comproprietari` nel sorgente `0026/0001/singolo_anno.mdb` ha `0` righe; - quindi in questo specifico archivio non esiste ancora una serie legacy da cui ricavare percentuali frazionate di comproprieta; - il codice di import e gia predisposto a leggerle quando il sorgente le conterra davvero. QA finale di questa fase: - comando: `php artisan netgescon:qa-millesimi-spese --stabile=0026 --anno=0001`; - esito: conteggi base riallineati su `8` tabelle, `92` righe millesimali, `171` righe importi, `46` voci e totale `15108.00`, ma il QA continua a segnalare warning da chiudere prima del via libera contabile; - `ACQUA`, `INDIV.`, `RI.ASS` e `RIPART` restano tabelle legacy attese senza righe millesimali positive nello snapshot corrente; - i frazionamenti legacy ora risultano `Fraz_gen=8`, `fraz_dett=22` nello staging attuale, quindi prima del via libera contabile va ancora verificato l aggancio `Z01`/`Z02`; - restano anche codici tabella presenti in staging ma non ancora portati a dominio (`CONG.R`, `RISC.L`, `RISC.`, `RISC.O`, `CONG.O`, `TABADL`, `L01.ST`, `L02.ST`, `L03.ST`, `P01.ST`, `TABASL`, `MED01`, `L04.ST`). Aggiornamento importante dopo il riallineamento dello staging e del dominio: - `gescon_import` per `0026/0001` ora riflette `8` tabelle e `46` voci legacy; - il dominio `0026` e stato riallineato sullo slice `millesimi + voci` con le nuove intestazioni `REND.` e `RI.ASS`; - `voci_spesa.meta_legacy` conserva ora la semantica minima indispensabile per il prosieguo contabile: tabella legacy di provenienza, flag `Fondo`, percentuali `C/I`, tipo gestione, eventuale numero straordinaria. - il fix sul pipeline `gescon:import-full` ora vincola davvero `millesimi` e `voci` a `cod_stabile + legacy_year`, deduplica righe staging replicate e impedisce che tabelle header-only come `ACQUA` gonfino il dominio. - per `ACQUA` il comportamento corretto non e piu “tenere il ruolo C a zero”, ma “tenere una sola riga operativa per unita scegliendo il ruolo con importo reale”: su `0026/0001` e stato verificato `id_cond 1 -> C 204.76` e `id_cond 2 -> I 154.76`. - la sorgente canonica delle unita (`condomin`) per `0026/0001` risulta pulita: `23` righe e `23` `cod_cond` distinti; la duplicazione riscontrata in questo giro riguarda `dett_tab` e `voc_spe`, non le unita immobiliari. Aggiornamento operativo sui fornitori per `0026`: - lo stabile `0026` appartiene a `amministratore_id = 3`; - il tenant `3` era quasi privo di fornitori legacy, quindi il solo fatto che `cod_forn` esistesse in altri tenant non era sufficiente per usare contabilita reale; - eseguito import reale: `php artisan gescon:import-fornitori-legacy 3 --mdb=/mnt/gescon-archives/gescon/dbc/Fornitori.mdb`; - esito finale sul tenant corretto: `363` fornitori con `cod_forn` valorizzato e `363` codici distinti. Semantica fissata per il KB operativo: - `RIPART`: una voce `Zxx` rappresenta una spesa unica da suddividere su piu voci reali (`fraz_gen` + `fraz_dett`) fino al `100%`; - `INDIV.`: riparto individuale basato prima sulle percentuali della voce e poi sui valori occupante/unita; - `REND.`: rendite condominiali, con ponte operativo verso l unita `cod_cond 18` (`APP. CONDOMINIALE`) e la procedura affitti gia prevista; - `RI.ASS`: rimborsi assicurativi, da trattare con attenzione per possibili residui sporchi del legacy su stabili nuovi; - `Fondo`: non va piu perso in import, ma conservato nel dominio per la futura contabilita in partita doppia. Aggiornamento operativo su situazione iniziale e passaggio consegne: - `CONG.O` e la tabella legacy dei conguagli ordinari iniziali e va letta da `dett_tab` del `singolo_anno.mdb`; - nella blade `Contabilita > Situazione iniziale > Conguagli` vanno mantenute tutte le righe `C/I`, anche a zero, per non perdere il tracciamento per singola unita; - `FONDI` sono esposti come bucket separato nella situazione iniziale e non vanno piu assorbiti dentro i debiti; - il disallineamento trovato su `0026/0001` non era nel legacy ma nello staging: il raw MDB conteneva `CONG.O`, mentre il preflight non ricaricava slice gia esistenti anche se incompleti; - con il nuovo `refresh-slice` su `gescon:load-mdb`, il reload scoped di `dett_tab` ha riallineato `0026/0001` a `244` righe totali, con `27` righe `CONG.O` realmente presenti in staging. Aggiornamento operativo su saldi, rate ed emissioni: - `s_cassa` del `singolo_anno.mdb` e ora caricabile in staging su `gescon_import.s_cassa`, con i campi `s_ordin_euro`, `s_riscald_euro`, `s_straord_euro` e `n_stra` preservati per `cod_stabile + legacy_year`; - la blade `Gescon > Importazione archivi` carica ora anche `s_cassa` quando aggiorna lo staging annuale insieme a `operazioni`, `voc_spe` e `tabelle`; - il pipeline preflight ricarica anche `s_cassa` nello slice annuale, quindi la situazione iniziale puo usare il saldo reale della gestione senza fallback; - `rate` del `singolo_anno.mdb` restano il credito verso l unita/soggetto, mentre `emes_gen` e `emes_det` del `generale_stabile.mdb` restano la sorgente delle emissioni inviate e del loro dettaglio di calcolo. Aggiornamento operativo su archivio fisico/digitale: - il path canonico per i documenti di stabile resta `storage/app/private/amministratori//stabili/`; - durante il load MDB viene ora creata anche la cartella canonica dello stabile se manca, cosi import documentale e backup partono da una base coerente per amministratore e stabile; - la documentazione va considerata sempre doppia: digitale per ricerca e workflow, fisica per obbligo archivistico e reperimento materiale; - il sistema deve quindi poter rispondere sia a `dammi il file` sia a `dimmi in quale faldone/scaffale si trova`, con conservazione minima operativa di `10 anni`. Aggiornamento operativo su anagrafica unica e comunicazioni: - sullo stabile `0021` i campi `cumulo_cond` e `cumulo_inq` sono risultati ampiamente presenti e ripetuti su piu unita, quindi sono una chiave reale di raggruppamento e non un dettaglio accessorio del legacy; - i casi rilevati includono gruppi proprietario e inquilino con recapiti non perfettamente identici tra le unita, quindi la deduplica per nome non e sufficiente; - l import ora conserva nel `legacy_payload` di `unita_immobiliare_nominativi` i `cumulo_*`, i recapiti raw, la `PEC`, `E_lostesso_Di` e il contesto anagrafico legacy del nominativo collegato all unita. Conseguenza pratica per le prossime lavorazioni: - l anagrafica unica puo continuare a deduplicare persone e ruoli, ma il raggruppamento comunicazioni dovra usare anche la semantica `cumulo_*` preservata sul legame con l unita; - per i contatti multipli la rubrica da sola non basta ancora, perche `rubrica_universale` espone solo campi primari mentre il multi-valore vive in `rubrica_contatti_canali` e nel ramo `PersonaEmailMultipla`. ### Check minimo da ripetere da zero 1. leggere `Stabili.mdb` e verificare `ORD_RATA_x` / `RIS_RATA_x` per lo stabile target; 2. leggere `generale_stabile.mdb` e verificare la tabella `anni`; 3. leggere `Anagr_casse` dal `singolo_anno.mdb` e annotare i codici legacy reali; 4. caricare staging e verificare che `gescon_import.anag_casse` abbia le stesse righe/codici; 5. eseguire la stessa blade `ImportazioneArchivi` e verificare il dominio: - `casse`: solo `CON` se il resto sono conti bancari; - `dati_bancari.legacy_cod_cassa`: codice reale tipo `CCB`; - `gestioni_contabili`: mesi per gestione coerenti con `Stabili.mdb`. ### Cosa osservare con attenzione - duplicazioni; - mapping incompleti; - dati importati in staging ma non propagati nel dominio; - regressioni sulle relazioni tra stabili, unita, soggetti, documenti e gestioni; - differenza tra percorso Linux archivio e caricamenti manuali da upload. ## Uso DEMO con persone esterne La DEMO va usata come ambiente di prova reale ma controllato. Regole consigliate: 1. usare account demo dedicati e riconoscibili; 2. distinguere i dati di test esterni dai dati demo persistenti di base; 3. annotare subito flusso seguito, input inserito e bug osservato; 4. non far eseguire import distruttivi o non tracciati senza supervisione; 5. ogni bug emerso da utente esterno va riportato in `docs/` se diventa ripetibile o operativo. ## Ordine di lavoro consigliato 1. consolidare nel KB e nei runbook la chiusura del problema login DEMO; 2. aprire il primo cantiere sul modulo di carico documenti; 3. riusare la stampa etichette DYMO gia presente per faldoni/cartelline; 4. definire il flusso minimo di upload documenti digitali in archivio; 5. avviare il test di import ex novo GESCON in staging; 6. registrare bug reali emersi durante inserimento dati e importazione. ## Output atteso del prossimo passaggio Il prossimo handoff tecnico dovrebbe consegnare almeno: - struttura del modulo di carico documenti; - punto di integrazione con stampa etichette `99014` e `11354`; - checklist operativa del primo test di import GESCON; - lista iniziale dei casi di prova per utenti esterni sulla DEMO.