421 lines
27 KiB
Markdown
421 lines
27 KiB
Markdown
# Inventario delle funzionalità legacy di gestione metadati di ThothAI
|
||
|
||
Data dell'inventario: 2026-08-23
|
||
|
||
Ultima verifica rispetto a ThothII: 2026-08-31
|
||
|
||
Stato: **inventario storico verificato; non è una specifica dello stato corrente**.
|
||
|
||
Issue originaria: [mptyl/ThothII#6](https://git.tylconsulting.it/mptyl/ThothII/issues/6)
|
||
|
||
Fonte primaria: repository legacy annidato `Thoth/ThothAI`, commit
|
||
`55855de0f18e5cb4bc72f0a2ab0a7317995186dd`.
|
||
|
||
Le citazioni che iniziano con `/Thoth/ThothAI/` sono relative alla radice di quella copia legacy
|
||
fissata al commit indicato. Alla verifica del 2026-08-31 tutti i 68 riferimenti univoci puntavano a
|
||
file esistenti e a intervalli di righe validi.
|
||
|
||
> Questo documento conserva l'inventario e le evidenze degli anti-pattern di ThothAI. Le frasi di
|
||
> requisito nelle sezioni successive descrivono la baseline proposta il 2026-08-23; non prevalgono
|
||
> su ADR, contratti, codice o `PROJECT_STATE.md` correnti.
|
||
|
||
## Stato rispetto al codice corrente
|
||
|
||
### Fonti autorevoli correnti
|
||
|
||
Per capire cosa esiste oggi, usare nell'ordine:
|
||
|
||
- `PROJECT_STATE.md`, per lo snapshot operativo aggiornato;
|
||
- `CONTEXT.md`, per il modello di dominio corrente;
|
||
- il [piano accettato del Metadata Catalog](../plans/2026-08-26-metadata-catalog-from-thothai.md)
|
||
e il [contratto dello schema snapshot](../contracts/catalog-schema-snapshot.md);
|
||
- gli ADR del catalogo, in particolare
|
||
[0001](../adr/0001-postgres-metadata-catalog.md),
|
||
[0004](../adr/0004-fastify-kysely-metadata-catalog.md),
|
||
[0006](../adr/0006-separate-physical-and-logical-relationships.md),
|
||
[0007](../adr/0007-durable-authoritative-schema-synchronization.md),
|
||
[0008](../adr/0008-allow-manual-catalog-metadata-cleanup.md),
|
||
[0009](../adr/0009-use-one-sequential-description-generation-run.md),
|
||
[0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e
|
||
[0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md);
|
||
- l'implementazione, soprattutto `backend/src/catalog/types.ts`,
|
||
`backend/src/routes/catalog-databases.ts`, `backend/src/routes/catalog-schema.ts`,
|
||
`backend/src/routes/catalog-description-generation.ts`,
|
||
`backend/src/routes/catalog-description-consolidation.ts` e
|
||
`frontend/src/shell/DatabaseManagementPage.tsx`.
|
||
|
||
### Disposizione della baseline storica
|
||
|
||
| Capacità inventariata | Disposizione al 2026-08-31 | Evidenza corrente o nota |
|
||
|---|---|---|
|
||
| Configurazione per workspace, secret separati e test connessione | **Adottata e implementata** | PostgreSQL interno, binding `postgres_direct`, `rest_api` o `ssh_tunnel`, secret write-only; ADR [0001](../adr/0001-postgres-metadata-catalog.md)–[0004](../adr/0004-fastify-kysely-metadata-catalog.md) e `backend/src/routes/catalog-databases.ts`. |
|
||
| Inventario fisico di tabelle, colonne, PK e FK | **Adottato e implementato** | La struttura osservata è distinta dai contenuti curati; `backend/src/catalog/types.ts`, `backend/src/routes/catalog-schema.ts` e ADR [0006](../adr/0006-separate-physical-and-logical-relationships.md). |
|
||
| Riconciliazione completa e osservabile dello schema | **Implementata; semantica storica parzialmente superata** | I durable Catalog Sync Runs sono autoritativi, fail-closed, atomici e richiedono conferma per diff distruttivi. Non esiste il lifecycle `drift/removed` proposto qui: la sincronizzazione riconcilia la membership e ADR [0008](../adr/0008-allow-manual-catalog-metadata-cleanup.md) consente anche cleanup manuale esplicito, superando ADR-0005. |
|
||
| Descrizione curata e Generated Description separate | **Adottata e implementata** | Tabelle e colonne espongono entrambi i campi in `backend/src/catalog/types.ts`; la copia selettiva AI → curato è in `backend/src/routes/catalog-description-consolidation.ts`. |
|
||
| Generazione AI selettiva con run, stato e log | **Adottata e implementata** | Un run asincrono installazione-wide, sequenziale, con eventi persistiti e senza resume automatico; ADR [0009](../adr/0009-use-one-sequential-description-generation-run.md) e `backend/src/routes/catalog-description-generation.ts`. I thread daemon legacy sono **esclusi**. |
|
||
| Campioni reali per la generazione e protezione dei campi sensibili | **Implementata come estensione correttiva** | ADR [0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e [0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md): campioni bounded per colonne non sensibili e valori sintetici deterministici per quelle sensibili. |
|
||
| Proposte persistenti, diff e versioni dei testi AI | **Escluse** | Resta un solo Generated Description modificabile. La cronologia dei run è operativa: non conserva prompt, output grezzo, proposta per colonna o audit della decisione umana. |
|
||
| Relazioni fisiche | **Adottate e implementate** | Sono constraint immutabili con coppie ordinate di colonne; ADR [0006](../adr/0006-separate-physical-and-logical-relationships.md). |
|
||
| Relazioni logiche curate o inferite | **Differite/aperto** | ADR-0006 riserva un modello e un lifecycle separati; non sono ancora parte del catalogo corrente. |
|
||
| Alias semantici, descrizioni dei valori, sinonimi e concetti | **Differiti/aperti** | `PROJECT_STATE.md` li assegna a slice dedicate; non vanno dedotti dai campi fisici già implementati. |
|
||
| Scope AI, ERD Mermaid e documentazione aggregata | **Differiti/aperti** | Restano capacità legacy inventariate, non una feature corrente del Metadata Catalog. Un eventuale lavoro dovrà avere contratto e gate propri. |
|
||
| Export CSV e script SQL dei commenti | **Differiti/aperti; varianti insicure escluse** | Non risultano nella API corrente. Export di segreti, CSV incoerenti e SQL ricostruito da tipi incompleti restano vietati dagli anti-pattern sotto. |
|
||
| Inferenza euristica e validazione di relazioni candidate | **Differita/aperta** | Non va confusa con la sincronizzazione delle FK fisiche; dipende dal futuro lifecycle delle relazioni logiche. |
|
||
| Pubblicazione del catalogo al core/schema-linking/Qdrant | **Differita e richiesta come design gate successivo** | Il runtime NL→SQL continua a usare configurazione e annotations del workspace; il cutover è esplicitamente rinviato in `PROJECT_STATE.md`. |
|
||
| Sette motori database del legacy | **Baseline superata** | La prima versione corrente supporta PostgreSQL; l'aggiunta di altri dialetti è una decisione futura, non parità automatica. |
|
||
| GDPR e import da installazioni ThothAI | **Fuori dalla baseline iniziale; import differito** | GDPR resta escluso. Un eventuale import richiede una iniziativa idempotente e un cutover separati, non il riuso degli ID Django. |
|
||
| Django Admin, modifica manuale della struttura sorgente, password nel catalogo, duplicazione opaca dei database | **Esclusi** | La UI e le API correnti amministrano il catalogo e non eseguono DDL sul DWH esterno; binding e segreti hanno ownership separata. |
|
||
|
||
## Sintesi storica
|
||
|
||
La baseline di parità proposta il 2026-08-23 comprende un catalogo dei database, l'inventario
|
||
completo di tabelle, colonne e relazioni fisiche, metadati descrittivi modificabili, relazioni
|
||
logiche, introspezione dello schema, generazione AI di descrizioni, scope, ERD Mermaid,
|
||
documentazione ed esportazioni operative. La UI Django Admin è soltanto l'interfaccia legacy:
|
||
non è un requisito architetturale da riprodurre.
|
||
|
||
Il flusso AI per le descrizioni individuato come baseline è volutamente semplice:
|
||
|
||
1. l'AI scrive nel campo `generated_comment` della tabella o colonna;
|
||
2. l'utente seleziona gli elementi desiderati;
|
||
3. un'azione copia il testo generato nel campo descrittivo canonico, sovrascrivendolo.
|
||
|
||
Nel codice esaminato **non esiste un'azione inversa che copi la descrizione canonica in
|
||
`generated_comment`**. Le due azioni inverse presenti sulle colonne copiano invece il nome
|
||
originale nel nome espanso e viceversa. Non risultano proposal, versioni, diff o workflow di
|
||
approvazione: aggiungerli non sarebbe parità con ThothAI.
|
||
|
||
La parità deve essere di capacità e comportamento utile, non dei difetti del legacy. In
|
||
particolare non vanno replicate esportazioni di password, SQL costruito con identificatori non
|
||
quotati, job in thread daemon, incoerenze CSV e azioni admin non funzionanti.
|
||
|
||
## 1. Modello dati legacy
|
||
|
||
### Database
|
||
|
||
`SqlDb` contiene:
|
||
|
||
- identità e connessione (`name`, host, tipo motore, nome database, porta, schema, utente e
|
||
password);
|
||
- configurazione SSH e ambiente (`dev`, `test`, `prod`);
|
||
- lingua per database, scope testuale e JSON, ERD Mermaid, direttive e report GDPR;
|
||
- stato e log separati per generazione commenti tabella/colonna, introspezione, scope, ERD,
|
||
documentazione e GDPR.
|
||
|
||
Evidenze: `/Thoth/ThothAI/backend/thoth_core/models.py:298-350`,
|
||
`/Thoth/ThothAI/backend/thoth_core/models.py:355-439`.
|
||
|
||
I motori dichiarati sono sette: Informix, MariaDB, MySQL, Oracle, PostgreSQL, SQL Server e
|
||
SQLite (`/Thoth/ThothAI/backend/thoth_core/models.py:116-123`).
|
||
|
||
Il modello `Workspace` collega un solo `SqlDb`; contiene inoltre configurazioni degli agenti e
|
||
duplica parte degli stati operativi (`/Thoth/ThothAI/backend/thoth_core/models.py:731-754`,
|
||
`/Thoth/ThothAI/backend/thoth_core/models.py:847-877`).
|
||
|
||
### Tabelle e colonne
|
||
|
||
`SqlTable` contiene nome, descrizione canonica, commento generato e riferimento al database
|
||
(`/Thoth/ThothAI/backend/thoth_core/models.py:454-465`).
|
||
|
||
`SqlColumn` contiene nome originale, nome espanso, formato dati normalizzato, descrizione
|
||
canonica, commento generato, descrizione dei valori e indicazioni PK/FK testuali
|
||
(`/Thoth/ThothAI/backend/thoth_core/models.py:468-485`).
|
||
|
||
La cancellazione usa le cascade Django: database → tabelle → colonne e relazioni. Nei modelli
|
||
non sono definite unicità composte per database/tabella/colonna. Ogni database ha un solo
|
||
campo `schema`; tabelle e colonne non portano una propria identità di schema. Questi limiti
|
||
non devono diventare vincoli del nuovo catalogo.
|
||
|
||
### Relazioni
|
||
|
||
`Relationship` collega tabella e colonna sorgente a tabella e colonna destinazione
|
||
(`/Thoth/ThothAI/backend/thoth_core/models.py:488-503`). Il metodo
|
||
`update_pk_fk_fields` ricostruisce stringhe descrittive PK/FK sulle colonne coinvolte
|
||
(`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`).
|
||
|
||
Il form admin verifica che le due tabelle appartengano allo stesso database e che ogni colonna
|
||
appartenga alla tabella selezionata
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:19-165`).
|
||
|
||
Per ThothII occorre distinguere:
|
||
|
||
- struttura fisica importata dal database, da trattare come inventario non modificabile;
|
||
- descrizioni e metadati semantici, modificabili con CRUD completo;
|
||
- relazioni logiche aggiunte dall'utente, modificabili con CRUD completo.
|
||
|
||
Questa separazione conserva le capacità utili del legacy senza permettere che la UI alteri o
|
||
falsifichi accidentalmente lo schema fisico osservato.
|
||
|
||
## 2. Capacità esposte dal Django Admin
|
||
|
||
La registrazione degli admin fornisce il CRUD Django standard per database, tabelle, colonne e
|
||
relazioni (`/Thoth/ThothAI/backend/thoth_core/admin.py:13-24`). Oltre al CRUD, le azioni
|
||
specifiche sono le seguenti.
|
||
|
||
### Database
|
||
|
||
L'admin di `SqlDb` espone:
|
||
|
||
- export/import CSV;
|
||
- scansione delle tabelle, creazione delle relazioni e introspezione completa;
|
||
- validazione FK e inferenza di relazioni candidate;
|
||
- test della connessione;
|
||
- duplicazione della configurazione;
|
||
- generazione commenti AI per tabelle e colonne;
|
||
- generazione sincrona o asincrona di scope, ERD e documentazione;
|
||
- report GDPR;
|
||
- export della struttura e script SQL dei commenti.
|
||
|
||
Evidenza: `/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:237-274`.
|
||
|
||
I campi di configurazione, contenuto e stato sono esposti in fieldset distinti
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:275-462`). In ThothII i segreti di
|
||
connessione non devono essere campi ordinari del catalogo né essere restituiti dalle API di
|
||
gestione metadati.
|
||
|
||
### Tabelle
|
||
|
||
L'admin delle tabelle permette export/import CSV, introspezione colonne, validazione e pulizia
|
||
PK/FK, copia del commento AI nella descrizione, generazione commenti sincrona/asincrona e
|
||
download dello script SQL (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:133-150`).
|
||
|
||
L'azione di applicazione AI opera solo sulle righe selezionate, ignora commenti generati vuoti
|
||
e sovrascrive direttamente `description`
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:165-190`).
|
||
|
||
### Colonne
|
||
|
||
L'admin delle colonne permette export/import CSV, copia del commento AI nella descrizione,
|
||
copia bidirezionale fra nome originale e nome espanso, validazione FK e generazione AI sulle
|
||
colonne selezionate (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:167-196`).
|
||
|
||
L'applicazione AI sovrascrive `column_description` soltanto per le colonne selezionate con
|
||
`generated_comment` valorizzato
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:219-245`). Le azioni inverse riguardano
|
||
esclusivamente i due campi nome
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:247-261`).
|
||
|
||
### Relazioni
|
||
|
||
L'admin delle relazioni offre il CRUD standard, filtri e ricerca, export/import e dichiara
|
||
un'azione per aggiornare i campi PK/FK
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). L'ultima azione è però un
|
||
difetto: `RelationshipAdmin` non implementa il metodo dichiarato; esiste soltanto il metodo
|
||
statico sul model. La capacità da conservare è la ricostruzione coerente degli indicatori, non
|
||
l'azione admin rotta.
|
||
|
||
## 3. Introspezione e riconciliazione dello schema
|
||
|
||
Il factory del database manager associa i sette motori ai rispettivi adapter e gestisce anche
|
||
il tunnel SSH (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:77-227`).
|
||
|
||
L'introspezione legacy:
|
||
|
||
- riduce i tipi nativi a un insieme generico limitato, con fallback `VARCHAR`
|
||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:237-266`);
|
||
- legge e crea le colonne mancanti, ma non aggiorna tipo o commento di quelle già note
|
||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:269-351`);
|
||
- crea le tabelle mancanti e aggiorna la descrizione di quelle esistenti
|
||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:431-481`);
|
||
- legge le foreign key fisiche, crea al bisogno colonne mancanti e crea relazioni assenti
|
||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:484-641`);
|
||
- esegue l'intero processo nell'ordine tabelle → colonne → relazioni
|
||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:718-891`).
|
||
|
||
Il comportamento è additivo: gli oggetti scomparsi dal database sorgente non sono eliminati o
|
||
marcati come obsoleti. Per ThothII la capacità richiesta è una scansione completa e
|
||
riconciliabile, con provenienza, data dell'osservazione e stato degli oggetti rimossi o cambiati;
|
||
non la semantica incompleta del refresh legacy.
|
||
|
||
L'inferenza di relazioni candidate combina convenzioni sui nomi, individuazione euristica delle
|
||
PK e campionamento dei valori, con soglia di corrispondenza del 70%
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:605-801`). Deve rimanere una proposta
|
||
esplicita da convalidare, non essere confusa con una foreign key fisica.
|
||
|
||
## 4. Generazione AI delle descrizioni
|
||
|
||
### Tabelle
|
||
|
||
La generazione procede in batch da dieci, utilizza lingua e contesto del database, schema
|
||
osservato, descrizioni disponibili e fino a cinque righe di esempio; il risultato JSON aggiorna
|
||
soltanto `table.generated_comment`
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:181-267`,
|
||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:269-482`).
|
||
|
||
### Colonne
|
||
|
||
La generazione usa contesto della tabella, nomi delle colonne selezionate ed esempi reali, e
|
||
scrive soltanto `column.generated_comment`
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:185-280`,
|
||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:283-487`).
|
||
|
||
Provider e modello AI provengono dalla configurazione globale del backend; la lingua è invece
|
||
per database (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/comment_generation_utils.py:156-219`).
|
||
|
||
### Comportamento di parità proposto il 2026-08-23
|
||
|
||
Il contratto funzionale minimo è esattamente questo:
|
||
|
||
- due campi per elemento: descrizione canonica e commento generato;
|
||
- comando AI su elementi selezionati o su un insieme più ampio esplicitamente scelto;
|
||
- scrittura/sovrascrittura del solo commento generato;
|
||
- azione separata, su selezione dell'utente, che copia il generato nel canonico;
|
||
- nessuna proposta persistente aggiuntiva, diff obbligatorio, approvazione multilivello o
|
||
versionamento del testo.
|
||
|
||
Non è stata trovata una copia `descrizione → commento generato`. Se si desiderasse in futuro,
|
||
sarebbe una nuova capacità, non parità legacy.
|
||
|
||
## 5. Scope, Mermaid e documentazione
|
||
|
||
### Scope
|
||
|
||
La generazione dello scope raccoglie nomi e descrizioni di tabelle e colonne, nome e lingua del
|
||
database, richiede JSON al modello e persiste sia il JSON sia una resa Markdown. Se il JSON non
|
||
è valido conserva il testo grezzo e svuota `scope_json`
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:25-163`).
|
||
|
||
### ERD Mermaid
|
||
|
||
L'ERD è prodotto dall'AI usando tabelle, colonne, PK/FK e relazioni. Il codice estrae un blocco
|
||
Mermaid oppure usa la risposta grezza e la salva in `SqlDb.erd`, senza una validazione
|
||
sintattica o semantica preventiva
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:18-145`).
|
||
|
||
Il rendering attivo usa un servizio Mermaid locale: health check, POST a `/svg` o `/png`,
|
||
timeout e file temporanei
|
||
(`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:29-72`,
|
||
`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:281-464`). Il servizio Express espone
|
||
`/health`, `/svg` e `/png` ed applica un limite al body
|
||
(`/Thoth/ThothAI/docker/mermaid-service/src/server.js:13-23`,
|
||
`/Thoth/ThothAI/docker/mermaid-service/src/server.js:70-115`). È distribuito come servizio
|
||
Compose autonomo con health check
|
||
(`/Thoth/ThothAI/docker-compose.yml:184-201`).
|
||
|
||
La vista ERD renderizza il Mermaid memorizzato in SVG tramite tale servizio e poi elimina il
|
||
file temporaneo (`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:227-288`).
|
||
|
||
### Documento del database
|
||
|
||
La documentazione HTML combina scope, relazioni, tabelle e colonne. Per le descrizioni usa il
|
||
campo canonico e, quando vuoto, il commento generato
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`).
|
||
|
||
Il processo di generazione chiede all'AI il diagramma Mermaid, lo salva nell'ERD e costruisce
|
||
deterministicamente l'HTML corrente; l'HTML generato non incorpora il diagramma
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:767-922`). La UI espone il
|
||
documento del database del workspace corrente e le route per HTML/PDF ed ERD/PDF
|
||
(`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:86-179`,
|
||
`/Thoth/ThothAI/backend/thoth_ai_backend/urls.py:179-188`).
|
||
|
||
Per la parità ThothII servono quindi contenuto documentale strutturato, sorgente Mermaid
|
||
persistita e rendering locale. La validazione Mermaid prima della pubblicazione è una
|
||
correzione necessaria, non un cambiamento di scopo.
|
||
|
||
## 6. Export e comandi operativi
|
||
|
||
Le capacità utili rilevate sono:
|
||
|
||
- CSV di tabelle e colonne selezionate
|
||
(`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:150-195`);
|
||
- export CSV generico dei modelli e della struttura completa
|
||
(`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:198-261`,
|
||
`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:399-569`);
|
||
- script SQL dei commenti per PostgreSQL, SQL Server, MySQL e MariaDB
|
||
(`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:25-316`);
|
||
- comandi `generate_scope` e `generate_documentation`, indirizzabili per workspace, database o
|
||
tutti i database (`/Thoth/ThothAI/backend/thoth_core/management/commands/generate_scope.py:12-89`,
|
||
`/Thoth/ThothAI/backend/thoth_core/management/commands/generate_documentation.py:12-89`);
|
||
- export globale e per workspace
|
||
(`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`,
|
||
`/Thoth/ThothAI/backend/thoth_core/management/commands/export_workspace.py:19-96`);
|
||
- aggiornamento delle descrizioni colonna da CSV per workspace
|
||
(`/Thoth/ThothAI/backend/thoth_ai_backend/management/commands/update_column_descriptions.py:24-92`).
|
||
|
||
I comandi di importazione dalla produzione legacy sono deliberatamente esclusi da questo
|
||
inventario di parità: costituiscono un progetto CLI `tht` separato, con mapping, validazione e
|
||
cutover propri.
|
||
|
||
## 7. Esecuzioni asincrone e stato
|
||
|
||
Scope, ERD, documentazione e commenti possono essere lanciati in background. Il legacy crea
|
||
thread daemon e memorizza task id, stato e log sui modelli
|
||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`,
|
||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_erd.py:21-30`,
|
||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_documentation.py:21-30`,
|
||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_table_comments.py:39-87`).
|
||
|
||
La capacità da mantenere è: operazione lunga non bloccante, esclusione di esecuzioni
|
||
confliggenti, stato osservabile e log. Il meccanismo daemon non è durevole, non permette
|
||
recovery o cancellazione e non deve essere replicato letteralmente.
|
||
|
||
## 8. Difetti e comportamenti da non replicare
|
||
|
||
| Area | Evidenza legacy | Decisione di parità |
|
||
|---|---|---|
|
||
| Segreti negli export | L'export struttura include `password` in chiaro (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:516-559`); l'export generico serializza tutti i campi (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`). | Escludere sempre credenziali e segreti. |
|
||
| SQL euristico | Il campionamento per inferire FK interpola identificatori senza quoting e usa query costruite come stringhe (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:697-750`). | Usare adapter sicuri, quoting per dialetto e query read-only con limiti. |
|
||
| Refresh incompleto | L'introspezione aggiunge oggetti ma non riconcilia rimozioni e non aggiorna tutte le proprietà (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:318-351`, `/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:459-481`). | Scansioni versionate e stato drift/removed. |
|
||
| Relazioni denormalizzate | L'aggiornamento ricostruisce stringhe PK/FK solo sulle colonne partecipanti e non ripulisce esplicitamente valori obsoleti (`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`). | Derivare indicatori dalle relazioni correnti. |
|
||
| Azione relazione rotta | L'admin dichiara `update_pk_fk_fields` ma non lo implementa (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). | Esporre un comando applicativo testato. |
|
||
| CSV colonne incoerente | L'header ha sei colonne, le righe ne emettono otto incluse PK/FK (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:165-195`). | Contratto CSV versionato e testato. |
|
||
| Comando export rotto | `export_single_model` usa l'app label `toth_be` e un attributo non definito (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_single_model.py:19-67`). | Non portare il comando; sostituirlo con export catalogo coerente. |
|
||
| Batch AI colonne | Un batch usa la prima tabella selezionata come contesto per tutte le colonne (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:230-268`). | Raggruppare sempre per database e tabella. |
|
||
| Contesto AI tabelle | Il fallback al commento generato è calcolato ma non incluso nel dataframe finale (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:485-525`). | Costruire il contesto dal valore effettivamente visibile. |
|
||
| Duplicazione DB | Duplica configurazione e vector DB, azzerando soltanto una data di aggiornamento (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:514-569`). | Se mantenuta, duplicare soltanto metadati esplicitamente scelti, mai segreti o stati. |
|
||
| Scope non JSON | Il generatore intercetta internamente il JSON non valido, mentre l'azione può comunque mostrare successo (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:92-192`). | Stato `failed` o `needs_review`, senza falso successo. |
|
||
| Mermaid non validato | La risposta AI viene salvata dopo la sola estrazione del blocco (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:88-121`). | Validare prima di pubblicare e conservare l'errore di rendering. |
|
||
| HTML non escapato | I valori descrittivi sono interpolati direttamente nell'HTML (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`). | Escape/sanitizzazione obbligatori. |
|
||
| Job daemon | I task sono thread in-process (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`). | Esecuzione durevole o almeno recuperabile, con idempotenza. |
|
||
| Script MySQL | I commenti colonna usano `ALTER ... MODIFY COLUMN` basandosi sul tipo normalizzato (`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:244-316`). | Generare solo con tipo nativo completo oppure bloccare l'export rischioso. |
|
||
|
||
Il modulo contiene anche un helper verso `mermaid.ink`, ma non risultano call site nel tree
|
||
legacy; il percorso attivo è il servizio locale. Non va quindi considerata una dipendenza
|
||
funzionale da conservare.
|
||
|
||
## 9. Baseline di parità proposta il 2026-08-23
|
||
|
||
### Necessario
|
||
|
||
- database gestiti derivati dalla configurazione dei workspace;
|
||
- inventario completo del database, anche oltre il sottoinsieme usato dal workflow core;
|
||
- scansione di tabelle, colonne, chiavi e relazioni fisiche con drift osservabile;
|
||
- descrizioni canoniche e commenti AI separati per tabelle e colonne;
|
||
- generazione AI selettiva e copia selettiva AI → descrizione, senza workflow aggiuntivo;
|
||
- CRUD dei metadati semantici e delle relazioni logiche;
|
||
- scope strutturato, documento generale strutturato ed ERD Mermaid;
|
||
- servizio locale per validazione/rendering Mermaid in SVG/PNG/PDF;
|
||
- test connessione, inferenza/validazione delle relazioni e operazioni lunghe con stato/log;
|
||
- export CSV sicuro e script SQL commenti solo quando il dialetto può essere ricostruito senza
|
||
perdita;
|
||
- API e UI dedicate, separate dal workflow NL→SQL;
|
||
- pubblicazione esplicita e controllata del sottoinsieme utile al core/Qdrant.
|
||
|
||
### Estensione, non requisito di parità iniziale
|
||
|
||
- analisi e report GDPR;
|
||
- importazione dei dati da installazioni ThothAI in produzione, da progettare come iniziativa
|
||
CLI `tht` separata.
|
||
|
||
### Esplicitamente escluso
|
||
|
||
- replica del Django Admin o del suo modello di permessi implicito;
|
||
- modifica manuale della struttura fisica osservata;
|
||
- memorizzazione o export di password nel catalogo;
|
||
- dipendenza del workflow SQL dalla disponibilità della nuova UI;
|
||
- proposal/versioning/diff per i commenti AI;
|
||
- copia descrizione → commento AI, non presente nelle fonti;
|
||
- difetti tecnici e comportamenti insicuri elencati sopra.
|
||
|
||
## Conclusione
|
||
|
||
ThothAI fornisce già il perimetro funzionale di un catalogo metadati, ma lo realizza mescolando
|
||
configurazione di connessione, inventario fisico, contenuti semantici, job e UI nel modello
|
||
Django. ThothII può raggiungere la parità separando questi aspetti e mantenendo invariato il
|
||
workflow SQL: il catalogo gestisce l'intero database, mentre il core continua a consumare
|
||
soltanto il sottoinsieme dichiarato dal workspace e pubblicato nel proprio indice Qdrant.
|
||
|
||
La regola di Q6 è semplice e verificata nelle fonti: generazione nel campo AI, selezione
|
||
esplicita dell'utente, copia nel campo canonico. Ogni meccanismo ulteriore sarebbe una nuova
|
||
funzionalità e non è necessario per la parità.
|