# 📘 MANUALE MANUTENZIONE - NetGescon Unified Platform

## 🎯 **PANORAMICA ARCHITETTURA**

### **Struttura Directory di Lavoro**
```
/home/michele/netgescon/netgescon-laravel/  (Directory principale Linux)
├── app/Http/Controllers/Admin/           # Controller amministrazione
├── resources/views/admin/               # View amministrazione
├── resources/views/components/          # Componenti riutilizzabili
├── resources/views/layouts/             # Layout principali
├── routes/web.php                       # Definizione route
└── docs/                               # Documentazione progetto
```

### **Sistema Multi-Tenant & Multi-Ruolo**
- **Utenti 8 caratteri**: Identificativo univoco per amministratore
- **Cartelle dedicate**: Ogni admin ha la sua directory isolata
- **Database separati**: Possibilità di separare i dati per amministratore
- **Backup distribuiti**: Google Drive, Microsoft, NAS locale
- **Migrazione facile**: Come VM Proxmox, portabilità completa

---

## 🔧 **GUIDE OPERATIVE**

### **1. MODIFICARE IL MENU SIDEBAR**

**File da modificare**: `/resources/views/components/menu/sidebar-dynamic.blade.php`

**Struttura Menu**:
```php
// Aggiungere nuovo elemento menu
@if($userPermissions['NUOVA_SEZIONE'] ?? false)
<li class="nav-item">
    <a href="#submenu" class="nav-link collapse-toggle dashboard-nav-link" 
       data-bs-toggle="collapse" data-section="NUOVA_SEZIONE">
        <i class="fas fa-ICON me-2"></i>
        <span>Nome Sezione</span>
        <i class="fas fa-chevron-down ms-auto collapse-icon"></i>
    </a>
    <div class="collapse" id="submenu">
        <ul class="nav flex-column ms-3">
            <li class="nav-item">
                <a href="#" class="nav-link dashboard-nav-link" data-section="NUOVA_SEZIONE">
                    <i class="fas fa-list me-2"></i>Lista
                </a>
            </li>
            <li class="nav-item">
                <a href="#" class="nav-link dashboard-nav-link" data-action="create-ITEM">
                    <i class="fas fa-plus me-2"></i>Nuovo
                </a>
            </li>
        </ul>
    </div>
</li>
@endif
```

**Aggiungere gestione JavaScript**: In `/admin/dashboard.blade.php`:
```javascript
case 'NUOVA_SEZIONE':
    title = 'Gestione XXXX';
    icon = 'fas fa-ICON';
    loadNuovaSezioneContent();
    break;
```

### **2. AGGIUNGERE NUOVA DASHBOARD SEZIONE**

**Step 1**: Aggiornare `/admin/dashboard.blade.php`
```javascript
function loadNuovaSezioneContent() {
    const content = `
        <div class="row mb-3">
            <div class="col-md-6">
                <h6 class="text-muted">Panoramica XXXXX</h6>
            </div>
            <div class="col-md-6 text-end">
                <button type="button" class="btn btn-primary btn-sm">
                    <i class="fas fa-plus me-2"></i>Nuovo XXXXX
                </button>
            </div>
        </div>
        
        <!-- Contenuto specifico della sezione -->
    `;
    $('#dynamic-content-body').html(content);
}
```

**Step 2**: Aggiungere route in `/routes/web.php`
```php
Route::middleware(['role:admin|amministratore|super-admin'])->prefix('admin')->name('admin.')->group(function () {
    Route::resource('NUOVA_RISORSA', NuovoController::class);
});
```

### **3. CREARE NUOVO FORM AJAX**

**Step 1**: Creare controller method
```php
public function createForm() {
    return view('admin.SEZIONE._form-bootstrap');
}
```

**Step 2**: Aggiungere route specifica
```php
Route::get('SEZIONE/create/form', [Controller::class, 'createForm'])->name('SEZIONE.create.form');
```

**Step 3**: Creare view form con struttura standard
```php
<!-- Form Header per AJAX -->
<div class="d-flex align-items-center justify-content-between mb-3">
    <div>
        <h4 class="text-primary mb-1">
            <i class="fas fa-plus-circle me-2"></i>Nuovo XXXXX
        </h4>
        <p class="text-muted mb-0 small">Descrizione form</p>
    </div>
</div>

<!-- Form con Tab Bootstrap -->
<div class="card">
    <!-- Tab Navigation -->
    <!-- Tab Content -->
    <!-- Footer con pulsanti -->
</div>
```

### **4. GESTIRE PERMESSI UTENTE**

**File**: `/app/Helpers/MenuHelper.php`
```php
public static function canUserAccessMenu($menuName) {
    // Logica permessi per $menuName
    return $hasPermission;
}
```

**Utilizzo nelle view**:
```php
@if(App\Helpers\MenuHelper::canUserAccessMenu('SEZIONE'))
    <!-- Contenuto visibile solo se ha permessi -->
@endif
```

---

## 📊 **TABELLE DATABASE**

### **Tabelle Principali**
- `stabili` - Dati stabili/condomini
- `unita_immobiliari` - Unità immobiliari
- `soggetti` - Anagrafica unificata (condomini, proprietari, etc.)
- `ruoli_soggetti` - Ruoli degli utenti nel sistema
- `permessi` - Sistema permessi granulare

### **Strutture JSON**
- `stabili.palazzine` - JSON array palazzine
- `stabili.locali` - JSON array locali servizio
- `stabili.banche` - JSON array conti bancari multipli

---

## 🚀 **PROCEDURE STANDARD**

### **Aggiungere Nuova Funzionalità**

1. **Leggere questo manuale** per capire dove intervenire
2. **Identificare la sezione** (admin, super-admin, etc.)
3. **Creare/modificare route** in `web.php`
4. **Implementare controller** in `app/Http/Controllers/Admin/`
5. **Creare view** in `resources/views/admin/SEZIONE/`
6. **Aggiornare sidebar** se necessario
7. **Aggiungere JavaScript** per navigazione AJAX
8. **Testare permessi** con diversi ruoli utente
9. **Aggiornare documentazione**

### **Debugging Route**
```bash
cd /home/michele/netgescon/netgescon-laravel
php artisan route:clear
php artisan route:list | grep "NOME_ROUTE"
```

### **Cache Management**
```bash
php artisan cache:clear
php artisan view:clear
php artisan config:clear
php artisan route:clear
```

---

## 🔒 **SICUREZZA & RUOLI**

### **Ruoli Utente**
- `super-admin` - Accesso completo, import dati, configurazioni sistema
- `admin/amministratore` - Gestione condomini assegnati
- `collaboratore` - Assistenza limitata
- `condomino` - Accesso ai propri dati

### **Middleware Protezione**
```php
Route::middleware(['role:super-admin'])->group(function () {
    // Solo super-admin può importare dati fiscali
});
```

---

## 📁 **ORGANIZZAZIONE FILE**

### **Controller Organization**
```
app/Http/Controllers/
├── Admin/              # Controllers amministrazione
├── SuperAdmin/         # Controllers super amministrazione  
├── Api/               # API controllers
└── Auth/              # Controllers autenticazione
```

### **View Organization**
```
resources/views/
├── admin/             # Dashboard e funzioni admin
├── superadmin/        # Funzioni super admin
├── components/        # Componenti riutilizzabili
├── layouts/           # Layout principali
└── auth/             # Login/registrazione
```

---

## 🎨 **STANDARDS UI/UX**

### **Colori Sezioni**
- Stabili: `bg-primary` (blu)
- Condomini: `bg-success` (verde)
- Tickets: `bg-warning` (giallo)
- Contabilità: `bg-info` (azzurro)
- Urgenze: `bg-danger` (rosso)

### **Icone Standard**
- Stabili: `fas fa-building`
- Condomini: `fas fa-users`
- Tickets: `fas fa-ticket-simple`
- Contabilità: `fas fa-calculator`
- Banche: `fas fa-university`

### **Pattern Form**
- Header con titolo e descrizione
- Tab per organizzare campi
- Footer con pulsanti azione
- JavaScript per gestione dinamica
- Validazione client e server

---

## 📋 **PROSSIMI SVILUPPI**

### **Milestone Immediate**
1. **Importazione Dati Legacy** - Sistema import dal vecchio gestionale
2. **Sistema Stampe** - Etichette faldoni, chiavi, documenti
3. **Gestione Documenti** - Upload e organizzazione documenti per stabile
4. **Dashboard Mobile** - Ottimizzazione per smartphone/tablet

### **Roadmap Futura**
1. **Multi-Tenant Completo** - Separazione database per amministratore
2. **Sincronizzazione Cloud** - Backup automatici distribuiti  
3. **API REST** - Integrazione con sistemi esterni
4. **Mobile App** - App nativa per gestione mobile

---

**📝 Mantenere sempre aggiornato questo documento ad ogni modifica significativa!**