michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
stabilization/205-zero
netgescon-day0/directives/sop_hub_catasto_sister.md

9.5 KiB
Raw Permalink Blame History

📑 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).