netgescon-master/docs/archived/MANUALE-MANUTENZIONE.md

📘 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:

// 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:

case 'NUOVA_SEZIONE':
    title = 'Gestione XXXX';
    icon = 'fas fa-ICON';
    loadNuovaSezioneContent();
    break;

2. AGGIUNGERE NUOVA DASHBOARD SEZIONE

Step 1: Aggiornare /admin/dashboard.blade.php

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

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

public function createForm() {
    return view('admin.SEZIONE._form-bootstrap');
}

Step 2: Aggiungere route specifica

Route::get('SEZIONE/create/form', [Controller::class, 'createForm'])->name('SEZIONE.create.form');

Step 3: Creare view form con struttura standard

<!-- 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

public static function canUserAccessMenu($menuName) {
    // Logica permessi per $menuName
    return $hasPermission;
}

Utilizzo nelle view:

@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

cd /home/michele/netgescon/netgescon-laravel
php artisan route:clear
php artisan route:list | grep "NOME_ROUTE"

Cache Management

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

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!