🗺️ ROADMAP VISIVA DEL PROGETTO (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:

Ispeziona i log di Laravel (storage/logs/laravel.log) e lo stack trace del terminale Linux.
Correggi la classe o lo script di migrazione, quindi riesegui il test.
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.
Non cancellare il codice funzionante dell'utente: ottimizzalo seguendo i 3 livelli,poi

8.4 KiB Raw Blame History