netgescon-day0/directives/ANAGRAFICHE_MAPPING_LEGACY.md

# 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`).

## 11. Matrice Permessi ACL Dinamica ed Estensibile per Moduli
- **Nessun Limite Rigido**: I permessi e le autorizzazioni applicative non sono cablati a codice ma gestiti in una matrice estensibile raggruppata per **Moduli Applicativi** (es. *Core, Contabilità, Assemblee, FE/Cassetto, Privacy, Catasto, Manutenzioni, CTI/PBX*).
- **Estensione Futura**: L'aggiunta di un nuovo modulo o ruolo registra automaticamente i nuovi permessi delegabili senza intaccare la struttura applicativa.

## 12. Gestione Recapiti Multicanale Illimitati (`rubrica_contatti_canali`)
- **Architettura Multi-Canale**: Ogni anagrafica/utente può associare un numero illimitato di contatti multicanale:
  - **Multi-Email**: Email Principale, Email Studio, Email Personale, PEC 1, PEC 2, ecc.
  - **Multi-Cellulare**: Cellulare Principale, Reperibilità Urgenze H24, WhatsApp Studio, ecc.
  - **Multi-Telefono Fisso**: Fisso Studio, Fisso Abitazione, Centralino VOIP (interno), Fax 1, Fax 2, ecc.
- **Materializzazione**: I recapiti aggiuntivi sono conservati nella tabella `rubrica_contatti_canali` specificando `tipo`, `etichetta`, `valore` e flag `is_principale`.

## 13. Strategia Display Desktop (High-Density) & Mobile (Adaptive Responsive Cards)
- **Desktop (High-Density Grid)**: Layout multi-colonna ad elevata densità informativa per sfruttare la risoluzione monitor del PC ed analizzare griglie contabili, millesimi e badge recapiti.
- **Mobile (Responsive Adaptive Cards)**: Schede adattive collassabili per smartphone e tablet, ottimizzate con target touch per consultazione e gestione rapida in mobilità.

## 14. Coesistenza Temporanea e Autorità della Sorgente Legacy MDB
- **Autorità della Sorgente**: Durante la fase di lavoro in contemporanea tra il vecchio gestionale MDB ed il nuovo NetGescon, **i dati del Legacy MDB sono la sorgente di verità primaria ed autoritativa**.
- **Flusso di Sincronizzazione Unidirezionale**: Eventuali aggiornamenti o modifiche effettuate sul Legacy MDB sovrascrivono e sincronizzano i dati verso NetGescon (Legacy MDB $\rightarrow$ NetGescon). NetGescon non sovrascrive mai al contrario i dati del MDB originale.
- **Importazione Differenziale Incrementale**: Il comando `php artisan gescon:load-mdb-staging --incremental` recepisce periodicamente le variazioni del legacy conservando la coerenza storica.

## 15. Importazione Note & Conti Correnti Bancari/Postali dallo Stabile (`Stabili.mdb`)
- **Comando di importazione**: `php artisan gescon:import-stabili-bank-notes`
- Estrae da `Stabili.mdb` (tabella `Stabili`):
  - **Note Stabile**: `note1` + `Note` (salvate nel campo `note`).
  - **Coordinate Bancarie 1**: `Banca`, `IBAN_Banca`, `Banca_num_cc`, `ABI`, `CAB`, `SIA`, `CIN`.
  - **Coordinate Bancarie 2 & Postali**: `Banca2`, `IBAN_Banca2`, `num_ccp` (CCP), `IBAN_Posta`, `num_ccp_2`, `IBAN_Posta_2`.
- I dati sono strutturati ed archiviati in `stabili.configurazione_avanzata['conti_correnti']` e nei campi diretti `iban_principale`, `banca_principale`, `iban_secondario`, `banca_secondaria`.

## 16. Sistema Grafico Unificato per l'Anagrafica Fornitori (`/admin-filament/gescon/anagrafica/fornitori`)
- **Design System Coerente**: La vista Fornitori condivide ed applica il design grafico unificato delle tabelle e schede anagrafiche del sistema (`FornitoriArchivio.php`).
- **Wireframe ASCII di Riferimento**: `skill-netgescon/ui-wireframes/fornitori-anagrafica.md`.
- **Filtri Tag & P.IVA**: Supporta la ricerca rapida per Ragione Sociale, Partita IVA, Codice Fiscale, recapiti e tag di categoria (es. *Idraulici, Elettricisti, Pulizie, Ascensori*).

## 17. Importazione Dati Fiscali Avanzati Fornitori (`Fornitori.mdb` & `Regime_fisclale.mdb`)
- **Comando di importazione**: `php artisan gescon:import-fornitori-fiscal-details`
- Estrae da `Fornitori.mdb` e `Regime_fisclale.mdb`:
  - **Ritenuta Tributo**: `Trib_1019_1020` (es. `1019`, `1020`, `1040`).
  - **Regime Fiscale**: `Regime_fiscale` (es. `RF01` Ordinario, `RF02` Minimi, `RF19` Forfettario).
  - **Cassa Professionale**: `Perc_cassa_prof` (Aliquota Cassa 4%, 5%).
  - **PEC & IBAN**: `PEC_Fornitore`, `Cod_IBAN`, `Intestaz_CC_esatta`.
- Collegamento diretto con la pipeline di importazione delle Fatture Elettroniche (FE) e la Certificazione Unica (CU/770).

## 18. Audit Log Permanente delle Modifiche ("Chi fa cosa")
- Ogni inserimento, modifica o cancellazione sui dati anagrafici, amministratori o stabili viene registrato nella tabella `audit_logs` memorizzando l'ID utente operante, il timestamp, i campi modificati ed i valori pre/post modifica.

## 19. Editing In-Place (Senza Modal Dialogs)
- Le maschere CRUD (es. Amministratori `/admin-filament/superadmin/amministratori` e Fornitori `/admin-filament/anagrafica/fornitori/{record}`) consentono l'editing diretto nella stessa pagina senza aprire popup o finestre modal.

## 20. Amministratore Cecilia Tordini & Impersonificazione Istantanea
- Amministratore censito con CF `TRDCCL74T52H501R` ed account principale `cecilia.tordini@gmail.com` (ID #13, Studio Tordini Cecilia).
- Azione **IMPERSONA** attiva nelle viste per consentire il login istantaneo contestuale da parte dei SuperAdmin senza richiedere digitazione di password o reindirizzamento alla schermata di login.

## 21. Navigazione a TAB Separati per la Gestione Amministratori (`/admin-filament/superadmin/amministratori`)
- L'interfaccia Amministratori è organizzata in un menu a **Pulsanti Tab** senza scroll orizzontale:
  - **TAB 1**: Elenco Amministratori Censiti.
  - **TAB 2**: Scheda & Modifica Inline (Dettaglio completo dell'amministratore selezionato).
  - **TAB 3**: Stabili & Fornitori Studio.
  - **TAB 4**: Modulo Importazione Legacy MDB (Protetto da ACL `import-gescon`).

## 22. Isolamento dei Fornitori per Studio Amministratore (`amministratore_id`)
- I 370 fornitori censiti ed importati appartengono allo studio di **Cecilia Tordini (`#13`)**.
- Gli archivi fornitori sono isolati per ciascun amministratore: ciascun amministratore visualizza in via esclusiva unicamente i fornitori accreditati per la propria gestione.

## 23. Gestione Menù e Moduli via ACL (PostgreSQL / Laravel Spatie Permissions)
- I menù di sistema ed i moduli operativi (es. *Modulo Importazione MDB Gescon*) sono regolati dalle ACL con permessi granulari (es. `import-gescon`, `manage-fornitori`, `admin`).
- Il passaggio a PostgreSQL garantisce integrità transazionale ed efficienza nel controllo dei permessi su tabelle ACL di grandi dimensioni.