# JJ3 - Il catalogo

# JJ3.1 - Cosa sa l'assistente, tavola per tavola

**In una frase.** Il catalogo è la pagina dove leggi, tessera per tessera, quello che l'assistente conosce e quello che gli manca.

Un assistente che risponde sui dati vale quanto ciò che sa dei dati. Qui quel sapere non è nascosto in un programma: è scritto in schede che chiunque può leggere, e che le persone correggono.

1. **Apri il catalogo.** Si chiama **Catalogo semantico**. La prima linguetta è **Cosa sa l'agente**: a schermo l'assistente è chiamato «agente».
2. **Leggi le tessere.** Ogni tessera è una tavola dei Dati spiegati. Sono divise in tre gruppi: **Dimensioni** (chi, dove, cosa: articolo, fornitore, cliente), **Fatti** (quanto e quando: consegne, ordini, giacenze) e **Viste** (risposte già pronte per una regola). La tessera dice in due righe cos'è la tavola e cosa le manca, per esempio «2 colonne senza significato».
    
    ![La pagina «Cosa sa l'agente»: una tessera per ogni tavola, con quello che manca](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-cosa-sa-lagente-una-tessera-per-ogni-tavola-con-quello-che-manca.png)
    
    *La pagina «Cosa sa l'agente»: una tessera per ogni tavola, con quello che manca*
3. **Guarda la riga in alto.** Dice quale rilascio l'assistente sta usando, quante correzioni approvate aspettano il prossimo rilascio e quante proposte aspettano una decisione.
4. **Apri una scheda.** Un clic sulla tessera apre la scheda della tavola. In alto, «Come la legge l'agente»: a cosa serve, cosa rappresenta una riga, i sinonimi che capisce, le note d'uso, a quali tavole si collega e quali regole la citano. A destra, «Da dove viene»: da quali tabelle del gestionale nasce e quando è stata caricata l'ultima volta. Sotto, le colonne, ognuna con il suo significato e il suo stato.
    
    ![La scheda della tavola «articolo»: come la legge l'assistente e da dove viene. Dati di prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-scheda-della-tavola-articolo-come-la-legge-lassistente-e-da-dove-viene-dati-di-prova.png)
    
    *La scheda della tavola «articolo»: come la legge l'assistente e da dove viene. Dati di prova*

<p class="callout info">**Nota.** Le altre linguette: **Da dove viene (ERP)** mostra le tabelle del gestionale e quanto se ne è capito; **Regole** le definizioni delle parole del lavoro; **Proposte** e **Rilasci** come cambia il catalogo.</p>

<p class="callout info">**Per chi sviluppa.** Lo Studio del catalogo è in `frontend/ade-next/src/studio/catalogo-semantico`; i dati arrivano da `/api/sigeagent/catalogo`, servito da `backend/middleware/sigeagent/src/sigeagent/catalogo_api.py`.</p>

<p class="callout info">**Per approfondire.**  
• Il disegno del catalogo: `backend/middleware/sigeagent/docs/DISEGNO_CATALOGO.md`</p>

# JJ3.2 - Correggere un significato

**In una frase.** Se una scheda dice una cosa sbagliata o poco chiara, la correggi sul posto: la correzione entra nel prossimo rilascio.

L'assistente risponde in base a quello che legge nelle schede. Una nota d'uso imprecisa diventa una risposta imprecisa, ogni volta. Correggerla una volta sistema tutte le domande che seguono.

1. **Scrivi il tuo nome in «Firmi come».** Resta scritto chi corregge.
2. **Apri la scheda e premi «Correggi».** Vale per la scheda di una tavola, per una colonna e per una regola. I testi diventano campi da modificare.
3. **Cambia il testo.** Sotto il campo vedi la differenza evidenziata: parola per parola, con barrato quello che togli. Così controlli la modifica prima di salvarla.
    
    ![«Correggi» aperto sulla scheda di una tavola: sotto il testo, la differenza evidenziata](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/correggi-aperto-sulla-scheda-di-una-tavola-sotto-il-testo-la-differenza-evidenziata.png)
    
    *«Correggi» aperto sulla scheda di una tavola: sotto il testo, la differenza evidenziata*
4. **Scegli come chiudere.**
    
    
    - **Salva**: la correzione è proposta e approvata nello stesso momento, con la tua firma.
    - **Chiedi a un collega**: crei solo la proposta. Serve scrivere il perché, in una riga. Decide un'altra persona.
    - **Annulla**: non cambia niente.
5. **Fai il rilascio.** Dopo «Salva» un avviso dice: «Entra nel prossimo rilascio: da lì l'agente la usa». Finché il rilascio non c'è, l'assistente continua a leggere il testo di prima. Vedi [Proposte e rilasci](https://gsdoc.genesyssoftware.eu/link/37902).

<p class="callout info">**Nota.** Correggere un testo non rende la scheda meno sicura: una scheda «verificata» resta verificata.</p>

<p class="callout warning">**Attenzione.** Cambiare il significato è una cosa. Cambiare **da dove nasce** un dato è un'altra: tocca la copia notturna e passa da chi sviluppa. Vedi [Chiedere un dato nuovo](https://gsdoc.genesyssoftware.eu/link/37901).</p>

<p class="callout info">**Per chi sviluppa.** Il componente è `frontend/ade-next/src/studio/catalogo-semantico/ui/correggi.component.ts`. «Salva» crea e decide la proposta in una sola transazione; le proposte sono gestite in `backend/middleware/sigeagent/catalogo`.</p>

# JJ3.3 - Chiedere un dato nuovo

**In una frase.** Se all'assistente manca un dato, lo chiedi dal catalogo con un percorso guidato: la richiesta diventa una proposta che qualcuno decide e chi sviluppa realizza.

L'assistente risponde solo su quello che ha. Quando una domanda utile resta senza risposta perché il dato non c'è, la strada non è una telefonata: è una richiesta scritta, con il perché, che non si perde.

1. **Premi «Chiedi un dato nuovo».** Il pulsante è in alto in ogni pagina del catalogo.
2. **Scegli cosa ti serve.** Le strade sono due:
    
    
    - **concetto nuovo**: una cosa che l'assistente oggi non conosce, cioè una tavola intera;
    - **dato in più**: una colonna in più su una tavola che ha già.
    
    Se non sai quale, parti dalla domanda a cui vuoi una risposta.
3. **Segui i passi.** Per un dato in più sono cinque: su quale concetto, cos'è, da dove viene nel gestionale, a cosa punta, perché serve. A destra il riquadro «La proposta finora» si riempie mentre scrivi.
    
    ![Il percorso «Chiedi un dato nuovo», al passo «Cos'è»: a destra la proposta che si riempie e le regole del catalogo](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-percorso-chiedi-un-dato-nuovo-al-passo-cose-a-destra-la-proposta-che-si-riempie-e-le-regole-del-catalogo.png)
    
    *Il percorso «Chiedi un dato nuovo», al passo «Cos'è»: a destra la proposta che si riempie e le regole del catalogo*
4. **Invia.** Nasce una proposta. La trovi nella pagina **Proposte**, fra quelle da decidere.
5. **Aspetta chi sviluppa.** Un dato nuovo cambia la struttura dei Dati spiegati. Dopo l'approvazione, chi sviluppa lo aggiunge alla copia notturna e ai suoi controlli. Solo allora entra in un rilascio e l'assistente lo usa.

<p class="callout info">**Nota.** Le regole del catalogo sono scritte nel riquadro a destra: il nome di una colonna non è una prova; decide una persona e resta scritto chi; nei Dati spiegati entra solo ciò che è verificato.</p>

<p class="callout info">**Nota.** Nel catalogo c'è anche la pagina **Assistente**: una chat che indaga sul catalogo e sui dati e prepara la proposta. La proposta la scrivi comunque tu, con **Procedi** e la tua firma. Senza la sua chiave la pagina dice «non configurato».</p>

<p class="callout info">**Per chi sviluppa.** Dalla proposta approvata, **Esporta l'incarico per chi sviluppa** scarica un file con il lavoro da fare: migrazione, passo della copia notturna con il suo controllo, test. A lavoro finito, in **Proposte** si preme **Segna applicata**. Il percorso è in `frontend/ade-next/src/studio/catalogo-semantico/proponi`.</p>

# JJ3.4 - Proposte e rilasci

**In una frase.** Nel catalogo niente cambia da solo: ogni modifica è una proposta, una persona la decide, un rilascio numerato la porta all'assistente.

È quello che rende affidabili le risposte. Sai sempre chi ha cambiato un significato, quando e perché. E sai con quale versione del catalogo l'assistente sta rispondendo.

<div drawio-diagram="2803"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/proposta-decisione-rilascio-la-strada-di-ogni-modifica-del-catalogo.png" alt="Proposta, decisione, rilascio: la strada di ogni modifica del catalogo"/></div>

*Proposta, decisione, rilascio: la strada di ogni modifica del catalogo*

1. **Guarda la linea delle proposte.** Nella pagina **Proposte** ogni proposta va da sinistra a destra: da decidere, approvate, in assestamento (quelle che aspettano chi sviluppa), nel rilascio. A parte, le chiuse: rifiutate o ritirate.
    
    ![La pagina «Proposte»: una proposta va da sinistra a destra e si ferma dove serve una persona](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-proposte-una-proposta-va-da-sinistra-a-destra-e-si-ferma-dove-serve-una-persona.png)
    
    *La pagina «Proposte»: una proposta va da sinistra a destra e si ferma dove serve una persona*
2. **Decidi una proposta.** Aprila. In alto c'è la domanda che ti viene fatta. Sotto, «Cosa cambia»: il testo di oggi e quello che avresti se approvi, uno accanto all'altro. Poi la prova e il perché. Premi **Approva**, oppure **Rifiuta** scrivendo il motivo. Chi l'ha proposta può anche ritirarla.
    
    ![Una proposta da decidere: la domanda, cosa cambia, la prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/una-proposta-da-decidere-la-domanda-cosa-cambia-la-prova.png)
    
    *Una proposta da decidere: la domanda, cosa cambia, la prova*
3. **Crea il rilascio.** Nella pagina **Rilasci** leggi in parole cosa conterrebbe il prossimo rilascio. Premi **Crea il rilascio** con il suo numero: da quel momento l'assistente lo usa.
    
    ![La pagina «Rilasci»: cosa conterrebbe il prossimo rilascio e il pulsante per crearlo](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-pagina-rilasci-cosa-conterrebbe-il-prossimo-rilascio-e-il-pulsante-per-crearlo.png)
    
    *La pagina «Rilasci»: cosa conterrebbe il prossimo rilascio e il pulsante per crearlo*
4. **Controlla la riga in alto.** In ogni pagina del catalogo dice «L'agente usa il rilascio» con numero e data. Un rilascio raccoglie più correzioni insieme.

<p class="callout info">**Nota.** L'intelligenza artificiale può preparare una proposta, ma non decide mai: decide una persona.</p>

<p class="callout info">**Per chi sviluppa.** Nella pagina **Rilasci**, la sezione chiusa «Per il low-code» pubblica un rilascio intero nel registro di ADEnext. Prima il rilascio va misurato sul banco: un insieme di domande con la risposta attesa già nota, in `backend/middleware/sigeagent/banco`. Si pubblica se il risultato non peggiora. Decisioni in `backend/middleware/sigeagent/docs/DECISIONI.md`.</p>

<p class="callout info">**Per approfondire.**  
• Il disegno del catalogo: `backend/middleware/sigeagent/docs/DISEGNO_CATALOGO.md`</p>