netgescon-day0/docs/90-UI-interfaccia-unica/04-BEST-PRACTICES-SVILUPPO.md

🚀 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

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

@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

APP_URL=http://192.168.0.200:8000
VITE_APP_URL="${APP_URL}"

⚡ Vite Configuration (vite.config.js)

export default defineConfig({
    server: {
        host: '0.0.0.0',
        port: 5174,
        hmr: {
            host: '192.168.0.200'
        }
    },
    // resto della config...
});

🚀 Comandi di Avvio

# 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

@extends('admin.layouts.app')           // ❌ Sidebar verde
@extends('layouts.app-universal-*')     // ❌ Bootstrap

❌ Mancanza Breadcrumbs

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