netgescon-master/docs/00-COPILOT-MASTER-GUIDE.md

# 🤖 NETGESCON - GUIDA PER GITHUB COPILOT/AI
## 📋 Istruzioni Complete per Continuare lo Sviluppo

> **🎯 DOCUMENTO MASTER** per GitHub Copilot/AI  
> **📍 Posizione:** `~/netgescon/docs/00-COPILOT-MASTER-GUIDE.md`  
> **🔄 Creato:** 18/07/2025 - Handoff completo Michele → AI

---

## 🚨 **ATTENZIONE: PRIMA DI INIZIARE**

### ⚠️ **REGOLA D'ORO: NON PERDERE I DATI**
1. **MAI** modificare direttamente il database di produzione
2. **SEMPRE** fare backup prima di modifiche strutturali
3. **TESTARE** ogni modifica su ambiente di sviluppo
4. **VERIFICARE** autenticazione e permessi dopo ogni modifica

### 🔑 **CREDENZIALI E ACCESSI ATTUALI**
```bash
# Login applicazione
URL: http://192.168.0.200:8000
Admin: admin@example.com / password
SuperAdmin: superadmin@example.com / password

# Server Linux
SSH: netgescon@192.168.0.200
Password: [verificare con Michele]

# Database
Host: localhost
DB: netgescon
User: netgescon_user
Password: [verificare .env]
```

---

## 📂 **STRUTTURA PROGETTO - MAPPA COMPLETA**

### 🏠 **DIRECTORY PRINCIPALE**
```
~/netgescon/
├── netgescon-laravel/          # 🌐 APPLICAZIONE PRINCIPALE LARAVEL
│   ├── app/                    # Models, Controllers, Middleware
│   ├── database/               # Migrations, Seeders
│   ├── resources/views/        # Template Blade
│   ├── routes/                 # Route definitions
│   ├── storage/logs/           # Log applicazione
│   └── .env                    # ⚠️ CONFIGURAZIONE CRITICA
├── docs/                       # 📚 DOCUMENTAZIONE UNIFICATA
│   ├── 00-COPILOT-MASTER-GUIDE.md    # 🤖 QUESTO DOCUMENTO
│   ├── 00-INDICE-DOCS-UNIFICATA.md   # 🧭 INDICE PRINCIPALE
│   ├── 00-transizione-linux/          # 🔑 GUIDE TRANSIZIONE
│   ├── 01-manuali-aggiuntivi/        # 🛠️ MANUALI OPERATIVI
│   ├── 02-architettura-laravel/      # 🏗️ ARCHITETTURA SISTEMA
│   ├── 03-scripts-automazione/       # ⚙️ SCRIPT UTILITÀ
│   └── images/                       # 🖼️ SCREENSHOT DEBUG
└── backup/                     # 💾 BACKUP SICUREZZA
```

### 🎯 **ENTRY POINT - DA DOVE INIZIARE**

#### 1️⃣ **DOCUMENTO PRINCIPALE**
**📍 INIZIO QUI:** [`docs/00-INDICE-DOCS-UNIFICATA.md`](00-INDICE-DOCS-UNIFICATA.md)
- Contiene **navigazione completa** di tutta la documentazione
- Link diretti a tutti i documenti chiave
- Scenari di navigazione per ogni situazione

#### 2️⃣ **DOCUMENTI CHIAVE FONDAMENTALI**
1. **[`docs/00-transizione-linux/README-TRANSITION-COMPLETE.md`](00-transizione-linux/README-TRANSITION-COMPLETE.md)**
   - 🔑 **GUIDA TRANSIZIONE COMPLETA**
   - Struttura progetto, configurazione, troubleshooting
   - **LEGGI QUESTO PER PRIMO**

2. **[`docs/00-transizione-linux/FEATURES-INVENTORY-COMPLETE.md`](00-transizione-linux/FEATURES-INVENTORY-COMPLETE.md)**
   - 📊 **INVENTARIO COMPLETO FUNZIONALITÀ**
   - Stato implementazione, roadmap, priorità
   - **CONSULTA PER CAPIRE COSA È GIÀ FATTO**

3. **[`docs/00-MANUALE-COMPLETO-NETGESCON-UNIFICATO.md`](00-MANUALE-COMPLETO-NETGESCON-UNIFICATO.md)**
   - 📖 **MANUALE COMPLETO SISTEMA**
   - Come funziona tutto, procedure operative

4. **[`docs/05-INTERFACCIA-UNIVERSALE.md`](05-INTERFACCIA-UNIVERSALE.md)**
   - 🎨 **SISTEMA INTERFACCIA UNIFICATA**
   - Come funziona il layout, sidebar, AJAX
   - **FONDAMENTALE** per modifiche frontend

---

## 🔧 **WORKFLOW SVILUPPO SICURO**

### ✅ **PROCEDURA STANDARD**
```bash
# 1. Backup prima di qualsiasi modifica
cd ~/netgescon/netgescon-laravel
./docs/03-scripts-automazione/manage-database.sh backup

# 2. Test ambiente
php artisan test

# 3. Verifica login funzionante
curl -I http://localhost:8000

# 4. Sempre versioning
git add .
git commit -m "Descrizione modifica"

# 5. Deploy step-by-step
php artisan migrate --dry-run  # Verifica migrations
php artisan migrate             # Solo se tutto OK
```

### ⚠️ **COSA NON FARE MAI**
- ❌ `php artisan migrate:fresh` in produzione
- ❌ Modificare .env senza backup
- ❌ Cancellare migrations esistenti
- ❌ Cambiare chiavi di autenticazione senza test
- ❌ Modificare ruoli/permessi senza verificare accessi

---

## 🎯 **TASK PRIORITARI - COSA FARE DOPO**

### 🚀 **IMMEDIATE (Prossimi giorni)**
1. **Completare gestione economica**
   - File: `app/Http/Controllers/EconomicaController.php`
   - Riferimento: [`docs/00-transizione-linux/FEATURES-INVENTORY-COMPLETE.md`](00-transizione-linux/FEATURES-INVENTORY-COMPLETE.md) sezione "GESTIONE ECONOMICA"

2. **Migliorare sistema upload documenti**
   - File: `app/Http/Controllers/DocumentiController.php`
   - Riferimento: [`docs/04-DATABASE-STRUTTURE.md`](04-DATABASE-STRUTTURE.md)

3. **Espandere reportistica**
   - Directory: `resources/views/reports/`
   - Riferimento: [`docs/07-API-INTEGRAZIONI.md`](07-API-INTEGRAZIONI.md)

### 📋 **BREVE TERMINE (1-2 settimane)**
1. **API REST complete**
   - Directory: `routes/api.php`
   - Riferimento: [`docs/02-architettura-laravel/ARCHITETTURA_MODULARE_COMPLETATA.md`](02-architettura-laravel/ARCHITETTURA_MODULARE_COMPLETATA.md)

2. **Sistema notifiche**
   - File: `app/Notifications/`
   - Riferimento: [`docs/06-SISTEMA-MULTI-RUOLO.md`](06-SISTEMA-MULTI-RUOLO.md)

---

## 🛠️ **SCRIPT E AUTOMAZIONE DISPONIBILI**

### 📁 **Directory:** `docs/03-scripts-automazione/`

#### 🔧 **Setup e Manutenzione**
- `setup-complete-environment.sh` - Setup ambiente completo
- `fix-vscode-install.sh` - Fix installazione VS Code
- `manage-database.sh` - Gestione database (backup/restore)

#### 🔄 **Sincronizzazione**
- `sync-bidirectional.sh` - Sync bidirezionale file
- `sync-to-remote.sh` - Sync verso server remoto

#### ⚡ **Testing e Deploy**
- `test-dashboard.sh` - Test dashboard e funzionalità
- `quick-deploy.sh` - Deploy rapido
- `verify-system.sh` - Verifica sistema

---

## 🗄️ **COMPRENSIONE DATABASE**

### 📊 **Tabelle Principali**
```sql
-- Riferimento: docs/04-DATABASE-STRUTTURE.md
stabili              # Edifici/condomini
persone              # Anagrafica (inquilini, proprietari, admin)
unita_immobiliari    # Appartamenti/locali
users                # Sistema autenticazione
roles                # Ruoli utenti (admin, superadmin, inquilino)
```

### 🔑 **Migrations Critiche**
```bash
# Directory: database/migrations/
# ATTENZIONE: Non modificare quelle esistenti
# Per nuove modifiche: php artisan make:migration nome_modifica
```

### 👥 **Sistema Autenticazione**
- **Controller:** `app/Http/Controllers/Auth/SecureDashboardController.php`
- **Middleware:** `app/Http/Middleware/`
- **Spatie Roles:** Sistema ruoli e permessi
- **Riferimento:** [`docs/06-SISTEMA-MULTI-RUOLO.md`](06-SISTEMA-MULTI-RUOLO.md)

---

## 🎨 **SISTEMA INTERFACCIA**

### 🏗️ **Layout Universale**
- **File principale:** `resources/views/components/layout/universal.blade.php`
- **Sistema sidebar:** `resources/views/components/sidebar-dynamic.blade.php`
- **AJAX navigation:** `public/js/dashboard.js`

### 📱 **Componenti UI**
- **Cards dashboard:** `resources/views/dashboard/`
- **Form modali:** `resources/views/forms/`
- **Tabelle data:** `resources/views/tables/`

### 🎯 **Riferimenti Interfaccia**
- [`docs/05-INTERFACCIA-UNIVERSALE.md`](05-INTERFACCIA-UNIVERSALE.md) - **Sistema completo**
- [`docs/02-architettura-laravel/sidebar-modulare.md`](02-architettura-laravel/sidebar-modulare.md) - **Sidebar**
- [`docs/08-FRONTEND-UX.md`](08-FRONTEND-UX.md) - **Frontend guidelines**

---

## 🔍 **TROUBLESHOOTING RAPIDO**

### ❌ **Problema: Dashboard non carica**
```bash
# Soluzione rapida
php artisan optimize:clear
php artisan config:cache
# Riferimento: docs/01-manuali-aggiuntivi/QUICK_REFERENCE_LARAVEL.md
```

### ❌ **Problema: Errori permessi**
```bash
# Fix permessi
sudo chown -R www-data:www-data ~/netgescon/netgescon-laravel
sudo chmod -R 755 ~/netgescon/netgescon-laravel
sudo chmod -R 775 storage bootstrap/cache
```

### ❌ **Problema: Database connection**
```bash
# Verifica configurazione
cat .env | grep DB_
mysql -u netgescon_user -p
# Riferimento: docs/00-transizione-linux/README-TRANSITION-COMPLETE.md
```

### ❌ **Problema: Autenticazione rotta**
```bash
# Verifica ruoli
php artisan tinker
User::with('roles')->get();
# Riferimento: docs/06-SISTEMA-MULTI-RUOLO.md
```

---

## 🔄 **SINCRONIZZAZIONE SERVER REMOTO**

### 📡 **Script Rsync Pronto**
```bash
# Da eseguire per sincronizzare con server remoto
cd ~/netgescon
rsync -avz --delete \
    --exclude='.git' \
    --exclude='node_modules' \
    --exclude='vendor' \
    --exclude='storage/logs' \
    ./ utente@server-remoto:/percorso/destinazione/
```

### 🎯 **Cartelle da Sincronizzare SEMPRE**
- `docs/` - Documentazione completa
- `netgescon-laravel/app/` - Codice applicazione
- `netgescon-laravel/resources/` - Template e asset
- `netgescon-laravel/database/migrations/` - Strutture DB
- `netgescon-laravel/.env.example` - Configurazione template

### ⚠️ **Cartelle da NON Sincronizzare**
- `netgescon-laravel/storage/logs/` - Log locali
- `netgescon-laravel/vendor/` - Dipendenze (ricostruire con composer)
- `netgescon-laravel/node_modules/` - Dipendenze npm
- `.git/` - Storia git (sync separato)

---

## 🤖 **MESSAGGI PER IL TUO ALTER EGO**

### 💬 **Cosa dirgli per iniziare**
```
"Ciao! Sono il tuo 'alter ego' Michele. Ho preparato tutto per te:

1. INIZIA DA: ~/netgescon/docs/00-INDICE-DOCS-UNIFICATA.md
2. LEGGI SUBITO: docs/00-transizione-linux/README-TRANSITION-COMPLETE.md  
3. INVENTARIO: docs/00-transizione-linux/FEATURES-INVENTORY-COMPLETE.md
4. QUESTA GUIDA: docs/00-COPILOT-MASTER-GUIDE.md

REGOLA D'ORO: Sempre backup prima di modifiche!

La struttura è completa e documentata. Hai accesso a:
- 301 file di documentazione
- Script automazione pronti
- Database funzionante
- Sistema autenticazione attivo

Tutto è nella cartella docs/ organizzato per categoria.
Non perderti, segui gli indici! 🧭"
```

### 🎯 **Come risolvere primi problemi**
```
"Per i primi problemi:

1. SEMPRE consulta: docs/01-manuali-aggiuntivi/QUICK_REFERENCE_LARAVEL.md
2. Script emergenza: docs/03-scripts-automazione/verify-system.sh
3. Troubleshooting: docs/00-transizione-linux/README-TRANSITION-COMPLETE.md
4. Database issues: docs/04-DATABASE-STRUTTURE.md

Tutti gli screenshot debug sono in: docs/images/
Michele ha documentato TUTTO. Usa la documentazione!"
```

---

## 📋 **CHECKLIST FINALE HANDOFF**

### ✅ **Verifica Completezza**
- [ ] Documentazione unificata in docs/
- [ ] Script automazione testati
- [ ] Database funzionante
- [ ] Autenticazione attiva
- [ ] Backup sistema configurato
- [ ] Rsync script preparato

### ✅ **Test Funzionalità**
- [ ] Login admin funziona
- [ ] Dashboard carica
- [ ] CRUD stabili operativo
- [ ] Sistema ruoli attivo
- [ ] Sidebar AJAX funziona

### ✅ **Documentazione Accessibile**
- [ ] Indici navigabili
- [ ] Cross-reference funzionanti
- [ ] Screenshot disponibili
- [ ] Script documentati

---

## 🚀 **PASSAGGIO DI CONSEGNE COMPLETATO**

> **🎯 Michele → GitHub Copilot/AI**  
> 
> **Data handoff:** 18/07/2025  
> **Stato sistema:** ✅ Funzionante e documentato  
> **Copertura documentazione:** 301 file, 11MB  
> **Entry point:** `docs/00-INDICE-DOCS-UNIFICATA.md`  
> 
> **🔑 Tutto è pronto per continuare lo sviluppo in autonomia!**

---

**🏢 NETGESCON** - Passaggio Consegne Completo  
**🤖 Da:** Michele (Human Developer)  
**🤖 A:** GitHub Copilot/AI Assistant  
**📅 Data:** 18 Luglio 2025