# JE2 - I dati

# JE2.1 - Il catalogo di record e campi

**In una frase.** Il catalogo è l'elenco di tutti gli archivi che il sistema conosce, con i loro campi: è da qui che form, tabelle ed endpoint prendono i nomi.

Tutto quello che disegni parte dai dati. Se ogni schermata si inventasse i nomi dei campi, due schermate sullo stesso archivio direbbero cose diverse. Il catalogo evita questo: un archivio (qui si chiama **record**) si descrive una volta, e tutti lo leggono da lì.

1. **Apri il catalogo.** Dal menu: **Strumenti di Sviluppo › Record &amp; Tabelle › Catalogo Record**. Ogni riga è un archivio: nome, tabella, quanti campi ha, a che punto è.
    
    ![Il Catalogo Record: 569 archivi, con la ricerca e i filtri su ogni colonna](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-catalogo-record-569-archivi-con-la-ricerca-e-i-filtri-su-ogni-colonna.png)
    
    *Il Catalogo Record: 569 archivi, con la ricerca e i filtri su ogni colonna*
2. **Cerca.** Scrivi nella casella **Cerca** o usa il filtro sull'intestazione di una colonna. La ricerca guarda tutto il catalogo, non solo la pagina che hai davanti. Il numero in alto dice quanti ne hai trovati.
3. **Apri un record.** Doppio clic sulla riga. In alto i dati dell'archivio, sotto le schede: **Campi**, **Chiavi**, **Relazioni**.
    
    ![Un record aperto: i suoi campi, con nome, tipo e lunghezza](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/un-record-aperto-i-suoi-campi-con-nome-tipo-e-lunghezza.png)
    
    *Un record aperto: i suoi campi, con nome, tipo e lunghezza*
4. **Guarda le relazioni.** La scheda **Relazioni** dice a quali altri archivi è collegato questo. Sono queste a permettere, più avanti, di aprire le righe di un ordine dalla sua testata, o di mostrare la descrizione accanto a un codice.

Il **Catalogo Campi**, nella stessa voce di menu, fa la stessa cosa al contrario: parte da un campo e ti dice in quali archivi compare.

<p class="callout success">**Cosa ci guadagni.** Un campo ha un nome solo in tutto il sistema. Quando disegni non lo scrivi: lo scegli da un elenco, e non puoi sbagliarlo.</p>

<p class="callout info">**Per chi sviluppa.** Il catalogo è il registro dei dati di ADEnext. Si riempie importando la struttura dal database o dai tracciati dell'ERP legacy/COBOL. Le scritture disegnate sono ammesse solo sugli archivi che sono nel registro.</p>

<p class="callout info">**Per approfondire.**  
• Catalogo record e campi — guida passo passo: `docs/guide/dati/catalogo-record/README.md`</p>

# JE2.2 - Elenchi chiusi

**In una frase.** Un elenco chiuso è un insieme di valori ammessi, come gli stati di un ordine: lo scrivi una volta e lo usano tendine, tabelle, filtri e controlli.

Senza un elenco in comune, gli stessi tre stati finiscono ricopiati in ogni campo che li usa, e prima o poi le copie non sono più uguali. Con l'elenco chiuso c'è un posto solo. E il sistema può controllare che il valore scritto sia uno di quelli ammessi.

1. **Apri la pagina.** Dal menu: **Strumenti di Sviluppo › Record &amp; Tabelle › Elenchi chiusi**. Con il **+** crei un elenco nuovo.
2. **Scrivi i valori.** Ogni valore ha un **codice** e un'**etichetta**. Il codice è quello che resta scritto nei dati. L'etichetta è quello che legge la persona.
    
    ![Un elenco salvato: tre stati, ciascuno con codice, etichetta e ordine. Elenco di prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/un-elenco-salvato-tre-stati-ciascuno-con-codice-etichetta-e-ordine-elenco-di-prova.png)
    
    *Un elenco salvato: tre stati, ciascuno con codice, etichetta e ordine. Elenco di prova*
3. **Oppure incollali.** Se l'elenco esiste già in un foglio di calcolo, premi **Incolla da un foglio**: una riga per valore, codice ed etichetta. Per gli elenchi lunghi c'è **Carica un foglio**.
    
    ![Incolla da un foglio: una riga per valore, il codice e poi l'etichetta](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/incolla-da-un-foglio-una-riga-per-valore-il-codice-e-poi-letichetta.png)
    
    *Incolla da un foglio: una riga per valore, il codice e poi l'etichetta*
4. **Salva.** Da questo momento il codice è bloccato: cambiarlo lascerebbe senza etichetta i dati già scritti. L'etichetta si può cambiare quando vuoi.

<p class="callout info">**Nota.** Un valore non si cancella, si **disattiva**. Non si può più scegliere, ma i dati di ieri che lo contengono continuano a mostrare la sua etichetta.</p>

<p class="callout success">**Cosa ci guadagni.** Un valore fuori elenco viene rifiutato, anche se arriva da un altro programma e non dalla pagina. Un campo lasciato vuoto non è un errore: quello lo decide la regola «obbligatorio».</p>

<p class="callout info">**Per chi sviluppa.** Nelle regole di un form il controllo è di tipo `staticEntity`, con il nome dell'elenco. Gli strumenti sono in `frontend/ade-next/src/studio/static-entity`.</p>

<p class="callout info">**Per approfondire.**  
• Elenchi chiusi (static entity): `docs/guide/dati/elenchi-chiusi/README.md`</p>

# JE2.3 - Regole di cancellazione

**In una frase.** Per ogni collegamento fra due archivi decidi cosa succede alle righe collegate quando cancelli quella da cui dipendono.

Pensa a un ordine con le sue righe. Se cancelli l'ordine e nessuno si occupa delle righe, restano lì a puntare a un ordine che non esiste più. Nessun errore, nessun avviso: lo si scopre mesi dopo. La regola di cancellazione serve a deciderlo prima.

1. **Apri il record.** Dal **Catalogo Record**, doppio clic sull'archivio, poi scheda **Relazioni**.
2. **Scegli la regola.** Nella colonna **Se cancello il padre** ogni collegamento ha una tendina con tre risposte.
    
    ![La scheda Relazioni: per ogni collegamento, la tendina «Se cancello il padre»](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-scheda-relazioni-per-ogni-collegamento-la-tendina-se-cancello-il-padre.png)
    
    *La scheda Relazioni: per ogni collegamento, la tendina «Se cancello il padre»*
3. **Leggi cosa fanno.**
    
    
    - **Niente (come oggi)**: non cambia nulla. È la scelta di partenza, così nessuna cancellazione che già esiste cambia comportamento.
    - **Impedisci**: se ci sono righe collegate, la cancellazione non parte, e ti dice quante sono.
    - **Cancella anche loro**: le righe collegate vengono cancellate insieme. O spariscono tutte, o non sparisce niente.

La scelta si salva subito. Se il salvataggio non riesce, la tendina torna al valore di prima.

<p class="callout success">**Cosa ci guadagni.** La regola vale ovunque: da una pagina, da un flusso, da un altro programma. L'anteprima di una cancellazione mostra anche quello che la regola aggiunge.</p>

<p class="callout warning">**Attenzione.** Le regole si applicano alle cancellazioni disegnate. Hanno i loro test, ma non sono ancora state usate su dati veri: accendile una relazione per volta, e prova prima sull'ambiente di prova.</p>

<p class="callout info">**Per chi sviluppa.** Nel database i tre valori sono `IGNORE`, `PROTECT`, `DELETE`, sulla relazione del record.</p>

<p class="callout info">**Per approfondire.**  
• Regole di cancellazione: `docs/guide/dati/regole-cancellazione/README.md`</p>

# JE2.4 - Valori dell'installazione

**In una frase.** Qui stanno i valori che cambiano da un'installazione all'altra, come la mail dell'assistenza, e i contatori che danno il numero ai documenti.

Certe cose non sono né dati né programma: l'indirizzo a cui scrivono gli utenti, la soglia oltre cui un ordine va approvato. Se finiscono scritte dentro una schermata, per cambiarle bisogna cercarle una per una. Qui hanno un posto solo, e ogni installazione ha i suoi.

1. **Apri la pagina.** Dal menu: **Strumenti di Sviluppo › Record &amp; Tabelle › Valori installazione**. Ci sono due schede: **Proprietà** e **Numerazioni**.
2. **Aggiungi una proprietà.** Una chiave, un valore, una descrizione. Nei flussi la leggi con il suo nome.
    
    ![Una proprietà nuova: chiave, valore e a cosa serve. Dati di prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/una-proprieta-nuova-chiave-valore-e-a-cosa-serve-dati-di-prova.png)
    
    *Una proprietà nuova: chiave, valore e a cosa serve. Dati di prova*
3. **Se è una password, spunta Segreta.** Da quel momento il valore si può scrivere ma non rileggere: l'elenco dice solo se è impostato. Salvare la descrizione senza riscrivere il valore non lo cancella.
4. **Aggiungi una numerazione.** Un nome e un formato. Nel formato `%y` è l'anno e `%06s` è il contatore su sei cifre: `FT-%y-%06s` dà `FT-2026-000001`.
    
    ![Una numerazione nuova: il formato decide come esce il numero](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/una-numerazione-nuova-il-formato-decide-come-esce-il-numero.png)
    
    *Una numerazione nuova: il formato decide come esce il numero*

<p class="callout success">**Cosa ci guadagni.** Due persone che salvano nello stesso istante non ricevono mai lo stesso numero. Con il vecchio «prendo l'ultimo e aggiungo uno» poteva succedere.</p>

<p class="callout warning">**Attenzione.** Un numero preso è preso, anche se poi il documento non viene salvato: la numerazione può avere buchi. Il contatore non si riporta indietro.</p>

<p class="callout info">**Per chi sviluppa.** In un flusso una proprietà si legge come `{{$site.chiave}}`, una volta per esecuzione. Gli strumenti sono in `frontend/ade-next/src/studio/site-property`.</p>

<p class="callout info">**Per approfondire.**  
• Valori dell'installazione e numerazioni: `docs/guide/dati/valori-installazione/README.md`</p>