netgescon-day0/docs/000-FILAMENT/02-ARCHIVI-E-IMPORT.md

Archivi legacy e import (GESCON)

Archivi da prendere

1) Stabili.mdb

Percorso tipico:

• /mnt/gescon-archives/gescon/dbc/Stabili.mdb

Contiene:

• Anagrafica stabili
• Dati bancari/postali
• Dati catasto
• Scadenze rate ordinarie/riscaldamento
• Parametri FE e PEC

2) Fornitori.mdb

Percorso tipico:

• /mnt/gescon-archives/gescon/dbc/Fornitori.mdb

Contiene:

• Anagrafica fornitori

3) singolo_anno.mdb

Percorso tipico:

• /mnt/gescon-archives/gescon/<cod_stabile>//singolo_anno.mdb

Contiene:

• Unità immobiliari + nominativi (condomin)
• Comproprietari
• Tabelle millesimali (legacy: tabelle)
• Voci spesa
• Dett_tab
• Incassi
• Operazioni
• Straordinarie
• Preventivi straordinari (tabella prevent_straordinari)
• dett_pers (addebiti personalizzati, I05)
• Frazionamenti (fraz_gen / fraz_dett, Z01/Z02)
• tabella Anagr_casse con i codici legacy da preservare per incassi e operazioni

4) generale_stabile.mdb

Percorso tipico:

• /mnt/gescon-archives/gescon/<cod_stabile>/generale_stabile.mdb

Contiene:

• anni
• emes_gen / emes_det
• Fatture legacy
• Dati trasversali

Regola fondamentale anni

Nel legacy i dati sono replicati per ogni anno. Per ricostruire correttamente:

• Importare tutte le annualità per ogni stabile.
• Consolidare in staging con campi legacy_year/legacy_period/legacy_file.

Staging DB (anti-duplicazione)

• DB: gescon_import
• È la sorgente primaria per evitare doppie importazioni.
• Tabelle aggiunte: tabelle_millesimali, dett_pers, fraz_gen, fraz_dett, mdb_fornitori
• Tabelle straordinarie: straordinarie, prevent_straordinari
• Per gescon:import-full --solo=millesimi|voci il filtro operativo corretto deve essere sempre su cod_stabile + legacy_year; in caso di righe staging duplicate dello stesso snapshot, l'import deve deduplicare prima di scrivere nel dominio.

Componenti di import (codice)

UI Filament

• app/Filament/Pages/Gescon/ImportazioneArchivi.php
  • Modalità Linux: path diretto
  • Modalità Windows: upload file/zip + estrazione
  • stessa blade per creare o aggiornare lo stabile selezionato, senza modal
  • sezione inline per banca principale e prima gestione contabile
  • al salvataggio/import normalizza la parte finanziaria usando i codici reali di Anagr_casse
  • la cassa locale resta solo CON; i conti bancari vengono salvati in dati_bancari con legacy_cod_cassa reale (es. CCB)

Comandi staging

• gescon:load-mdb
• import:gescon-mdb
• import:gescon-fornitori
• import:gescon-fatture-legacy

Import movimenti banca (Intesa XLSX)

• Parser XLSX con descrizione estesa (colonna F)
• Salva descrizione_estesa + match_data + flag da_confermare
• Duplicati gestiti con row_hash

Import banca per istituto (regole)

Intesa (XLSX)

• Layout rilevato: A Data, B Valuta, C Descrizione, D Avere, E Dare, F Descrizione estesa
• Import in Casse/Banche → Movimenti

Intesa (CSV)

• Supporto CSV con parser dedicato

Unicredit (WRI)

• Import con parser WRI

Spese bancarie (parole chiave iniziali)

• commissione / commissioni
• spese tenuta conto / canone
• imposta di bollo
• competenze
• spese invio / notifiche
• interessi debitori
• costo bonifico

Nota: l’elenco va aggiornato per ogni banca con termini specifici presenti negli estratti.

Pipeline dominio

• gescon:import-full
• gescon:import-gestioni

Flusso operativo raccomandato dalla stessa blade

Per i nuovi stabili importati da GESCON il flusso raccomandato e:

1. caricare l elenco stabili da Stabili.mdb;
2. selezionare lo stabile e usare Carica setup inline per leggere anagrafica, banca e mesi rate;
3. correggere direttamente nella stessa schermata i campi dello stabile e il setup della prima gestione;
4. usare Salva stabile inline per creare o aggiornare lo stabile locale senza duplicarlo;
5. eseguire Importa dati selezionati oppure Import + allineamento;
6. se serve, rifinire la prima gestione con Salva gestione inline.

Risultato atteso:

• una sola cassa locale CON;
• conto bancario reale del condominio presente in dati_bancari con is_nostro_conto=true;
• legacy_cod_cassa del conto bancario allineato a Anagr_casse del singolo_anno.mdb;
• prima gestione ordinaria creata o aggiornata dalla stessa blade;
• mesi emissione rate letti da Stabili.mdb (ORD_RATA_x, RIS_RATA_x) e memorizzati gestione per gestione;
• nessuna creazione ripetuta dello stesso stabile a ogni passaggio.

Regole sorgente senza fallback

Per il ramo import stabile/gestioni usare queste sorgenti come riferimento:

• codici cassa e banca: Anagr_casse dentro ogni singolo_anno.mdb;
• dati descrittivi e IBAN banca principale: Stabili.mdb / stabili dominio gia sincronizzato;
• mesi rate ordinaria e riscaldamento: Stabili.mdb tramite campi ORD_RATA_x e RIS_RATA_x;
• anni gestione: tabella anni di generale_stabile.mdb; se l archivio non la espone correttamente, usare il dato anno ricavabile dall archivio reale dello stesso stabile, ma non inventare anni sintetici.

Da evitare:

• seeding automatico di CDL;
• codici banca sintetici tipo BANCA-PRINCIPALE;
• mesi rate dedotti da fallback quando il master Stabili.mdb e disponibile.

Verifica base confermata su stabile 0026

Validazione eseguita sulla base legacy:

• condomin = 23;
• Comproprietari = 0 nel file 0026/0001/singolo_anno.mdb;
• tabelle = 8;
• dett_tab = 171;
• voc_spe = 46;
• Fraz_gen = 4;
• fraz_dett = 11.

Esito dominio importato:

• unita_immobiliari = 23;
• proprieta = 23;
• locazioni = 4;
• soggetti distinti collegati = 21.

Nota importante sui soggetti:

• i 23 proprietari attesi sono 23 rapporti di proprieta, non 23 persone uniche;
• nel legacy di 0026 i proprietari distinti sono 18, gli inquilini distinti sono 4, con almeno una anagrafica coincidente tra i due insiemi;
• il risultato 21 soggetti distinti in dominio e quindi coerente con deduplica reale e non con una perdita di record.

Esito millesimi e voci:

• tabelle_millesimali = 8;
• dettaglio_millesimi = 92;
• dettaglio_importi_tabella = 171;
• voci_spesa = 46;
• SUM(importo_default) = 15108.00.

Riallineamento confermato dopo fix import millesimi/voci:

• il pipeline non deve piu accumulare righe da anni/stabili diversi quando si usa --stabile=0026 --anno=0001;
• lo snapshot staging 0026/0001 puo contenere righe replicate x2, quindi l'import deve deduplicare prima di scrivere;
• per tabelle legacy header-only come ACQUA, le righe dett_tab a millesimi 0 non devono gonfiare dettaglio_millesimi;
• per ACQUA, in dettaglio_importi_tabella va mantenuta una sola riga operativa per unita scegliendo il ruolo legacy con importo reale: esempio verificato id_cond=1 -> C 204.76, id_cond=2 -> I 154.76.

QA dedicato:

• comando: php artisan netgescon:qa-millesimi-spese --stabile=0026 --anno=0001;
• esito: conteggi base riallineati (8 / 92 / 171 / 46 / 15108.00), ma restano warning da chiudere prima del via libera contabile definitivo;
• ACQUA, INDIV., REND., RI.ASS e RIPART sono tabelle legacy senza righe dett_tab attive nello snapshot 0026/0001, quindi non vanno trattate come tabelle ordinarie con righe millesimali positive finche il sorgente non le valorizza;
• restano aperti i 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);
• resta da verificare il comportamento contabile di Z01/Z02 prima del via libera finale alla partita doppia, perche i frazionamenti legacy sono presenti in staging.

Situazione iniziale patrimoniale

Regole operative fissate per Contabilita > Situazione iniziale:

• cre_deb_preced resta la sorgente dei valori pregressi da riportare avanti, separati in modo esplicito per Crediti e Debiti;
• CONG.O va letto da dett_tab del singolo_anno.mdb come tabella dei conguagli ordinari iniziali;
• nella tab conguagli vanno mantenute tutte le righe C / I, anche quando cons_euro = 0, per evitare fallback e permettere lo spostamento puntuale del valore sulla singola unita;
• FONDI non vanno piu confusi con i debiti: nella situazione iniziale esiste ora un bucket separato dedicato agli accantonamenti;
• Perc_proprietario e perc_inquilino di voc_spe rappresentano la quota legacy della singola voce per l unita, ma non devono essere usati per ricalcolare importi storici gia emessi nelle rate.

Base contabile condominiale

Impostazione da mantenere nel dominio Day0:

• il piano dei conti universale va tenuto minimale e condominiale, non esteso come una contabilita aziendale completa;
• i gruppi base restano quelli della partita doppia standard: Attivita, Passivita, Patrimonio Netto, Ricavi, Costi;
• i crediti principali sono le quote/rate emesse verso unita e soggetti responsabili (condomino / inquilino), non crediti commerciali generici;
• i debiti principali sono i fornitori e gli altri soggetti che erogano beni o servizi allo stabile;
• la chiusura di gestione non deve cercare utile o perdita ma il conguaglio necessario a coprire i costi sostenuti e chiudere le partite della gestione;
• i fondi restano conti patrimoniali standard di partita doppia (fondo rischi, fondo oneri, fondo ammortamento, fondo riserva, accantonamenti), senza introdurre bucket inventati fuori schema.

Sorgenti legacy da considerare autorevoli nel flusso contabile:

• condomin per unita e occupanti responsabili;
• tabelle + voc_spe per struttura di riparto e voci del piano dei conti operativo;
• rate del singolo_anno.mdb come credito verso l unita/soggetto;
• emes_gen e emes_det del generale_stabile.mdb come intestazioni e dettagli delle emissioni fisiche inviate;
• incassi del singolo_anno.mdb come realizzo del credito emesso, da riconciliare con cod_cassa e poi con i movimenti banca/cassa di dominio;
• s_cassa del singolo_anno.mdb come saldo iniziale delle gestioni (s_ordin_euro, s_riscald_euro, s_straord_euro, n_stra).

Stato reale osservato oggi su 0026/0001:

• il raw singolo_anno.mdb contiene davvero intestazione CONG.O e righe dett_tab per 0026/0001;
• il problema osservato era uno slice staging stantio: il preflight si fermava appena trovava righe gia presenti per stabile + legacy_year;
• dopo il fix refresh-slice sul loader e il reload scoped, gescon_import.dett_tab per 0026/0001 risulta riallineato a 244 righe totali, di cui 27 CONG.O.

Controllo sorgente unita immobiliari su 0026/0001:

• gescon_import.condomin contiene 23 righe e 23 cod_cond distinti;
• non risultano duplicati sulla sorgente unita (condomin) per questo snapshot;
• la duplicazione osservata in questo passaggio riguarda dett_tab e voc_spe, non la sorgente canonica delle unita.

Fornitori legacy sul tenant corretto

Verifica operativa eseguita su 0026:

• lo stabile 0026 appartiene a amministratore_id = 3;
• prima del riallineamento fornitori, il tenant 3 aveva solo 2 fornitori con cod_forn, mentre il catalogo storico principale era stato importato sotto un altro tenant;
• eseguito php artisan gescon:import-fornitori-legacy 3 --mdb=/mnt/gescon-archives/gescon/dbc/Fornitori.mdb;
• esito finale sul tenant 3: 363 fornitori con cod_forn valorizzato e 363 codici distinti.

Conseguenza pratica:

• prima di usare contabilita e scritture legacy su uno stabile reale, verificare sempre che fornitori.cod_forn sia presente nello stesso amministratore_id dello stabile, non solo in qualche altro tenant del dominio.

Semantica operativa delle tabelle speciali legacy

ACQUA

• ACQUA non va letta come tabella millesimale ordinaria da scrivere in dettaglio_millesimi;
• il totale resta in voc_spe, mentre il riparto operativo per unita vive in dett_tab ed e collegato all unita tramite id_cond e al soggetto addebitato tramite cond_inquil (C o I);
• nello staging corrente di 0026/0001 le righe ACQUA sono replicate x2, quindi l import deve deduplicare e poi collassare a una sola riga operativa per unita scegliendo il ruolo con importo effettivo.

RIPART

• RIPART divide una singola voce legacy in piu voci reali di riparto, mantenendo sempre il 100% dell importo originario;
• la sorgente autorevole e la coppia fraz_gen + fraz_dett del singolo_anno.mdb;
• esempio verificato su 0026: Z01 (ACEA: Energia elettrica) viene suddivisa in 825 = 20%, A02 = 40%, B02 = 40%;
• lo stesso criterio vale anche per pesi non percentuali normalizzati come 1-2-2, che rappresentano comunque una divisione integrale dell importo.

INDIV.

• INDIV. non usa una tabella millesimale classica ma una ripartizione individuale su occupanti C / I dell unita immobiliare;
• il primo livello resta la percentuale della voce (Perc_proprietario / Perc_Inquilino in voc_spe);
• il secondo livello dipende dai valori individuali collegati alle unita e alle spese personali (dett_pers, n_spe, occupanti della UI);
• per questo motivo la presenza della sola intestazione INDIV. non implica righe dett_tab valorizzate.

REND.

• REND. gestisce le rendite condominiali da ripartire secondo regolamento, su millesimi o altro criterio definito per lo stabile;
• nello stabile 0026 il riferimento operativo e l unita condominiale cod_cond = 18 (APP. CONDOMINIALE), da usare come ponte verso la gestione affitti gia prevista nel dominio;
• le voci RD* possono essere marcate come Fondo nel legacy e non vanno trattate come semplici ricavi ordinari.

RI.ASS

• RI.ASS rappresenta i rimborsi assicurativi gestiti dall amministratore (RB1..RB5);
• nello snapshot 0026/0001 le intestazioni e le voci sono presenti ma senza dettagli dett_tab, quindi oggi sono considerate non bloccanti per l import base;
• se compaiono importi anomali in uno stabile nuovo, assumere prima una contaminazione del legacy e verificare archivio/storico prima di costruire automatismi di quadratura.

Conservazione della semantica legacy senza fallback

• voci_spesa.meta_legacy conserva almeno legacy_tabella, legacy_is_fondo, legacy_fondo_raw, percentuali legacy e tipo gestione della voce importata;
• questo vale anche per voci come RD1 e RB5, dove il flag Fondo = Si deve restare disponibile al dominio prima del collegamento a partita doppia, FE e banca/posta;
• non inventare dettagli di riparto o fondi nel dominio quando il legacy espone solo intestazioni: importare il dato reale e lasciare tracciata la provenienza.

Cumuli legacy e anagrafica unica

Verifica eseguita su 0021/0001/singolo_anno.mdb:

• gruppi cumulo_cond trovati: 77, di cui 75 con piu unita collegate;
• gruppi cumulo_inq trovati: 191, di cui 21 con piu unita collegate;
• esempi reali confermati: ATER C/O UFFICIO CONDOMINI PASSIVI, MINERVA FRANCESCO, ROSSI ENRICO, MASTRANGELI ALFREDO - GIUFFRIDA STEFANIA.

Conclusione operativa:

• cumulo_cond e cumulo_inq non sono un artefatto di stampa ma una semantica reale di raggruppamento comunicazioni e recapiti;
• la deduplica per solo nominativo non basta, perche nello stesso gruppo esistono casi con email e cellulari parzialmente diversi tra una unita e l altra;
• la chiave di raggruppamento va quindi conservata vicino al legame unita <-> nominativo, non solo ricostruita a valle.

Stato del dominio dopo la patch corrente:

• unita_immobiliare_nominativi.legacy_payload conserva ora anche cumulo_*, recapiti raw, PEC, E_lostesso_Di, indirizzo legacy e altri campi utili del record condomin;
• questo permette di materializzare in modo deterministico i futuri gruppi di comunicazione senza dover riaprire ogni volta il file MDB;
• la rubrica universale continua a essere il contenitore anagrafico principale, ma il legame canonico per la comunicazione multipla deve passare dal rapporto con l unita e non dal solo contatto principale.

Nota sui recapiti multipli:

• rubrica_universale ha ancora campi primari singoli (email, telefono_cellulare);
• i recapiti multipli esistono gia nel progetto tramite rubrica_contatti_canali e, sul ramo persona, tramite PersonaEmailMultipla;
• la normalizzazione finale dei recapiti deve quindi usare questi contenitori strutturati partendo dal payload legacy appena preservato.

Servizi

• app/Services/GesconImport/LegacyArchiveService.php
• app/Services/GesconImport/EssentialImportService.php
• app/Services/GesconImport/StabileEnrichmentService.php