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

1.1 Identità Fisica dell'Unità Immobiliare (scala + interno) e Gestione Temporale dei Codici

• Identità Fisica Costante: L'Unità Immobiliare è definita univocamente dalla combinazione cod_stabile + scala + interno (es. Stabile 0013, Scala B, Interno 8). Questa identità fisica rimane stabile nel tempo ed è collegata ai dati catastali.
• Dinamica dei Codici di Gestione (id_cond, cod_cond): Nei file delle singole gestioni annuali (singolo_anno.mdb), i codici id_cond e cod_cond variano nel tempo con i subentri (es. su Stabile 0013 B/8: id_cond = 18 Maurelli Rossana -> id_cond = 82 Ranchino Valentina -> id_cond = 83 D'Aniello Andrea).
• Regola di Isolamento per Unità: Il matching delle anagrafiche e dei comproprietari deve sempre vincolarsi tassativamente all'identità fisica dell'unità (scala + interno). È tassativamente vietato raccogliere comproprietari o legami da altre unità basandosi unicamente sul valore numerico del codice di gestione senza verificare la corrispondenza di scala ed interno.

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.