# 📑 SOP - INTEGRAZIONE HUB CATASTO (SERVIZIO SISTER AGENZIA DELLE ENTRATE) > **Documento di Livello 1 (SOP Esecutiva)** > Integrazione per la validazione della consistenza catastale e della titolarità (Proprietari/Comproprietari) per le 212 unità immobiliari dello Stabile. --- ## 1. Visione del Modulo e Sicurezza (Privacy Multi-Tenant) L'HUB Catasto consente di incrociare in modo deterministico i dati delle unità immobiliari NetGescon con le risultanze ufficiali dell'Agenzia delle Entrate tramite il provider Sister (`thenetworksolution.it`). - **Autenticazione Centralizzata**: - Il sistema eredita le credenziali in background (username `u` e password `p` o chiave licenza `passwordScript`) dal file `.env` (configurazione `SISTER_USERNAME`, `SISTER_PASSWORD`, `SISTER_LICENSE_KEY`). - **Isolamento Documentale Multi-Tenant**: - Tutti i file scaricati (visure PDF, file XML firmati digitalmente, file JSON temporanei e archivi ZIP per omoimmobili) devono essere salvati in modo isolato nel cloud drive dello stabile rispettando rigidamente il percorso: `[Codice_Amministratore_8_Caratteri]/[Codice_Stabile_0021]/catasto/` - I cookie di sessione e i log delle chiamate per le sessioni concorrenti devono essere salvati nella sotto-cartella temporanea dello stabile per evitare collisioni. --- ## 2. Flusso dei Metodi di 'SisterCatastoService.php' Il service Laravel `App\Services\SisterCatastoService.php` gestirà la comunicazione con gli endpoint di TheNetworkSolution tramite `Http` client o cURL, implementando i seguenti metodi tecnici deterministici: ### Metodo A: `ricercaImmobiliSoggetto` (mashImmobili.php) - **Endpoint**: `https://thenetworksolution.it/sister/mashImmobili.php` - **Parametri**: - `cf` (se persona fisica) o `pg` (se persona giuridica) - `tipoCatasto` (`F` per Fabbricati, `T` per Terreni, `E` per Entrambi - di default `E`) - `uffprovinciale` (es: `ROMA Territorio-RM`) - **Regole & Easy Mode**: - Utilizza il parametro `&easy=1` per restituire il `SID` di sessione nel JSON di risposta, semplificando il tracciamento dei cookie HTTP senza dipendere dallo stato di sessione del browser. - **Output**: Array JSON contenente i dati anagrafici del soggetto e la lista di immobili associati con coordinate (Foglio, Particella, Subalterno) e Rendita. ### Metodo B: `ricercaIntestatiImmobile` (mashIntestati.php) - **Endpoint**: `https://thenetworksolution.it/sister/mashIntestati.php` - **Parametri**: - `tipoCatasto` (`F` / `T`) - `uffprovinciale` - `denomComune` (es: `D969#GENOVA#10#3` recuperato dall'ausiliario `comuni.php`) - `sezione` (opzionale) - `sezUrb` (opzionale) - `foglio` (nullable, convertito a stringa vuota) - `particella` (nullable, convertito a stringa vuota) - `subalterno` - **Output**: Array JSON contenente tutti i soggetti intestatari reali dell'immobile rilevati dall'Agenzia delle Entrate, comprensivo di quote di possesso (es: `1/2`, `1/1`) e titoli (Proprietà, Usufrutto, Nuda Proprietà). ### Metodo C: `acquistaEPrelevaVisura` (mashVisureI.php / elencoRichieste.php) - **Endpoint Visura**: `https://thenetworksolution.it/sister/mashVisureI.php` - **Endpoint Polling**: `https://thenetworksolution.it/sister/elencoRichieste.php` - **Regole di Evasione e Polling**: - Se il servizio restituisce direttamente il file PDF/XML, lo salva nel Drive dello Stabile. - Se il servizio riscontra un'evasione differita restituendo `{idRichiesta: 1555611493}`, il sistema avvia un polling asincrono in background richiamando `elencoRichieste.php?download=1555611493` a intervalli regolari (es. ogni 10 secondi, per un massimo di 5 tentativi) fino al prelievo del documento. - **Gestione Omoimmobili**: - In caso di omoimmobili, Sister restituisce un archivio ZIP contenente le visure multiple. Il service deve scompattare l'archivio ZIP memorizzando i singoli file PDF/XML all'interno del percorso cloud drive dello stabile. - **Gestione Cache delle 24 Ore**: - Tutte le chiamate di acquisto mantengono di default la cache a 24 ore per impedire addebiti duplicati accidentali. Per forzare un nuovo acquisto o per visure storiche entro 24 ore da una completa, passare esplicitamente il parametro `&cache=0`. --- ## 3. Regole di Business e Allineamento Dati (NetGescon Core) L'importazione e la validazione dei dati catastali devono proteggere i dati core ed allinearsi al modello anagrafico temporale: ### A. Ereditarietà e Variazioni Temporali (Proprietari vs Inquilini) - I dati estratti (soggetti intestatari e quote) devono essere associati **esclusivamente** ai Condòmini/Proprietari (ruolo `C` o comproprietari storici). - Gli Inquilini (ruolo `I`) sono esclusi da questa verifica catastale. - Le variazioni di titolarità e quote devono essere registrate como record storici all'interno della tabella pivot `unita_anagrafica_periodo` con le date di decorrenza (dal/al) rilevate dalla visura catastale o dall'atto. ### B. Audit, Revisione ed Isolamento Anomalie - In caso di sbilanciamenti catastali (es: discrepanza di Rendita, Subalterno errato o Foglio disallineato rispetto al database legacy): - Il sistema **NON** deve sovrascrivere in modo automatico i campi catastali dell'unità immobiliare. - La discrepanza deve essere registrata come anomalia e presentata in evidenza (in colore rosso) all'interno del pannello "Audit e Revisione" dello stabile e dell'anno di gestione attivo. - L'operatore deve poter cliccare su "Riallinea" o "Aggiorna" per correggere ed associare manualmente i dati catastali corretti dell'unità direttamente in-place. --- ## 4. Flusso dell'Interfaccia Web (CatastoHub Filament) La pagina Filament `CatastoHub.php` esporrà un'interfaccia a due Tab principali: ### TAB A (Visione Globale Stabile): - **Sotto-Sezione Sinistra (SX)**: Mostra l'elenco completo di tutti i subalterni rilevati catastalmente su Sister (inclusi quelli soppressi, es. 3 e 7 per Milizie 3). - **Sotto-Sezione Destra (DX)**: Mostra la griglia ordinata delle nostre 212 unità immobiliari core ereditate dal legacy, consentendo un riscontro visivo in-line per verificare immediatamente se mancano immobili o se i dati coincidono. ### TAB B (Scheda Variazioni Appartamento): - **Colonna Sinistra (SX)**: L'elenco ordinato in modo naturale delle unità immobiliari core per Palazzina/Scala/Interno progressivo. - **Colonna Destra (DX - Raffronto a specchio)**: Espone un confronto visivo riga per riga afocato tra i Dati Catastali Legacy (dall'array `$stagingRawData` della tabella condomin) e i Dati Catastali Ufficiali scaricati da Sister. - Tutti i campi di allineamento manuale (Foglio, Particella, Subalterno, Sezione Urbana, Categoria, Rendita) sono editabili in-place. L'azione "Applica e Correggi" e "Approva Variazione" scrive a database i campi supportati ed inserisce le modifiche storiche in `unita_anagrafica_periodo` solo previa approvazione manuale dell'operatore. --- ## 5. Aggiornamenti e Ottimizzazioni Fase 7b A seguito del feedback degli utenti e della risoluzione dei bug bloccanti, sono state introdotte le seguenti evoluzioni: ### A. Rimozione Limite Scarico Geometria (Ingestione Massiva) - Il metodo `interrogaGeometriaStabile()` non limita l'acquisizione dei subalterni a un tetto massimo di 10 record, ma esegue l'elaborazione dell'elenco completo di tutti i subalterni della particella 256 del Foglio 405 (Milizie 3) storicizzandoli in cache. ### B. Tolleranza Coordinate Vuote (TypeError Check) - I parametri `$foglio` e `$particella` nei metodi `ricercaIntestatiImmobile` e `acquistaEPrelevaVisura` in `SisterCatastoService.php` sono nullable (`?string`). - Durante l'invocazione da parte del controller `CatastoHub.php`, viene effettuato un casting stringa preventivo con fallback a stringa vuota: `(string)($unita->foglio ?? '')` e `(string)($unita->particella ?? '')` per impedire blocchi di esecuzione causati da record legacy incompleti. ### C. Gestione Doppie Scale e Ricerca Unità - Per ovviare alle apparenti duplicazioni delle unità a sinistra (es. quattro volte l'interno 1 per scale diverse A, B, C, D), l'elenco della colonna di sinistra visualizza sia la **Scala** che l'**Interno** (es: `Scala A · Int. 1`). - Introdotto un campo di input per filtrare in tempo reale l'elenco delle unità e un pulsante per invertire l'ordinamento (`Sort: ASC/DESC`) agendo progressivamente su `interno` e `scala`. ### D. Scorciatoie nell'Header (Eliminazione Dropdown) - Rimosso il selettore della gestione dalla topbar. - Inseriti due link rapidi per navigare direttamente a `/admin-filament/condomini/riscaldamento-utenze` (badge compatto **[RISCALDAMENTO]**) e a `/admin-filament/gescon/straordinarie` (badge compatto **[STRAORDINARIE]**), ereditando correttamente il parametro `stabile_id` attivo. - Il selettore dell'anno di gestione contabile corrente rimane fisso e visibile per non compromettere il cambio anno dell'operatore. ### E. Dizionario Categorie Catastali Standard dello Stato Il sistema integra a livello di Service e Controller la mappatura deterministica ufficiale dell'Agenzia delle Entrate per la decodifica automatica delle categorie: - **Gruppo A (A/1 - A/11)**: Abitazioni (es. A02 ➔ A/2 - Abitazioni di tipo civile). - **Gruppo B (B/1 - B/8)**: Collegi, caserme, ospedali, scuole (es. B01 ➔ B/1). - **Gruppo C (C/1 - C/7)**: Negozi, magazzini, autorimesse (es. C02 ➔ C/2 - Magazzini e locali di deposito, C06 ➔ C/6). - **Gruppo D (D/1 - D/10)**: Opifici, alberghi, teatri (es. D01 ➔ D/1 - Opifici). - **Gruppo E (E/1 - E/9)**: Stazioni, ponti, recinti pubblici. - **Gruppo F (F/1 - F/7)**: Aree urbane, lastrici solari, unità collabenti (es. F05 ➔ F/5 - Lastrico solare).