# 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`)**. ```mermaid 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: > ```php > 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](file:///home/michele/netgescon-day0-backup/app/Services/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. ```mermaid 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.