# Relazioni MDB → NetGescon (mappa operativa)

## 1) Stabili
**Fonte:** `dbc/Stabili.mdb` → tabella `Stabili`
- **stabili** (dominio)
  - chiave legacy: `stabili.codice_stabile` = `Stabili.cod_stabile`
  - serve per collegare tutte le tabelle per stabile/cartella

### 📁 Regola archivi per amministratore (obbligatoria)
Gli archivi legacy **devono** stare nella cartella dell’amministratore:

- Base: `storage/app/amministratori/<COD_AMM>/legacy`
- Stabili: `.../legacy/dbc/Stabili.mdb`
- Indice anni: `.../legacy/cartellestabili_e_anni.mdb`
- Per stabile: `.../legacy/<COD_STABILE>/<ANNO>/singolo_anno.mdb`
- Generale: `.../legacy/<COD_STABILE>/generale_stabile.mdb`

Questo evita contaminazioni tra amministratori (es. tabelle “fantasma” come TABADL su stabili che non la hanno).

### 📁 Archivi per stabile (documenti interni)
Oltre alla separazione per amministratore, i **documenti interni** devono vivere anche per stabile:

- `storage/app/amministratori/<COD_AMM>/stabili/<CODICE_UNIVOCO_STABILE>/...`

Qui vanno PDF, XML, allegati e documenti generati dall’app. In questo modo non si sovrappongono tra stabili diversi.

### 🔒 Legacy: lettura diretta (no copia)
Gli archivi legacy si leggono **in sola lettura** per portare dati in staging. Non si copiano in locale.
Il percorso viene risolto in base a amministratore/stabile per evitare contaminazioni.

## 2) Unità / nominativi (condomin)
**Fonte:** `singolo_anno.mdb` → tabella `condomin`
- **condomin.cod_cond** = **ID unità legacy**
- **condomin.cond_inq** o `cond_inquil` = `C` (condomino) / `I` (inquilino)
- **condomin.scala + condomin.interno** → **unità immobiliare**
- **condomin.(nome/cognome/cf/email)** → **soggetto**

**Nota rubrica ruoli:** in `rubrica_ruoli.meta.cod_cond` possono comparire formati legacy tipo `I0012` o `13-INQ`. In questi casi si normalizza il codice con sola parte numerica per il match con `condomin.cod_cond`.

**Relazioni target:**
- `unita_immobiliari` (dominio) ← condomin (scala, interno, cod_stabile)
- `soggetti` (dominio) ← condomin (dati anagrafici)
- `proprieta` (pivot) collega `soggetti` ↔ `unita_immobiliari` usando `condomin.cond_inq`

## 3) Rate emesse (emes_gen / emes_det)
**Fonte:** `generale_stabile.mdb` → tabelle `emes_gen`, `emes_det`

- **emes_gen.n_emissione** = chiave emissione
- **emes_det.n_emissione** → collega emissione
- **emes_det.anno_emissione** → cartella (es. 0001=2024, 0002=2025)
- **emes_det.cod_cond** → unità legacy (condomin.cod_cond)
- **emes_det.cond_inq** → soggetto (C/I)

**Relazioni target:**
- `rate_emissioni` (staging) ← `emes_gen`
- `rate_emissioni_dettaglio` (staging) ← `emes_det`
- `rate_emesse` (dominio) ← `rate_emissioni_dettaglio`
  - `unita_immobiliare_id` risolto da `condomin.cod_cond`
  - `soggetto_responsabile_id` in base a `cond_inq`
  - `piano_rateizzazione_id` per `n_emissione`

## 4) Incassi
**Fonte:** `singolo_anno.mdb` → tabella `incassi`
- **incassi.cod_cond** → unità legacy (condomin.cod_cond)
- **incassi.cond_inq** → soggetto (C/I)
- **incassi.n_riferimento / n_mese / anno_rif** → aggancio rate

**Relazioni target:**
- `incassi` (dominio)
- match con `rate_emesse` per riconciliazione

## 5) Tabelle millesimali
**Fonte:** `singolo_anno.mdb` → `tabelle`, `dett_tab`
- **tabelle.cod_tab** = tabella millesimale
- **dett_tab.cod_tab** → tabella
- **dett_tab.id_cond** → unità legacy (condomin.cod_cond)

**Relazioni target:**
- `tabelle_millesimali` (dominio)
- `dettagli_millesimali` (dominio) collegato a `unita_immobiliari`

## 6) Voci di spesa
**Fonte:** `singolo_anno.mdb` → `voc_spe`
- **voc_spe.cod_tab** → tabella millesimale
- **voc_spe.cod_spe** → voce spesa

**Relazioni target:**
- `voci_spesa` (dominio) collegate a `tabelle_millesimali`
- usate per ripartizioni e prima nota

## 7) Operazioni / mastrino
**Fonte:** `singolo_anno.mdb` → `operazioni`
- **operazioni.cod_spe** → `voc_spe`
- **operazioni.cod_tab** → `tabelle`
- **operazioni.cod_cond** → `condomin`

**Relazioni target:**
- `operazioni_contabili` (dominio)
- legame con `voci_spesa` e `tabelle_millesimali`

---

## Diagramma relazioni (mermaid)
```mermaid
flowchart LR
  Stabili[(Stabili.mdb)] -->|cod_stabile| STABILI[stabili]

  Condomin[(condomin)] -->|cod_stabile| STABILI
  Condomin -->|scala+interno| UNITA[unita_immobiliari]
  Condomin -->|anagrafica| SOGG[soggetti]
  SOGG -->|pivot| PROP[proprieta]
  PROP -->|unita_id| UNITA

  EmesGen[(emes_gen)] -->|n_emissione| EMISSI[rate_emissioni]
  EmesDet[(emes_det)] -->|n_emissione| EMDET[rate_emissioni_dettaglio]
  EmesDet -->|cod_cond| Condomin
  EMDET -->|unità/soggetto| RATE[rate_emesse]
  EMISSI -->|piano per emissione| PIANI[piano_rateizzazione]
  PIANI --> RATE

  Incassi[(incassi)] -->|cod_cond| Condomin
  Incassi -->|incasso| INCASSI[incassi]
  INCASSI -. riconcilia .- RATE

  Tabelle[(tabelle)] -->|cod_tab| TM[tabelle_millesimali]
  DettTab[(dett_tab)] -->|cod_tab| TM
  DettTab -->|id_cond| Condomin
  TM --> DETT[dettagli_millesimali]
  DETT --> UNITA

  VocSpe[(voc_spe)] -->|cod_tab| TM
  VocSpe --> VOCI[voci_spesa]
  Operazioni[(operazioni)] -->|cod_spe| VOCI
  Operazioni -->|cod_tab| TM
  Operazioni --> OPER[operazioni_contabili]
```

## Verifica import (checklist)
1. **Stabili** importati da `Stabili.mdb`.
2. **condomin** importato (staging), poi **unità + soggetti + proprietà** in dominio.
3. **emes_gen / emes_det** importati in staging → `rate_emissioni*`.
4. **rate_emesse** (dominio) generate da `rate_emissioni_dettaglio` con legame a unità/soggetto.
5. **tabelle / dett_tab** → `tabelle_millesimali` + dettagli.
6. **voc_spe** → `voci_spesa` con link a tabella millesimale.
7. **operazioni** collegate a tabella + voce.

## Conformità import per stabile (rate/incassi)
**Obiettivo:** per ogni stabile/cartella assicurare coerenza tra staging e dominio.

### Rate emesse
- `rate_emissioni` (staging) deve avere le emissioni per `anno_emissione` atteso (es. 0001, 0002).
- `rate_emissioni_dettaglio` deve avere righe per `cod_cond` e `n_emissione`.
- `rate_emesse` (dominio) deve avere **una riga per ogni dettaglio** (o più se duplicati legittimi), con:
  - `unita_immobiliare_id` risolto da `condomin.cod_cond`.
  - `soggetto_responsabile_id` coerente con `cond_inq` (`C`/`I`).
  - `note` con `n_emissione` e `cod_cond_src` per tracciabilità.

### Incassi
- `incassi` (dominio) deve avere `cod_cond_gescon` e `cond_inquil` valorizzati.
- La riconciliazione con `rate_emesse` deve usare:
  - `cod_cond` + `n_rata_riferimento` (o `n_mese`)
  - importo e data (tolleranza data/periodo).

## Controlli automatici suggeriti
- **Unità duplicate o mancanti**: verificare `condomin.cod_cond` mappati su `unita_immobiliari`.
- **Inquilini multipli**: una sola relazione `locazione` attiva per unità, altrimenti dedup.
- **Rate orfane**: `rate_emesse` senza `unita_immobiliare_id` o `soggetto_responsabile_id`.
- **Emissioni incoerenti**: `rate_emissioni` con `n_emissione` non presenti in `rate_emissioni_dettaglio`.

## Bonifica relazioni rubrica (inquilini/proprietari)
Comando utile:
- `php artisan gescon:bonifica-ruoli-legacy --stabile-id=<ID> [--apply]`

Note operative:
- Se in `rubrica_ruoli.meta.cod_cond` compaiono prefissi `I` o suffissi `-INQ`, sono **inquilini**.
- Le relazioni con ruolo incoerente vengono disattivate in bonifica.
- Dopo bonifica, una sola relazione `inquilino` attiva per unità.

## Esempio controllo (stabile 0019)
- `rate_emesse` collegate: 535
- rate con `unita_immobiliare_id` mancanti: 0
- rate con `soggetto_responsabile_id` mancanti: 0
- inquilini duplicati in rubrica: risolti tramite bonifica

Se vuoi, posso aggiungere una tabella “checklist” per ogni stabile con esito ✅/⚠️.