# Direttiva Operativa: Sincronizzazione Contabilità Stabili da Legacy MDB

## Scopo

Questa direttiva definisce il processo standardizzato, riusabile ed autonomo per l'importazione e la sincronizzazione della contabilità condominiale dagli archivi storici Microsoft Access MDB (`singolo_anno.mdb`, `generale_stabile.mdb`, `dbc/Fornitori.mdb`) verso il database canonico PostgreSQL / MySQL di NetGescon.

La procedura è applicabile in piena autonomia dall'operatore sia tramite interfaccia grafica Filament che tramite comando da terminale Artisan CLI.

---

## Architettura Dati e Mapping delle Tabelle

### 1. Fornitori Centralizzati (`dbc/Fornitori.mdb`)
- **Sorgente MDB**: Tabella `Fornitori`.
- **Target Canonico**: Tabella `fornitori` e `anagrafiche`.
- **Campi Chiave**: `cod_forn`, `Descrizione` / `cognome` + `nome`, `cod_fisc`, `p_iva`, `Cod_IBAN`, `indirizzo`, `cap`, `citta`, `pr`, `Telef_1`, `Cellulare`, `Indir_Email`.
- **Regola di Unicità**: Codice univoco fornitore normalizzato a 8 caratteri (`F` + padding o `FORN_*`).

### 2. Mappatura Esercizi Gestionali (`generale_stabile.mdb`)
- **Sorgente MDB**: Tabella `anni`.
- **Mapping**: `nome_dir` (es. `0003`, `0013`, `0014`, `0015`) $\leftrightarrow$ `anno_o` (es. `2017`, `2024`, `2025`, `2026`).
- **Target Canonico**:
  - `gestioni_contabili` (`anno_gestione`, `tipo_gestione`, `protocollo_prefix`, `data_inizio`, `data_fine`, `stato`, `gestione_attiva`).
  - `gestioni` (`id_gestione`, `anno_gestione`, `tipo_gestione = 'Ord.'`, `stabile_id`).

### 3. Millesimi e Conguagli di Apertura (`singolo_anno.mdb` $\rightarrow$ `dett_tab`)
- **Sorgente MDB**: Tabella `dett_tab`.
- **Target**: Tabella di staging `dett_tab` su connessione `gescon_import`.
- **Conguagli Apertura**: `cod_tab` con prefissi `CONG.O` (Ordinario), `CONG.R` (Riscaldamento), `CONG.S` (Straordinario).
- **Legame Soggetti**: `id_cond` associato alla corretta unità immobiliare, con distinzione `cond_inquil` (`'C'` Condomino, `'I'` Inquilino).

### 4. Rate Emesse e Conguaglio Finale CF (`singolo_anno.mdb` $\rightarrow$ `rate`)
- **Sorgente MDB**: Tabella `rate`.
- **Target Canonico**: `piano_rateizzazione` e `rate_emesse`.
- **Rata Conguaglio Finale (CF)**:
  - Identificata da `n_mese = 'CF'`, `dt_empag = '31/12/99'` o descrizione contenente 'CONGUAGLIO FINALE'.
  - Marcata con flag `is_conguaglio_finale = 1` e `numero_rata_progressivo = 999`.
  - Riporta il saldo esatto di chiusura dell'unità per l'anno di gestione.

### 5. Incassi Effettuati (`singolo_anno.mdb` $\rightarrow$ `incassi`)
- **Sorgente MDB**: Tabella `incassi`.
- **Target Canonico**: Tabella `incassi`.
- **Conto Bancario**: Risoluzione automatica del conto bancario attivo su `conti_bancari` per lo stabile (`codice = '{cod_stabile}-{cod_cassa}'`, es. `0013-CCB`).
- **Titolare Movimento**: Distinzione tassativa tramite `cond_inquil` (`'C'` vs `'I'`).

### 6. Operazioni Contabili, Fatture e Ritenute d'Acconto (`singolo_anno.mdb` $\rightarrow$ `Operazioni`)
- **Sorgente MDB**: Tabella `Operazioni`.
- **Target Canonico**:
  - `contabilita_registrazioni` (Prima Nota): `entry_date`, `document_number`, `document_type`, `description`, `status = 'confirmed'`.
  - `contabilita_fatture_fornitori`: `fornitore_id`, `data_documento`, `imponibile`, `totale`, `netto_da_pagare`, `ritenuta_aliquota`.
  - `registro_ritenute_acconto`: `fornitore_id`, `data_competenza`, `imponibile`, `aliquota_ritenuta` (4% Condominio cod. tributo 1019, 20% Professionisti cod. tributo 1040), `stato_versamento` (`'versata'` per `VER_4`/`VER_20`, `'da_versare'` per `RDA_4`/`RDA_20`), `data_versamento`.

### 7. Consolidamento Bilanci (`bilanci`)
- **Target Canonico**: Tabella `bilanci`.
- **Calcolo**:
  - `totale_entrate`: Somma rate emesse (`rate_emesse`).
  - `totale_uscite`: Somma fatture fornitori consuntivate (`contabilita_fatture_fornitori`).
  - `saldo`: Differenza algebrica Entrate - Uscite.
  - `stato`: `'CHIUSO'` per esercizi pregressi, `'DRAFT'` per esercizio corrente.

---

## Modalità di Esecuzione

### 1. Da Terminale (Artisan CLI)
Per sincronizzare un singolo stabile su tutti gli anni di gestione:
```bash
php artisan gescon:sync-contabilita-stabile {codice_stabile} --all-years
```
Esempio per Stabile 0013:
```bash
php artisan gescon:sync-contabilita-stabile 0013 --all-years
```

Per sincronizzare un singolo anno specifico (es. 2026):
```bash
php artisan gescon:sync-contabilita-stabile 0013 --anno=2026
```

Per simulare senza scritture a database (Dry Run):
```bash
php artisan gescon:sync-contabilita-stabile 0013 --dry-run
```

### 2. Da Interfaccia Web Filament (One-Click Sync)
Nelle schermate di contabilità:
- **Situazione Iniziale** (`/admin-filament/contabilita/situazione-iniziale`)
- **Chiusure Gestione** (`/admin-filament/contabilita/chiusure-gestione`)

Fare clic sul pulsante in alto a destra:
`[ 🔄 Sincronizza da Legacy ]`
e confermare la modale. Il sistema elaborerà automaticamente tutti gli esercizi e aggiornerà i saldi e le quadrature.

---

## Regole di Integrità e Conformità

1. **Zero Mock Data**: È rigorosamente vietato generare dati fittizi. Se mancano riscontri o corrispondenze certe, la procedura registra l'anomalia o interrompe con blocco dati strutturato.
2. **Segregazione Ruoli**: I conguagli, le rate e gli incassi mantengono costantemente separata la titolarità tra Proprietario/Condomino (`'C'`) e Inquilino/Conduttore (`'I'`).
3. **Idempotenza**: I comandi possono essere eseguiti ripetutamente senza duplicare registrazioni, rate, fatture o ritenute d'acconto (chiavi di aggiornamento basate su riferimenti legacy univoci).