michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
22be2be817
netgescon-day0/docs/07-struttura-amministratori/21-AUDIT-IMPORT-GESCON-MDB-ZIP-MAPPING.md

14 KiB
Raw Blame History

Audit Import GESCON (MDB/ZIP) → NetGescon

Obiettivo: avere una mappa trasparente di cosa importiamo da GESCON (file MDB dentro archivio/cartelle o ZIP unico) e in quali tabelle NetGescon finisce.

Questo documento è volutamente “operativo”: non descrive l’interfaccia, ma input → staging → dominio.

1) Che cosa esporta GESCON (scenario reale)

Dalla pratica (e dai materiali già presenti nel repo) emergono 2 modalità equivalenti:

  1. Archivio su filesystem (cartelle)

    • un path base tipo .../gescon/
    • per ogni stabile una cartella /<codice_stabile>/
    • dentro: generale_stabile.mdb
    • per ogni anno: /<anno_cartella>/singolo_anno.mdb
    • spesso esiste anche un indice: cartellestabili_e_anni.mdb

  2. ZIP unico “bulk”

    • contiene gli stessi MDB (o una struttura equivalente) compressi
    • concettualmente: ZIP → estrazione temporanea → si riusa la pipeline “filesystem”

Nel codice attuale, la pipeline lavora nativamente sul filesystem (--path e cartelle per stabile/anno). Lo scenario “ZIP unico” è quindi: estrai ZIP → passa la cartella estratta come --path.

Riferimenti codice:

2) File MDB “chiave” (cosa contengono)

2.1 Stabili.mdb

  • Anagrafica stabili (denominazione/indirizzo/cf/iban/…)
  • Usato come fonte metadati (arricchimento) quando lo staging non è sufficiente.

Nel codice:

2.2 cartellestabili_e_anni.mdb

  • indice master che collega cod_stabile ↔ cartella stabile ↔ cartelle anni

Nel codice:

2.3 generale_stabile.mdb

  • dati “di stabile” (non anno-specifici): tipicamente casse/conti, parametri, e in alcune installazioni anche fatture/altre tabelle.

Nel codice:

2.4 singolo_anno.mdb

  • dati dell’anno: condòmini/unità/rapporti, millesimi, voci, operazioni, rate/incassi, giroconti, straordinarie, ecc.

Nel codice:

  • staging/dominio usa soprattutto la tabella condomin e le tabelle contabili (operazioni, rate, incassi, …)

3) Pipeline “canonica” attuale (3 livelli)

Livello A — Staging DB gescon_import (import tecnico)

È un database “ponte” che replica (in parte o in toto) tabelle GESCON in MySQL.

Nel repo coesistono più migrazioni/strategie di staging (storiche). Le principali:

Nota: nella pipeline gescon:import-full i riferimenti principali sono a:

  • condomin
  • dett_tab
  • tabelle_millesimali
  • voc_spe
  • operazioni
  • rate
  • incassi
  • giri_conti / Giri_conti
  • straordinarie
  • dett_pers
  • detrazioni_fiscali
  • stabili

(estratto automaticamente dai riferimenti in codice).

Livello B — Tabelle dominio “NetGescon” (dati usati dall’app)

La pipeline gescon:import-full non si limita a riempire lo staging: crea/aggiorna anche entità di dominio.

Le tabelle di dominio toccate direttamente (principali):

  • stabili
  • unita_immobiliari
  • soggetti
  • proprieta (diritti reali / legami soggetto↔unità)
  • tabelle_millesimali e tabelle_millesimali_righe
  • voci_spesa
  • operazioni_contabili
  • rate_emesse (solo se esiste colonna legacy_id)
  • incassi
  • movimenti_interni
  • lavori_straordinari
  • addebiti_personalizzati
  • detrazioni_fiscali_dom

Per supportare alcune parti del dominio e QA post-import esiste una migrazione dedicata:

Livello C — QA (viste)

La stessa migrazione crea viste vw_gescon_import_* per verificare rapidamente il risultato import.

4) Mapping operativo: STAGING → DOMINIO (pipeline gescon:import-full)

Questa è la mappa “vera” per l’import end-to-end.

4.1 Step stabili

Input staging:

  • gescon_import.stabili (se presente)
  • altrimenti gescon_import.condomin (distinct cod_stabile)
  • fallback (solo metadati): lettura Stabili.mdb se fornito --mdb o deducibile da --path

Output dominio:

  • stabili (crea/aggiorna non distruttivo: completa campi mancanti)

Riferimento:

4.2 Step unita

Input staging:

  • gescon_import.condomin

Output dominio:

  • unita_immobiliari (crea unità “STAB-SCALA-INT”, riconosce pertinenze e normalizza piano)

Riferimento:

4.3 Step soggetti

Input staging:

  • gescon_import.condomin

Output dominio:

  • soggetti (dedup: CF → email → nome+cognome)
  • crea/associa anche record Persona (rubrica universale) tramite PersonaSyncService

Riferimento:

4.4 Step diritti

Input staging:

  • gescon_import.condomin

Output dominio:

  • proprieta (legame unita_immobiliari ↔ soggetti come proprietà/locazione)

Riferimento:

4.5 Step millesimi

Input staging:

  • gescon_import.dett_tab (righe millesimi)
  • gescon_import.tabelle_millesimali (intestazioni) se presente
  • join con gescon_import.condomin per risalire a cod_stabile (quando necessario)

Output dominio:

  • tabelle_millesimali (intestazioni)
  • tabelle_millesimali_righe (righe per unità)

Riferimento:

4.6 Step voci

Input staging:

  • gescon_import.voc_spe

Output dominio:

  • voci_spesa (collega tabella millesimale default quando possibile)

Riferimento:

4.7 Step banche

Input file (filesystem):

  • /<path>/<stabile>/generale_stabile.mdb tabella Anagr_casse
  • fallback: Anagr_casse anche nei singolo_anno.mdb

Output dominio:

  • dati_bancari (conti, IBAN, flag conto nostro)
  • casse (es. CON, CDL, eventuali codici locali)

Riferimento:

4.8 Step operazioni

Input staging:

  • gescon_import.operazioni

Output dominio:

  • operazioni_contabili (con legacy_id)
  • collegamento opzionale a dati_bancari tramite cod_cassa (se colonna conto_bancario_id esiste)

Riferimento:

4.9 Step rate

Input staging:

  • gescon_import.rate (con eventuale join a condomin se manca cod_stabile)

Output dominio:

  • rate_emesse SOLO se schema ha legacy_id
    • altrimenti lo step “salta” (perché la tabella storica richiede molti campi)

Riferimento:

4.10 Step incassi

Input staging:

  • gescon_import.incassi

Output dominio:

  • incassi con legacy_id (o id_incasso_gescon se presente)
  • link a dati_bancari/casse se le colonne esistono

Riferimento:

4.11 Step giroconti

Input staging:

  • gescon_import.Giri_conti o gescon_import.giri_conti

Output dominio:

  • movimenti_interni

Riferimento:

4.12 Step straord

Input staging:

  • gescon_import.straordinarie

Output dominio:

  • lavori_straordinari

Riferimento:

4.13 Step addebiti

Input staging:

  • gescon_import.dett_pers

Output dominio:

  • addebiti_personalizzati

Riferimento:

4.14 Step detrazioni

Input staging:

  • gescon_import.detrazioni_fiscali

Output dominio:

  • detrazioni_fiscali_dom

Riferimento:

5) Come viene popolato lo STAGING (MDB → gescon_import.*)

Qui ci sono più “strade” nel repo (alcune legacy/storiche).

5.1 Import via Artisan (consigliato per pipeline moderna)

  • Comando principale: gescon:import-full
  • Fa preflightStaging() e può caricare condomin da singolo_anno.mdb quando manca nello staging.

Riferimento:

5.2 Import diretto MDB → tabelle staging “stg_*” (workflow alternativo)

Esiste anche un comando “diretto” che importa alcune tabelle MDB in tabelle stg_* (non è la stessa cosa dello staging gescon_import.* usato dal full pipeline):

Questo è utile per casi specifici (rate/operazioni/incassi da estratto), ma non è la base del “bulk import ZIP” come richiesto.

5.3 Script Python generici (storici / tooling)

Nel repo ci sono script per importare MDB in MySQL con naming “raw”:

E un mapping “generico” (non allineato al dominio Laravel moderno):

Questi tool sono utili per “dump” e diagnostica, ma la pipeline Laravel principale usa l’approccio gescon:import-full.

6) Cosa manca per supportare davvero “ZIP unico” end-to-end

A oggi abbiamo:

  • pipeline su filesystem completa (gescon:import-full) che richiede un --path e struttura cartelle
  • lettura MDB via mdb-tools

Per lo scenario ZIP unico mancano (a livello prodotto):

  1. Upload ZIP (UI)
  2. Extract in area temporanea per utente/stabile (storage)
  3. Validazione: verifica presenza minima di:
    • Stabili.mdb oppure cartellestabili_e_anni.mdb
    • almeno un singolo_anno.mdb per lo stabile selezionato
  4. Esecuzione pipeline puntando --path alla cartella estratta
  5. Pulizia della cartella temporanea + log import

Questo documento copre (3) e (4) dal punto di vista di “dati che entrano e dove finiscono”.

7) Quick checklist (per controllare che importiamo “la base funzionante”)

Base GitHub “funzionante” = anagrafiche + unità + ruoli/rapporti + contabilità minima.

  • stabili creati (dominio)
  • unita_immobiliari create
  • soggetti creati + dedup OK
  • proprieta (diritti) creati
  • tabelle_millesimali + tabelle_millesimali_righe
  • voci_spesa
  • dati_bancari / casse (almeno CON e un conto nostro)
  • operazioni_contabili (se si vuole “prima nota/contabilità”)
  • rate_emesse e incassi (dipende dallo schema: rate richiede legacy_id)

Per la QA, usare le viste vw_gescon_import_* create dalla migrazione: