ThothII/docs/operations/shell-and-localization.md

Shell, autenticazione e lingue

Questa guida accompagna la specifica approvata e il contratto Portal Shell Adapter.

Scegliere il contenitore

La modalità della shell è indipendente dal profilo di distribuzione e dal metodo di autenticazione. Un server può ospitare full; un ambiente locale può ospitare embedded per provare un'integrazione.

Per questo Mac, nel descrittore installato:

shell:
  mode: full
  defaultLocale: en

Per il server Omics:

shell:
  mode: embedded
  adapter: omics-portal

L'assenza di shell conserva embedded con adapter Omics. Un nome adapter sconosciuto è un errore, non una richiesta di fallback a full. Full ignora l'adapter Omics riconosciuto e non lo istanzia. Un locale ben formato per cui non esiste ancora un catalogo usa l'inglese nell'interfaccia.

defaultLocale è il valore iniziale, non un vincolo che annulla ogni scelta dell'utente. Full ricorda lingua e tema nel browser; embedded segue soltanto Omics. Le preferenze non modificano il descrittore installato.

Applicare una modifica all'installazione

Aggiornare prima il binario nativo tht: le versioni precedenti rifiutano la sezione shell. Modificare poi il descrittore e generare le proiezioni:

tht --installation /percorso/assoluto/thothii-installation.yaml installation generate

Il comando non avvia né arresta servizi. Genera anche generated/frontend/config.js, che contiene configurazione pubblica, e il relativo mount Compose. Non modificare a mano i file generati. tht start rigenera le proiezioni nel normale percorso di avvio.

Applicare il normale processo di aggiornamento dei container dell'installazione. Se si usa un launcher Compose personalizzato, deve includere la proiezione Compose generata e ricreare il frontend quando cambia la configurazione. Il fingerprint della configurazione pubblica permette a Compose di rilevare il cambio. La stessa immagine frontend supporta entrambe le modalità.

Controllare il config.js effettivamente servito, che non deve essere memorizzato in cache. In full la route API ordinaria è /api; Omics imposta nel template il prefisso same-origin /datamart-builder/api, mantenendo le altre impostazioni.

Accesso in parole semplici

In Omics l'utente effettua l'accesso al portale come oggi. Quando sceglie Datamart Builder, il server controlla che possa usarlo e comunica a ThothII chi è. ThothII apre l'applicazione per quella persona: non presenta un altro login e non crea una seconda sessione browser. Le password non vengono trasmesse a ThothII. Il nome e il comando Esci rimangono nell'header del portale.

Sul Mac full, ThothII presenta il proprio login locale. Dopo l'accesso mostra il nome nell'header; il menu del nome contiene il logout. Riutilizza gli utenti e la configurazione di accesso dell'installazione. Full supporta anche un'eventuale autenticazione OIDC configurata; il suo logout termina la sessione ThothII, non promette di disconnettere l'utente da tutti gli altri servizi OIDC.

I controlli server restano autorevoli. Un errore su una singola operazione non deve cancellare automaticamente l'accesso all'intera applicazione. Un rifiuto della verifica dell'utente chiude invece lo stato protetto. L'accesso viene ricontrollato anche al ritorno alla pagina e quando il collegamento eventi deve riconnettersi. Questo non equivale a una revoca istantanea di ogni connessione già aperta in altre schede.

Contratto server Omics

Il percorso corrente usa il controllo Django della capability datamart_builder.access, la subrequest nginx auth_request e gli header normalizzati X-Thoth-Principal-Issuer, X-Thoth-Principal-Subject, X-Thoth-Principal-Display-Name e X-Thoth-Is-Admin. Il browser non può scegliere queste identità: il proxy ricava gli header dal controllo server e sostituisce quelli eventualmente forniti dal client.

Mantenere il backend configurato per l'autenticazione upstream e i suoi controlli di autorizzazione. Non esporre un percorso alternativo che permetta al browser di raggiungerlo aggirando quel controllo. Non introdurre token nel documento, negli eventi UI o nella configurazione pubblica.

Come funziona l'adapter

OmicsPortalAdapter è il solo modulo frontend che conosce il documento Omics. Legge il data-lang del selettore lingua, osserva data-bs-theme e ascolta lo stato fullscreen del documento. Fornisce snapshot { locale, theme, fullscreen } al controller di shell. Non invia comandi al portale e non usa un handshake.

La pagina Omics deve continuare a esporre il selettore select.omics-language-select con la lingua renderizzata nel suo data-lang, e il tema light/dark nell'attributo di html. Il selettore lingua usa il normale form Django; non occorre convertirlo in una richiesta asincrona.

Per un altro portale, implementare la stessa sottoscrizione e selezionare il nuovo adapter nel punto di composizione. Le pagine, l'i18n e il workflow non devono acquisire riferimenti al nuovo portale. Sul lato server, il nuovo contenitore deve anche fornire un'identità verificata conforme al contratto upstream. Cambiare una classe JavaScript non sostituisce quel requisito.

Lingue e sessioni

Ci sono tre scelte distinte:

Scelta	Dove viene conservata	Cosa influenza
Lingua UI	preferenza full o stato Omics	label, form, messaggi e controlli
Lingua di interazione	interaction_language nel manifest	nuove domande, spiegazioni e scelte del modello
Lingua workspace	configurazione del workspace	documenti, descrizioni e contenuti di dominio

La creazione web acquisisce la lingua UI prima delle operazioni asincrone e la invia come interactionLanguage. Un cambio successivo non modifica quella richiesta. La ripresa legge il manifest e non usa il locale del browser come override. SQL, identificatori, valori e citazioni dei contenuti rimangono invariati.

Per sessioni precedenti senza interaction_language, la prima ripresa fissa la lingua del workspace in modo idempotente. Se il workspace era stato modificato nel frattempo, non esiste una registrazione da cui ricostruire con certezza la vecchia lingua: il criterio di compatibilità è quella disponibile alla ripresa.

Il cambio lingua di Omics ricarica la pagina. ThothII ricorda soltanto l'identificatore della sessione per utente e pagina, senza salvare una trascrizione nel browser. Il recupero riapre il pannello dei documenti; la ripresa operativa è esplicita e non avvia una generazione soltanto perché la pagina è stata ricaricata. Le bozze non inviate e le modifiche amministrative richiedono protezione dalla navigazione.

Aggiungere e verificare traduzioni

I messaggi inglesi fungono da identificatori gettext-style e fallback. I cataloghi italiani sono divisi per area per agevolarne la manutenzione. Usare useI18n() nei componenti e interpolazioni nominate, evitando concatenazioni che rendano impossibile cambiare l'ordine delle parole. Non chiamare il traduttore su SQL, testi del modello o descrizioni del workspace.

Per una nuova lingua aggiungere il catalogo, registrarlo nel risolutore e renderlo disponibile nel selettore full. Il portale deve fornire il relativo locale. La lingua delle sessioni è già esplicita e non richiede una nuova struttura del manifest. Le traduzioni dei controlli della griglia provengono dal catalogo ufficiale della stessa versione di AG Grid.

cd frontend
npm run check:i18n
npx tsc -b
npx vitest run

Il controllo dei cataloghi segnala messaggi statici mancanti, interpolazioni incompatibili e traduzioni discordanti. Non può provare da solo la copertura di tutti i messaggi dinamici: completarlo con i test delle pagine e la verifica visiva.

La build verifica anche il CSS effettivamente generato: il reset Tailwind viene limitato al mount React e ai suoi popup con selettori ordinari, senza richiedere supporto browser a @scope. Mantenere letterali le classi dei due modi della shell per conservarle durante la rimozione del CSS inutilizzato. Le griglie usano il tema CSS esistente con i token light/dark; non mescolarlo con la nuova Theming API di AG Grid.

Verifica prima del deploy server

Provare l'apertura dal menu Omics con un utente autorizzato e uno senza accesso; verificare assenza di un secondo login e di header ThothII, italiano/inglese già selezionati prima dell'apertura, tema, fullscreen e uscita con Esc. Ripetere con un menu o un form aperto, una bozza non inviata e una sessione esistente.

Verificare perdita dell'accesso, ritorno alla scheda e riconnessione degli eventi; distinguere questi casi dal rifiuto di una sola operazione. Controllare che una ripresa conservi la lingua salvata e che il reload non avvii una nuova generazione. Eseguire i test Omics nel suo ambiente Docker e includere gli aggiornamenti dei template, degli asset e dei cataloghi Django nel suo normale rebuild.

La verifica del codice e i test locali non costituiscono un deploy sul server di produzione. Usare il normale processo di rilascio per applicare entrambe le revisioni e annotare immagini, descrittore e revisioni realmente installate.