Ruoli e permessi (Spatie) — RBAC base con UI

Modulo «Ruoli e permessi (Spatie) — RBAC base con UI»: scheda inventario del layer foundation per autorizzazioni granulari su qualunque progetto Laravel del workspace. A differenza del modulo #8054 «auth-multi-ruolo» (che copre autenticazione + 2FA + gestione utenti + ruoli come pacchetto end-to-end), questo specializza il sotto-layer «solo authorization layer» pronto da montare anche su progetti dove il modulo auth esiste già custom (es. Footility, Gestionale Casarile, HSD dashboard) — utile come riuso isolato del solo RBAC con UI di gestione. Stack: `spatie/laravel-permission` ^6 come SSOT permessi/ruoli + UI admin Livewire/Blade riusabile + seeder ruoli base + policy/gate convenzionati + middleware `role:`/`permission:`/`role_or_permission:` + audit log assegnazioni #8330. Tabelle standard Spatie (`roles`, `permissions`, `model_has_roles`, `model_has_permissions`, `role_has_permissions`) + estensioni opzionali (`role_groups` opt. raggruppamento ruoli per UI/scoping multi-tenant, `permission_categories` opt. tassonomia permessi per UI grouped, `permission_audit_logs` opt. dedicato o delega a #8330 con event listener). Convenzioni naming permessi: pattern `{azione}.{risorsa}` o `{risorsa}.{azione}` consistent tra moduli (`viewAny`/`view`/`create`/`update`/`delete`/`restore`/`forceDelete` allineato a policy Laravel native + permessi custom dominio tipo `bookings.confirm`/`invoices.refund`/`leads.export`/`pages.publish`/`users.impersonate`/`settings.write`/`agentic.dispatch`). Permission Registrar caching (default Spatie 24h con tag `spatie.permission.cache`) + invalidation auto su create/update/delete role/permission via observer. Ruoli base seeder (`RolesAndPermissionsSeeder`, idempotente updateOrCreate): **`super-admin`** (gate Before bypass su tutto, riservato dev/owner workspace), **`admin`** (gestione utenti + ruoli + impostazioni + tutti CRUD dominio), **`editor`** (CRUD risorse contenuto/business, no admin utenti, no impostazioni globali), **`operator`** (operatività quotidiana: prenotazioni/lead/calendario, no settings/billing), **`viewer`** (read-only audit/report), **`cliente`** (area riservata #8326, accesso ai propri record), **`api-client`** (token Sanctum/Passport per integrazioni S2S, guard `api`, permessi scoped per endpoint). Mappa permessi base raggruppati per area (categoria UI): `users.*` (viewAny/view/create/update/delete/impersonate/assignRoles), `roles.*` (viewAny/view/create/update/delete/assignPermissions), `settings.*` (read/write/billing/integrations/agentic), `audit.*` (viewAny/export #8330), + permessi dominio per ogni modulo del workspace dichiarati nei service provider del modulo (auto-discovery permessi via attributi PHP 8 `#[Permission('bookings.confirm')]` o config statica). Guard multipli: `web` per pannello admin Livewire + `api` per token Sanctum (mobile/integrazioni) + opt. `client` per area riservata (#8326) — modelli `User`/`ApiClient`/`Customer` usano `HasRoles` trait con guard esplicito per evitare cross-guard role leak. Multi-tenant scoping opt.: se il progetto è multi-tenant (es. Footility serve N progetti cliente), team-scoped roles attivabile via Spatie `teams` feature (colonna `team_id` su `model_has_roles`/`model_has_permissions`) — utente può essere `editor` su tenant A e `viewer` su tenant B, switch tenant cambia ruoli attivi (`setPermissionsTeamId`). UI admin: pagina Livewire `RolesAndPermissionsManager` con 3 tab: **Ruoli** (lista ruoli con count utenti + permessi assegnati + azioni edit/duplicate/delete, ruoli sistema marcati e non eliminabili, form create/edit con name/guard/description/permessi check-tree grouped per categoria con search/filter/select-all-category), **Permessi** (lista permessi con guard/categoria/count ruoli che lo hanno, form create/edit name/guard/categoria/description, bulk import permessi da config modulo, delete con warning ruoli affected), **Utenti↔Ruoli** (datatable utenti #8327 con colonna ruoli badge multi-select inline + filtro per ruolo + bulk assign/revoke ruolo a selezione + audit log accessi assegnazione recenti #8330). Componenti riusabili: `<x-role-badge :role>` colorato per ruolo, `<x-permission-tree :permissions :selected>` checkbox tree grouped, `<x-user-roles-select :user>` multi-select inline ruoli con conferma su revoke `super-admin`. Helper blade/middleware: `@role('admin')` / `@can('users.create')` / `@hasanyrole('admin|editor')` + middleware route `->middleware('role:admin')` / `->middleware('permission:invoices.refund')` + facade `Gate::define` per logica custom (es. `bookings.confirm` solo se prenotazione del tenant corrente + non già confermata). Policy Laravel: comandi artisan `make:policy` con stub modificato che mappa metodi standard a permessi (`viewAny`→`{model}.viewAny`), generator artisan custom `php artisan rbac:make-policy {Model}` che crea policy boilerplate + permessi associati + seeder entry. Workflow assegnazione ruoli: utente admin apre profilo utente → tab «Ruoli» → toggle ruolo con conferma su ruoli privilegiati (`super-admin`/`admin`) → audit log #8330 traccia chi/quando/da-quale-IP/diff ruoli (`before: [editor], after: [editor, admin]`) → notifica email opt. al destinatario «Ti sono stati assegnati ruoli aggiuntivi» + notifica admin owner cliente su escalation privilegi → eventuale revoca con motivo testuale richiesto. Sicurezza/edge: blocco auto-revoke ultimo `super-admin` (almeno 1 deve esistere sempre, controllo a DB level + UI warning), blocco self-revoke `super-admin` proprio account (richiede altro super-admin), blocco delete ruolo se utenti lo hanno (force riassegnazione o warning con count), blocco rename ruolo `super-admin` (riservato hard-coded), prevenzione privilege escalation (editor non può assegnare ad altri permessi che lui stesso non ha — check `auth()->user()->can($perm)` prima di permettere assegnazione), guard mismatch (impedire assegnare role guard `api` a utente guard `web`), cache invalidation su rename permission (UI mostra warning «permesso referenziato in N policy/middleware, aggiorna codice»), permission removed used by middleware → fallback deny + log warning admin, role duplicato (case-insensitive name+guard unique), import seeder ruoli su DB con dati esistenti → updateOrCreate per name+guard idempotente non sovrascrive descrizione manuale, race condition concurrent role edit → optimistic locking version + merge UI, permessi orphan (non più referenziati in codice) → comando `rbac:audit-orphans` evidenzia + suggerisce delete, ruolo con 100+ permessi → UI tree con virtualization + search, multi-tenant team switch → flush cache permessi corrente + reload ruoli active context, impersonate user (admin → user) → log audit + banner ribbon UI «stai impersonando X — esci», impersonate non permesso per ruoli >= proprio (admin non può impersonate super-admin), test E2E policy verifica matrice ruolo×permesso×endpoint (matrix test PHPUnit con dataprovider). Comandi artisan dedicati: `rbac:install` setup migrazione+seeder ruoli base+pubblica config Spatie, `rbac:sync-permissions` legge config modulo dichiarazioni permessi + crea/aggiorna in DB rimuovendo orfani con conferma, `rbac:audit-orphans` lista permessi DB non referenziati in codice grep, `rbac:audit-policies` verifica ogni Policy ha permessi corrispondenti registrati, `rbac:assign-role {user} {role}` CLI per ops/onboarding rapido, `rbac:cache-reset` flush cache permessi, `rbac:export` JSON export ruoli+permessi+assegnazioni per backup/migrazione tenant, `rbac:import` ripristino da JSON con dry-run. Integrazione con altri moduli workspace: **#8054 auth-multi-ruolo** dipendenza/coesistenza (auth gestisce login+2FA+users, questo RBAC è il sotto-layer authorization riusabile), **#8326 area-cliente-riservata** ruoli `cliente`/`cliente-premium` con middleware route area cliente, **#8330 audit-log-azioni-utente** event listener `RoleAssigned`/`RoleRevoked`/`PermissionGranted`/`PermissionRevoked` → log azione + diff JSON utente affected, **#8327 crud-generico-anagrafiche-livewire** datatable utenti con colonna ruoli + bulk assign, **#8328 export-excel-pdf** export matrice utenti×ruoli per audit compliance, **#8312 multilingua-base-it-en** traduzioni descrizioni ruoli/permessi UI cliente, **#8307 pagine-statiche-editabili** permessi `pages.*` editor-content/publisher/admin-content, **#8308 blog-news** permessi `posts.*` editor/author/publisher, **#8004 GA4** opt. event tracking azioni admin per security analytics, **agentic queue Footility** ruolo `agentic-operator` per azioni Kanban (human-complete/raffina/rivedi-dopo) separato da admin generico. Casi d'uso per progetto workspace: **Footility** (super-admin Paolo + admin developer team + editor content marketing + operator gestione coda agentic + viewer stakeholder esterni per dashboard read-only + api-client per bridge S2S/CI), **Holiday Self Drive [APP+SITO]** (admin owner + operator front-desk noleggio + viewer contabile + cliente B2C area riservata storico noleggi + api-client integrazione gestionale), **Gestionale Casarile B&B** (admin Casarile owner + operator reception check-in/out + viewer contabile commercialista esterno + cliente ospite area riservata prenotazioni storico), **Klabhouse scuola musica** (admin direzione + editor segreteria iscrizioni + operator docente vista propri corsi + cliente studente area riservata orari/pagamenti rate), **Gestionale Altramusica** (admin scuola + operator segreteria + viewer docenti propri corsi), **TMK / LB advisory** (admin studio + editor commercialista junior CRUD pratiche + viewer cliente B2B propria pratica + cliente area riservata documenti firmati #8326), **mscarichi/prontointervento** (admin owner + operator dispatcher chiamate + tecnico operativo da app mobile + viewer contabile fatture). Performance e cache: Spatie Permission Registrar cache 24h tag `spatie.permission.cache` (key per guard), invalidation auto via observer su create/update/delete role+permission+sync, cache per-user permessi opt. (eager load `$user->roles.permissions` once + memo per request), bulk assign N utenti × M ruoli evita N+1 con `attach()` array, query report ruoli×utenti uso JOIN diretto su `model_has_roles` no Eloquent quando >1k record. Testing: factory `RoleFactory`/`PermissionFactory`, traits test `ActingAsAdmin`/`ActingAsCustomer`/`AsAnyRole('editor')`, matrix policy test (PHPUnit dataProvider role×endpoint×expected status), seeder di test che crea ruoli baseline isolati, RefreshDatabase + cache flush in setUp, assertion `$response->assertForbidden()` per accesso negato, test middleware `permission:` su route critiche, fuzzing test assegnazione ruolo random utente verifica nessun crash. Compliance/audit: ogni cambio ruolo/permesso loggato #8330 con (actor_id, target_user_id, action enum role_assigned/role_revoked/permission_granted/permission_revoked, before JSON, after JSON, ip, user_agent, timestamp), retention log 5+ anni per requisiti GDPR/SOC2, export audit log CSV/PDF #8328 per richiesta autorità/cliente B2B, notification webhook #8324 su escalation privilegi (notifica Slack security team), report mensile «utenti con accessi anomali» (es. login da nuovo IP + ruolo privilegiato). Estensioni roadmap: **AI permission suggester** #8261 (LLM analizza ruolo descrizione + UI mockup → suggerisce permessi appropriati pre-popolati), **attributo-based access control (ABAC)** oltre RBAC (es. «editor può modificare pagina solo se autore=lui»), **conditional permissions** (permesso valido solo in determinate ore/giorni/tenant context), **role templates marketplace** (ruoli baseline per industry: hotelier/agency/healthcare/legal precompilati), **delegated admin** (admin di tenant A può gestire ruoli del proprio tenant ma non globalmente), **just-in-time (JIT) elevation** (richiesta temporanea elevazione `admin` per 1h con approvazione + auto-revoke), **MFA enforcement per ruolo** (ruoli privilegiati richiedono 2FA #8054 enforcement obbligatorio), **session-bound roles** (alcuni ruoli attivi solo in sessione corrente con conferma password recente <15min), **break-glass account** (account super-admin emergency con accesso log-all + notifica immediata team), **certificazione periodica accessi** (ogni 90gg admin deve ri-certificare lista utenti×ruoli — workflow alert + bulk approve/revoke per compliance SOC2/ISO27001), **integrazione SSO/SAML** mapping group AD → ruoli automatico, **integrazione SCIM** provisioning automatico utenti+ruoli da IdP esterno (Okta/Azure AD), **policy-as-code** (Cedar/OPA Rego per regole complesse fuori da Spatie quando RBAC non basta). Differenze e relazioni: **#8054 auth-multi-ruolo** copre auth completo (login+2FA+password reset+register+users CRUD+ruoli) end-to-end; questo modulo (#8306) è il sotto-layer «solo RBAC» riusabile isolatamente quando auth è già implementato custom (es. gestionali legacy) o quando si vuole estendere un auth esistente con ruoli/permessi avanzati — entrambi compatibili e tipicamente coesistono sullo stesso progetto con #8054 che include #8306 come dipendenza interna; **#8326 area-cliente-riservata** consuma ruolo `cliente` definito qui per middleware route area cliente; **#8330 audit-log-azioni-utente** consuma eventi RoleAssigned/PermissionGranted/Revoked per audit trail; **#8327 crud-generico-anagrafiche-livewire** datatable utenti riusa componenti `<x-user-roles-select>` di questo modulo; **#8307 pagine-statiche-editabili** definisce permessi `pages.*` registrati qui; **#8308 blog-news** definisce permessi `posts.*` registrati qui; **#8312 multilingua-base-it-en** traduzioni UI gestione ruoli per cliente B2B IT/EN; **#8004 GA4** opt. tracking azioni admin per security analytics; **agentic Footility** ruolo `agentic-operator` separato per azioni Kanban senza concedere admin globale. Costo nuovo modulo (greenfield): 0.25g install `spatie/laravel-permission` + publish config+migration + pubblicazione tabelle + factory/seeder `RolesAndPermissionsSeeder` ruoli base (super-admin/admin/editor/operator/viewer/cliente/api-client), 0.25g convenzioni naming permessi documentate + config registry permessi per modulo (auto-discovery via service provider), 0.5g `RolesAndPermissionsManager` Livewire UI 3-tab (Ruoli/Permessi/Utenti×Ruoli) con datatable+form+permission-tree+badge multi-select+filtri+search+bulk action, 0.25g componenti blade riusabili (`<x-role-badge>`/`<x-permission-tree>`/`<x-user-roles-select>`), 0.25g middleware/blade helpers (`role:`/`permission:` route middleware + `@role`/`@can`/`@hasanyrole` direttive — riuso nativo Spatie), 0.25g policy generator `php artisan rbac:make-policy {Model}` stub modificato che mappa metodi a permessi, 0.5g comandi artisan dedicati (`rbac:install`/`rbac:sync-permissions`/`rbac:audit-orphans`/`rbac:audit-policies`/`rbac:assign-role`/`rbac:cache-reset`/`rbac:export`/`rbac:import`), 0.25g multi-tenant scoping opt. (Spatie teams feature attivazione + `setPermissionsTeamId` middleware + tenant switch UI), 0.25g impersonate flow (admin→user banner ribbon UI + log audit + uscita), 0.25g sicurezza/edge (blocco auto-revoke ultimo super-admin + self-revoke + delete ruolo con utenti + privilege escalation prevention check `can($perm)` + guard mismatch + duplicate role unique), 0.25g integrazione #8330 audit log (event listener RoleAssigned/Revoked/PermissionGranted/Revoked → log diff JSON + ip + user_agent), 0.25g notification email opt. al destinatario su escalation privilegi + webhook #8324 Slack security team, 0.5g testing matrix policy×role×endpoint (PHPUnit dataProvider + factory + traits ActingAs*), 0.25g performance cache permessi-per-request memo + bulk assign attach array no N+1, 0.25g documentazione interna (README ruoli baseline + naming convention + come aggiungere nuovo permesso + come aggiungere nuovo ruolo + how-to security review). Costo riuso nuovo cliente (modulo pronto): 0.1g install package + pubblicazione migrazioni + seeder ruoli base in DB cliente, 0.1g configurazione ruoli/permessi specifici dominio cliente (es. operator+dispatcher per mscarichi, reception+housekeeping per Casarile, segreteria+docente per Klabhouse), 0.1g eventuali permessi custom dominio (es. `tours.confirm` HSD, `rooms.checkin` Casarile, `lessons.attendance` Klabhouse), 0.1g assegnazione ruoli iniziali utenti cliente baseline (admin owner + operatori), 0.1g test happy path (admin assegna ruolo a operator + operator accede solo a sezioni consentite + audit log loggato + cache permessi corretta + revoca funziona). Dipendenze: Laravel 10/11, `spatie/laravel-permission` ^6 (SSOT RBAC), `livewire/livewire` ^3 (UI admin Livewire) o alternativa Filament 3 + alpine.js, `laravel/sanctum` ^4 per guard `api` (api-client role), opt. `spatie/laravel-activitylog` o delega `#8330 audit-log-azioni-utente` per event log RoleAssigned/Revoked, opt. `lab404/laravel-impersonate` ^1.7 per impersonate flow admin→user (compatibile Spatie), opt. integration #8326 area-cliente-riservata, #8327 datatable utenti, #8328 export Excel/PDF audit matrice utenti×ruoli, #8004 GA4 tracking azioni admin opt., opt. SAML2 SSO via `aacotroneo/laravel-saml2` per integrazione AD enterprise cliente B2B (TMK/legal), opt. SCIM provisioning roadmap, opt. `cerbero/laravel-enum` per enum azioni audit log, opt. `pusher-php-server`/Slack incoming webhook per notification escalation privilegi security team.