# 🚀 BEST PRACTICES SVILUPPO - NetGescon

> **Guida rapida per sviluppo veloce e senza errori**  
> **📅 Creato:** 06/08/2025  
> **🎯 Obiettivo:** Evitare errori comuni e accelerare lo sviluppo

---

## ✅ **CHECKLIST PRE-SVILUPPO**

### 🎨 **Layout e Grafica**
- [ ] **SEMPRE usare:** `@extends('admin.layouts.netgescon')`
- [ ] **MAI usare:** `admin.layouts.app` (sidebar verde vecchia)
- [ ] **MAI usare:** `layouts.app-universal-*` (Bootstrap invece di Tailwind)
- [ ] Vite dev server attivo: `npm run dev`
- [ ] Server Laravel attivo: `php artisan serve --host=0.0.0.0 --port=8000`

### 📋 **Structure Controller Standard**
```php
<?php

namespace App\Http\Controllers\Admin;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class MioController extends Controller
{
    public function index(Request $request)
    {
        // 1. Breadcrumbs
        $breadcrumbs = [
            ['title' => 'Categoria Principale', 'icon' => 'fas fa-icon'],
            ['title' => 'Pagina Corrente', 'icon' => 'fas fa-icon']
        ];

        // 2. Page setup
        $pageTitle = 'Titolo Pagina';
        $pageSubtitle = 'Descrizione di cosa fa questa pagina';
        
        // 3. Page actions
        $pageActions = [
            [
                'type' => 'secondary',
                'label' => 'Azione Secondaria',
                'url' => route('admin.route.action'),
                'icon' => 'fas fa-icon'
            ],
            [
                'type' => 'primary',
                'label' => 'Azione Principale',
                'url' => route('admin.route.create'),
                'icon' => 'fas fa-plus'
            ]
        ];

        // 4. Dati per la vista
        $data = $this->getData($request);

        // 5. Return view
        return view('admin.modulo.pagina', compact(
            'breadcrumbs',
            'pageTitle', 
            'pageSubtitle',
            'pageActions',
            'data'
        ));
    }
}
```

### 🎯 **Template Vista Standard**
```blade
@extends('admin.layouts.netgescon')

@section('title', 'Titolo Pagina')

@section('content')
<!-- Breadcrumb -->
<nav class="flex mb-6" aria-label="Breadcrumb">
    <ol class="inline-flex items-center space-x-1 md:space-x-3">
        @foreach($breadcrumbs as $breadcrumb)
            <li class="inline-flex items-center">
                @if(!$loop->last)
                    @if(isset($breadcrumb['url']))
                        <a href="{{ $breadcrumb['url'] }}" 
                           class="inline-flex items-center text-sm font-medium text-gray-700 hover:text-blue-600">
                            <i class="{{ $breadcrumb['icon'] }} w-3 h-3 mr-2.5"></i>
                            {{ $breadcrumb['title'] }}
                        </a>
                        <svg class="w-3 h-3 text-gray-400 mx-1">...</svg>
                    @else
                        <span class="inline-flex items-center text-sm font-medium text-gray-700">
                            <i class="{{ $breadcrumb['icon'] }} w-3 h-3 mr-2.5"></i>
                            {{ $breadcrumb['title'] }}
                        </span>
                        <svg class="w-3 h-3 text-gray-400 mx-1">...</svg>
                    @endif
                @else
                    <span class="ml-1 text-sm font-medium text-gray-500">
                        <i class="{{ $breadcrumb['icon'] }} w-3 h-3 mr-2.5"></i>
                        {{ $breadcrumb['title'] }}
                    </span>
                @endif
            </li>
        @endforeach
    </ol>
</nav>

<!-- Page Header -->
<div class="bg-white rounded-lg shadow-sm border border-gray-200 mb-6">
    <div class="p-6">
        <div class="flex flex-col lg:flex-row lg:items-center lg:justify-between">
            <!-- Title & Subtitle -->
            <div class="mb-4 lg:mb-0">
                <h1 class="text-2xl font-bold text-gray-900 mb-2">
                    {{ $pageTitle }}
                </h1>
                <p class="text-gray-600">
                    {{ $pageSubtitle }}
                </p>
            </div>

            <!-- Page Actions -->
            <div class="flex flex-col sm:flex-row space-y-2 sm:space-y-0 sm:space-x-3">
                @foreach($pageActions as $action)
                    <a href="{{ $action['url'] }}" 
                       class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md
                              @if($action['type'] === 'primary') 
                                  text-white bg-blue-600 hover:bg-blue-700
                              @else
                                  text-gray-700 bg-white border-gray-300 hover:bg-gray-50
                              @endif">
                        <i class="{{ $action['icon'] }} w-4 h-4 mr-2"></i>
                        {{ $action['label'] }}
                    </a>
                @endforeach
            </div>
        </div>
    </div>
</div>

<!-- Main Content -->
<div class="bg-white rounded-lg shadow-sm border border-gray-200">
    <div class="p-6">
        {{-- Contenuto principale qui --}}
    </div>
</div>

@endsection
```

---

## 🔧 **CONFIGURAZIONE AMBIENTE**

### 📝 **File .env Requirements**
```env
APP_URL=http://192.168.0.200:8000
VITE_APP_URL="${APP_URL}"
```

### ⚡ **Vite Configuration (vite.config.js)**
```javascript
export default defineConfig({
    server: {
        host: '0.0.0.0',
        port: 5174,
        hmr: {
            host: '192.168.0.200'
        }
    },
    // resto della config...
});
```

### 🚀 **Comandi di Avvio**
```bash
# Terminal 1: Laravel Server
php artisan serve --host=0.0.0.0 --port=8000

# Terminal 2: Vite Dev Server  
npm run dev

# Oppure usa i task VS Code configurati
```

---

## 📁 **ORGANIZZAZIONE MENU SIDEBAR**

### 🎯 **Struttura Attuale**
- **STABILI** - Gestione edifici e unità
- **CONDOMINI** - Persone e relazioni
- **AMMINISTRAZIONE** - Tickets e documenti
- **CONTABILITÀ** - Bilanci e registrazioni NetGescon
- **GESTIONE ECONOMICA** - Preventivi e fornitori
- **MODULI** - Funzionalità aggiuntive
- **GESCON IMPORT** - ⭐ Sistema import/export GESCON
- **SUPPORTO** - Help e configurazioni

### 🆕 **Aggiungere Nuova Voce Menu**
1. Aggiungere la voce nel file: `resources/views/components/menu/sidebar-netgescon.blade.php`
2. Aggiornare array JavaScript `categories`
3. Aggiornare `routeMapping` per l'auto-opening
4. Aggiornare selettori in `document.querySelectorAll`

---

## 🚨 **ERRORI COMUNI DA EVITARE**

### ❌ **Layout Sbagliato**
```blade
@extends('admin.layouts.app')           // ❌ Sidebar verde
@extends('layouts.app-universal-*')     // ❌ Bootstrap
```

### ❌ **Mancanza Breadcrumbs**
```php
// ❌ SBAGLIATO - Nessun breadcrumb
return view('admin.pagina');

// ✅ CORRETTO - Con breadcrumbs
$breadcrumbs = [...];
return view('admin.pagina', compact('breadcrumbs', ...));
```

### ❌ **Asset Non Caricati**
- Vite non attivo
- APP_URL non configurato
- Percorsi asset sbagliati

### ❌ **Variabili Mancanti**
- `$pageTitle` non definito
- `$pageActions` vuoto
- Dati non passati con `compact()`

---

## 🎯 **WORKFLOW SVILUPPO VELOCE**

1. **Setup ambiente:** Vite + Laravel server attivi
2. **Copia template:** Usa controller e vista standard
3. **Modifica breadcrumbs:** Personalizza categorie
4. **Aggiungi logica:** Implementa getData() e filtri
5. **Test immediato:** Accesso remoto funzionante
6. **Commit frequenti:** Small iterations

---

## 📚 **RIFERIMENTI RAPIDI**

- **Layout corretto:** `admin.layouts.netgescon`
- **CSS Framework:** Tailwind CSS (via Vite)
- **Icone:** FontAwesome 6.4.0
- **Documentazione completa:** `03-CONTENT.md`
- **Sidebar menu:** `components/menu/sidebar-netgescon.blade.php`

---

**✅ ULTIMO AGGIORNAMENTO: 06/08/2025 - GESCON Menu separato creato**