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>/<anno>/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 `C`rediti e `D`ebiti;
- `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