171 lines
12 KiB
Markdown
171 lines
12 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
|
|
```
|
|
|
|
---
|
|
|
|
# ⭐ CENTRO STELLA DI COORDINAMENTO MULTI-MACCHINA
|
|
|
|
Questo repository di skill non e solo un contenitore di SOP. Da oggi funge da **concentratore centrale** per coordinare il lavoro distribuito tra le macchine NetGescon, con la `.53` come centro di raccolta direttive e con la `.205` come sorgente principale del nuovo sviluppo applicativo fino alla validazione della `.200`.
|
|
|
|
## Obiettivo operativo del Centro Stella
|
|
|
|
- centralizzare direttive, handoff e priorita operative in un unico punto leggibile dagli Agent
|
|
- separare le regole stabili di architettura dagli handoff temporanei per macchina
|
|
- permettere alla `.200` di essere la prima macchina di riallineamento del nuovo sviluppo proveniente dalla `.205`
|
|
- preparare il passaggio successivo verso la macchina AI dedicata e poi verso il nodo Docker pubblico
|
|
|
|
## Struttura operativa del Centro Stella
|
|
|
|
- `directives/`
|
|
SOP stabili, memoria architetturale e regole di business consolidate
|
|
- `control-tower/`
|
|
plancia centrale con stato macchine, stream, priorita e blocchi aperti
|
|
- `handoffs/`
|
|
pacchetti operativi per singola macchina, con input, vincoli, branch e output attesi
|
|
- `skills/`
|
|
kit tematici riusabili dai vari Agent per dominio o modulo funzionale
|
|
|
|
## Ordine di messa in linea previsto
|
|
|
|
1. organizzare il Centro Stella e consolidare il primo livello documentale
|
|
2. allineare la `.200` al nuovo sviluppo pubblicato dalla `.205` tramite branch di stabilizzazione
|
|
3. estendere il modello alla macchina AI dedicata per riconciliazione e supporto dati
|
|
4. predisporre il nodo Docker destinato all'esposizione pubblica solo dopo validazione interna
|
|
|
|
---
|
|
|
|
# 🧠 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 1B: Control Tower e Handoff Macchina (Chi fa cosa e quando)**
|
|
- Le decisioni di coordinamento multi-macchina vivono in `control-tower/`.
|
|
- Gli incarichi operativi per nodo vivono in `handoffs/`.
|
|
- Ogni macchina deve leggere prima il proprio handoff e poi le SOP collegate in `directives/`.
|
|
- Le direttive stabili non vanno mescolate ai diari storici o ai report temporanei.
|
|
|
|
**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**.
|
|
- Il codice deve contenere anche ancore leggibili dagli Agent per spiegare: scopo del modulo, dati letti e scritti, invarianti, vincoli di business e punti che non vanno rotti. La documentazione non deve vivere solo fuori dal codice.
|
|
|
|
---
|
|
|
|
## 🎯 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)├── control-tower/ # Coordinamento macchine, stream, blocchi e priorita├── handoffs/ # Pacchetti operativi per singola macchina├── skills/ # Kit tematici riusabili dagli Agent├── 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.
|
|
|
|
---
|
|
|
|
## 🎛️ Modalita di Lavoro Assistita: Utente di Dominio -> Agent Interfaccia -> Agent Esecutori
|
|
|
|
Quando l'utente conosce bene il risultato funzionale atteso ma non vuole scrivere direttive tecniche complesse, il Centro Stella deve usare questo flusso:
|
|
|
|
1. l'utente descrive obiettivo, risultato atteso, cosa non va e casi reali
|
|
2. l'Agent Interfaccia traduce la richiesta in forma tecnica strutturata
|
|
3. la `.205` riceve il prompt di implementazione
|
|
4. la `.200` riceve il prompt di validazione indipendente
|
|
5. l'utente osserva il risultato e invia note correttive
|
|
6. l'Agent Interfaccia prepara il giro successivo senza chiedere all'utente di riscrivere tutto in forma tecnica
|
|
|
|
Questo modello e obbligatorio quando il dominio e chiaro ma la formulazione tecnica rischia di essere ambigua o dispersiva.
|
|
|
|
---
|
|
|
|
## 🧾 Principio Open Source e Codice Auto-Spiegante
|
|
|
|
NetGescon deve essere predisposto per essere compreso in due modi complementari:
|
|
|
|
1. documentazione centrale versionata
|
|
2. documentazione locale dentro il codice
|
|
|
|
Ogni modulo importante deve quindi essere leggibile anche aprendo direttamente:
|
|
|
|
- model
|
|
- migration
|
|
- service
|
|
- command
|
|
- Filament page
|
|
- Blade principale
|
|
|
|
Ogni file chiave deve poter spiegare almeno:
|
|
|
|
- cosa fa
|
|
- quali tabelle o entita tocca
|
|
- quali invarianti di business protegge
|
|
- quali effetti ha sulle altre parti del sistema
|
|
- quali campi o relazioni un Agent puo modificare in sicurezza e quali no |