# 🗺️ ROADMAP VISIVA DEL PROGETTO (Mermaid)
<!-- Antigravity mostrerà questo blocco come un grafico interattivo delle fasi -->

```mermaid
graph TD
    classDef completato fill:#28a745,stroke:#1e7e34,stroke-width:2px,color:#fff;
    classDef inCorso fill:#ffc107,stroke:#d39e00,stroke-width:2px,color:#000;
    classDef pianificato fill:#6c757d,stroke:#545b62,stroke-width:2px,color:#fff;

    subgraph Livello 1: Direttive & Stato Core
        A[Configurazione database.php gescon_import MySQL]:::completato --> B[Esecuzione 17 Migrazioni Staging]:::completato
        B --> C[Launcher /supporto/aggiornamento-nodo]:::completato
    end

    subgraph Livello 2 & 3: Orchestrazione ed Esecuzione
        C --> D[Fase 7: Scansione Ricorsiva MDB]:::inCorso
        D --> E[Esecuzione Comandi Artisan Nativi]:::inCorso
        E --> F[Iniezione Centralizzata Dati in Blade]:::pianificato
    end

    subgraph Obiettivi Futuri Enterprise
        F --> G[Pannello Quadratura in Partita Doppia]:::pianificato
        G --> H[Integrazione XML Fatture ed API Banche]:::pianificato
        H --> I[Modulo Fiscale 770 / Quadro AC / F24]:::pianificato
    end
```

---

# 🧠 ISTRUZIONI AGENTE: ARCHITETTURA DETERMINISTICA NETGESCON (LARAVEL ENTERPRISE)
> **Istruzione per l'Agent:** Non ignorare questo file. Usalo come unica sorgente di verità per lo stato dell'applicazione, l'organizzazione della documentazione e le convenzioni di scrittura del codice.

Operi all'interno di un'architettura a 3 livelli applicata al framework **Laravel 11+ / PHP 8.2+ su Linux**. Gli LLM sono probabilistici, mentre la logica di business contabile e di migrazione è deterministica e richiede tolleranza d'errore ZERO. Non devi sovrascrivere o cancellare il sistema esistente, ma completarne lo sviluppo.

## 🏛️ Architettura a 3 Livelli & Organizzazione File

Per evitare che l'Agent dimentichi i progressi o ripeta errori già risolti, il progetto adotta una struttura rigida di documentazione e codice:

**Livello 1: Direttiva e Memoria Storica (Cosa fare)**
- Vivono all'interno della cartella `directives/` nella root del progetto sotto forma di file Markdown (`.md`).
- Ogni file definisce gli obiettivi, gli input necessari, i comandi da lanciare, gli output attesi e i casi limite (SOP).
- Questa cartella funge da **Cervello del Progetto**: quando un errore viene risolto, la direttiva corrispondente viene aggiornata per fare in modo che l'Agent non ripeta lo stesso errore in futuro.

**Livello 2: Orchestrazione (Decisioni dell'Agent)**
- Il tuo lavoro: routing intelligente lato codice e analisi dello staging su MySQL.
- Leggi le direttive in `directives/`, pianifica le modifiche con `/plan`, chiedi chiarimenti se mancano dati contabili, esegui il `/review` del codice generato e aggiorna le direttive con ciò che apprendi dall'analisi dei database.
- Utilizza l'estensione grafica **Database Client / DBCode** integrata nell'IDE sul pannello di **Destra (DX)** per ispezionare visivamente le relazioni e i campi reali del database MySQL.

**Livello 3: Esecuzione (Il Lavoro Deterministico in Laravel)**
- Non scrivere script estemporanei o isolati. I tool deterministici di NetGescon sono:
  1. **Comandi Artisan Nativi** in `app/Console/Commands/` (es. `gescon:import-align`, `gescon:sync-fornitori-legacy`).
  2. **Migration standard e agnostiche (PostgreSQL Ready)** in `database/migrations/`.
  3. **Service Classes e Repository** in `app/Services/` per la logica di business contabile.
- Tutto il codice deve essere rigorosamente commentato in lingua italiana con standard PHPDoc per favorire il futuro rilascio **Open Source**.

---

## 🎯 Pilastri Logici e Strutturali Intoccabili (Regole di Business)

### 1. Il Modello Spazio-Temporale (Unità vs Persone)
- **L'Ancora Fissa (Spazio):** L'Unità Immobiliare è fissa (dati catastali, interni, subalterni). Ad essa si legano in modo permanente: Tabelle Millesimali, Seriali dei Contatori (Acqua, Calore, Luce) e relative letture storiche. Il sistema gestisce sia le unità censite sia quelle **Non Censite** (locali caldaia, ascensori, cantine, lavatoi, portineria, aree a reddito come posteggi).
- **Il Flusso Mobile (Tempo):** Le persone (Condomini, Inquilini, Comproprietari, Fornitori, Manutentori) ruotano nel tempo. Il collegamento `Unita <-> Persona` deve essere governato da una tabella pivot con intervalli temporali (`data_inizio` / `data_fine`). Le spese saranno ripartite in base ai giorni esatti di presenza in quel periodo.

### 2. Rivoluzione Contabile: Partita Doppia Nativa (PostgreSQL Ready)
- NetGescon abbandona la contabilità a cassa semplice del legacy. Tutto il motore finanziario si basa su Libro Giornale, Mastro e Piano dei Conti (Dare/Avere).
- **Mappatura da Legacy:** Le Tabelle Millesimali ereditate sono mappate come **Conti Mastro** principali. Le Voci di Spesa legacy sono mappate come **Sottoconti** operativi. Aggiungi d'ufficio i conti patrimoniali stabili: Fondi di riserva, Banche/Poste (Attività), Debiti verso Fornitori e Crediti verso Condomini per la chiusura dell'esercizio.
- Le scritture di fine anno (ratei, risconti, chiusure) devono essere automatizzate via codice, mai gestite su carta.
- **Codice Agnostico:** Evita dialetti specifici di MySQL (No `INSERT IGNORE` o `ON DUPLICATE KEY`). Utilizza esclusivamente le astrazioni di Eloquent (`updateOrCreate()`, `upsert()`, `firstOrCreate()`). Le viste SQL (`CREATE VIEW`) devono usare espressioni ANSI standard (es. `COALESCE`).

### 3. Logica di Importazione e Scansione Ricorsiva Legacy (Tolleranza Zero Errori)
- Il sistema deve scansionare in modo ricorsivo la cartella `/mnt/gescon-archives/gescon/` per individuare tutte le cartelle stabili numeriche.
- **Sequenza di Caricamento:** Prima legge l'indice generale da `/mnt/gescon-archives/gescon/dbc/Stabili.mdb` e `Fornitori.mdb`, inserisce i dati nell'Anagrafica Unica Centralizzata e applica il **Codice Univoco Anti-Collisione** esistente (se già presente fa `merge/update`, altrimenti `insert`). Solo successivamente legge le cartelle specifiche e i file dei singoli anni.
- **Isolamento delle Gestioni:** Gli esercizi ordinari sono nella tabella `[anni]` di `Generale_stabile.mdb`. Le spese straordinarie sono in `[straordinaria]` dentro ogni `singolo_anno.mdb`. I dati contabili non devono MAI essere sovrascritti, ma isolati per `id_gestione` o `anno_competenza`. Se un codice spesa ha descrizioni diverse tra gli anni, duplica il codice internamente creando una variante (es. ID-Spesa-A, ID-Spesa-B) per preservare la storia contabile.
- **Nessun dato a caso:** Se mancano informazioni contabili durante l'importazione automatica, lo script deve bloccarsi e notificare l'errore all'operatore sul pannello di quadratura.

### 4. Condivisione dei Dati e Interfaccia Blade
- I dati dell'anagrafica centralizzata e dello stabile attivo devono essere iniettati globalmente in tutte le viste Blade tramite il metodo `boot()` di `app/Providers/AppServiceProvider.php` (usando `View::share` o View Composers) per eliminare la duplicazione di query nei singoli controller.

---

## 🛠️ Struttura Directory del Progetto NetGescon

NetGescon/ (Laravel Root)├── app/│   ├── Console/Commands/  # Livello 3: Comandi Artisan di importazione e sync (Strumenti deterministici)│   ├── Providers/         # AppServiceProvider (Iniezione globale dati nei Blade)│   └── Services/          # Logiche di Partita Doppia e Riconciliazione├── database/│   ├── migrations/        # Strutture tabelle e Viste SQL (PostgreSQL Ready)│   └── seeders/├── resources/views/       # Viste e maschere Blade (Componenti centralizzati)├── directives/            # Livello 1: SOP e file di contesto/memoria (Dizionario e file storici .md)├── config/database.php    # Configurazione multi-database (MySQL NetGescon + Staging gescon_import)├── .env                   # Chiavi e credenziali locali└── .tmp/                  # Esportazioni temporanee MDB/CSV (Ignorate da Git)

---

## 🔄 Loop di Auto-Correzione dell'Agente
Quando un comando Artisan o una migrazione fallisce:
1. Ispeziona i log di Laravel (`storage/logs/laravel.log`) e lo stack trace del terminale Linux.
2. Correggi la classe o lo script di migrazione, quindi riesegui il test.
3. Aggiorna o crea un file specifico nella cartella `directives/` se scopri nuovi comportamenti anomali o vincoli strutturali dei vecchi file MDB, espandendo la memoria del sistema.
4. Non cancellare il codice funzionante dell'utente: ottimizzalo seguendo i 3 livelli,poi