netgescon-master/docs/09-MANUALE-UTENTE-SISTEMA-CONTABILE.md

# 📚 MANUALE UTENTE: SISTEMA CONTABILE CONDOMINIALE NETGESCON

## 📋 **OVERVIEW**
Guida completa all'utilizzo del sistema contabile condominiale NetGescon basato su **partita doppia** e **gestioni amministrative**.

---

## 🎯 **CONCETTI FONDAMENTALI**

### 📅 **GESTIONI AMMINISTRATIVE**
```
⚠️  IMPORTANTE: NetGescon NON usa l'anno solare!

GESTIONE = Esercizio contabile del condominio
├── 📅 Inizio: Delibera assemblea (es: 01/01/2024) 
├── 📊 Operazioni: Durante tutto l'esercizio
├── 🔄 Estensione: Può proseguire oltre 31/12
└── 🏛️  Chiusura: Solo con approvazione assemblea bilancio
```

### 💰 **PARTITA DOPPIA**
```
PRINCIPIO: DARE = AVERE (sempre bilanciato)

ESEMPIO Pagamento Fattura €1.000:
  DARE:  Conto Spesa Pulizie      €1.000
  AVERE: Conto Corrente Bancario  €1.000
                                  -------
  TOTALE: €1.000 = €1.000 ✅
```

### 🏗️ **STRUTTURA PIANO CONTI**
```
🏛️ MASTRO (Categoria principale)
   ├── 📂 CONTO (Sottocategoria)
   │   ├── 📄 SOTTOCONTO (Voce specifica)
   │   └── 📄 SOTTOCONTO
   └── 📂 CONTO

ESEMPIO:
🏛️ 200 - SPESE AMMINISTRATIVE
   ├── 📂 201 - Pulizie
   │   ├── 📄 201.01 - Pulizie Scala A
   │   └── 📄 201.02 - Pulizie Scala B
   └── 📂 202 - Energia Elettrica
```

---

## 🚀 **GUIDA QUICK START**

### 1️⃣ **SETUP INIZIALE**

#### 🖥️ **Su Windows (usando PowerShell)**
```powershell
# Naviga alla directory NetGescon
cd "U:\home\michele\netgescon"

# Esegui diagnosi sistema
.\scripts\NetGescon-Contabilita.ps1 diagnosi

# Se necessario, esegui setup completo
.\scripts\NetGescon-Contabilita.ps1 setup
```

#### 🐧 **Su VM Linux**
```bash
# Naviga alla directory
cd /home/michele/netgescon

# Diagnosi sistema
./scripts/diagnosi-contabilita.sh

# Setup completo
./scripts/setup-contabilita-condominiale.sh
```

### 2️⃣ **CONFIGURAZIONE PRIMO CONDOMINIO**
```bash
# Configura gestione per condominio ID 1, anno 2024
cd /var/www/netgescon
php artisan contabilita:setup 1 2024
```

### 3️⃣ **ACCESSO PORTALE WEB**
```
🌐 Portale NetGescon:  http://192.168.0.200:8000/admin
🗄️  phpMyAdmin:        http://192.168.0.200/phpmyadmin
🔧 Gitea:             http://192.168.0.200:3000
```

---

## 🎛️ **UTILIZZO PORTALE WEB**

### 📊 **Dashboard Gestioni Contabili**
```
👤 Login Admin → 💰 Contabilità → 📊 Gestioni

AZIONI DISPONIBILI:
✅ Visualizza gestioni attive/chiuse
✅ Crea nuova gestione
✅ Consulta saldi e totali
✅ Chiudi gestione (con approvazione assemblea)
```

### 📝 **Registrazioni Contabili**
```
💰 Contabilità → 📝 Registrazioni

WORKFLOW:
1️⃣  Seleziona gestione attiva
2️⃣  Crea nuova registrazione
3️⃣  Inserisci movimenti DARE/AVERE
4️⃣  Sistema verifica bilanciamento
5️⃣  Ripartizione automatica ai condomini
```

### 🗂️ **Piano dei Conti**
```
💰 Contabilità → 🗂️  Piano Conti

GESTIONE:
✅ Visualizza struttura MASTRO/CONTO/SOTTOCONTO
✅ Aggiungi nuove voci contabili
✅ Configura ripartizioni automatiche
✅ Imposta tabelle millesimali
```

---

## 📋 **WORKFLOW OPERATIVO TIPO**

### 🧾 **SCENARIO 1: Pagamento Fattura Pulizie**

#### 📄 **Step 1: Raccolta Dati**
```
📄 Fattura: Ditta Pulizie Rossi
💰 Importo: €800,00 + IVA €176,00 = €976,00
📅 Data: 15/03/2024
🏦 Pagamento: Bonifico
```

#### 💻 **Step 2: Registrazione Portale**
```
1️⃣  Vai in: Contabilità → Registrazioni → Nuova
2️⃣  Seleziona: Gestione 2024
3️⃣  Compila:
    📅 Data operazione: 15/03/2024
    💰 Importo totale: €976,00
    📝 Causale: "Pagamento pulizie marzo 2024"
    🏢 Fornitore: Ditta Pulizie Rossi
```

#### ⚖️ **Step 3: Movimenti Partita Doppia**
```
DARE:
📄 201.01 - Pulizie Scala A        €400,00
📄 201.02 - Pulizie Scala B        €400,00
📄 501.01 - IVA su Acquisti        €176,00

AVERE:
📄 401.01 - C/C Banco BPM          €976,00

TOTALE: €976,00 = €976,00 ✅
```

#### 🔄 **Step 4: Ripartizione Automatica**
```
Sistema calcola automaticamente per ogni unità:

Unità 101 (millesimi 45,5):
- Pulizie Scala A: €400 × 45,5/1000 = €18,20
- IVA: €176 × 45,5/1000 = €8,01
TOTALE UNITÀ 101: €26,21

[Ripetere per tutte le unità]
```

### 💰 **SCENARIO 2: Incasso Rata Condominiale**

#### 📄 **Step 1: Raccolta Dati**
```
👤 Condomino: Mario Rossi (Unità 101)
💰 Importo: €350,00
📅 Data: 10/03/2024
🏦 Metodo: Bonifico bancario
```

#### 💻 **Step 2: Registrazione**
```
DARE:
📄 401.01 - C/C Banco BPM          €350,00

AVERE:
📄 101.01 - Rate Ordinarie         €350,00

RISULTATO: Entrata senza ripartizione
```

---

## 🔧 **COMANDI ARTISAN DISPONIBILI**

### 📊 **Gestione Sistema**
```bash
# Setup completo condominio
php artisan contabilita:setup {condominio_id} {anno}

# Verifica partita doppia
php artisan contabilita:verifica {gestione_id?}

# Ricalcola totali gestioni
php artisan contabilita:ricalcola-totali

# Chiudi gestione contabile
php artisan contabilita:chiudi {gestione_id}
```

### 🗃️ **Database e Seeder**
```bash
# Popola piano conti standard
php artisan db:seed --class=PianoContiSeeder

# Stato migrazioni
php artisan migrate:status

# Rollback se necessario
php artisan migrate:rollback --step=1
```

### 🔍 **Diagnostica e Debug**
```bash
# Lista route contabilità
php artisan route:list --name=contabilita

# Cache clear
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

---

## 🛠️ **SCRIPTS DI AUTOMAZIONE**

### 🖥️ **Windows PowerShell**
```powershell
# Script principale
.\scripts\NetGescon-Contabilita.ps1 {azione}

# Azioni disponibili:
diagnosi    # 🔍 Diagnosi completa sistema
setup       # 🔧 Setup automatico  
sync        # 🔄 Sincronizzazione Git
verifica    # ⚖️  Verifica partita doppia
backup      # 💾 Backup database
status      # 📊 Stato sistema
```

### 🐧 **Linux Bash**
```bash
# Diagnosi completa
./scripts/diagnosi-contabilita.sh

# Setup sistema
./scripts/setup-contabilita-condominiale.sh
```

---

## 🧭 **RISOLUZIONE PROBLEMI COMUNI**

### ❌ **ERRORE: Partita Doppia Non Bilanciata**
```
SINTOMO: "DARE €1000 ≠ AVERE €976"

SOLUZIONE:
1️⃣  Verifica importi inseriti
2️⃣  Controlla tutti i movimenti
3️⃣  Esegui: php artisan contabilita:verifica
4️⃣  Correggi registrazione dalla dashboard
```

### ❌ **ERRORE: Gestione Non Trovata**
```
SINTOMO: "Gestione ID non esiste"

SOLUZIONE:
1️⃣  Verifica gestioni esistenti: Contabilità → Gestioni
2️⃣  Crea nuova gestione se necessario
3️⃣  Esegui: php artisan contabilita:setup {id} {anno}
```

### ❌ **ERRORE: Millesimi Non Configurati**
```
SINTOMO: "Impossibile ripartire - millesimi mancanti"

SOLUZIONE:
1️⃣  Vai in: Stabili → Unità Immobiliari
2️⃣  Configura millesimi per ogni unità
3️⃣  Verifica totale = 1000 millesimi
```

### ❌ **ERRORE: Migrazioni Duplicate**
```
SINTOMO: "Table already exists"

SOLUZIONE:
1️⃣  Esegui: php artisan migrate:status
2️⃣  Identifica migrazioni duplicate
3️⃣  Rimuovi file migrazione duplicato
4️⃣  Esegui: php artisan migrate
```

### ❌ **ERRORE: Permissions**
```
SINTOMO: "Permission denied"

SOLUZIONE:
sudo chown -R www-data:www-data /var/www/netgescon/storage
sudo chown -R www-data:www-data /var/www/netgescon/bootstrap/cache
sudo chmod -R 775 /var/www/netgescon/storage
sudo chmod -R 775 /var/www/netgescon/bootstrap/cache
```

---

## 📊 **REPORTS E STATISTICHE**

### 📈 **Report Disponibili**
```
🏛️  Dashboard Admin:
├── 📊 Saldi per gestione
├── 📈 Andamento entrate/uscite  
├── 💰 Situazione debitoria condomini
├── 🧾 Registrazioni per periodo
└── ⚖️  Verifica bilancio partita doppia

📱 Dashboard Condomino:
├── 💰 Situazione personale
├── 📋 Ripartizioni ricevute
├── 🧾 Storico pagamenti
└── 📊 Dettaglio quote millesimali
```

### 📁 **Export e Stampe**
```
FORMATI SUPPORTATI:
✅ PDF - Report ufficiali
✅ Excel - Analisi dati
✅ CSV - Import/export
✅ JSON - API integrations
```

---

## 🔐 **SICUREZZA E BACKUP**

### 💾 **Backup Automatici**
```
FREQUENZA: Giornaliera (03:00)
DESTINAZIONE: /home/michele/netgescon/backup/database/
RETENTION: 30 giorni
FORMATO: mysqldump compresso
```

### 🔐 **Controlli Accesso**
```
RUOLI SISTEMA:
👑 Super Admin: Controllo totale
🛠️  Admin: Gestione condominio
👤 Condomino: Solo propri dati
👁️  Lettura: Consultazione
```

### 🛡️ **Log e Audit**
```
TRACCIAMENTO:
✅ Ogni registrazione contabile
✅ Modifiche partita doppia
✅ Chiusure gestioni
✅ Accessi utenti
✅ Export/import dati
```

---

## 📚 **DOCUMENTAZIONE TECNICA**

### 📖 **Manuali Disponibili**
```
docs/
├── 07-SISTEMA-CONTABILE-CONDOMINIALE.md          # 💰 Manuale contabilità
├── 08-IMPLEMENTAZIONE-SISTEMA-CONTABILE-PRATICO.md # 🔧 Guida implementazione
├── 04-DATABASE-STRUTTURE.md                       # 🗄️  Schema database
├── 05-INTERFACCIA-UNIVERSALE.md                   # 🎨 UI/UX Guide
└── 06-DESIGN-SYSTEM-NETGESCON.md                  # 🎯 Design System
```

### 🔗 **Link Utili**
```
DEVELOPMENT:
🌐 Portale: http://192.168.0.200:8000
🗄️  DB: http://192.168.0.200/phpmyadmin
🔧 Git: http://192.168.0.200:3000

DOCUMENTAZIONE:
📚 Laravel: https://laravel.com/docs
💰 Contabilità: docs/07-SISTEMA-CONTABILE-CONDOMINIALE.md
🎯 API: http://192.168.0.200:8000/api/documentation
```

---

## 🎉 **CONCLUSIONI**

### ✅ **VANTAGGI SISTEMA NETGESCON**
```
💎 CONTROLLO TOTALE: Ogni centesimo tracciato
⚖️  PARTITA DOPPIA: Bilanciamento garantito
📅 GESTIONI REALI: Segue delibere assembleari
🔄 RIPARTIZIONE AUTOMATICA: Calcolo preciso millesimi
🏢 MULTI-CONDOMINIO: Gestione centralizzata
🛡️  SICUREZZA: Backup e audit completi
🌐 ACCESSIBILITÀ: Web-based multi-dispositivo
```

### 🎯 **OBIETTIVO RAGGIUNTO**
```
"ZERO perdite economiche nelle gestioni condominiali"

Il sistema NetGescon garantisce il controllo assoluto di ogni 
movimento contabile attraverso:
- Partita doppia rigorosa
- Gestioni amministrative reali
- Ripartizioni automatiche precise
- Controlli incrociati continui
- Audit trail completo
```

### 🚀 **CRESCITA FUTURA**
```
ROADMAP:
🔄 Integrazione sistemi bancari
📱 App mobile condomini  
🤖 AI per categorizzazione automatica
📊 Business Intelligence avanzata
🌐 API per commercialisti
☁️  Cloud deployment
```

---

## 📞 **SUPPORTO**

### 🆘 **In Caso di Problemi**
```
1️⃣  Consulta questo manuale
2️⃣  Esegui diagnosi: .\scripts\NetGescon-Contabilita.ps1 diagnosi
3️⃣  Verifica logs: /var/www/netgescon/storage/logs/
4️⃣  Consulta documentazione tecnica
```

### 📧 **Contatti Sviluppo**
```
🔧 Supporto Tecnico: docs/team/
📚 Documentazione: docs/
🐛 Bug Report: Via Gitea Issues
💡 Suggerimenti: docs/idee/
```

---

**💎 NetGescon - Sistema Contabile Condominiale di Nuova Generazione**  
**🎯 Controllo Totale. Partita Doppia. Gestioni Reali. Zero Perdite Economiche.**