Add full shell, replaceable Omics adapter and bilingual interaction
Implement approved specification #32 and tickets #33-#37. Keep host authentication server-verified and pin session interaction language. Compile scoped base selectors for browser compatibility and retain full gutters during CSS pruning.
This commit is contained in:
Codex
@@ -0,0 +1,186 @@
|
||||
# Shell, autenticazione e lingue
|
||||
|
||||
Questa guida accompagna la [specifica approvata](../plans/2026-09-13-full-shell-spec.md)
|
||||
e il [contratto Portal Shell Adapter](../contracts/portal-shell-adapter-v1.md).
|
||||
|
||||
## 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:
|
||||
|
||||
```yaml
|
||||
shell:
|
||||
mode: full
|
||||
defaultLocale: en
|
||||
```
|
||||
|
||||
Per il server Omics:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user