netgescon-day0/docs/000-IMPORT/01-GESCON/GUIDA-IMPORT-GESCON-MDB.md

Guida Import GESCON da MDB

Obiettivo

Usare Stabili.mdb come sorgente di controllo iniziale per decidere quali stabili importare, con una finestra dati prudente e verificabile prima della distribuzione operativa.

Sorgenti da considerare

1. Metadati stabili

• dbc/Stabili.mdb
• campi chiave attesi:
  • cod_stabile
  • nome_directory
  • campo CF stabile/condominio valorizzato

2. Dati annuali per stabile

• <cod_stabile>/<anno>/singolo_anno.mdb
• tabelle minime da validare:
  • condomin
  • operazioni
  • rate
  • incassi
  • dett_tab
  • voc_spe
  • straordinarie

3. Dati trasversali stabile

• <cod_stabile>/generale_stabile.mdb
• utile per verifiche aggiuntive su rate emesse, casse, incassi da estratto conto e dati generali

Regola multi-amministratore verificata 03/06/2026

• Lo stesso codice_stabile deve poter convivere sotto amministratori diversi; la chiave corretta del contenitore dominio non e il solo codice stabile ma almeno amministratore_id + codice_stabile.
• La stessa regola vale per le unita importate: codice_unita non puo restare globale se si vuole importare lo stesso stabile sotto due amministratori distinti.
• Nel dominio DEV e stata verificata la coesistenza di 0026 su due tenant distinti:
  • stabile_id=31 sotto amministratore test 00000000
  • stabile_id=32 sotto amministratore reale HWFGITXK
• Il reimport deve aggiornare il tenant selezionato senza riattribuire lo stabile all'altro amministratore.

Regola sorgenti MDB per contabilita Gescon

• singolo_anno.mdb resta la sorgente annuale per condomin, operazioni, rate, incassi, dett_tab, voc_spe, straordinarie.
• generale_stabile.mdb e la sorgente autorevole per EMES_GEN, EMES_DET e Inc_da_ec / in_da_ec.
• Le tabelle annuali caricate in gescon_import devono sempre portare con se cod_stabile e legacy_year; se la staging proviene da schema storico va eseguito il reload con il loader aggiornato, non un semplice riuso delle righe gia presenti.
• Per operazioni il reload deve essere idempotente su id_operaz: in caso contrario la pagina Filament puo vedere scritture miste o righe non riallineate allo slice reale dello stabile.
• Per in_da_ec il reload deve produrre una staging slice-aware (cod_stabile, legacy_year) e una materializzazione read-only nel dominio (incassi_estratto_conto) con hash stabile del movimento, senza creare incassi applicativi automatici: l abbinamento finale resta umano-assistito.
• Il nuovo HUB operativo e admin-filament/contabilita/incassi: deve mostrare sia incassi dominio sia snapshot legacy in_da_ec con payload pronto per AI interna; lo stesso snapshot e disponibile via GET api/v1/incassi/hub protetto da auth:sanctum.
• Per lo stabile 0026 / anno 0001 e stato verificato che:
  • incassi nel singolo_anno.mdb contiene 0 righe, quindi uno staging vuoto non e un errore di import ma un dato legacy reale.
  • EMES_GEN nel generale_stabile.mdb contiene 3 emissioni.
  • EMES_DET nel generale_stabile.mdb contiene 81 righe dettaglio.
• Le verifiche funzionali attese per 0026 / stabile_id=32 dopo il reload corretto delle sorgenti sono:
  • prima emissione 2026-01-05: totale 5037,00, 24 ricevute distinte
  • seconda emissione 2026-05-05: totale 5037,00, 24 ricevute distinte
  • conguaglio 2026-06-02: totale 1226,27, 24 ricevute distinte
  • ricevuta 24: unita legacy 20-21-22-23 (SEM-A, SEM-B, SEM-C, SEM-D)
• Smoke test reale eseguito il 04/06/2026 su 0026 / anno 0001 / stabile_id=32 / amministratore_id=5:
  • archivio disponibile nel mount GESCON: solo cartella 0001
  • gescon:import-full --stabile=0026 --amministratore-id=5 --anno=1 --path=/mnt/gescon-archives/gescon completa la pipeline senza errori
  • al rerun gli importi rate_emesse restano stabili a 81 righe e somma 11300.27
  • al rerun dati_bancari resta consolidato a 1 riga (CCB, IBAN IT58P0103003203000001300987)
  • gli incassi restano 0, coerenti con il contenuto reale di singolo_anno.mdb

Regole operative di preselezione

Importare nello smoke test solo gli stabili che rispettano tutte queste condizioni:

1. lo stabile esiste in Stabili.mdb
2. il campo CF stabile/condominio e valorizzato
3. cod_stabile e presente e usabile come codice mnemonico principale
4. nome_directory e presente e punta a una cartella archivio esistente

Regola gestioni cross-year e riferimenti emissione

• Per stabili come 0016 l esercizio non va letto come anno solare: la gestione corretta e quella esposta in generale_stabile.mdb -> anni (anno_o, ordinarie_dal, ordinarie_al).
• gescon_import.gestioni_annuali deve essere popolata o riallineata da quella tabella prima di rileggere rate, cosi la UI e i piani dominio possono raggruppare i movimenti su etichette come 2024/25 o 2025/26.
• Anche gestioni_contabili dominio va riallineata sugli stessi periodi: anno_gestione puo restare numerico come chiave tecnica, ma denominazione, data_inizio e data_fine devono seguire il periodo reale (Ordinaria 2024/25, 2024-10-01 -> 2025-09-30).
• rate_emissioni_dettaglio e la sorgente autorevole della contabilità per unità quando servono split proprietario/inquilino e riferimenti legacy: usare almeno questi campi:
  • cod_cond
  • cond_inq
  • anno_gestione
  • numero_mese
  • numero_ricevuta
  • data_emissione
  • importo_dovuto_euro
• Regola validata sui riferimenti:
  • avviso_code = anno(data_emissione) + numero_mese con padding a due cifre
  • numero_ricevuta resta il riferimento da conservare per l aggancio degli incassi
  • nelle viste dominio delle rate_emesse il riferimento legacy da esporre e Gestione {anno_gestione} · ricevuta n.{numero_ricevuta}; se numero_ricevuta manca, mostrare almeno Gestione {anno_gestione} e avviso_code
  • esempio reale 0016-B-4: 1/2 Rata di Marzo 2025 -> anno_gestione=2024/25, numero_mese=1, data_emissione=2025-03-05, avviso_code=202501, numero_ricevuta=339
• Quando unita_immobiliari.legacy_cond_id non coincide piu con il cod_cond corrente, la scheda unità deve risolvere i cod_cond candidati tramite gescon_import.condomin usando almeno cod_stabile + scala + interno; pero, se il legacy_cond_id salvato ha ancora righe reali in rate_emissioni_dettaglio per quella unità/stabile, va preferito per l estratto compatto per non mischiare snapshot correnti con la contabilità storica autoritativa. Caso validato: 0016-B-4 usa legacy_cond_id=47 per leggere 52/196/268/626/697/766 in 2024/25.
• Per la scheda unità il campo Condomino di riferimento deve riflettere gescon_import.condomin.nom_cond; i comproprietari restano dettaglio accessorio e non sorgente del riferimento principale.

Regola consultazione esercizi importati

• In fase di riallineamento al legacy, gli archivi importati devono restare simmetrici al dato sorgente: nessuna somma implicita e nessuno spostamento automatico tra esercizi senza controllo.
• La consultazione NetGescon distingue ora tra:
  • anni conteggiabili: gestioni aperte o attive, usate per il dovuto corrente
  • anni visibili ma chiusi: ultima gestione chiusa, mantenuta per confronti totali e controlli legacy
  • storico nascosto: esercizi piu vecchi importati e memorizzati, esclusi da estratti e conteggi finche non si abilita un filtro dedicato
• Sessione di test validata su 0016:
  • 2025 (0914) visibile e conteggiabile
  • 2024 (0913) visibile e conteggiabile
  • 2023 (0912) visibile ma chiusa, quindi fuori dal dovuto corrente
  • 2022 e precedenti (0909, 0005, 0004, ...) nascosti per default

Regole di naming e archivio

• codice stabile operativo: usare stabile.cod_stabile
• cartella archivio stabile: usare stabile.nome_directory
• cartella dominio NetGescon: usare sempre il codice univoco/canonico dello stabile
• sincronizzazione documentale: mantenere mapping stabile tra codice canonico NetGescon e cartella legacy, cosi da poter allineare anche Google Drive

Finestra temporale smoke test

Per il primo passaggio operativo non importare tutto lo storico.

Criterio autorevole unita e nominativi

• Lo snapshot corrente di unita, soggetti e diritti deve derivare sempre dall'ultimo anno legacy disponibile per lo stabile, non dall'anno storico che si sta rileggendo in quel momento.
• La chiave stabile di allineamento tra staging e dominio deve essere condomin.id_cond o condomin.legacy_id_cond quando disponibile. Nel dominio questo valore va mantenuto in unita_immobiliari.legacy_cond_id.
• condomin.cod_cond va trattato come codice di snapshot annuale: puo cambiare tra una gestione e l altra e quindi non e una chiave storica affidabile.
• Se cod_cond non coincide con l anno precedente, il fallback corretto e:
  • verificare prima id_cond
  • se il record annuale non basta, verificare il nominativo (nom_cond / proprietario_denominazione) tra annualita consecutive
  • usare cod_cond solo come aggancio locale alla singola gestione per rate, incassi e pagamenti di quell anno
• scala, interno e catasto_sub servono per esporre il codice mnemonico operatore e per le verifiche di riconciliazione, ma non devono sostituire id_cond come chiave interna.
• Se si rilancia un'importazione su un anno precedente, il preflight deve comunque precaricare anche l'ultima annualita disponibile per evitare che lo snapshot corrente venga ricostruito con un anno vecchio.
• Non vanno creati fallback artificiali come interno = 0, unita sintetiche o nominativi fittizi per colmare buchi che non esistono nella sorgente.

Regola operativa per import da blade

• La blade admin-filament/gescon/importazione-archivi deve guidare l operatore a partire dall ultima gestione aperta e a selezionare solo le gestioni da caricare andando a ritroso.
• Le annualita vanno mostrate in ordine decrescente, con la piu recente come default per gestioni aperte.
• Il pulsante consigliato per il flusso completo resta Import + allineamento, usando la selezione Gestioni da caricare (ultima aperta -> ritroso).
• Questo passaggio e importante soprattutto nei casi legacy dove cod_cond e stato riallineato a mano dal vecchio amministratore e quindi ha spostato di uno o piu posti le righe delle annualita successive.

Regola storico anni precedenti

• Gli anni precedenti arricchiscono unita_immobiliare_nominativi come cronologia delle variazioni.
• Non devono sovrascrivere il nominativo corrente dell'ultimo anno disponibile.
• Le compresenze di piu comproprietari nello stesso intervallo sono lecite e vanno distinte dai duplicati veri dello stesso nominativo.
• Il payload storico deve conservare integralmente le famiglie legacy utili alla UI e ai rebuild successivi: cond_*, catasto_*, pertinenze_*, diritti_*, inquilin_* e inquil_*.
• Per gli inquilini il CF autorevole e condomin.inquilin_cod_fisc; la data inizio contratto autorevole e condomin.inquilin_contratto_dal.
• Dopo una correzione anagrafica su 0016 o casi analoghi, il giro minimo coerente e:
  • php artisan gescon:import-full --stabile=<codice> --anno=<ultima_gestione> --path=<archivio> --solo=unita
  • php artisan gescon:import-full --stabile=<codice> --anno=<ultima_gestione> --path=<archivio> --solo=relazioni
  • pulizia mirata di rubrica_ruoli sullo stabile
  • php artisan gescon:sync-rubrica-ruoli --stabile=<stabile_id> --limit=5000 --create-missing --apply

Bonifica anagrafiche post-import

• Dopo gli step unita, soggetti e diritti, eseguire la bonifica recapiti con php artisan gescon:bonifica-rubrica-canali --stabile=<codice> --apply.
• La bonifica spezza telefoni, email e PEC salvati nello stesso campo usando separatori legacy come ;, ,, newline o /.
• I recapiti vengono materializzati in rubrica_contatti_canali con tipo esplicito (telefono, cellulare, email, pec) e flag is_principale.
• Regola di classificazione attuale:
  • numeri che iniziano con 3 => cellulare
  • numeri che iniziano con 0 => telefono
  • gli altri restano sul tipo di origine se gia noto
• La push/sync Google deve leggere e scrivere anche i canali aggiuntivi, non solo i campi primari della rubrica.

Regola codice unita

• unita_immobiliari.codice_unita e limitato a varchar(20) nel dominio corrente.
• I codici generati dall'import devono quindi essere compatti e deterministici:
  • rimozione dei separatori interni non significativi nei segmenti legacy
  • se il codice supera ancora il limite, uso di suffisso hash corto stabile invece di troncare in modo ambiguo
• Questa regola e necessaria per stabili come 0013, dove gli interni legacy aggregati possono produrre stringhe del tipo 0013-NGOT-107/109-C47.

Piloti verificati 08/04/2026

0002 - Carlo Alberto Racchia 2

• anno autorevole importato: 2024 (0038)
• unita: 61
• soggetti: 52
• diritti: 82 inseriti
• QA netgescon:qa-unita-nominativi --stabile_id=8:
  • unita attive 61
  • unita senza nominativi 0
  • duplicati periodi 0
  • nessuna anomalia bloccante
• caso da tenere distinto dai buchi veri:
  • cod_cond = 62 nello snapshot 0038 risulta come record comune (nome = CONDOMINIO (magazzino)) e non ha scala, interno, catasto_sub, piano
  • quindi oggi viene correttamente escluso dalla costruzione delle UI ordinarie se si pretende un identificativo fisico autorevole

0013 - Ottaviano 105 / Giulio Cesare 171

• anno autorevole importato: 2026 (0015)
• fix necessario prima del rilancio:
  • compattazione deterministica di codice_unita per non superare il limite DB
• esito finale dopo fix:
  • unita: 26 processate, 12 aggiornate
  • soggetti: 50
  • diritti: 90 inseriti, 3 aggiornati, 39 ignorati
  • QA netgescon:qa-unita-nominativi --stabile_id=16: nessuna anomalia bloccante
• attenzione funzionale aperta:
  • stabile con unita fisicamente/catastalmente uniche ma spezzate nel legacy per gestire piu titolari
  • la futura unione UI deve appoggiarsi a dati catastali e a logiche di cumulo/quote, non a merge distruttivi dei record legacy

0023 - Germanico 79 (legacy 8)

• anno autorevole importato: 2025 (0096)
• unita: 27 processate, 16 aggiornate
• soggetti: 20
• diritti: 25 inseriti, 15 aggiornati, 2 ignorati
• QA netgescon:qa-unita-nominativi --stabile_id=24: nessuna anomalia bloccante

Regola straordinarie

• Le spese straordinarie vanno considerate aperte nella gestione in cui vengono lette.
• Codici legacy uguali presenti in anni diversi non vanno collassati tra loro: devono restare distinti almeno per anno gestione e, se serve, per numero progressivo straordinaria.

Import base

• anno corrente legacy piu recente disponibile
• anno precedente

Import esteso solo per straordinarie

• includere fino a 5 anni indietro
• fermarsi prima se non esistono MDB annuali o non esistono righe utili nelle tabelle straordinarie

Storico oltre la finestra base

• da importare solo su richiesta o quando serve per quadrature, estratti conto storici o audit mirati

Copertura minima richiesta per rendere operativo il sistema

Lo smoke test deve confermare che per ogni stabile selezionato siano importabili almeno:

1. nominativi completi da condomin
2. unita immobiliari e riferimenti scala/interno/piano
3. collegamenti proprietario/inquilino/comproprietari
4. voci spesa e tabelle millesimali essenziali
5. rate e incassi degli ultimi 2 anni
6. straordinarie degli ultimi 5 anni, se presenti

Questo e il minimo per attivare senza dati monchi:

• ticket
• letture acqua
• CRM/rubrica unica
• estratti conto da cellulare
• pagamento online rate condominiali

Smoke Test pratico per stabile

Per ogni stabile filtrato da Stabili.mdb eseguire questa checklist.

A. Controllo metadati

• cod_stabile valorizzato
• nome_directory valorizzato
• CF stabile valorizzato
• cartella legacy esistente

B. Controllo annualita

• individuato ultimo anno disponibile
• individuato anno precedente disponibile
• individuate eventuali annualita straordinarie fino a -5 anni

C. Controllo file

• esiste singolo_anno.mdb per ogni anno scelto
• se presente, esiste generale_stabile.mdb
• Stabili.mdb leggibile senza errori

D. Controllo tabelle minime

• condomin leggibile
• operazioni leggibile
• rate leggibile
• incassi leggibile
• dett_tab leggibile
• voc_spe leggibile
• straordinarie leggibile o assente in modo coerente

E. QA dominio post-import

• stabile creato/aggiornato correttamente
• unita importate
• rubrica/nominativi deduplicati
• snapshot corrente allineato all'ultima annualita disponibile
• legacy_cond_id valorizzato e coerente con condomin.cod_cond
• nessuna unita attiva con interno = 0 o codice sintetico inventato
• rate/incassi coerenti per gli anni caricati
• nessun crash nelle pagine operative principali

Raccomandazione di rollout

Ordine consigliato:

1. caricare elenco candidati da Stabili.mdb
2. filtrare solo stabili con CF valorizzato
3. per ciascuno verificare nome_directory
4. importare ultimi 2 anni
5. importare straordinarie fino a 5 anni
6. eseguire QA per stabile/anno
7. abilitare progressivamente ticket, letture, CRM e consultazione mobile

Nota importante

La tabella staging gescon_import.stabili non va usata come unica base per questa preselezione se i CF risultano non materializzati. In quel caso la fonte corretta per lo smoke test resta il Stabili.mdb reale.