michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9d8e412c49
netgescon-day0/directives/sop_importazione_sperimentale_stabile.md

14 KiB
Raw Blame History

SOP - Importazione Sperimentale Stabile e Gestione Anagrafica Avanzata (Fase 7)

Questo documento definisce i criteri per l'amministrazione interamente via interfaccia grafica Web, la logica di allineamento dinamico degli anni e la mappatura dei campi avanzati della tabella legacy condomin con le relative regole di business.

1. Paradigma Cloud & Amministrazione Web (No CLI / Terminale)

Il sistema NetGescon è progettato per essere interamente amministrato via interfaccia Web, rendendo l'applicazione Docker-ready e portabile:

  • Punto di Accesso: L'allineamento automatico, il pull da Git e il ripristino/aggiornamento della struttura DB vengono eseguiti esclusivamente tramite la pagina grafica: /admin-filament/gescon/importazione-archivi.
  • Hot Backup SQLite: Ogni stabile genera a caldo il proprio file SQLite (es. stabile_0021.sqlite). Questo archivio granulare garantisce l'elaborazione locale offline, consentendo la sincronizzazione e il ripristino di singole righe di pagamento o fatture via Google Drive o OneDrive.

2. Allineamento Dinamico Esercizi (1:1 Speculare)

Gli anni e i periodi non sono codificati in modo statico:

  1. Lo script interroga la tabella master [anni] all'interno del file /mnt/gescon-archives/gescon/0021/generale_stabile.mdb.
  2. Identifica l'ultima gestione disponibile (anno_o / anno_r) e la directory ad essa associata (nome_dir).
  3. Procede a ritroso caricando gli esercizi precedenti, garantendo che le anagrafiche e i saldi siano speculari allo stato del legacy contabile.

3. Matrice Completa di Mapping condomin (Raw MDB)

Di seguito è dettagliato lo schema di associazione per tutti i campi censiti nella tabella condomin dello stabile 0021:

Campo Legacy condomin Modello / Tabella NetGescon Regola di Trasformazione
id_cond unita_immobiliari.legacy_id Riferimento chiave primaria dell'unità legacy.
cod_cond rubrica_universale.codice_univoco Codice alfanumerico del soggetto.
scala / int / piano unita_immobiliari Posizione spaziale dell'unità.
nom_cond rubrica_universale.ragione_sociale Denominazione unificata condomino/proprietario.
presso / inquil_presso rubrica_indirizzi.care_of (o c_o) Mappato come intestatario c/o (Care Of) per le spedizioni delle buste cartacee.
ind / cap / citta / pr rubrica_indirizzi Indirizzo di residenza/spedizione del condomino.
tel1 / tel2 / Cell_cond / Fax_cond rubrica_universale Numeri di telefono, cellulare e fax del condomino.
E_mail_condomino / PEC_condomino rubrica_universale Email e PEC del condomino per invii digitali.
inquil_nome rubrica_universale Nominativo dell'inquilino/occupante.
inquil_indir / inquil_cap / inquil_citta / inquil_pr rubrica_indirizzi Indirizzo completo dell'inquilino.
inquil_tel1 / inquil_tel2 / Cell_inq / Fax_inq rubrica_universale Recapiti telefonici dell'inquilino.
E_mail_inquilino / PEC_inquilino rubrica_universale Email e PEC dell'inquilino.
inquil_dal / inquil_al unita_anagrafica_periodo Date d'inizio e fine locazione per subentri.
subentrato_dal / attivo_fino_al unita_anagrafica_periodo Date di variazione possesso dell'unità.
subentro_prima_cera / subentro_adesso_ce unita_anagrafica_periodo.meta Audit testuale dei condòmini uscenti/subentranti.
cumulo_cond / E_lostesso_Di unita_pertinenze E_lostesso_Di punta all'unità principale (id_cond) per il cumulo pertinenze.
Cumulo_ass / Cumulo_elenchi unita_pertinenze Regola l'unificazione del voto assembleare a "Testa Singola".
titolo_cond / titolo_inq rubrica_universale.titolo Titolo di cortesia (es. Egr. Sig., Dott.).
Selez_mail_ASS_cond / Selez_spediz_ASS_cond rubrica_universale.canale_notifiche Preferenze di spedizione: se mail "Si" ➔ digitale (Email/PEC); se spediz "Si" ➔ cartaceo (Posta/Raccomandata).
Ricorda_che_Cond rubrica_universale.note_promemoria_proprietario Campo text visualizzato como popup Filament all'operatore.
Ricorda_che_Inq rubrica_universale.note_promemoria_inquilino Campo text visualizzato como popup Filament all'operatore.
Cond_cod_fisc / Inquil_cod_fisc rubrica_universale.codice_fiscale Codici fiscali di condòmino ed inquilino, validati tramite Regex italiana (con log in caso di errore).
Cond_dt_nasc / Cond_Luogo_nasc rubrica_universale Data e luogo di nascita per adempimenti fiscali.
Catasto_sez_Urbana / Catasto_foglio / Catasto_particella / Catasto_sub unita_immobiliari.dati_catastali Dati catastali dell'unità (Sezione, Foglio, Particella, Subalterno) per Quadro AC.
Catasto_Rendita / Catasto_superfice unita_immobiliari Rendita catastale e superficie per dichiarazioni.
Diritto_reale / Diritto_godimento unita_anagrafica_periodo.tipo_diritto Definisce il ruolo giuridico e la sussidiarietà per rate scadute.

4. Mappatura File Master generale_stabile.mdb

Per blindare la quadratura finanziaria e riconciliare i solleciti con il dovuto reale, la migrazione integra la tabella master di allineamento:

A. Tabella [emes_gen] e [emes_det] (Emissione Rate)

  • emes_gen: id_emissione, data_emissione, descrizione_emissione ➔ rate_emissioni_master. Mantiene la cronologia delle emissioni deliberate.
  • emes_det: id_unita, num_rata, importo_richiesto, scadenza ➔ rate_scadenze. Mappa il dovuto di cassa associato alla singola unità.

B. Tabella [inc_da_ec] (Incassi Estratto Conto)

  • num_incasso / data_incasso / importo_incassato ➔ movimenti_cassa (Partita Doppia: Dare banca, Avere crediti condòmini).
  • nome_file_pdf ➔ campo_audit.codice_verifica_pdf. Associa la registrazione all'estratto conto stampato.
  • num_incasso ➔ Si aggancia alla tabella incassi.n_riferimento del file singolo_anno.mdb (trovato seguendo anni.nome_dir), assicurando la continuità contabile dell'anno.

C. Tabella [protoc_ec] (Registro Spedizioni)

  • id_protocollo / data_invio / tipo_comunicazione (Sollecito/Estratto Conto) ➔ registro_protocollo_comunicazioni.
  • nome_pdf ➔ percorso_documentale_allegato.
  • cod_condomino / id_unita ➔ Collegati alle anagrafiche e alle unità immobiliari per consentire il confronto a schermo tra l'estratto conto cartaceo d'epoca e quello calcolato a runtime.

5. Sequenza Esecutiva Importazione Core (Filament Orchestrator)

L'importazione dello stabile pilota 0021 viene avviata dalla pagina /admin-filament/gescon/importazione-archivi e segue questi step deterministici:

  • STEP 0 (Fondamenta):
    1. Lookup ed allineamento dell'anagrafica Amministratore / Studio (Multi-Tenant a 8 cifre).
    2. Importazione dell'elenco completo dei Fornitori (da Fornitori.mdb) compilando le preferenze fiscali, aliquote ritenuta rit_95100, codici tributo F24 Trib_1019_1020 ed IBAN d'appoggio.
  • STEP 1 (Esercizi & Stabile):
    1. Importazione anagrafica Stabile 0021, coordinate bancarie e SMTP/PEC dedicati.
    2. Lettura dinamica della tabella [anni] di generale_stabile.mdb per risolvere l'ultima gestione e le directory anno su /mnt/gescon-archives/gescon/.
  • STEP 2 (Unità & Timeline Persone):
    1. Creazione delle entità fisse unita_immobiliari mediante algoritmo di de-duplicazione spaziale.
    2. Importazione ed associazione delle anagrafiche Proprietari (C), Inquilini (I) e Comproprietari con timeline temporale in unita_anagrafica_periodo a ritroso per tutti gli anni storici.
  • STEP 3 (Millesimi & Piano dei Conti):
    1. Collegamento permanente delle tabelle millesimali (Mastri) alle unità.
    2. Associazione delle voci di spesa (Sottoconti) mappate per ciascun anno per conservare variazioni di descrizione ed importo.

Tutte le anomalie riscontrate (CF errati, PDF mancanti) vengono loggate in storage/logs/migrazione_test.log.

6. Sincronizzazione Incrementale 1:1 (Update/Merge No-Duplicates)

Per evitare la duplicazione dei dati in caso di esecuzioni ripetute dell'importatore, il sistema adotta le seguenti politiche:

  1. De-duplicazione e Upsert: Ogni record importato (Anagrafiche, Fornitori, Unità, Millesimi, Voci di spesa) viene confrontato con le chiavi univoche ereditate dal legacy (es. legacy_id, cod_cond, cod_forn).
  2. Aggiornamento Speculare: Se il record esiste già, viene eseguito un aggiornamento (Update/Merge) delle sole colonne variate, mantenendo intatti gli ID primari interni (id autoincrementale di MySQL) e le relazioni consolidate (FK).
  3. Preservazione dei Dati Locali: Eventuali arricchimenti inseriti direttamente in NetGescon non vengono sovrascritti, a meno che il campo corrispondente nel legacy non sia stato esplicitamente modificato.

7. Filosofia Interfaccia Utente: CRUD In-line (No Modal)

Per la successiva gestione dei dati di base importati, l'interfaccia grafica NetGescon adotta una filosofia a zero pop-up:

  • Modifica In-place: Tutte le maschere Filament per Anagrafiche, Fornitori, Unità e Spese utilizzano componenti editabili integrati direttamente nelle righe delle tabelle o all'interno delle schede (Tab) della pagina corrente.
  • No Modal: È vietato l'uso di finestre modali o pop-up per le operazioni di inserimento e modifica, consentendo all'utente di lavorare in modo continuo e concentrato sul contesto visivo originale.

8. Indipendenza e Transizione da Legacy

L'architettura dei dati (Tabelle Millesimali come Conti, Spese come Sottoconti, Timeline Unità) è progettata in modo da garantire l'autonomia di NetGescon:

  • Una volta completata la migrazione storica degli archivi d'epoca, lo stabile può essere scollegato definitivamente dal vecchio Gescon.
  • Le gestioni future verranno inserite ed elaborate nativamente in Partita Doppia direttamente nell'interfaccia di NetGescon, senza alcuna dipendenza dai file MDB o dalle vecchie strutture dati.

9. Vincoli Rigidi Contabili (Rimozione Risolutore Semantico)

Per garantire un approccio deterministico matematico all'importazione dei millesimi e delle spese, è vietato l'uso di qualsiasi risolutore semantico o euristiche basate su parole chiave per abbinare le gestioni straordinarie:

  1. Identificazione della Gestione:
    • Il tipo di gestione viene ricavato esclusivamente dal campo tipologia di tabelle_millesimali di staging ('O' Ordinaria, 'R' Riscaldamento, 'S' Straordinaria).
    • Per le tabelle millesimali o le spese straordinarie, il campo dett_tab.n_stra e straordinarie.codice identificano in modo rigido e deterministico l'ID numerico sequenziale della gestione straordinaria (es. da 1 a 5 per lo stabile 0021).
  2. Eliminazione degli Helper Semantici:
    • Gli helper matchExtraordinaryNumber e inferStraordinariaSequence sono stati completamente rimossi e sostituiti da un abbinamento basato rigidamente sulle chiavi numeriche reali presenti nel database di staging.

10. Geometria Fisica Reale 0021 e Rincorsa Codici

Per la de-duplicazione spaziale e il tracciamento dei subentri storici dello stabile 0021, si applicano le seguenti regole tassative:

  1. Geometria Fisica Reale dello Stabile 0021 (212 Unità Immobiliari Reali): Lo stabile non ha 221 o 239 unità, ma esattamente 212 unità fisiche, così composte:
    • Palazzina A: 27 interni scala A + 1 interno speciale + 6 altri locali (box/cantine) = 34 unità totali.
    • Palazzina B: 27 interni scala B + 1 interno speciale + 6 altri locali = 34 unità totali.
    • Palazzina C: 27 interni scala C + 1 interno speciale + 6 altri locali = 34 unità totali.
    • Palazzina D: 27 interni scala D + 1 interno speciale + 6 altri locali = 34 unità totali.
    • Altre pertinenze e locali accessori: 76 unità. Per garantire la composizione corretta, la query di estrazione currentSnapshotCondominQuery() caricherà tutte le unità storicamente registrate, senza filtrare per il solo anno di snapshot più recente (che escluderebbe unità chiuse o storiche).
  2. Algoritmo di Rincorsa dei Codici:
    • Ancoraggio su Unità Fisica: I subentri e i passaggi storici sono collegati all'unità fisica immutabile.
    • Mappatura Chiave Incassi: Il campo legacy_cond_id in unita_immobiliari e in unita_immobiliare_nominativi è mappato rigidamente su condomin.cod_cond (codice stabile nel tempo usato per le rate), slegandolo dall'ID record temporaneo annuale condomin.id_cond.
    • Storico Comproprietà: Viene mantenuto il join storico tra condomin.id_cond e comproprietari.id_cond per ricostruire le percentuali e i diritti dei comproprietari associati ad ogni specifico esercizio annuale.
  3. Mappatura Cumuli e Diritto Reale:
    • I campi cumulo_cond, cumulo_inq, cumulo_cond_orig, cumulo_inq_orig e e_lostesso_di vengono salvati nel payload JSON (legacy_payload) dell'anagrafica.
    • Si legge dynamicamente la presenza delle colonne nel database SQLite di staging tramite hasColumn().

11. Modulo Importatore Contatori e Auto-Apprendimento Associazioni Seriali

Il sistema gestisce l'importazione di letture da file CSV esterni per i contatori di consumo:

  1. Parsing CSV Flessibile: Il modulo accetta file CSV contenenti matricole e indicazioni di interno non normalizzate.
  2. Staging degli Orfani (contatori_orfani_staging): Se una matricola non corrisponde ad alcuna unità immobiliare censita, la lettura viene inserita nello staging temporaneo degli orfani.
  3. Associazione In-line & Auto-Apprendimento: Tramite la Tab "Orfani Contatori" in /servizi-utenze, l'amministratore associa manualmente la matricola all'unità corretta. Questa azione aggiorna permanentemente la colonna acqua_contatore_seriale del modello UnitaImmobiliare (auto-apprendimento).
  4. Importazioni Successive: Ai successivi caricamenti di file CSV contenenti la stessa matricola, il sistema riconoscerà l'associazione in modo deterministico e caricherà le letture direttamente nella tabella stabile_servizio_letture.