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 e dati generali

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

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 certa di allineamento tra staging e dominio e condomin.cod_cond, che nel dominio va mantenuta in unita_immobiliari.legacy_cond_id.
• scala, interno e catasto_sub servono per esporre il codice mnemonico operatore e per le verifiche di riconciliazione, ma non devono sostituire cod_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 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.

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.