JL - Archivi
Dove restano scritti i dati e chi li usa.
Cosa ci guadagni. Si sa sempre dov'è un dato e chi lo può cambiare.
- JL1 - A cosa servono
- JL2 - Uno per uno
- JL2.1 - Dati aziendali (SIGEA2)
- JL2.2 - Schermate salvate (ADENEXT2)
- JL2.3 - Modelli di stampa (GPENEXT2)
- JL2.4 - Dati spiegati (DB semantico)
- JL3 - Regole
JL1 - A cosa servono
JL1.1 - Quattro archivi, quattro compiti
In una frase. ADSWnext tiene i dati in quattro archivi separati: ognuno conserva una cosa sola e ha un servizio che se ne occupa.
Un archivio è il posto dove i dati restano scritti quando spegni il computer. In ADSWnext non ce n'è uno solo dove finisce tutto. Ce ne sono quattro, e ognuno ha un compito preciso. Così, quando cerchi una cosa, sai già dove sta.
- Dati aziendali. I dati veri dell'azienda: clienti, fornitori, ordini, magazzino. Li usa SIGEAnext e li usa l'ERP legacy/COBOL. Sono gli stessi dati, non due copie.
- Schermate salvate. Come sono fatte le schermate disegnate con ADEnext, i cruscotti di Analytics e i ruoli. Qui non c'è nemmeno una fattura: c'è il disegno della pagina che la mostra.
- Modelli di stampa. I modelli dei documenti di GPEnext, le ditte e i loro loghi.
- Dati spiegati. Una copia riordinata dei dati aziendali, con nomi chiari, rifatta ogni notte. Serve solo all'Assistente dei dati.
Quattro archivi, quattro compiti: ogni archivio ha il servizio che lo usa
Cosa ci guadagni.
• Sai sempre dov'è un dato e chi lo può cambiare. Un ordine sta nei Dati aziendali. Il disegno di una schermata sta nelle Schermate salvate. Un modello di fattura sta nei Modelli di stampa. Ogni archivio lo scrive solo il suo servizio.
• ERP nuovo e legacy lavorano sugli stessi dati. Un ordine inserito da una maschera storica si vede nella pagina nuova, e viceversa. Non c'è una copia da allineare e non c'è un passaggio di dati da fare prima di cominciare.
• I dati per l'intelligenza artificiale sono separati da quelli veri. L'Assistente dei dati legge solo la copia notturna, e non la può modificare. Qualunque domanda tu faccia, i dati dell'azienda non cambiano.
Questo libro presenta gli archivi uno per uno, poi le regole: chi legge, chi scrive, e come si aggiorna la struttura di un archivio quando esce una versione nuova.
Per chi sviluppa.
• I nomi tecnici sono SIGEA2, ADENEXT2, GPENEXT2 e il DB semantico (sigeagent).
• SIGEA2 sta su Oracle o su MySQL, secondo l'installazione. Gli altri tre sono MySQL.
• Ogni servizio ha le sue variabili di collegamento: SIGEA_DB_*, ADE_DB_*, GPE_DB_*, SIGEAGENT_DB_*. Il registro è docs/devops/ENVIRONMENT.md.
JL1.2 - Dove stanno nella mappa
In una frase. Gli Archivi sono lo strato più in basso della mappa: sotto i servizi, lontano dal browser.
La posizione dice già la regola più importante. Dal browser non si arriva mai a un archivio. In mezzo ci sono sempre il Gateway, che controlla chi sei, e un servizio, che decide cosa puoi leggere e cosa puoi cambiare.
La mappa di ADSWnext con accesi i quattro archivi
Chi usa gli archivi. Ogni archivio ha sopra di sé il suo servizio. GPEnext usa i Modelli di stampa. ADEnext e Analytics usano le Schermate salvate. SIGEAnext usa i Dati aziendali. L'Assistente dei dati usa i Dati spiegati.
L'archivio con due ingressi. Ai Dati aziendali arriva anche una freccia dal Gestionale storico: l'ERP legacy/COBOL legge e scrive lì, come ha sempre fatto. È l'unico archivio usato da due programmi.
La freccia lunga in basso. Va dai Dati aziendali ai Dati spiegati. È la copia notturna: ogni notte i dati vengono letti, riordinati e scritti con nomi chiari per l'assistente. Va in una direzione sola.
Cosa vuol dire per te. Tu lavori sempre da una pagina. La pagina chiede al servizio, il servizio parla con il suo archivio. Nessuno apre un archivio direttamente per lavorare.
Per chi sviluppa.
• Tessere della mappa: gpedb, adedb, sigeadb, agentdb.
• Le schermate disegnate con ADEnext mostrano dati aziendali, ma non li leggono da sole: li chiedono a SIGEAnext (docs/low-code/entita-runtime.md).
• I Dati spiegati stanno su un MySQL a parte, che parte insieme all'Assistente dei dati e non pubblica porte all'esterno.
JL2 - Uno per uno
JL2.1 - Dati aziendali (SIGEA2)
In una frase. I Dati aziendali sono l'archivio dei dati veri dell'azienda: lo usano insieme SIGEAnext e l'ERP legacy/COBOL.
È l'archivio che esisteva già prima di ADSWnext, ed è rimasto dov'era. Le pagine nuove sono state costruite sopra gli stessi dati del gestionale di sempre. Per questo si può passare al nuovo una funzione alla volta, senza fermare il lavoro.
Cosa c'è dentro. Clienti, fornitori, articoli, ordini, movimenti di magazzino, mezzi. Le tabelle hanno i nomi brevi, in sigla, che hanno sempre avuto: chi conosce il gestionale li riconosce.
Chi lo usa. SIGEAnext legge e scrive: quando salvi da una pagina nuova, il dato finisce qui. L'ERP legacy/COBOL legge e scrive, come sempre. La copia notturna per l'Assistente dei dati legge soltanto.
Un esempio. Un collega inserisce un ordine da una maschera storica. Tu apri la pagina nuova degli ordini e lo trovi. Non c'è stato nessun passaggio di dati: avete guardato lo stesso archivio.
Cosa non c'è dentro. Il disegno delle schermate, i cruscotti, i modelli di stampa. Stanno negli altri archivi, così i dati dell'azienda restano solo dati dell'azienda.
La struttura non la tocca SIGEAnext. SIGEAnext non crea tabelle e non le modifica quando si accende. La forma dell'archivio resta quella del gestionale.
Attenzione. Questi sono i dati veri. Una prova fatta collegandosi all'archivio sbagliato scrive dati veri. Per questo SIGEAnext non parte se non gli si dice in modo esplicito a quale archivio collegarsi.
Per chi sviluppa.
• Motore: Oracle o MySQL, si sceglie all'installazione (profili oracle e mysql di backend/business-logic/it_gsba_sigea_next).
• Tutti e due i profili hanno ddl-auto=none e il servizio non ha migrazioni.
• Collegamento: SIGEA_DB_URL, SIGEA_DB_USER, SIGEA_DB_PASSWORD, senza valore predefinito.
• Lo stesso archivio visto da SIGEAnext: libro JD - SIGEAnext, pagina «JD5.2 - I dati: SIGEA2».
JL2.2 - Schermate salvate (ADENEXT2)
In una frase. Le Schermate salvate sono l'archivio di ADEnext: conserva come sono fatte le schermate disegnate, i cruscotti di Analytics e i ruoli.
Con ADEnext una schermata non si programma: si disegna. Il disegno deve restare scritto da qualche parte, altrimenti al riavvio sarebbe perso. Sta qui. Quando apri una pagina disegnata, ADEnext legge il disegno da questo archivio e la pagina si compone.
Cosa c'è dentro.
- I disegni: moduli, tabelle, grafici, viste, e le loro versioni.
- I flussi e i punti di accesso ai dati, disegnati senza scrivere programmi.
- I cruscotti di Analytics e l'elenco delle sorgenti che si possono analizzare.
- I ruoli di ADEnext: quale ruolo dà quale livello.
- Il registro dei dati: la descrizione delle tabelle del gestionale, con nomi e significati dei campi.
Cosa non c'è dentro. I dati dell'azienda. Qui c'è scritto che la tabella degli ordini ha una colonna «Cliente» larga così. Gli ordini stanno nei Dati aziendali.
Chi lo usa. Solo ADEnext, con Analytics che ne fa parte. Legge e scrive.
Cosa ci guadagni. Una schermata disegnata oggi vale per tutti, perché tutti leggono lo stesso disegno. E i disegni hanno un posto loro: si possono salvare e ripristinare senza toccare i dati dell'azienda.
La struttura si aggiorna da sola. Quando esce una versione nuova di ADEnext, è il servizio che adegua l'archivio mentre si accende. Vedi Aggiornamenti dello schema.
Per chi sviluppa.
• Schema MySQL ADENEXT2. Collegamento: ADE_DB_URL, ADE_DB_USER, ADE_DB_PASSWORD.
• Tabelle principali: dynamic_form, dynamic_table, dynamic_chart, view, low_code_endpoint, low_code_flow, analysis_source, ruoli, ade_record.
• Migrazioni in backend/middleware/it_gsba_ade_next/src/main/resources/db/migration.
JL2.3 - Modelli di stampa (GPENEXT2)
In una frase. I Modelli di stampa sono l'archivio di GPEnext: conserva i modelli dei documenti, le ditte e i loro loghi.
Una fattura stampata è fatta di due cose: i dati di quella fattura e il modello che dice dove vanno, con quale carattere, con quale logo. I dati arrivano al momento della stampa. Il modello sta qui, pronto per la prossima.
Cosa c'è dentro.
- I modelli dei documenti e le loro versioni di base.
- Le ditte, ognuna con il suo logo.
- Le immagini caricate: loghi e figure usate nei modelli.
- I profili di stampa attivi e i ruoli di GPEnext.
- I dati dell'installazione: nome dell'azienda e logo predefinito.
Cosa non c'è dentro. I dati dell'azienda. GPEnext non ha un collegamento ai Dati aziendali: riceve i dati da stampare insieme alla richiesta e compone il documento.
Chi lo usa. Solo GPEnext. Legge e scrive. Quando cambi un modello o carichi un logo, la modifica finisce qui.
Cosa ci guadagni. Il logo di una ditta si carica una volta e sta in un posto solo. E i modelli hanno un archivio loro: si possono salvare e ripristinare senza muovere i dati dell'azienda.
La struttura si aggiorna da sola. Come per ADEnext, è GPEnext che adegua l'archivio quando si accende con una versione nuova. Al primo avvio le tabelle le crea lui: chi installa prepara solo l'archivio vuoto.
Per chi sviluppa.
• Schema MySQL GPENEXT2. Collegamento: GPE_DB_URL, GPE_DB_USER, GPE_DB_PASSWORD. Sul server, senza queste il servizio non parte.
• Tabelle principali: templates, template_base_versions, ditte, images, installation, ruoli.
• Migrazioni in backend/middleware/it_gsba_gpe_next/src/main/resources/db/migration-mysql.
• Come si usano modelli e loghi: libro JK - GPEnext.
JL2.4 - Dati spiegati (DB semantico)
In una frase. I Dati spiegati sono una copia dei dati aziendali con nomi chiari, rifatta ogni notte: è l'unico archivio che l'Assistente dei dati legge.
Le tabelle del gestionale hanno nomi in sigla e regole che conosce solo chi ci lavora da anni. Un'intelligenza artificiale che le leggesse così sbaglierebbe senza accorgersene. E non è prudente lasciarla lavorare sui dati veri. La soluzione è una copia fatta apposta: ordinata, con nomi in italiano, e separata.
La copia notturna, passo per passo, e la domanda del giorno dopo
Cosa c'è dentro. Tavole con nomi che si capiscono: articolo, fornitore, giacenza_giornaliera. Insieme ai dati c'è scritto cosa vuol dire ogni colonna, e fino a che data ogni tavola è caricata.
Come si riempie. Ogni notte una copia automatica legge i Dati aziendali, senza scrivere niente. Tiene solo le righe che servono, dà i nomi chiari e scrive il risultato qui. Se non si sceglie un altro orario, parte alle 02:30.
Chi lo usa. La copia notturna scrive. L'Assistente dei dati legge soltanto: non ha il permesso di modificare niente, nemmeno questa copia.
Cosa ci guadagni. L'assistente non tocca mai i dati veri. E se la copia si rovina, si rifà dai Dati aziendali: non contiene niente che non si possa ricostruire.
Nota. I dati sono quelli della notte prima. Per sapere com'è una cosa «adesso» vale la schermata del gestionale.
Nota. L'Assistente dei dati si accende a parte, installazione per installazione. Dove è spento, questo archivio non c'è.
Per chi sviluppa.
• MySQL proprio dell'assistente, schema sigeagent. Tre utenti distinti: uno di sola lettura per l'assistente, uno per la copia, uno per il catalogo.
• La copia è backend/middleware/sigeagent/etl. Legge SIGEA2 con la connessione di SIGEAnext, in transazioni di sola lettura. Orario: SIGEAGENT_ETL_ORA_NOTTURNA.
• Accanto c'è lo schema sigeagent_catalogo: contiene lavoro fatto dalle persone e va salvato, perché la copia notturna non lo ricostruisce.
• Come ragiona l'assistente: libro JJ - Strato agentico.
Per approfondire.
• Lo schema dei Dati spiegati: backend/middleware/sigeagent/docs/SCHEMA.md
JL3 - Regole
JL3.1 - Chi legge e chi scrive
In una frase. Ogni archivio ha un solo servizio che lo scrive; l'unica eccezione, voluta, sono i Dati aziendali, scritti da SIGEAnext e dall'ERP legacy/COBOL.
Quando un dato è sbagliato, la prima domanda è: chi lo ha scritto? Se ogni archivio ha un solo padrone, la risposta è breve. È la regola che tiene in ordine tutto il resto.
Chi legge e chi scrive ciascun archivio
| Archivio | Chi scrive | Chi legge soltanto |
|---|---|---|
| Dati aziendali | SIGEAnext, ERP legacy/COBOL | La copia notturna |
| Schermate salvate | ADEnext, con Analytics | Nessuno |
| Modelli di stampa | GPEnext | Nessuno |
| Dati spiegati | La copia notturna | L'Assistente dei dati |
Dati aziendali: due programmi, apposta. SIGEAnext e l'ERP legacy/COBOL scrivono le stesse tabelle. È ciò che permette di usare insieme pagine nuove e maschere storiche. Non ci sono due copie da tenere allineate.
Schermate salvate e Modelli di stampa: un padrone ciascuno. Se un cruscotto è cambiato, è passato da ADEnext. Se un modello è cambiato, è passato da GPEnext.
Dati spiegati: si scrive di notte, si legge di giorno. Li riempie solo la copia notturna. L'Assistente dei dati ha un permesso di sola lettura: anche volendo, non può modificare niente.
Le schermate disegnate e i dati aziendali. Una schermata disegnata con ADEnext mostra clienti e ordini, ma ADEnext non li va a prendere da solo. Li chiede a SIGEAnext, che li legge dai Dati aziendali e glieli passa.
E tu? Tu non scrivi mai in un archivio. Premi Salva su una pagina: la pagina chiede al servizio, il servizio controlla il tuo livello e scrive. I livelli sono spiegati nel libro JB - Accesso e permessi.
Per chi sviluppa.
• L'assistente si collega con un utente di database suo, che ha solo il permesso di lettura. La copia notturna apre su SIGEA2 solo transazioni di sola lettura.
• In produzione, per la copia notturna va usato un utente di sola lettura anche sui Dati aziendali: lo chiede devops/deploy/README.md.
• Solo chi disegna, nello Studio di ADEnext, può far leggere la struttura di un archivio (tabelle e colonne) per descriverla nel registro dei dati. ADE_DB_HOST_AMMESSI limita a quali archivi.
• GPEnext non ha variabili di collegamento a SIGEA2: riceve i dati da stampare con la richiesta.
JL3.2 - Aggiornamenti dello schema
In una frase. Quando esce una versione nuova, ADEnext e GPEnext adeguano da soli il proprio archivio mentre si accendono; i Dati aziendali, invece, SIGEAnext non li modifica mai.
Lo «schema» è la forma di un archivio: quali tabelle ha, quali colonne. Una funzione nuova spesso ne chiede una in più. Se qualcuno dovesse aggiungerla a mano su ogni server, prima o poi un server resterebbe indietro. Per questo l'aggiornamento viaggia insieme al programma.
Come funziona. Ogni modifica alla forma dell'archivio è un piccolo file numerato, chiamato migrazione. Il servizio li porta con sé. Quando si accende, guarda nell'archivio quali sono già state applicate e applica solo quelle che mancano, in ordine. Poi comincia a rispondere.
ADEnext si accende, vede che manca una modifica e la applica
Schermate salvate. Le aggiorna ADEnext all'avvio. Oggi le migrazioni sono una settantina: ognuna è un passo nella crescita del motore.
Modelli di stampa. Li aggiorna GPEnext all'avvio. Al primo avvio su un archivio vuoto crea tutte le tabelle.
Dati aziendali. Qui la regola è opposta. SIGEAnext non crea e non modifica tabelle: la forma dell'archivio resta quella del gestionale.
Dati spiegati. Non si aggiornano da soli all'avvio. Le tavole si creano una volta, con un comando. Le modifiche successive le applica chi gestisce il server, una alla volta, quando l'aggiornamento lo chiede.
Cosa ci guadagni. Dopo un aggiornamento di ADEnext o GPEnext non c'è niente da ricordare: programma e archivio sono alla stessa versione. E i dati dell'azienda non cambiano forma perché è uscita una pagina nuova.
Attenzione. Una migrazione già applicata non si corregge: se ne aggiunge una nuova. Un archivio che l'ha già eseguita non la esegue una seconda volta.
Per chi sviluppa.
• Lo strumento è Flyway. Cartelle: backend/middleware/it_gsba_ade_next/src/main/resources/db/migration e backend/middleware/it_gsba_gpe_next/src/main/resources/db/migration-mysql.
• ADEnext fa repair() prima di migrate() a ogni avvio, con la validazione accesa (ADE_FLYWAY_VALIDATE_ON_MIGRATE).
• SIGEAnext: ddl-auto=none, nessuna migrazione.
• Dati spiegati: file numerati in backend/middleware/sigeagent/sql, passi in devops/deploy/README.md.
• In questo repository una migrazione si crea o si modifica solo con il permesso esplicito di chi lavora.
JL3.3 - Se qualcosa non va
In una frase. I problemi più comuni con gli archivi, come «vedo questo, faccio questo», e le parole da sapere.
Quasi sempre il problema non è l'archivio: è il servizio che non riesce a raggiungerlo. Sapere quale archivio serve a cosa aiuta a capire subito a chi chiedere.
Per chi usa il gestionale
- Ho salvato da una maschera storica e nella pagina nuova non lo vedo. I dati sono gli stessi. Aggiorna la pagina: stai guardando un elenco caricato prima.
- L'Assistente dei dati non sa di un ordine inserito stamattina. È normale: legge la copia della notte prima. Per l'«adesso» apri la schermata del gestionale.
- L'assistente dichiara dati vecchi di più giorni. La copia notturna non è andata a buon fine. Avvisa chi gestisce il server.
- Una schermata disegnata non si apre, le altre pagine sì. È fermo ADEnext, o non raggiunge le Schermate salvate. I dati dell'azienda non c'entrano.
- La stampa esce senza logo. Il logo sta nei Modelli di stampa, legato alla ditta. Controlla la ditta in GPEnext: vedi il libro JK - GPEnext.
Per chi gestisce il server
- Un servizio non parte dopo un aggiornamento. Guarda il suo registro: se una migrazione è fallita, lo dice lì, con il numero.
- GPEnext si riavvia di continuo. Manca il collegamento al suo archivio. Il resto di ADSWnext lavora lo stesso.
- SIGEAnext non parte. Controlla che gli sia stato detto a quale archivio collegarsi: non ha un valore predefinito, apposta.
- La copia notturna segna un gruppo di dati come «saltato». In quei Dati aziendali mancano le tabelle di partenza. Gli altri gruppi sono caricati.
- Devo ripristinare i Dati spiegati. Non serve un salvataggio: si rifanno lanciando la copia. Il catalogo dell'assistente invece va salvato.
Parole da sapere
- Archivio. Il posto dove i dati restano scritti. Qui sono quattro.
- Dati aziendali. I dati veri dell'azienda, usati da SIGEAnext e dall'ERP legacy/COBOL.
- Schermate salvate. I disegni di ADEnext, i cruscotti di Analytics, i ruoli.
- Modelli di stampa. Modelli dei documenti, ditte e loghi di GPEnext.
- Dati spiegati. La copia notturna con nomi chiari, per l'Assistente dei dati.
- Schema. La forma di un archivio: tabelle e colonne.
- Migrazione. Un file numerato che cambia lo schema. Il servizio la applica quando si accende.
- Copia notturna. Il lavoro automatico che ogni notte riempie i Dati spiegati.
- Sola lettura. Il permesso di guardare senza poter cambiare.
Per chi sviluppa. Variabili di collegamento e orari: docs/devops/ENVIRONMENT.md. Preparare gli archivi su un server, salvataggio e ripristino del catalogo: devops/deploy/README.md.