309 lines
17 KiB
Markdown
Executable File
309 lines
17 KiB
Markdown
Executable File
# Guida Import GESCON da MDB
|
|
|
|
## Obiettivo
|
|
|
|
Usare `Stabili.mdb` come sorgente di controllo iniziale per decidere quali stabili importare, con una finestra dati prudente e verificabile prima della distribuzione operativa.
|
|
|
|
## Sorgenti da considerare
|
|
|
|
### 1. Metadati stabili
|
|
|
|
- `dbc/Stabili.mdb`
|
|
- campi chiave attesi:
|
|
- `cod_stabile`
|
|
- `nome_directory`
|
|
- campo CF stabile/condominio valorizzato
|
|
|
|
### 2. Dati annuali per stabile
|
|
|
|
- `<cod_stabile>/<anno>/singolo_anno.mdb`
|
|
- tabelle minime da validare:
|
|
- `condomin`
|
|
- `operazioni`
|
|
- `rate`
|
|
- `incassi`
|
|
- `dett_tab`
|
|
- `voc_spe`
|
|
- `straordinarie`
|
|
|
|
### 3. Dati trasversali stabile
|
|
|
|
- `<cod_stabile>/generale_stabile.mdb`
|
|
- utile per verifiche aggiuntive su rate emesse, casse, incassi da estratto conto e dati generali
|
|
|
|
## Regola multi-amministratore verificata 03/06/2026
|
|
|
|
- Lo stesso `codice_stabile` deve poter convivere sotto amministratori diversi; la chiave corretta del contenitore dominio non e il solo codice stabile ma almeno `amministratore_id + codice_stabile`.
|
|
- La stessa regola vale per le unita importate: `codice_unita` non puo restare globale se si vuole importare lo stesso stabile sotto due amministratori distinti.
|
|
- Nel dominio DEV e stata verificata la coesistenza di `0026` su due tenant distinti:
|
|
- `stabile_id=31` sotto amministratore test `00000000`
|
|
- `stabile_id=32` sotto amministratore reale `HWFGITXK`
|
|
- Il reimport deve aggiornare il tenant selezionato senza riattribuire lo stabile all'altro amministratore.
|
|
|
|
## Regola sorgenti MDB per contabilita Gescon
|
|
|
|
- `singolo_anno.mdb` resta la sorgente annuale per `condomin`, `operazioni`, `rate`, `incassi`, `dett_tab`, `voc_spe`, `straordinarie`.
|
|
- `generale_stabile.mdb` e la sorgente autorevole per `EMES_GEN`, `EMES_DET` e `Inc_da_ec` / `in_da_ec`.
|
|
- Le tabelle annuali caricate in `gescon_import` devono sempre portare con se `cod_stabile` e `legacy_year`; se la staging proviene da schema storico va eseguito il reload con il loader aggiornato, non un semplice riuso delle righe gia presenti.
|
|
- Per `operazioni` il reload deve essere idempotente su `id_operaz`: in caso contrario la pagina Filament puo vedere scritture miste o righe non riallineate allo slice reale dello stabile.
|
|
- Per `in_da_ec` il reload deve produrre una staging slice-aware (`cod_stabile`, `legacy_year`) e una materializzazione read-only nel dominio (`incassi_estratto_conto`) con hash stabile del movimento, senza creare incassi applicativi automatici: l abbinamento finale resta umano-assistito.
|
|
- Il nuovo HUB operativo e `admin-filament/contabilita/incassi`: deve mostrare sia `incassi` dominio sia snapshot legacy `in_da_ec` con payload pronto per AI interna; lo stesso snapshot e disponibile via `GET api/v1/incassi/hub` protetto da `auth:sanctum`.
|
|
- Per lo stabile `0026 / anno 0001` e stato verificato che:
|
|
- `incassi` nel `singolo_anno.mdb` contiene `0` righe, quindi uno staging vuoto non e un errore di import ma un dato legacy reale.
|
|
- `EMES_GEN` nel `generale_stabile.mdb` contiene `3` emissioni.
|
|
- `EMES_DET` nel `generale_stabile.mdb` contiene `81` righe dettaglio.
|
|
- Le verifiche funzionali attese per `0026 / stabile_id=32` dopo il reload corretto delle sorgenti sono:
|
|
- prima emissione `2026-01-05`: totale `5037,00`, `24` ricevute distinte
|
|
- seconda emissione `2026-05-05`: totale `5037,00`, `24` ricevute distinte
|
|
- conguaglio `2026-06-02`: totale `1226,27`, `24` ricevute distinte
|
|
- ricevuta `24`: unita legacy `20-21-22-23` (`SEM-A`, `SEM-B`, `SEM-C`, `SEM-D`)
|
|
- Smoke test reale eseguito il `04/06/2026` su `0026 / anno 0001 / stabile_id=32 / amministratore_id=5`:
|
|
- archivio disponibile nel mount GESCON: solo cartella `0001`
|
|
- `gescon:import-full --stabile=0026 --amministratore-id=5 --anno=1 --path=/mnt/gescon-archives/gescon` completa la pipeline senza errori
|
|
- al rerun gli importi `rate_emesse` restano stabili a `81` righe e somma `11300.27`
|
|
- al rerun `dati_bancari` resta consolidato a `1` riga (`CCB`, IBAN `IT58P0103003203000001300987`)
|
|
- gli `incassi` restano `0`, coerenti con il contenuto reale di `singolo_anno.mdb`
|
|
|
|
## Regole operative di preselezione
|
|
|
|
Importare nello smoke test solo gli stabili che rispettano tutte queste condizioni:
|
|
|
|
1. lo stabile esiste in `Stabili.mdb`
|
|
2. il campo CF stabile/condominio e valorizzato
|
|
3. `cod_stabile` e presente e usabile come codice mnemonico principale
|
|
4. `nome_directory` e presente e punta a una cartella archivio esistente
|
|
|
|
## Regola gestioni cross-year e riferimenti emissione
|
|
|
|
- Per stabili come `0016` l esercizio non va letto come anno solare: la gestione corretta e quella esposta in `generale_stabile.mdb -> anni` (`anno_o`, `ordinarie_dal`, `ordinarie_al`).
|
|
- `gescon_import.gestioni_annuali` deve essere popolata o riallineata da quella tabella prima di rileggere `rate`, cosi la UI e i piani dominio possono raggruppare i movimenti su etichette come `2024/25` o `2025/26`.
|
|
- Anche `gestioni_contabili` dominio va riallineata sugli stessi periodi: `anno_gestione` puo restare numerico come chiave tecnica, ma `denominazione`, `data_inizio` e `data_fine` devono seguire il periodo reale (`Ordinaria 2024/25`, `2024-10-01 -> 2025-09-30`).
|
|
- `rate_emissioni_dettaglio` e la sorgente autorevole della contabilità per unità quando servono split proprietario/inquilino e riferimenti legacy: usare almeno questi campi:
|
|
- `cod_cond`
|
|
- `cond_inq`
|
|
- `anno_gestione`
|
|
- `numero_mese`
|
|
- `numero_ricevuta`
|
|
- `data_emissione`
|
|
- `importo_dovuto_euro`
|
|
- Regola validata sui riferimenti:
|
|
- `avviso_code = anno(data_emissione) + numero_mese` con padding a due cifre
|
|
- `numero_ricevuta` resta il riferimento da conservare per l aggancio degli incassi
|
|
- nelle viste dominio delle `rate_emesse` il riferimento legacy da esporre e `Gestione {anno_gestione} · ricevuta n.{numero_ricevuta}`; se `numero_ricevuta` manca, mostrare almeno `Gestione {anno_gestione}` e `avviso_code`
|
|
- esempio reale `0016-B-4`: `1/2 Rata di Marzo 2025` -> `anno_gestione=2024/25`, `numero_mese=1`, `data_emissione=2025-03-05`, `avviso_code=202501`, `numero_ricevuta=339`
|
|
- Quando `unita_immobiliari.legacy_cond_id` non coincide piu con il `cod_cond` corrente, la scheda unità deve risolvere i `cod_cond` candidati tramite `gescon_import.condomin` usando almeno `cod_stabile + scala + interno`; pero, se il `legacy_cond_id` salvato ha ancora righe reali in `rate_emissioni_dettaglio` per quella unità/stabile, va preferito per l estratto compatto per non mischiare snapshot correnti con la contabilità storica autoritativa. Caso validato: `0016-B-4` usa `legacy_cond_id=47` per leggere `52/196/268/626/697/766` in `2024/25`.
|
|
- Per la scheda unità il campo `Condomino di riferimento` deve riflettere `gescon_import.condomin.nom_cond`; i comproprietari restano dettaglio accessorio e non sorgente del riferimento principale.
|
|
|
|
## Regola consultazione esercizi importati
|
|
|
|
- In fase di riallineamento al legacy, gli archivi importati devono restare simmetrici al dato sorgente: nessuna somma implicita e nessuno spostamento automatico tra esercizi senza controllo.
|
|
- La consultazione NetGescon distingue ora tra:
|
|
- anni conteggiabili: gestioni aperte o attive, usate per il dovuto corrente
|
|
- anni visibili ma chiusi: ultima gestione chiusa, mantenuta per confronti totali e controlli legacy
|
|
- storico nascosto: esercizi piu vecchi importati e memorizzati, esclusi da estratti e conteggi finche non si abilita un filtro dedicato
|
|
- Sessione di test validata su `0016`:
|
|
- `2025` (`0914`) visibile e conteggiabile
|
|
- `2024` (`0913`) visibile e conteggiabile
|
|
- `2023` (`0912`) visibile ma chiusa, quindi fuori dal dovuto corrente
|
|
- `2022` e precedenti (`0909`, `0005`, `0004`, ...) nascosti per default
|
|
|
|
## Regole di naming e archivio
|
|
|
|
- codice stabile operativo: usare `stabile.cod_stabile`
|
|
- cartella archivio stabile: usare `stabile.nome_directory`
|
|
- cartella dominio NetGescon: usare sempre il codice univoco/canonico dello stabile
|
|
- sincronizzazione documentale: mantenere mapping stabile tra codice canonico NetGescon e cartella legacy, cosi da poter allineare anche Google Drive
|
|
|
|
## Finestra temporale smoke test
|
|
|
|
Per il primo passaggio operativo non importare tutto lo storico.
|
|
|
|
## Criterio autorevole unita e nominativi
|
|
|
|
- Lo snapshot corrente di `unita`, `soggetti` e `diritti` deve derivare sempre dall'ultimo anno legacy disponibile per lo stabile, non dall'anno storico che si sta rileggendo in quel momento.
|
|
- La chiave stabile di allineamento tra staging e dominio deve essere `condomin.id_cond` o `condomin.legacy_id_cond` quando disponibile. Nel dominio questo valore va mantenuto in `unita_immobiliari.legacy_cond_id`.
|
|
- `condomin.cod_cond` va trattato come codice di snapshot annuale: puo cambiare tra una gestione e l altra e quindi non e una chiave storica affidabile.
|
|
- Se `cod_cond` non coincide con l anno precedente, il fallback corretto e:
|
|
- verificare prima `id_cond`
|
|
- se il record annuale non basta, verificare il nominativo (`nom_cond` / `proprietario_denominazione`) tra annualita consecutive
|
|
- usare `cod_cond` solo come aggancio locale alla singola gestione per rate, incassi e pagamenti di quell anno
|
|
- `scala`, `interno` e `catasto_sub` servono per esporre il codice mnemonico operatore e per le verifiche di riconciliazione, ma non devono sostituire `id_cond` come chiave interna.
|
|
- Se si rilancia un'importazione su un anno precedente, il preflight deve comunque precaricare anche l'ultima annualita disponibile per evitare che lo snapshot corrente venga ricostruito con un anno vecchio.
|
|
- Non vanno creati fallback artificiali come `interno = 0`, unita sintetiche o nominativi fittizi per colmare buchi che non esistono nella sorgente.
|
|
|
|
## Regola operativa per import da blade
|
|
|
|
- La blade `admin-filament/gescon/importazione-archivi` deve guidare l operatore a partire dall ultima gestione aperta e a selezionare solo le gestioni da caricare andando a ritroso.
|
|
- Le annualita vanno mostrate in ordine decrescente, con la piu recente come default per `gestioni aperte`.
|
|
- Il pulsante consigliato per il flusso completo resta `Import + allineamento`, usando la selezione `Gestioni da caricare (ultima aperta -> ritroso)`.
|
|
- Questo passaggio e importante soprattutto nei casi legacy dove `cod_cond` e stato riallineato a mano dal vecchio amministratore e quindi ha spostato di uno o piu posti le righe delle annualita successive.
|
|
|
|
## Regola storico anni precedenti
|
|
|
|
- Gli anni precedenti arricchiscono `unita_immobiliare_nominativi` come cronologia delle variazioni.
|
|
- Non devono sovrascrivere il nominativo corrente dell'ultimo anno disponibile.
|
|
- Le compresenze di piu comproprietari nello stesso intervallo sono lecite e vanno distinte dai duplicati veri dello stesso nominativo.
|
|
- Il payload storico deve conservare integralmente le famiglie legacy utili alla UI e ai rebuild successivi: `cond_*`, `catasto_*`, `pertinenze_*`, `diritti_*`, `inquilin_*` e `inquil_*`.
|
|
- Per gli inquilini il CF autorevole e `condomin.inquilin_cod_fisc`; la data inizio contratto autorevole e `condomin.inquilin_contratto_dal`.
|
|
- Dopo una correzione anagrafica su `0016` o casi analoghi, il giro minimo coerente e:
|
|
- `php artisan gescon:import-full --stabile=<codice> --anno=<ultima_gestione> --path=<archivio> --solo=unita`
|
|
- `php artisan gescon:import-full --stabile=<codice> --anno=<ultima_gestione> --path=<archivio> --solo=relazioni`
|
|
- pulizia mirata di `rubrica_ruoli` sullo stabile
|
|
- `php artisan gescon:sync-rubrica-ruoli --stabile=<stabile_id> --limit=5000 --create-missing --apply`
|
|
|
|
## Bonifica anagrafiche post-import
|
|
|
|
- Dopo gli step `unita`, `soggetti` e `diritti`, eseguire la bonifica recapiti con `php artisan gescon:bonifica-rubrica-canali --stabile=<codice> --apply`.
|
|
- La bonifica spezza telefoni, email e PEC salvati nello stesso campo usando separatori legacy come `;`, `,`, newline o `/`.
|
|
- I recapiti vengono materializzati in `rubrica_contatti_canali` con tipo esplicito (`telefono`, `cellulare`, `email`, `pec`) e flag `is_principale`.
|
|
- Regola di classificazione attuale:
|
|
- numeri che iniziano con `3` => `cellulare`
|
|
- numeri che iniziano con `0` => `telefono`
|
|
- gli altri restano sul tipo di origine se gia noto
|
|
- La push/sync Google deve leggere e scrivere anche i canali aggiuntivi, non solo i campi primari della rubrica.
|
|
|
|
## Regola codice unita
|
|
|
|
- `unita_immobiliari.codice_unita` e limitato a `varchar(20)` nel dominio corrente.
|
|
- I codici generati dall'import devono quindi essere compatti e deterministici:
|
|
- rimozione dei separatori interni non significativi nei segmenti legacy
|
|
- se il codice supera ancora il limite, uso di suffisso hash corto stabile invece di troncare in modo ambiguo
|
|
- Questa regola e necessaria per stabili come `0013`, dove gli interni legacy aggregati possono produrre stringhe del tipo `0013-NGOT-107/109-C47`.
|
|
|
|
## Piloti verificati 08/04/2026
|
|
|
|
### `0002` - Carlo Alberto Racchia 2
|
|
|
|
- anno autorevole importato: `2024` (`0038`)
|
|
- `unita`: `61`
|
|
- `soggetti`: `52`
|
|
- `diritti`: `82` inseriti
|
|
- QA `netgescon:qa-unita-nominativi --stabile_id=8`:
|
|
- unita attive `61`
|
|
- unita senza nominativi `0`
|
|
- duplicati periodi `0`
|
|
- nessuna anomalia bloccante
|
|
- caso da tenere distinto dai buchi veri:
|
|
- `cod_cond = 62` nello snapshot `0038` risulta come record comune (`nome = CONDOMINIO (magazzino)`) e non ha `scala`, `interno`, `catasto_sub`, `piano`
|
|
- quindi oggi viene correttamente escluso dalla costruzione delle UI ordinarie se si pretende un identificativo fisico autorevole
|
|
|
|
### `0013` - Ottaviano 105 / Giulio Cesare 171
|
|
|
|
- anno autorevole importato: `2026` (`0015`)
|
|
- fix necessario prima del rilancio:
|
|
- compattazione deterministica di `codice_unita` per non superare il limite DB
|
|
- esito finale dopo fix:
|
|
- `unita`: `26` processate, `12` aggiornate
|
|
- `soggetti`: `50`
|
|
- `diritti`: `90` inseriti, `3` aggiornati, `39` ignorati
|
|
- QA `netgescon:qa-unita-nominativi --stabile_id=16`: nessuna anomalia bloccante
|
|
- attenzione funzionale aperta:
|
|
- stabile con unita fisicamente/catastalmente uniche ma spezzate nel legacy per gestire piu titolari
|
|
- la futura unione UI deve appoggiarsi a dati catastali e a logiche di cumulo/quote, non a merge distruttivi dei record legacy
|
|
|
|
### `0023` - Germanico 79 (legacy `8`)
|
|
|
|
- anno autorevole importato: `2025` (`0096`)
|
|
- `unita`: `27` processate, `16` aggiornate
|
|
- `soggetti`: `20`
|
|
- `diritti`: `25` inseriti, `15` aggiornati, `2` ignorati
|
|
- QA `netgescon:qa-unita-nominativi --stabile_id=24`: nessuna anomalia bloccante
|
|
|
|
## Regola straordinarie
|
|
|
|
- Le spese straordinarie vanno considerate aperte nella gestione in cui vengono lette.
|
|
- Codici legacy uguali presenti in anni diversi non vanno collassati tra loro: devono restare distinti almeno per anno gestione e, se serve, per numero progressivo straordinaria.
|
|
|
|
### Import base
|
|
|
|
- anno corrente legacy piu recente disponibile
|
|
- anno precedente
|
|
|
|
### Import esteso solo per straordinarie
|
|
|
|
- includere fino a 5 anni indietro
|
|
- fermarsi prima se non esistono MDB annuali o non esistono righe utili nelle tabelle straordinarie
|
|
|
|
### Storico oltre la finestra base
|
|
|
|
- da importare solo su richiesta o quando serve per quadrature, estratti conto storici o audit mirati
|
|
|
|
## Copertura minima richiesta per rendere operativo il sistema
|
|
|
|
Lo smoke test deve confermare che per ogni stabile selezionato siano importabili almeno:
|
|
|
|
1. nominativi completi da `condomin`
|
|
2. unita immobiliari e riferimenti scala/interno/piano
|
|
3. collegamenti proprietario/inquilino/comproprietari
|
|
4. voci spesa e tabelle millesimali essenziali
|
|
5. rate e incassi degli ultimi 2 anni
|
|
6. straordinarie degli ultimi 5 anni, se presenti
|
|
|
|
Questo e il minimo per attivare senza dati monchi:
|
|
|
|
- ticket
|
|
- letture acqua
|
|
- CRM/rubrica unica
|
|
- estratti conto da cellulare
|
|
- pagamento online rate condominiali
|
|
|
|
## Smoke Test pratico per stabile
|
|
|
|
Per ogni stabile filtrato da `Stabili.mdb` eseguire questa checklist.
|
|
|
|
### A. Controllo metadati
|
|
|
|
- `cod_stabile` valorizzato
|
|
- `nome_directory` valorizzato
|
|
- CF stabile valorizzato
|
|
- cartella legacy esistente
|
|
|
|
### B. Controllo annualita
|
|
|
|
- individuato ultimo anno disponibile
|
|
- individuato anno precedente disponibile
|
|
- individuate eventuali annualita straordinarie fino a -5 anni
|
|
|
|
### C. Controllo file
|
|
|
|
- esiste `singolo_anno.mdb` per ogni anno scelto
|
|
- se presente, esiste `generale_stabile.mdb`
|
|
- `Stabili.mdb` leggibile senza errori
|
|
|
|
### D. Controllo tabelle minime
|
|
|
|
- `condomin` leggibile
|
|
- `operazioni` leggibile
|
|
- `rate` leggibile
|
|
- `incassi` leggibile
|
|
- `dett_tab` leggibile
|
|
- `voc_spe` leggibile
|
|
- `straordinarie` leggibile o assente in modo coerente
|
|
|
|
### E. QA dominio post-import
|
|
|
|
- stabile creato/aggiornato correttamente
|
|
- unita importate
|
|
- rubrica/nominativi deduplicati
|
|
- snapshot corrente allineato all'ultima annualita disponibile
|
|
- `legacy_cond_id` valorizzato e coerente con `condomin.cod_cond`
|
|
- nessuna unita attiva con `interno = 0` o codice sintetico inventato
|
|
- rate/incassi coerenti per gli anni caricati
|
|
- nessun crash nelle pagine operative principali
|
|
|
|
## Raccomandazione di rollout
|
|
|
|
Ordine consigliato:
|
|
|
|
1. caricare elenco candidati da `Stabili.mdb`
|
|
2. filtrare solo stabili con CF valorizzato
|
|
3. per ciascuno verificare `nome_directory`
|
|
4. importare ultimi 2 anni
|
|
5. importare straordinarie fino a 5 anni
|
|
6. eseguire QA per stabile/anno
|
|
7. abilitare progressivamente ticket, letture, CRM e consultazione mobile
|
|
|
|
## Nota importante
|
|
|
|
La tabella staging `gescon_import.stabili` non va usata come unica base per questa preselezione se i CF risultano non materializzati. In quel caso la fonte corretta per lo smoke test resta il `Stabili.mdb` reale.
|