208 lines
7.9 KiB
Markdown
Executable File
208 lines
7.9 KiB
Markdown
Executable File
# Rete docs e agent - operativita condivisa
|
|
|
|
## Scopo
|
|
|
|
Questo manuale definisce come distribuire i manuali di sviluppo e i runbook su tutte le macchine della rete.
|
|
|
|
La strategia ha due fasi compatibili:
|
|
|
|
- fase 0: condivisione LAN immediata di `docs/` con NFS, senza dipendere subito da Gitea;
|
|
- fase 1: sincronizzazione Git/Gitea come sorgente autorevole versionata.
|
|
|
|
## Decisione operativa
|
|
|
|
Da ora in avanti:
|
|
|
|
- `docs/` non e solo documentazione locale del workspace, ma memoria distribuita del gruppo di lavoro;
|
|
- finche tutte le macchine non sono collegate a Gitea, la prima condivisione avviene via cartella LAN NFS;
|
|
- Gitea resta il canale ufficiale finale per propagare manuali, indici e runbook su tutta la rete;
|
|
- ogni macchina che ospita agent o servizi deve poter leggere una copia aggiornata di `docs/`;
|
|
- gli agent devono coordinarsi a partire da indice e runbook, non da ricostruzione manuale del contesto.
|
|
|
|
## Architettura minima consigliata
|
|
|
|
### Livello 0 - share LAN provvisorio ma operativo
|
|
|
|
Macchina capofila della rete:
|
|
|
|
- nodo capofila attuale: `192.168.0.200`
|
|
- espone una share NFS di sola lettura o lettura/scrittura per `docs/`;
|
|
- mantiene anche una piccola area condivisa per `scripts/ai/`, `exchange/` e moduli selezionati;
|
|
- diventa il punto comune da cui tutte le altre macchine montano i manuali.
|
|
|
|
Uso consigliato:
|
|
|
|
1. una macchina Day0 funge da sorgente LAN iniziale;
|
|
2. le altre macchine montano la share in un path fisso, per esempio `/srv/netgescon/docs-mirror`;
|
|
3. ogni workspace locale punta a quel mount per leggere i manuali, gli indici e gli script di supporto.
|
|
4. la cartella `exchange/` serve per handoff, messaggi, allegati e materiale di appoggio tra macchine.
|
|
|
|
### Livello 1 - sorgente autorevole
|
|
|
|
- repository `netgescon-day0`
|
|
- remote `origin -> ssh://git@192.168.0.53:2222/michele/netgescon-day0.git`
|
|
- branch operativo `main`
|
|
|
|
### Livello 2 - mirror docs sulle macchine di rete
|
|
|
|
Ogni macchina tecnica puo usare uno di questi modelli:
|
|
|
|
1. checkout completo del repository Day0
|
|
2. mirror leggero con sparse checkout di `docs/` e `scripts/ai/`
|
|
|
|
Il secondo modello e preferibile per macchine di supporto, agent dedicati e nodi che non devono eseguire tutta l applicazione.
|
|
|
|
### Livello 3 - agent e servizi
|
|
|
|
Ogni agent deve sapere prima di tutto:
|
|
|
|
1. dove si trova il mirror `docs/`
|
|
2. qual e il commit corrente del mirror
|
|
3. quale indice leggere per trovare il cantiere attivo
|
|
4. dove riportare il risultato quando finisce
|
|
|
|
## Procedura standard per aggiungere una macchina
|
|
|
|
### Modalita A - prima di Gitea, con share LAN NFS
|
|
|
|
1. scegliere una macchina capofila che ospita il repository Day0 aggiornato;
|
|
2. esportare in rete una cartella condivisa che contiene almeno:
|
|
- `docs/`
|
|
- `scripts/ai/`
|
|
- `exchange/`
|
|
- eventuali moduli di lavoro selezionati
|
|
3. montare la share sulla macchina nuova in un path stabile;
|
|
4. creare un workspace locale che punti a quel mount condiviso;
|
|
5. leggere almeno:
|
|
- `docs/README.md`
|
|
- `docs/00-INDICE-LAVORO-DISTRIBUITO.md`
|
|
- `docs/support/CONTINUITA-SVILUPPO-AGENT.md`
|
|
6. assegnare alla macchina un ruolo esplicito.
|
|
|
|
### Modalita B - dopo il collegamento a Gitea
|
|
|
|
1. verificare accesso Git a Gitea dalla macchina
|
|
2. creare il mirror docs con lo script `scripts/ai/bootstrap_docs_mirror.sh`
|
|
3. leggere almeno:
|
|
- `docs/README.md`
|
|
- `docs/00-INDICE-LAVORO-DISTRIBUITO.md`
|
|
- `docs/support/CONTINUITA-SVILUPPO-AGENT.md`
|
|
4. assegnare alla macchina un ruolo esplicito
|
|
5. aprire o aggiornare il runbook del cantiere che quella macchina seguira
|
|
|
|
## Ruoli macchina gia previsti
|
|
|
|
### `.53` - Gitea + update server interno
|
|
|
|
Ruolo:
|
|
|
|
- sorgente Git della rete
|
|
- primo relay della documentazione distribuita
|
|
- nodo update interno per manifest e pacchetti
|
|
|
|
Runbook principale:
|
|
|
|
- `docs/support/UPDATE-SERVER-53-RUNBOOK-2026-05.md`
|
|
|
|
### Nodi app/demo/prod
|
|
|
|
Ruolo:
|
|
|
|
- consumare aggiornamenti applicativi
|
|
- poter leggere i runbook di supporto senza dipendere dalla singola sessione agent
|
|
|
|
### Macchina mini AI banca/contabilita
|
|
|
|
Ruolo:
|
|
|
|
- stream tecnico dedicato a riconciliazione movimenti bancari e scritture contabili
|
|
- supporto a matching, classificazione e proposte operative
|
|
|
|
Nota:
|
|
|
|
- prima di renderla operativa a pieno titolo, va creato un runbook dedicato a input, output, fonti dati e criteri di validazione.
|
|
- per il cantiere banca/contabilita esiste ora un primo runbook operativo in `docs/INTEGRAZIONE-CONTABILE.md` con la procedura validata di import Fucino su `0016`.
|
|
- runbook dedicato chiamata `.202`: `docs/support/MINI-AI-202-RICONCILIAZIONE-RUNBOOK.md`.
|
|
|
|
## Modus operandi di gruppo
|
|
|
|
1. ogni cantiere deve avere un documento indice o runbook esplicito
|
|
2. ogni avanzamento che diventa utile per altri deve essere scritto in `docs/`
|
|
3. gli agent non devono inventarsi workflow locali scollegati da Gitea
|
|
4. se due macchine lavorano sullo stesso stream, si sincronizzano via repository e non tramite copia manuale di file
|
|
5. prima di iniziare una nuova implementazione si legge l indice distribuito
|
|
|
|
### Regola pratica per KB e passaggi di consegne
|
|
|
|
Quando un incidente di rete/applicazione viene chiuso o un cantiere cambia fase:
|
|
|
|
1. aggiornare prima il runbook o il documento guida nel repository Day0;
|
|
2. aggiungere o aggiornare il passaggio di consegne del cantiere interessato;
|
|
3. sincronizzare poi `docs/` verso la `.53` con `scripts/ai/sync_docs_to_53.sh`;
|
|
4. solo dopo considerare il KB centrale allineato per gli altri agent.
|
|
|
|
Nota operativa:
|
|
|
|
- il KB centrale sulla `.53` va trattato come layer di retrieval e memoria condivisa;
|
|
- la prova di verita resta sempre il documento versionato nel repository, non una nota rimasta solo dentro una sessione o una macchina.
|
|
|
|
## Sequenza pratica di lavoro condiviso
|
|
|
|
### Fase 0 - rete locale senza Gitea
|
|
|
|
1. una sola macchina aggiorna il repository Day0 autorevole della LAN
|
|
2. quella macchina espone la share NFS di `docs/` e `scripts/ai/`
|
|
3. le altre macchine montano la share nello stesso path logico
|
|
4. ogni agent legge l indice distribuito dalla stessa share
|
|
5. quando una procedura cambia, si aggiorna prima il repository Day0 della macchina capofila
|
|
|
|
### Fase 1 - rete con Gitea attivo
|
|
|
|
1. definire il cantiere in `docs/00-INDICE-LAVORO-DISTRIBUITO.md`
|
|
2. fissare o aggiornare il runbook tecnico del cantiere
|
|
3. implementare nel repository Day0
|
|
4. commit + push su Gitea
|
|
5. pull o sync dei mirror sulle altre macchine
|
|
6. validazione locale della macchina che esegue il pezzo operativo
|
|
7. aggiornamento del runbook con esito, problemi e prossimo check
|
|
|
|
## Script consigliato
|
|
|
|
### Bootstrap share LAN NFS
|
|
|
|
Per preparare una macchina capofila o un client di rete senza Gitea usare:
|
|
|
|
```bash
|
|
bash bootstrap_docs_lan_share.sh server /home/michele/netgescon/netgescon-day0 192.168.0.0/24 /srv/netgescon/shared-docs "docs,scripts/ai,app,config,routes,resources,tests"
|
|
bash bootstrap_docs_lan_share.sh client 192.168.0.200:/srv/netgescon/shared-docs /srv/netgescon/shared-docs /home/utente/netgescon-lan-workspace
|
|
```
|
|
|
|
Comportamento atteso:
|
|
|
|
- lato server: prepara la cartella condivisa con `docs/`, `scripts/ai/`, `exchange/` e moduli selezionati, genera la riga `exports` e i comandi `exportfs`
|
|
- lato client: monta la share, crea un workspace locale minimo e collega `docs/`, `scripts/ai/`, `exchange/` e `modules/` alla share di rete
|
|
|
|
### Bootstrap mirror Git
|
|
|
|
Per creare o aggiornare un mirror leggero della documentazione su una macchina di rete usare:
|
|
|
|
```bash
|
|
bash scripts/ai/bootstrap_docs_mirror.sh /percorso/mirror-docs
|
|
```
|
|
|
|
Comportamento atteso:
|
|
|
|
- clone iniziale se il mirror non esiste
|
|
- sparse checkout di `docs/` e `scripts/ai/`
|
|
- pull `--ff-only` se il mirror esiste gia
|
|
- stampa di remote, branch e commit corrente
|
|
|
|
## Criterio di successo
|
|
|
|
Questa strategia puo dirsi attiva quando:
|
|
|
|
1. tutte le macchine agent leggono `docs/` dalla stessa sorgente, inizialmente LAN e poi Git
|
|
2. l indice distribuito mostra i cantieri realmente in corso
|
|
3. la `.53` puo essere istruita con runbook invece che con contesto orale disperso
|
|
4. i limiti di memoria della singola sessione vengono compensati da runbook e indici versionati
|