120 lines
9.5 KiB
Markdown
120 lines
9.5 KiB
Markdown
# 📑 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). |