135 lines
9.6 KiB
Markdown
135 lines
9.6 KiB
Markdown
# 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.
|
|
|