Sistema di Auto-Documentazione¶

Sistema automatizzato di generazione e aggiornamento della documentazione tecnica e utente del gestionale Eurocoge, basato su Claude Code (AI) e schedulato via cron.

Panoramica¶

Il sistema monitora le modifiche ai sorgenti COBOL, ai documenti di import e ai bug tracciati su ClickUp. Quando rileva cambiamenti, invoca Claude Code in modalita' non-interattiva per analizzare le modifiche e aggiornare la documentazione.

Cosa produce¶

Output	Destinazione	Descrizione
Doc tecnica	`docs/dev/` (mkdocs-dev.yml, porta 8001)	Struttura programmi, tabelle, flussi, logica di business
Doc utente	`docs/user/` (mkdocs.yml, porta 8000)	Guide operative per utenti non tecnici
Bug risolti	`docs/dev/bugs/` + indice `bugs-risolti.md`	Analisi causa-soluzione dei bug da ClickUp
Configurazioni	`docs/dev/interno/configurazioni/`	Parametri RNEWCONF sincronizzati dal gestionale
Registro modifiche tecnico	`docs/dev/changelog/YYYY/MM/YYYY-MM-DD.md`	Pagine giornaliere con link alle pagine modificate (sezione "Registro modifiche" nel portale tecnico)
Registro modifiche utente	`docs/user/changelog/YYYY/MM/YYYY-MM-DD.md`	Pagine giornaliere solo con modifiche visibili all'utente (sezione "Aggiornamenti" nel portale utente)
Log operativo	`logs/auto-doc-YYYY-MM-DD.log`	Log tecnico giornaliero dello script

Architettura¶

                    ┌─────────────┐
                    │   CRON      │  Ogni giorno alle 03:00
                    │  auto-doc.sh│
                    └──────┬──────┘
                           │
              ┌────────────┼────────────────┐
              v            v                v
     ┌────────────┐  ┌───────────┐  ┌──────────────┐
     │Sync bugs   │  │ Snapshot  │  │ Sync config  │
     │ ClickUp    │  │ filesystem│  │ RNEWCONF     │
     │ (Python)   │  │ (bash)    │  │ (Python)     │
     └─────┬──────┘  └─────┬─────┘  └──────┬───────┘
           │               │               │
           v               v               │
     docs/import/    Diff con snapshot      │
     bugs/           precedente             │
           │          (incl. prog.txt)      │
           │               │               │
           └───────┬───────┘               │
                   v                       │
          ┌─────────────────┐              │
          │   Claude Code   │              │
          │  (claude -p)    │              │
          │                 │              │
          │ Analizza diff,  │              │
          │ genera/aggiorna │              │
          │ documentazione, │              │
          │ riconcilia nav  │              │
          │ da prog.txt     │              │
          └────────┬────────┘              │
                   │                       │
        ┌──────────┼──────────┐            │
        v          v          v            v
   docs/dev/  docs/user/  mkdocs*.yml  docs/dev/interno/
   (tecnica)  (utente)    (navigazione) configurazioni/

Script e file di configurazione¶

File	Ruolo
`scripts/auto-doc.sh`	Orchestratore principale (bash). Gestisce snapshot, smistamento, invocazione Claude Code
`scripts/sync-bugs-clickup.py`	Scarica bug chiusi da ClickUp e li salva in `docs/import/bugs/`
`scripts/sync-configurazioni.py`	Sincronizza configurazioni RNEWCONF da `docs/import/configurazioni/` verso `docs/dev/interno/configurazioni/`
`AUTO-DOC.md`	Istruzioni operative per Claude Code (cosa documentare e come)
`CLAUDE.md`	Convenzioni generali del progetto (encoding, stile, struttura)
`.env`	Token API ClickUp e parametri di connessione (non versionato)
`.claude/settings.json`	Permessi di scrittura per Claude Code in modalita' non-interattiva
`docs/user/.autodoc-snapshot.tsv`	Snapshot filesystem dell'ultima esecuzione riuscita
`prog.txt`	Mappa completa del menu applicativo, generata dal programma `WPOPTRE` (paragrafo `m-estrai-dati-menu` in `cbl/wpoptre.cbl`). Legge le tabelle MASKMENU/MASKBODY/MASKPARA e produce un TSV a 9 colonne (Menu, Sottomenu 1-5, Descrizione, Programma, MenuId). Va rigenerato manualmente dal gestionale quando vengono aggiunti programmi a menu

Flusso di esecuzione dettagliato¶

Passo 0 — Sync bug da ClickUp¶

Lo script sync-bugs-clickup.py interroga l'API ClickUp per i task con:

Lista: "TASK | BUG (Generici)" nello space PROGETTI
Tipologia: BUG (campo custom dropdown)
Stato: "complete" o "archiviato"
Filtro incrementale: solo task aggiornati dopo l'ultimo sync

I bug vengono salvati come markdown in docs/import/bugs/bug_{task_id}.md. Lo stato del sync e' in docs/import/bugs/.sync-state.json.

Passo 1 — Generazione snapshot¶

Lo script genera un elenco di tutti i file monitorati:

Sorgenti COBOL: cbl/*.cbl (esclusi Y*, MAU*, BG*, BEP*, AND*, STE*) — tracciati con mtime + size
Documenti di import: tutto docs/import/ ricorsivamente (esclusi ._*) — tracciati con md5 del contenuto (non mtime+size, perche' il sync ClickUp aggiorna il mtime anche senza modificare il contenuto)
Mappa menu: prog.txt (export periodico dal gestionale) — tracciato con mtime + size

Passo 2 — Confronto con snapshot precedente¶

Identifica file nuovi o modificati (mtime o size diversi) confrontando con docs/user/.autodoc-snapshot.tsv.

Passo 3 — Smistamento¶

I file modificati vengono classificati in tre categorie:

Categoria	Pattern	Gestione
Sorgenti COBOL	`cbl/*.cbl`	Passati a Claude Code
Configurazioni RNEWCONF	`docs/import/configurazioni/*`	Gestiti da `sync-configurazioni.py` (NON da Claude Code)
Altri import (inclusi bug)	`docs/import/*`	Passati a Claude Code
Mappa menu	`prog.txt`	Passato a Claude Code per riconciliazione albero nav

Passo 4 — Sync configurazioni¶

Se ci sono file di configurazione modificati, viene eseguito sync-configurazioni.py che raggruppa le chiavi per programma e genera/aggiorna i file in docs/dev/interno/configurazioni/.

Se prog.txt risulta modificato (aggiornamento manuale periodico dal gestionale), Claude Code esegue la riconciliazione dell'albero della documentazione utente:

Confronta i programmi in prog.txt con le voci nel nav di mkdocs.yml
Per i programmi non presenti nel nav, cerca se esiste gia' una pagina .md in docs/user/menu/
Se la pagina esiste, aggiunge la voce nel nav nella posizione corretta (seguendo la gerarchia Menu > Sottomenu di prog.txt)
Programmi presenti in piu' posizioni di menu vengono aggiunti in tutte le posizioni, puntando allo stesso file .md
Segnala nel changelog i programmi a menu privi di documentazione utente

Questo passo permette di colmare progressivamente le lacune dell'albero di navigazione senza richiedere la creazione immediata di tutte le pagine mancanti.

Passo 5b — Invocazione Claude Code¶

Claude Code viene invocato ad ogni esecuzione (non solo quando ci sono sorgenti modificati). Il prompt include:

La lista dei sorgenti COBOL e documenti di import modificati (se presenti)
L'istruzione di riconciliazione nav se prog.txt e' cambiato
L'istruzione di documentazione incrementale (Fase 4b, sempre)

Claude Code per ciascun sorgente modificato:

Esegue git diff per identificare le modifiche
Cerca marcatori *>DOC: nel codice
Classifica la modifica (logica di business, strutturale, correttiva, cosmetica)
Crea o aggiorna documentazione tecnica e/o utente
Aggiorna la navigazione mkdocs se necessario

Per i bug da ClickUp:

Crea pagina di dettaglio in docs/dev/bugs/
Aggiunge riga nell'indice docs/dev/bugs-risolti.md
Integra nella sezione "Casistica problemi noti" della doc tecnica dei programmi coinvolti

Passo 5c — Documentazione incrementale (Fase 4b)¶

Ad ogni esecuzione, dopo aver processato le modifiche, Claude Code documenta ~20 programmi a menu ancora privi di documentazione utente:

Confronta prog.txt con le pagine esistenti in docs/user/menu/
Esclude i programmi fuori perimetro (5 menu esclusi + categorie escluse, vedi sotto)
Seleziona ~20 programmi non ancora documentati (priorita': aree principali, programmi interattivi, programmi multi-menu)
Per ciascuno: legge il sorgente, crea doc utente + doc tecnica, aggiorna il nav
Registra nel changelog sotto "Documentazione incrementale"

Questo garantisce una crescita costante della copertura documentale (~20 programmi/giorno).

Se non ci sono sorgenti modificati, Claude Code viene comunque invocato solo per questo passo.

Definiti nel piano di documentazione (docs/dev/piano-documentazione.md, sezione 3):

Menu/Categoria	Motivo
Contanti	Vendita al banco, non core
Assist vecchio (AST*)	Legacy, sostituito da Assist 2.0
Areapostel (COGI6-9, LDS*)	Verticale assicurazioni
Ordini Bar (PST*)	Verticale ristorazione
Clinica (APO, GRP)	Verticale cliniche dentali (diverso da Lab.Odontotecnico)
TEM, WIN	Template e sotto-componenti finestra
Senza sorgente in `cbl/`	Rimossi o esterni

I programmi condivisi tra menu esclusi e menu in perimetro vanno comunque documentati.

Passo 6 — Validazione e snapshot¶

Se Claude Code produce output significativo (>50 bytes), lo snapshot viene aggiornato. Altrimenti i file verranno riprocessati al ciclo successivo.

Struttura delle cartelle¶

docs/
├── import/                          # Materiale sorgente (input)
│   ├── areagate/api/
│   │   ├── dev/                     # Specifiche API (doc tecnica)
│   │   └── user/                    # Specifiche API (doc utente)
│   ├── bugs/                        # Bug da ClickUp (generati automaticamente)
│   │   ├── bug_{task_id}.md
│   │   └── .sync-state.json         # Stato ultimo sync
│   └── configurazioni/              # Chiavi RNEWCONF esportate dal gestionale
│       └── c_{gruppo}_{chiave}.md
├── dev/                             # Documentazione tecnica (output)
│   ├── programmi/                   # Doc per singolo programma
│   ├── flussi/                      # Flussi di business
│   ├── interno/                     # Documentazione interna
│   │   └── configurazioni/          # Chiavi RNEWCONF (generate da sync script)
│   ├── bugs/                        # Pagine dettaglio bug
│   │   └── bug_{task_id}.md
│   ├── bugs-risolti.md              # Indice bug risolti
│   └── changelog/                   # Registro modifiche tecnico (giornaliero)
│       └── YYYY/MM/YYYY-MM-DD.md
├── user/                            # Documentazione utente (output)
│   ├── menu/                        # Pagine per funzione di menu
│   ├── changelog/                   # Registro aggiornamenti utente (giornaliero)
│   │   └── YYYY/MM/YYYY-MM-DD.md
│   └── .autodoc-snapshot.tsv        # Snapshot filesystem

Schedulazione¶

Il cron e' configurato sul server come utente root:

0 3 * * * /programmi/eurocoge/scripts/auto-doc.sh

Il log operativo e' in logs/auto-doc.log.

Esecuzione manuale¶

Ciclo completo¶

bash scripts/auto-doc.sh

Forzare rielaborazione di file specifici¶

bash scripts/auto-doc.sh --force docs/import/bugs/
bash scripts/auto-doc.sh --force cbl/cogo05w.cbl

Solo sync bug da ClickUp¶

python3 scripts/sync-bugs-clickup.py            # incrementale
python3 scripts/sync-bugs-clickup.py --force     # tutti i bug chiusi

Solo sync configurazioni¶

python3 scripts/sync-configurazioni.py

Documentazione Areagate¶

Il modulo Areagate e' sviluppato e documentato esternamente a questo pacchetto. Tutta la documentazione prodotta all'esterno (specifiche API, guide, tracciati, ecc.) deve essere depositata in docs/import/areagate/ e relative sottocartelle, da dove il processo di auto-documentazione la rileva e la integra nella sezione Areagate del portale (docs/dev/areagate/).

Le fonti di alimentazione della sezione sono due:

Fonte	Contenuto	Meccanismo
Programmi `SWN*`	Documentazione sincronizzazione	Automatico: quando un sorgente `SWN*` risulta modificato, Claude Code analizza il diff e aggiorna la sezione Sincronizzazione
`docs/import/areagate/`	Specifiche API, guide, tracciati	Automatico: quando vengono aggiunti o aggiornati file in questa cartella, Claude Code li elabora e aggiorna le sezioni corrispondenti (API, ecc.)

Struttura attuale della cartella di import:

docs/import/areagate/
└── api/
    ├── dev/     # Specifiche API per documentazione tecnica
    └── user/    # Specifiche API per documentazione utente

Per aggiungere nuova documentazione Areagate (es. setup, configurazione, nuove API): depositare i file markdown nella sottocartella appropriata di docs/import/areagate/ e attendere il prossimo ciclo di auto-documentazione, oppure forzare l'esecuzione con bash scripts/auto-doc.sh.

Marcatore *>DOC: nei sorgenti¶

I programmatori possono inserire nel codice COBOL commenti con il prefisso *>DOC: per segnalare modifiche rilevanti. Il sistema di auto-documentazione li usa come guida principale per capire cosa documentare.

      *>DOC: Aggiunto controllo giacenza minima per articoli deperibili.
      *>DOC: Se la giacenza scende sotto la soglia, blocca l'importazione.

Quando si modifica la logica di business di un programma, e' fortemente consigliato inserire questi marcatori. Migliorano significativamente la qualita' della documentazione generata.

Permessi Claude Code¶

I permessi per la modalita' non-interattiva sono in .claude/settings.json:

Edit: docs/**, mkdocs.yml, mkdocs-dev.yml
Read, Glob, Grep: senza restrizioni
Bash: comandi di sola lettura (grep, ls, find, cat, head, wc) + mkdocs build + python3

Se Claude Code non riesce ad aggiornare un file, lo segnala nel changelog e nel log. Verificare i permessi in caso di problemi.

Troubleshooting¶

L'auto-doc non rileva modifiche¶

Verificare che il file sia nella directory monitorata (cbl/ o docs/import/)
Verificare che non sia escluso (programmi personali MAU, BG, ecc.)
Controllare lo snapshot: cat docs/user/.autodoc-snapshot.tsv | grep nomefile

Claude Code non produce output¶

Controllare logs/auto-doc.log per errori
Verificare che il token API Anthropic sia valido
Se l'output e' vuoto (<50 bytes), lo snapshot NON viene aggiornato e i file verranno riprocessati

Navigazione mkdocs non aggiornata¶

Verificare i permessi in .claude/settings.json (servono Edit(mkdocs.yml) e Edit(mkdocs-dev.yml))
Le voci mancanti sono riportate nel registro modifiche giornaliero (docs/dev/changelog/YYYY/MM/YYYY-MM-DD.md) sotto "Note"
Se prog.txt non e' aggiornato, l'albero nav non puo' essere riconciliato. Rieseguire il programma di estrazione menu dal gestionale e poi lanciare bash scripts/auto-doc.sh

Configurazioni non sincronizzate¶

Le configurazioni RNEWCONF sono gestite da sync-configurazioni.py, NON da Claude Code
Eseguire manualmente: python3 scripts/sync-configurazioni.py

Bug ClickUp non scaricati¶

Verificare il token in .env (puo' scadere se rigenerato)
Verificare che il bug sia in stato "complete" o "archiviato" e abbia Tipologia = BUG
Per forzare un riscaricamento completo: python3 scripts/sync-bugs-clickup.py --force

Git diff non disponibile¶

Il repository richiede safe.directory per operare come root. Lo script lo configura automaticamente tramite variabili d'ambiente GIT_CONFIG_*. Se il problema persiste, verificare che la sezione relativa in auto-doc.sh sia presente.