# 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à.