# NetGesCon - Specifiche Tecniche e Componenti

**Ultima modifica**: 8 Luglio 2025  
**Versione progetto**: 2.1 - 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

---

## 🚀 **SISTEMA RIPARTIZIONE SPESE E GESTIONE RATE - IMPLEMENTAZIONE COMPLETATA**

### ✅ **IMPLEMENTAZIONE COMPLETA 8 LUGLIO 2025**

Il sistema NetGesCon Laravel ha raggiunto una milestone importante con l'implementazione completa del sistema di ripartizione spese e gestione rate. Questo rappresenta il cuore del business logic per la gestione condominiale.

#### **🎯 FUNZIONALITÀ IMPLEMENTATE**:

**Backend Completo**:
- ✅ **Modelli Eloquent**: VoceSpesa, RipartizioneSpese, DettaglioRipartizioneSpese, PianoRateizzazione, Rata
- ✅ **Controller RESTful**: CRUD completo per tutte le entità con metodi personalizzati
- ✅ **Policy e Autorizzazioni**: Sicurezza basata su ruoli e ownership
- ✅ **Migration Database**: Strutture ottimizzate con relazioni e indici

**Frontend Completo**:
- ✅ **Interfacce Responsive**: 12 viste complete con design mobile-first
- ✅ **Componenti Avanzati**: DataTables, Select2, Chart.js, modal interattivi
- ✅ **Calcoli Automatici**: AJAX per ripartizioni, rate, importi, scadenze
- ✅ **Dashboard Avanzate**: Filtri, statistiche, monitoraggio pagamenti

**Business Logic Avanzata**:
- ✅ **Calcolo Ripartizioni**: Automatico tramite tabelle millesimali con personalizzazioni
- ✅ **Piani Rateizzazione**: Configurazione frequenze, interessi, spese gestione
- ✅ **Gestione Pagamenti**: Registrazione, marcatura, posticipazioni, scadenze
- ✅ **Workflow Completi**: Da creazione voce spesa a pagamento finale

#### **🏆 RISULTATI OTTENUTI**:

**Architettura Enterprise**:
- Database modernizzato secondo best practices Laravel
- Sistema multi-database pronto per scalabilità
- Relazioni Eloquent ottimizzate per performance
- Codici alfanumerici per identificazione univoca

**Interfacce Professionali**:
- Design system coerente con Bootstrap 5
- Componenti riutilizzabili e manutenibili
- Responsive design testato su dispositivi multipli
- Accessibilità e UX ottimizzate

**Funzionalità Avanzate**:
- Calcoli automatici con validazioni business
- Esportazioni e report configurabili
- Monitoraggio scadenze e notifiche
- Audit trail completo per compliance

#### **🎯 SISTEMA PRONTO PER PRODUZIONE**:

Il sistema è ora completamente operativo per:
- **Amministratori di condominio**: Gestione completa spese e rate
- **Gestione multi-stabile**: Ogni amministratore può gestire più stabili
- **Workflow completi**: Dalla creazione spesa al pagamento finale
- **Reporting avanzato**: Statistiche, esportazioni, monitoraggio

### **📋 TECNOLOGIE UTILIZZATE**:
- **Backend**: Laravel 10+ con Eloquent ORM, Policy, Migration
- **Frontend**: Bootstrap 5, jQuery, DataTables, Select2, Chart.js
- **Database**: MySQL 8.0+ con strutture ottimizzate
- **Sicurezza**: Autenticazione Laravel, autorizzazioni granulari
- **Responsive**: Design mobile-first con sidebar collassabile

### **🔧 CARATTERISTICHE TECNICHE**:
- **Architettura MVC**: Separazione chiara tra logica e presentazione
- **API Ready**: Strutture preparate per future API REST
- **Scalabilità**: Database multi-tenant e performance ottimizzate
- **Manutenibilità**: Codice pulito, documentato, testabile
- **Estendibilità**: Architettura modulare per future implementazioni

Il sistema rappresenta ora una soluzione completa e professionale per la gestione condominiale, pronta per deployment e utilizzo in produzione.

---

*Ultima modifica: 8 Luglio 2025 - Documentazione completa stack tecnologico*