netgescon-master/TECHNICAL_SPECS.md

NetGesCon - Specifiche Tecniche e Componenti

Ultima modifica: 7 Luglio 2025
Versione progetto: 2.0 - UI Universale

---

🏗️ ARCHITETTURA DEL SISTEMA

📊 Stack Tecnologico Principale

• Framework: Laravel 10.x (PHP 8.1+)
• Database: MySQL 8.0+ / MariaDB 10.4+
• Frontend: Blade Templates + Tailwind CSS + Alpine.js
• Autenticazione: Laravel Breeze + Spatie Permission
• Build Assets: Vite (sostituisce Laravel Mix)
• Package Manager: Composer (PHP) + NPM (Node.js)

🔧 Dipendenze PHP Principali

{
    "laravel/framework": "^10.0",
    "laravel/breeze": "^1.24",
    "spatie/laravel-permission": "^5.11",
    "spatie/laravel-backup": "^8.3",
    "barryvdh/laravel-dompdf": "^2.0",
    "maatwebsite/excel": "^3.1",
    "intervention/image": "^2.7"
}

🎨 Frontend Dependencies

{
    "tailwindcss": "^3.3.0",
    "alpinejs": "^3.13.0",
    "@tailwindcss/forms": "^0.5.0",
    "@tailwindcss/typography": "^0.5.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0",
    "vite": "^4.0.0",
    "laravel-vite-plugin": "^0.8.0"
}

---

🗃️ STRUTTURA DATABASE

📋 Tabelle Principali (Best Practice Laravel)

• users: Autenticazione multi-ruolo
• amministratori: Gestori condomini (codice 8 caratteri)
• stabili: Immobili gestiti
• unita_immobiliari: Appartamenti/Box/Cantine
• soggetti: Proprietari/Inquilini/Fornitori
• movimenti_contabili: Prima nota contabile
• allegati: File collegati ai movimenti
• assemblee: Verbali e delibere
• preventivi: Offerte e preventivi

🔑 Convenzioni Database

• Chiavi primarie: id (auto-increment, unsigned big integer)
• Foreign keys: nome_tabella_id (es: stabile_id, user_id)
• Timestamps: created_at, updated_at su tutte le tabelle
• Soft deletes: deleted_at dove necessario
• Codici unici: 8 caratteri alfanumerici per entità principali

---

🎨 UI/UX DESIGN SYSTEM

🎯 Layout Universale (app-universal.blade.php)

• Responsive: Mobile-first design (Tailwind breakpoints)
• Sidebar: Permission-based con menu dinamico
• Mobile: Hamburger menu + overlay sidebar
• Dark mode: Toggle persistente con localStorage
• Colori tema:
  • Primario: Blue (500-700)
  • Secondario: Green (300-500) per admin
  • Errore: Red (500-600)
  • Successo: Green (500-600)

📱 Breakpoints Responsive

/* Mobile first approach */
sm: 640px   /* Tablet piccolo */
md: 768px   /* Tablet */
lg: 1024px  /* Desktop */
xl: 1280px  /* Desktop large */
2xl: 1536px /* Desktop XL */

🔐 Sistema Permessi

• Super-Admin: Accesso completo sistema
• Amministratore: Gestione condomini assegnati
• Collaboratore: Funzioni amministrative limitate
• Condomino: Solo informazioni personali e ticket
• Fornitore: Solo preventivi e fatture

---

🔄 SISTEMA AGGIORNAMENTI (PIANIFICATO)

🌐 Architettura Distribuita

• Server Master: Repository centrale aggiornamenti
• API Endpoint: /api/updates/check e /api/updates/download
• Client Locale: Script auto-update integrato
• Versioning: Semantic versioning (MAJOR.MINOR.PATCH)

📦 Gestione Versioni

• Stable: Versione produzione testata
• Development: Versione con ultime features
• LTS: Long Term Support (solo bugfix)
• Rollback: Possibilità di tornare alla versione precedente

🔒 Sicurezza Updates

• Firma digitale: Ogni aggiornamento firmato
• Checksum: Verifica integrità file
• Backup automatico: Prima di ogni aggiornamento
• Rollback: In caso di errori nell'aggiornamento

---

🛠️ TOOLS E UTILITÀ

📊 Monitoring e Debug

• Laravel Debugbar: Per ambiente sviluppo
• Laravel Telescope: Monitoring queries e performance
• Log Viewer: Visualizzazione log in UI
• Laravel Pulse: Real-time application monitoring

🧪 Testing

• PHPUnit: Test unitari e di integrazione
• Laravel Dusk: Test browser automatizzati
• Pest: Alternative moderna a PHPUnit
• Factory/Seeders: Dati fake per testing

📁 File Management

• Laravel Storage: Gestione file con disks
• Intervention Image: Manipolazione immagini
• Spatie Media Library: Gestione media avanzata

---

🔧 CONFIGURAZIONE AMBIENTE

🐧 Requisiti Sistema Linux

• OS: Ubuntu 20.04+ / CentOS 8+ / Debian 11+
• PHP: 8.1+ con estensioni: pdo_mysql, mbstring, xml, gd, zip
• MySQL: 8.0+ o MariaDB 10.4+
• Nginx: 1.18+ o Apache 2.4+
• Node.js: 18+ con NPM
• Composer: 2.4+
• SSL: Let's Encrypt o certificato valido

⚡ Performance

• OPcache: Abilitato per PHP
• Redis: Per cache e sessioni
• Queue: Laravel Horizon per job in background
• CDN: Per asset statici (opzionale)

🔐 Sicurezza

• Firewall: UFW o iptables configurato
• SSH: Solo chiavi, no password
• HTTPS: Forzato su tutte le route
• Headers: Security headers configurati
• Rate Limiting: Su API e form

---

📈 ROADMAP FEATURES

🎯 Versione 2.1 (Q3 2025)

• Multi-lingua completo
• Sistema aggiornamenti automatici
• API REST per mobile app
• Modulo assemblee avanzato

🎯 Versione 2.2 (Q4 2025)

• App mobile companion
• Integrazione PEC/email
• Modulo fatturazione elettronica
• Dashboard analytics avanzate

🎯 Versione 3.0 (Q1 2026)

• Multi-tenant SaaS completo
• Marketplace plugin
• AI per categorizzazione automatica
• Integrazione bancaria

---

Ultima modifica: 7 Luglio 2025 - Documentazione completa stack tecnologico