# 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**
```json
{
    "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**
```json
{
    "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**
```css
/* 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*