167 lines
14 KiB
Markdown
167 lines
14 KiB
Markdown
# 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`.
|
|
|
|
|