# 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