netgescon-master/TECHNICAL_SPECS.md

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

{
    "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

---

🚀 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