michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
248bdd032c
netgescon-day0/docs/DEVELOPER_GUIDE.md

9.6 KiB
Raw Blame History

Guida allo Sviluppo e Architettura Modulare di NetGescon

Benvenuto nella guida ufficiale allo sviluppo di NetGescon. Questo documento descrive l'architettura tecnica del sistema, la struttura del database, i flussi di importazione dei dati legacy e le linee guida per lo sviluppo di moduli estensibili open-source.

L'obiettivo di NetGescon è fornire una piattaforma gestionale condominiale solida, sicura ed estensibile in stile Odoo, in cui moduli e componenti esterni possono essere agganciati facilmente al core dell'applicazione.

1. Visione Open-Source ed Estensibilità Modulare

NetGescon è strutturato per consentire a sviluppatori terzi di aggiungere funzionalità senza alterare il nucleo dell'applicazione.

1.1 La Directory app/Modules/

L'applicazione organizza le macro-funzionalità estendibili all'interno di app/Modules/. Attualmente sono presenti i moduli:

  • Contabilita: Modelli, viste e servizi relativi alla contabilità, bilancio e prima nota.
  • StampeRate: Logica di generazione e formattazione dei report e delle stampe per le rate.

1.2 Regole per Creare un Nuovo Modulo (es. LettureAcqua)

Ogni modulo deve essere autocontenuto:

  1. Struttura: Crea una cartella in app/Modules/NomeModulo contenente sotto-cartelle per Models, Services, Http (o Livewire/Filament).
  2. Database: Le tabelle di database di un modulo devono avere chiavi esterne verso le tabelle principali (es. unita_immobiliari_id, stabili_id) ma risiedere in tabelle separate per evitare collisioni.
  3. Filament Integration: Le risorse Filament del modulo devono essere registrate dinamicamente nel pannello principale, garantendo la compatibilità con i temi e i permessi globali dell'applicazione.

2. Struttura del Database e Mappatura dei Dati

Il sistema gestisce due connessioni e schemi di database principali: la connessione di Produzione e la connessione di Staging (gescon_import).

graph TD
    MDB[File Legacy MDB] -->|Caricamento| Staging[Database Staging: gescon_import]
    Staging -->|Pipeline di Importazione| Prod[Database di Produzione]
    Prod -->|Pannello di Amministrazione| Filament[Filament v3 UI]

2.1 Connessione Staging (gescon_import)

Utilizzata per caricare temporaneamente i dati legacy dagli archivi MDB. Le tabelle principali di staging sono:

  • condomin: Contiene le anagrafiche dei condomini, proprietari, inquilini e informazioni sulle unità.
  • dett_tab: Dettaglio dei millesimi e importi associati a ciascuna tabella millesimale legacy.
  • dett_pers: Contiene le spese personali/addebiti specifici per condomino o inquilino.
  • operazioni: Elenco delle registrazioni e movimenti legacy.

Warning

Lo schema di staging è altamente flessibile. Colonne differenti possono essere presenti a seconda della versione del file MDB originario. Prima di effettuare query, verificare sempre la presenza delle colonne via:

Schema::connection('gescon_import')->getColumnListing($table)

2.2 Database di Produzione (Tabelle Chiave)

  • stabili: Collegato alla rubrica universale tramite rubrica_id.
  • unita_immobiliari: Rappresenta le singole unità (interni, scale, palazzine).
  • tabelle_millesimali: Definizione delle tabelle (millesimi di proprietà, riscaldamento, ascensore, ecc.). Contiene la colonna nord per determinare l'ordinamento legacy di visualizzazione.
  • dettaglio_millesimi: Associa le unità immobiliari alle tabelle millesimali.
    • Chiave composita unica: ['tabella_millesimale_id', 'unita_immobiliare_id', 'ruolo_legacy'].
    • Questo consente di avere record separati sulla stessa unità per Condomino (ruolo_legacy = C) ed Inquilino (ruolo_legacy = I), garantendo la corretta attribuzione dei millesimi per tipo di soggetto.
  • voci_spesa: Elenco delle voci di costo collegate ai bilanci e alle gestioni contabili.

3. Pipeline d'Importazione dei Dati (ImportGesconFullPipeline.php)

La pipeline esegue l'importazione sequenziale dei dati con un flusso incrementale:

  1. stepStabili: Importa gli stabili e li sincronizza con la Rubrica Universale.
  2. stepMillesimi:
    • Associa i millesimi senza collassare le righe con ruoli differenti (C e I).
    • Conserva e mappa il campo nord per l'ordinamento delle righe.
  3. stepAffitti: Esegue l'importazione dei canoni e dei contratti dal database parti_comuni.mdb.
  4. stepOperazioni: Sincronizza in modo incrementale i movimenti in prima nota.

4. Validazioni e Regole di Business Contabili

4.1 Quadratura Millesimi a Consuntivo (Blocco di Sicurezza)

Per evitare errori nei bilanci finali, la ripartizione contabile a Consuntivo è protetta da un blocco di sicurezza in RipartizioneSpesaService.php:

  • Se la somma dei millesimi di dettaglio presenti in dettaglio_millesimi per la tabella specificata differisce dal totale dichiarato in tabelle_millesimali.totale_millesimi (solitamente 1000.00):
    • A Preventivo: Il sistema solleva un warning non bloccante memorizzato nei log.
    • A Consuntivo: Il sistema lancia un'eccezione che blocca l'esecuzione e impedisce il salvataggio della ripartizione.

5. Strategia per Moduli e Integrazioni Future (API & Gateway)

Questa sezione delinea l'architettura programmata per le prossime implementazioni, facilitando l'allacciamento di servizi esterni tramite API.

5.1 Portale Condomini/Inquilini ed Estratto Conto con Gateway Esterni

Per consentire il pagamento autonomo delle rate e dei debiti minimizzando i rischi di sicurezza:

  • Zero Dati Finanziari in Locale: NetGescon non memorizzerà credenziali di carte di credito, IBAN o dati sensibili di pagamento nei propri server.
  • Flusso del Pagamento:
    1. Il condomino accede alla propria area riservata (Estratto Conto) e seleziona le rate da pagare.
    2. Il sistema genera un token di sessione di pagamento univoco e reindirizza l'utente a un gateway sicuro esterno (es. Stripe, PayPal, PagoPA).
    3. Al completamento del pagamento, il gateway esterno notifica NetGescon tramite un Webhook sicuro.
    4. NetGescon elabora il webhook, verifica la firma e aggiorna lo stato della rata a pagata registrando l'incasso e la relativa operazione contabile.
sequenceDiagram
    Condomino->>NetGescon: Richiesta pagamento rate
    NetGescon->>Gateway Esterno: Crea sessione e reindirizza
    Condomino->>Gateway Esterno: Inserisce dati e paga
    Gateway Esterno-->>NetGescon: Webhook (Notifica Pagamento Avvenuto)
    NetGescon->>NetGescon: Registra Incasso e Prima Nota
    Gateway Esterno->>Condomino: Conferma Pagamento

5.2 Modulo Letturisti e Gestione Consumi Acqua (API-First)

Per agevolare chi effettua le letture e le installazioni sul campo, l'integrazione avverrà in modalità API-First:

  • Interfaccia Dedicata: Una sezione autonoma per i tecnici letturisti in cui gestire:
    • Installazione e anagrafica contatori.
    • Inserimento rapido delle letture periodiche (anche offline/mobile).
  • Algoritmi di Consumo e Rilevamento Perdite Silenti:
    • NetGescon riceve le letture e applica algoritmi predittivi basati sullo storico dei consumi.
    • Se viene rilevato un consumo continuo anomalo (es. prelievo d'acqua notturno costante per più giorni), il sistema invia automaticamente notifiche push o email di allarme al condomino e all'amministratore per prevenire danni da perdite d'acqua.

5.3 Integrazioni Governative (Italia)

Il core sarà espanso per interfacciarsi con le banche dati della pubblica amministrazione italiana:

  • ANPR / Agenzia delle Entrate: Per verificare la correttezza dei codici fiscali e delle anagrafiche dei condomini importati.
  • SDI (Fatturazione Elettronica): Integrazione nativa per la ricezione automatica in prima nota delle fatture fornitori in formato XML.

6. Riepilogo Modifiche Recenti (Changelog Tecnico)

Durante questo ciclo di sviluppo sono stati implementati i seguenti miglioramenti architetturali e correttivi:

  • Configurazione e Toggle Globali: Introdotta la chiave legacy_import_enabled in config/netgescon.php per condizionare l'accesso ed eliminare/nascondere le viste di importazione legacy se non attive.
  • Sincronizzazione Rubrica Universale: Implementato il metodo syncRubricaContatto() sul modello Stabile.php per inserire automaticamente i contatti degli stabili in rubrica (categoria 'condomino', tipo 'persona_giuridica').
  • Importazione Canoni di Locazione: Aggiunto lo step CLI 'affitti' alla pipeline per avviare affitti:import-mdb --refresh-canoni sul database parti_comuni.mdb.
  • Campo nord e Count Voci: Introdotta la colonna nord per l'ordinamento manuale legacy delle tabelle millesimali e calcolato/mostrato a schermo il conteggio delle voci di spesa collegate (voci_count).
  • Unificazione Prospetto Millesimi: Eliminazione della pagina ridondante TabelleMillesimaliProspetto e conversione dei link con parametro ?tab=prospetto. Iconizzazione delle azioni in griglia.
  • Preservazione Ruoli Comproprietari/Inquilini: Modifica del processo di importazione millesimi per non fondere le righe con lo stesso condomino ed unità ma ruoli differenti, salvando sia ruolo_legacy sia nord.
  • Filtro Ricerca Addebiti: Implementata la ricerca testuale nel modal addebiti personali (section.blade.php), salvaguardando la reattività e gli indici Livewire per le modifiche degli importi.
  • Quadratura Millesimi: Integrazione della validazione bloccante a consuntivo per controllare la discrepanza tra la somma dei dettagli millesimi e il totale dichiarato della tabella.