michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
86928f069b
netgescon-day0/skill-netgescon/.ai-context.md

12 KiB
Raw Blame History

🗺️ 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

⭐ 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