netgescon-day0/docs/07-struttura-amministratori/21-AUDIT-IMPORT-GESCON-MDB-ZIP-MAPPING.md

# 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:
- Pipeline: [netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)
- Scan/risoluzione archivio per anni: [netgescon-laravel/app/Services/GesconImport/LegacyArchiveService.php](netgescon-laravel/app/Services/GesconImport/LegacyArchiveService.php)
- Controller legacy con path MDB: [netgescon-laravel/app/Http/Controllers/Admin/GesconImportController.php](netgescon-laravel/app/Http/Controllers/Admin/GesconImportController.php)

---

## 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:
- fallback “crea stabile da MDB” nello step `stabili`: [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 2.2 `cartellestabili_e_anni.mdb`
- indice master che collega `cod_stabile` ↔ cartella stabile ↔ cartelle anni

Nel codice:
- usato nella UI legacy per dedurre struttura anni/cartelle: [GesconImportController.php](netgescon-laravel/app/Http/Controllers/Admin/GesconImportController.php)

### 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:
- step `banche` legge `Anagr_casse` da `generale_stabile.mdb`: [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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:

- **Schema staging completo** (replica ampia):
  - [netgescon-laravel/database/migrations/2025_08_05_000001_create_gescon_import_database_schema.php](netgescon-laravel/database/migrations/2025_08_05_000001_create_gescon_import_database_schema.php)
  - Crea (tra le altre): `stabili`, `fornitori`, `condomin`, `voc_spe`, `operazioni`, `rate`, `incassi`, `dett_tab`, `tabelle_millesimali`, `dett_pers`, `detrazioni_fiscali`, …

- **Schema staging “essential”** (tabelle essenziali e campi “puliti”):
  - [netgescon-laravel/database/migrations/2025_08_06_000002_create_gescon_import_essential_tables.php](netgescon-laravel/database/migrations/2025_08_06_000002_create_gescon_import_essential_tables.php)
  - Crea: `stabili`, `anni_gestione`, `condomini`, `voci_spesa`, `operazioni`, `rate`, `incassi`, `millesimi_dettaglio`, `fornitori`, `import_log`

- **Schema staging “optimized/verified”** (alcune tabelle verificate):
  - [netgescon-laravel/database/migrations/2025_08_05_235537_create_gescon_import_optimized_tables.php](netgescon-laravel/database/migrations/2025_08_05_235537_create_gescon_import_optimized_tables.php)
  - Crea: `stabili_gescon`, `fornitori_gescon`, `fatture_gescon`, `rate_*_gescon`, `f24_gescon`, `destinatari_*_gescon`, `import_log`

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:
- [netgescon-laravel/database/migrations/2025_08_14_120000_create_gescon_domain_tables_and_views.php](netgescon-laravel/database/migrations/2025_08_14_120000_create_gescon_domain_tables_and_views.php)

### 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:
- step `stabili` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.2 Step `unita`
Input staging:
- `gescon_import.condomin`

Output dominio:
- `unita_immobiliari` (crea unità “STAB-SCALA-INT”, riconosce pertinenze e normalizza piano)

Riferimento:
- trait [HandlesUnitaStep.php](netgescon-laravel/app/Services/GesconImport/Steps/HandlesUnitaStep.php)

### 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:
- trait [HandlesSoggettiStep.php](netgescon-laravel/app/Services/GesconImport/Steps/HandlesSoggettiStep.php)

### 4.4 Step `diritti`
Input staging:
- `gescon_import.condomin`

Output dominio:
- `proprieta` (legame `unita_immobiliari` ↔ `soggetti` come proprietà/locazione)

Riferimento:
- trait [HandlesDirittiStep.php](netgescon-laravel/app/Services/GesconImport/Steps/HandlesDirittiStep.php)

### 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:
- step `millesimi` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.6 Step `voci`
Input staging:
- `gescon_import.voc_spe`

Output dominio:
- `voci_spesa` (collega tabella millesimale default quando possibile)

Riferimento:
- step `voci` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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:
- step `banche` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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:
- step `operazioni` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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:
- step `rate` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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:
- step `incassi` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.11 Step `giroconti`
Input staging:
- `gescon_import.Giri_conti` o `gescon_import.giri_conti`

Output dominio:
- `movimenti_interni`

Riferimento:
- step `giroconti` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.12 Step `straord`
Input staging:
- `gescon_import.straordinarie`

Output dominio:
- `lavori_straordinari`

Riferimento:
- step `straord` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.13 Step `addebiti`
Input staging:
- `gescon_import.dett_pers`

Output dominio:
- `addebiti_personalizzati`

Riferimento:
- step `addebiti` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 4.14 Step `detrazioni`
Input staging:
- `gescon_import.detrazioni_fiscali`

Output dominio:
- `detrazioni_fiscali_dom`

Riferimento:
- step `detrazioni` in [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

---

## 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:
- [ImportGesconFullPipeline.php](netgescon-laravel/app/Console/Commands/ImportGesconFullPipeline.php)

### 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):
- [ImportGesconMdbCommand.php](netgescon-laravel/app/Console/Commands/ImportGesconMdbCommand.php)

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”:
- [netgescon-laravel/scripts/import_mdb_to_mysql.py](netgescon-laravel/scripts/import_mdb_to_mysql.py)
- [netgescon-laravel/scripts/import_mdb_to_mysql_advanced.py](netgescon-laravel/scripts/import_mdb_to_mysql_advanced.py)

E un mapping “generico” (non allineato al dominio Laravel moderno):
- [netgescon-laravel/scripts/mapping_mdb_mysql.json](netgescon-laravel/scripts/mapping_mdb_mysql.json)

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:
- [netgescon-laravel/database/migrations/2025_08_14_120000_create_gescon_domain_tables_and_views.php](netgescon-laravel/database/migrations/2025_08_14_120000_create_gescon_domain_tables_and_views.php)