docs: inventory legacy metadata capabilities

2026-08-31 14:43:23 +02:00
parent 57928347b3
commit 374e8aabc8
1 changed files with 361 additions and 0 deletions
@@ -0,0 +1,361 @@
 # Inventario delle funzionalità legacy di gestione metadati di ThothAI
 Data: 2026-08-23
 Issue: `mptyl/ThothII#6`
 Fonte primaria: repository legacy annidato `Thoth/ThothAI`, commit
 `55855de0f18e5cb4bc72f0a2ab0a7317995186dd`.
 ## Sintesi
 La parità funzionale richiesta a ThothII 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 è volutamente semplice e va mantenuto tale:
 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à da implementare
 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à per il Metadata Catalog di ThothII
 ### 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à.