92 lines
8.4 KiB
Markdown
92 lines
8.4 KiB
Markdown
# 🗺️ 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 |