netgescon-master/docs/00-ROLE-PERMISSION-SYSTEM.md

# 🔐 NETGESCON - GESTIONE RUOLI E PERMESSI UTENTE
**Data Creazione:** 22/07/2025  
**Versione:** 1.0  
**Sistema:** Layout Management + Role-Based Access Control

## 🚨 PROBLEMA RISOLTO: LAYOUT MULTIPLI E CONFUSIONE

### ✅ **SITUAZIONE PRIMA**
- **❌ Directory multiple** con file duplicati (netgescon-laravel/, netgescon/, resources/)
- **❌ Layout inconsistenti** (`layouts.app`, `layouts.app-universal-v2`, `admin.layouts.netgescon`)  
- **❌ Pagine che caricavano** layout sbagliati o obsoleti
- **❌ Confusione grafica** quando si modificavano i pulsanti

### ✅ **SITUAZIONE DOPO**
- **✅ Directory duplicate spostate** in `_BACKUP_OLD_*_INACTIVE` 
- **✅ Layout unificato** - SOLO `admin.layouts.netgescon`
- **✅ 31 file corretti** automaticamente
- **✅ Sistema automatico** per prevenire regressioni future

---

## 🛠️ **SISTEMA AUTOMATICO IMPLEMENTATO**

### **1. CONFIGURAZIONE CENTRALIZED**
File: `/config/netgescon.php`
```php
'active_layout' => 'admin.layouts.netgescon',
'deprecated_layouts' => [
    'layouts.app-universal-v2',
    'layouts.app', 
    'layouts.app-clean'
]
```

### **2. MIDDLEWARE AUTOMATICO** 
File: `/app/Http/Middleware/NetgesconLayoutMiddleware.php`
- **Applica automaticamente** il layout corretto
- **Gestisce i ruoli utente** (amministratore, collaboratore, operatore, condomino)
- **Condivide variabili** con tutte le viste

### **3. COMANDO PULIZIA AUTOMATICA**
```bash
# Controlla cosa cambierebbe
php artisan netgescon:clean-layouts --dry-run

# Applica correzioni automatiche  
php artisan netgescon:clean-layouts

# Risultato: 31 file corretti automaticamente!
```

---

## 👥 **SISTEMA RUOLI UTENTE**

### **AMMINISTRATORE** (Accesso Completo)
```php
'amministratore' => [
    'layout' => 'admin.layouts.netgescon',
    'permissions' => ['*'], // Tutti i permessi
    'menus' => [
        'dashboard', 'stabili', 'palazzine', 'unita-immobiliari',
        'condomini', 'contabilita', 'assemblee', 'risorse-economiche',
        'affitti', 'fiscale', 'comunicazioni', 'pratiche', 
        'consumi', 'tickets', 'superadmin'
    ]
]
```

### **COLLABORATORE** (R/W Limitato)  
```php
'collaboratore' => [
    'permissions' => ['read', 'create', 'update'], // No delete
    'menus' => [
        'dashboard', 
        'stabili' => ['read', 'create', 'update'],
        'palazzine' => ['read', 'create', 'update'], 
        'unita-immobiliari' => ['read', 'create', 'update'],
        'condomini' => ['read'], // Solo lettura
        'contabilita' => ['read'], // Solo lettura
        'comunicazioni' => ['read', 'create'],
        'tickets' => ['read', 'create', 'update']
    ]
]
```

### **OPERATORE** (R/Create Limitato)
```php  
'operatore' => [
    'permissions' => ['read', 'create'], // Solo lettura e inserimento
    'menus' => [
        'dashboard',
        'stabili' => ['read'],
        'palazzine' => ['read'], 
        'unita-immobiliari' => ['read'],
        'tickets' => ['read', 'create']
    ]
]
```

### **CONDOMINO** (Solo Lettura Personale)
```php
'condomino' => [
    'layout' => 'condomino.layout', // Layout diverso
    'permissions' => ['read'],
    'menus' => [
        'dashboard',
        'my-unita' => ['read'], // Solo la sua unità
        'documenti' => ['read'],
        'comunicazioni' => ['read'], 
        'contabilita' => ['read'] // Solo la sua quota
    ]
]
```

---

## 🎯 **IMPLEMENTAZIONE NEI TEMPLATE**

### **USO NELLE VISTE BLADE**
```blade
@extends($activeLayout ?? 'admin.layouts.netgescon')

{{-- Controllo permessi --}}
@if(in_array('create', $userPermissions ?? []))
    <a href="{{ route('admin.stabili.create') }}" class="btn btn-primary">
        <i class="fas fa-plus"></i> Nuovo Stabile
    </a>
@endif

{{-- Menu condizionale --}}
@if(isset($userMenus['superadmin']))
    <li class="nav-item">
        <a class="nav-link" href="{{ route('superadmin.dashboard') }}">
            <i class="fas fa-cog"></i> Configurazione Sistema
        </a>
    </li>
@endif
```

### **CONTROLLER AUTOMÁTICO**
```php
// Il middleware automaticamente fornisce:
// $userRole, $userPermissions, $userMenus, $activeLayout

public function index()
{
    // I permessi sono già verificati dal middleware
    $stabili = Stabile::all();
    return view('admin.stabili.index', compact('stabili'));
}
```

---

## 🔧 **MANUTENZIONE E PREVENZIONE**

### **COMANDI UTILI**
```bash
# Controlla stato layout
php artisan netgescon:clean-layouts --dry-run

# Pulizia automatica (da eseguire dopo modifiche)
php artisan netgescon:clean-layouts

# Pulizia cache completa
php artisan view:clear && php artisan config:clear && php artisan route:clear
```

### **DIRECTORY INATTIVE**
```
_BACKUP_OLD_netgescon-laravel_INACTIVE/  ← Directory resa inattiva
_BACKUP_OLD_netgescon_INACTIVE/          ← Directory resa inattiva

resources/views/                         ← UNICA DIRECTORY ATTIVA
```

### **FILE DA NON TOCCARE**
- `/config/netgescon.php` - Configurazione ruoli e layout
- `/app/Http/Middleware/NetgesconLayoutMiddleware.php` - Middleware automatico  
- `/app/Console/Commands/CleanDeprecatedLayouts.php` - Comando pulizia

---

## 🎉 **RISULTATI FINALI**

### ✅ **LAYOUT UNIFICATO**
- **31 file corretti** automaticamente
- **Layout consistente** in tutte le pagine
- **Logout funzionale** ovunque con header blu

### ✅ **SISTEMA RUOLI** 
- **4 tipi utente** configurati (admin, collaboratore, operatore, condomino)
- **Permessi granulari** (R/W per sezione)
- **Menu condizionali** basati su ruolo

### ✅ **PREVENZIONE FUTURA**
- **Middleware automatico** applica layout corretto
- **Comando pulizia** per correzioni massive
- **Directory backup inattive** per evitare confusione

### ✅ **PRONTO PER**
- **Personalizzazione accessi** per ruolo utente  
- **Layout specifici** per tipologia utente
- **Scalabilità futura** con nuovi ruoli

---

## 📋 **WORKFLOW FUTURO**

### **QUANDO AGGIUNGI UNA NUOVA PAGINA**
1. Usa sempre `@extends('admin.layouts.netgescon')`  
2. Implementa controlli permessi con `$userPermissions`
3. Testa con diversi ruoli utente
4. Esegui `php artisan netgescon:clean-layouts --dry-run`

### **QUANDO MODIFICHI LAYOUT**
1. Modifica SOLO `/resources/views/admin/layouts/netgescon.blade.php`
2. Testa logout e navigazione  
3. Pulisci cache: `php artisan view:clear`
4. Verifica funzionamento su tutte le pagine principali

### **QUANDO AGGIUNGI RUOLI**
1. Configura in `/config/netgescon.php`
2. Aggiorna middleware se necessario
3. Testa accesso condizionale ai menu
4. Documenta nuovi permessi

---

**🚀 SISTEMA COMPLETAMENTE AUTOMATIZZATO E PRONTO PER LA PRODUZIONE!** 🚀