netgescon-day0/docs/support/ARCHITETTURA-RUOLI-MODULI-COWORKING.md

Architettura ruoli, moduli e coworking

Obiettivo

NetGescon non va piu letto come un applicativo monoruolo dedicato solo all amministrazione condominiale.

La direzione corretta e questa:

1. una base dominio unica e coerente
2. moduli attivabili sopra la stessa base dati
3. ruoli e abilitazioni che decidono cosa una persona puo fare
4. stessa persona abilitabile su piu funzioni operative

In pratica: uno spazio unico di coworking operativo, non una somma di mini-app scollegate.

Base dominio da tenere stabile

La base comune resta:

• anagrafica unica dei nominativi
• stabili, unita immobiliari, relazioni e ruoli
• movimenti, banca, ripartizione spese, piano dei conti
• contabilita in partita doppia
• ticket, allegati, documenti e storico operativo

Questa base non va duplicata per mestiere o per modulo.

Cosa cambia davvero tra un uso e l altro

Quello che cambia non e il dato di partenza, ma:

• il ruolo
• la procedura disponibile
• il modulo abilitato
• il livello di permesso sul tenant, sullo stabile o sul progetto

Esempi reali della stessa persona:

• supporto informatico
• sviluppo software
• revisione contabile
• collaboratore dell amministratore
• gestione PBX / CTI
• supervisione di ticket e fornitori

Regola architetturale

NetGescon deve diventare:

• domain-first
• permission-first
• module-first

Non deve diventare:

• menu-first
• pagina-first
• ruolo singolo hard-coded

Moduli principali gia visibili o in formazione

• Condominio e anagrafica
• Contabilita e banca
• Ripartizioni e tabelle millesimali
• Ticket e Post-it operativi
• CTI / PBX / click-to-call
• Import legacy Gescon
• Revisione contabile
• Storage tenant-aware e archivi
• Distribuzione server e manutenzione nodo

Effetto pratico sulla UI

La UI deve progressivamente convergere verso:

1. stessa base record
2. azioni visibili solo se abilitate
3. moduli attivabili senza biforcare il prodotto
4. procedure specialistiche innestate sul contesto corretto

Esempio:

• una chiamata entra nel CRM
• produce un Post-it
• il Post-it puo essere assegnato a operatore, collaboratore o fornitore
• se serve diventa ticket
• il ticket impatta documenti, fornitore, stabile, contabilita o revisione

Sempre sullo stesso grafo dati.

Modello di abilitazione consigliato

Tre livelli distinti:

1. Ruolo base

Definisce il perimetro generale:

• amministratore
• collaboratore
• fornitore
• revisore
• tecnico
• sviluppatore / ops

2. Capacita operative

Definiscono le azioni concrete:

• vedere contabilità
• modificare ripartizioni
• usare CTI
• lanciare sync staging
• aprire ticket
• assegnare Post-it
• gestire fornitori

3. Ambito

Definisce dove valgono:

• tenant / amministratore
• stabile
• progetto
• modulo

Conseguenza tecnica

Ogni nuova funzione dovrebbe chiedersi prima:

1. su quale base dominio si appoggia
2. quale modulo la ospita
3. quale permission la abilita
4. su quale ambito agisce

Se una funzione non risponde a queste quattro domande, rischia di diventare una pagina isolata e fragile.

Stato implementativo 2026-05-09

Per iniziare a togliere i controlli hardcoded pagina-per-pagina, in Day0 e stata introdotta una prima base ACL centrale per programmi Filament.

Componenti introdotti:

• config/program_acl.php con catalogo programmi e ruoli default;
• program_acl_rules come storage di override per ruolo e per utente;
• App\Services\ProgramAclService come risolutore unico;
• pagina Super Admin > ACL programmi per governare le eccezioni;
• primi programmi collegati: supporto.modifiche, fornitore.ticket-operativi, mobile.dashboard.

Aggiornamento 2026-06-02:

• il catalogo ACL programmi e stato esteso anche a contabilita.situazione-iniziale, strumenti.documenti-archivio e condomini.unita-hub;
• le relative pagine Filament usano ora ProgramAclService come gate di accesso quando il catalogo ACL e disponibile;
• questo porta il super-admin a governare almeno la visibilita pagina-per-pagina su contabilita iniziale, archivio documenti e hub unita, anche se la granularita solo lettura / modifica resta ancora da costruire sopra il ponte attuale.

Questo non sostituisce ancora tutto il sistema ruoli/permessi esistente, ma crea il ponte giusto per arrivare a un modello davvero permission-first invece di continuare con soli hasAnyRole([...]) sparsi.

Regola di migrazione pratica

Quando una pagina Filament oggi usa ruoli hardcoded, il percorso consigliato e:

1. lasciare il ruolo come fallback iniziale nel catalogo ACL;
2. introdurre una chiave programma stabile;
3. spostare canAccess() verso ProgramAclService;
4. mantenere gli ambiti dominio separati: ruolo base, capacita operative, contesto tenant/stabile.

Ruoli leggeri e redirect iniziale

Per i ruoli condomino, inquilino e proprietario, il login Filament puo reindirizzare verso la dashboard mobile invece della home amministrativa piena.

Questo aiuta a rispettare la regola funzionale corrente:

• fornitori -> area operativa ticket/fornitore;
• condomini/inquilini/proprietari -> dashboard e menu mobile essenziali;
• amministratore -> delega operativa ai collaboratori, non governo completo di tutti i ruoli di sistema.

Stato reale ACL su ruoli leggeri

Verifica aggiornata sul codice applicativo:

• ProgramAclService e il catalogo config/program_acl.php governano oggi solo tre chiavi: supporto.modifiche, fornitore.ticket-operativi, mobile.dashboard;
• il ponte ACL centrale esiste quindi davvero, ma non copre ancora in modo atomico i singoli moduli utente come documenti, ticket, anagrafe o estratto conto;
• permessi e redirect per condomino / inquilino restano ancora in parte hardcoded in gate, middleware, helper menu e servizi di visibilita.

Implicazione architetturale:

• il modello corretto resta permission-first, ma non bisogna confondere il ponte attuale con il risultato finale;
• prima di dichiarare chiuso il perimetro ACL dei condomini/inquilini serve migrare le singole pagine o procedure verso chiavi programma stabili, lasciando i ruoli come fallback e non come unica regola.

Decisione attuale

La direzione da seguire nelle prossime sessioni e:

1. consolidare i moduli gia emersi invece di moltiplicare pagine parallele
2. portare la gestione operativa sempre piu vicino alle procedure abilitate
3. usare la pagina Supporto > Modifiche come ponte fra sviluppo, documentazione e deploy
4. preparare la distribuzione di NetGescon su nodi separati per ambienti di debug e collaudo