# Direttiva Architetturale: Mapping Anagrafico, Contabile e Catastale Legacy Gescon

## 1. Collegamento tra `condomin` e `comproprietari`
- **Campo primario**: `id_cond`
- **Regola tassativa**: La tabella `comproprietari` deve essere collegata alla tabella `condomin` **esclusivamente** tramite il campo `id_cond`.
- **Esempio Stabile 0016 (Interno B/4)**:
  - `condomin`: `id_cond = 47`, `cod_cond = 50`, `scala = B`, `int = 4`, `nom_cond = Barone Michele`, `perc_diritto_reale = 50`
  - `comproprietari`: `id_cond = 47`, `nom_cond = Francioni Claudia`, `email = cecilia.tordini@gmail.com`, `perc_diritto_reale = 50`
  - Risultato unificato: Int. B/4 -> **Barone Michele (50% Comproprietà)** e **Francioni Claudia / Cecilia Tordini (50% Comproprietà)**.
  - Divieto: È vietata qualsiasi associazione tra `comproprietari` e `condomin` basata sul campo `cod_cond`, in quanto `cod_cond` è il progressivo contabile della singola gestione e può identificare un'altra unità in quell'anno (es. `cod_cond = 47` appartiene all'interno E - Giovagnoni Marina).

## 2. Collegamento Contabile (`incassi`, `rate`, `emes_det`)
- **Campo contabile per anno gestione**: `cod_cond`
- **Distinzione ruolo contabile**: `cond_inquil`
  - `'C'`: Condomino / Proprietario
  - `'I'`: Inquilino / Locatario
- **Funzione**: Il campo `cod_cond` accoppiato con `cond_inquil` lega in maniera univoca ciascuna riga di addebito o incasso (`incassi`, `rate`, `emes_det` in `generale_stabile.mdb`) all'anagrafica del condomino o dell'inquilino per quella specifica gestione.

## 3. Gestione Percentuali e Movimentazioni Temporali
- Le quote e percentuali di possesso (`perc_diritto_reale`, es. 50% / 50%) devono essere mantenute con precisione senza forzare la Piena Proprietà (100%) in presenza di comproprietari o contitolari.
- Ciascun avvicendamento storico va conservato nelle movimentazioni temporali per l'anno gestione di competenza.

## 4. Dati Catastali Stabile (`Stabili.mdb` - Prefisso `AC_`)
- **Estrazione da `Stabili.mdb`**:
  - `AC_Foglio` -> `foglio` (es. `404`)
  - `AC_partic1` / `AC_partic2` -> `particella` (es. `98`, `96`, `49`)
  - `AC_urb_cat` -> `sezione` (es. `H501`)
  - `Catasto_comune` -> `codice_comune` (es. `Roma`, `H501`)
  - `Catasto_PR` -> `provincia` (es. `RM`)
- **Gestione Sezioni Catastali Multiple / Palazzine**:
  - Negli stabili articolati o supercondomini (es. Milizie 3 / 0021 con Palazzina D in altra sezione/particella), la configurazione avanzata dello stabile conserva l'array `altri_riferimenti_catastali`.
  - Ciascun riferimento sezionale o di palazzina specifica `descrizione`, `foglio`, `particella`, `sezione`, `subalterno`, consentendo l'aggancio diretto alle rispettive unità immobiliari.

## 5. Tabelle Millesimali da Legacy (`tabelle` e `dett_tab` in `singolo_anno.mdb`)
- **Tabella definizioni**: `tabelle` con campi `cod_tab`, `des_tab`, `totale`.
- **Tabella dettagli ed attribuzione**: `dett_tab` con campi `cod_tab`, `id_cond`, `cond_inquil`, `mm`.
- **Regola di collegamento**:
  - `tabelle.cod_tab` si lega a `dett_tab.cod_tab`.
  - `dett_tab.id_cond` si lega tassativamente a `condomin.id_cond` dell'unità immobiliare per quella specifica gestione.
  - `dett_tab.cond_inquil` (`'C'` Condomino, `'I'` Inquilino) attribuisce i millesimi (`mm`) al soggetto titolare.

## 6. Principio di Deterministicità Assoluta (Regola Commercialista)
- **Divieto di Fallback o Date Fittizie**: È tassativamente vietato inventare date fittizie (es. `01/01/2000` o `01/01/2026` ripetute) o stimare ruoli non presenti negli archivi MDB.
- **Trattamento dati mancanti**: Se una relazione o una data di decorrenza non è presente negli archivi consolidati, il sistema deve riportare unicamente le gestioni storiche certe (es. `Gestioni 0004, 0005, 0909, 0912, 0913, 0914`) oppure restituire `BLOCCO_DATI`. I dati devono essere certificabili e certi al 100%.

## 7. Struttura Cartelle Canonica dello Stabile, Codice Univoco e Portabilità
- **Codice Univoco Stabile (Non Legacy)**: Le cartelle fisiche di archivio documenti e backup SQLite sono identificate tassativamente tramite il `codice_univoco` generato dal sistema (es. `HWAGIBXK` o `0000000C`), **mai tramite il codice numerico del legacy** (es. `0001` o `0021`).
- **Motivazione Architetturale**: L'uso del `codice_univoco` evita conflitti sulla stessa macchina nel caso in cui due amministratori differenti abbiano entrambi uno stabile con il medesimo identificativo legacy (es. `0001`), e garantisce la portabilità e l'interconnessione multi-tenant di fornitori, proprietari ed inquilini durante i passaggi di gestione.
- **Percorsi Tipo**:
  - Cartella Stabile: `storage/app/private/amministratori/{codice_amministratore}/stabili/{codice_univoco}`
  - Documenti Stabile: `storage/app/private/amministratori/{codice_amministratore}/stabili/{codice_univoco}/documenti`
  - Backup & SQLite: `storage/app/private/amministratori/{codice_amministratore}/stabili/{codice_univoco}/database/backups`

## 8. Architettura Database PostgreSQL e Visualizzatore Web (Stile PhpMyAdmin)
- **Database Engine**: PostgreSQL per persistenza strutturale multi-tenant e gestione passaggio gestioni tra amministratori.
- **Visualizzatore Web PostgreSQL (Adminer)**:
  - Strumento di consultazione ed editing DB PostgreSQL accessibile via web all'URL `http://192.168.0.205:8000/adminer.php`.
  - Consente la consultazione immediata di tabelle, schemi, indici e record con interfaccia equivalente a PhpMyAdmin.
- **Script di Inizializzazione Server DB**: `scripts/ops/setup_postgresql.sh`.

## 9. Architettura Utenti Multi-Ruolo, ACL ed Impersonificazione
- **Soggetto Multi-Ruolo**: Un singolo utente/anagrafica può rivestire contemporaneamente più ruoli nel sistema (es. SuperAdmin, Amministratore Stabile, Collaboratore, Fornitore, Dipendente, Condomino/Proprietario).
- **Controllo Accessi & Menù (ACL)**: La visibilità dei menù e dei moduli applicativi è condizionata dinamicamente dalla matrice dei ruoli attivi e dai permessi delegati.
- **Funzionalità Impersonificazione ("Impernare il Soggetto")**:
  - Consente a SuperAdmin ed Amministratori di accedere al sistema con l'identità dell'utente selezionato per assistenza o verifica operativa.
  - Ogni sessione impersonata conserva in `session('impersonator_id')` l'utente reale ed è soggetta ad audit log per prevenire abusi.
- **Ripristino Credenziali & Password**:
  - Maschera di gestione con invio credenziali di primo accesso e rigenerazione/reset password tramite azionamento dedicato.

## 10. Importazione Automatica Amministratori da Legacy (`Stabili.mdb`)
- **Comando di importazione**: `php artisan gescon:import-amministratori-legacy`
- Esegue l'estrazione automatica degli amministratori dalla tabella `Stabili` dei file MDB (`Stabili.mdb`), popola la tabella `amministratori` e crea i relativi utenti di sistema con codice univoco canonico (es. `00000001`, `00000002`).