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

# Shell, autenticazione e lingue

Questa è la procedura operativa del rendering corrente. Leggerla insieme a
[architettura full/embedded](../architecture/application-shell.md),
[autenticazione upstream](../install/authentication-upstream.md) e
[contratto PortalAdapter](../contracts/portal-shell-adapter-v1.md).
La [specifica approvata](../plans/2026-09-13-full-shell-spec.md) documenta la
progettazione, non sostituisce i vincoli verificati nel codice e riportati qui.

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

| Destinazione | Shell | Autorità di accesso | Login/logout visibile |
| --- | --- | --- | --- |
| Mac attuale | full, default en | `auth.yaml` local | ThothII |
| Server autonomo | full | `auth.yaml` OIDC | ThothII, con redirect al provider |
| Datamart Builder in Omics | embedded, adapter Omics | core `AUTH_MODE=upstream`, sessione Omics al proxy | Solo Omics |

Non confondere la lingua inglese iniziale del Mac con quella del workspace o
delle sessioni già create. Non copiare sul server l'intero descrittore del Mac:
contiene percorsi e scelte locali, oltre a full.

Per questo Mac, nel descrittore installato:

```yaml
shell:
  mode: full
  defaultLocale: en
```

Per il server Omics:

```yaml
shell:
  mode: embedded
  defaultLocale: en
  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

Per una nuova installazione autonoma, selezionare esplicitamente full:

```bash
tht setup --profile local --shell-mode full --shell-default-locale en
```

Il setup senza opzioni shell conserva per compatibilità il default embedded.
Per un'installazione esistente non rilanciare setup per sovrascrivere il
descrittore: registrare la configurazione attuale, modificarne la sezione shell
e usare la generazione seguente. Le credenziali rimangono nei file protetti.

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

Nel percorso standard del CLI, dopo avere approvato l'aggiornamento:

```bash
tht --installation /percorso/assoluto/thothii-installation.yaml start
tht --installation /percorso/assoluto/thothii-installation.yaml status
tht --installation /percorso/assoluto/thothii-installation.yaml doctor --json
```

Usare `start --build` per una revisione di codice che richiede nuove immagini,
non per la sola modifica della shell. Questo è un lifecycle dell'installazione,
non un comando garantito frontend-only. Un launcher personalizzato deve conservare
tutti gli override di rete, autenticazione, workspace e modelli già approvati.
Non usare `down --volumes`. Registrare gli identificatori delle immagini prima
dell'aggiornamento e conservare il descrittore precedente per il rollback.

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.

Il file pubblico standalone deve essere equivalente a:

```javascript
window.__THOTHII_CONFIG__ = {
  backendBaseUrl: "/api",
  shell: { mode: "full", defaultLocale: "en" }
};
```

È un risultato da controllare, non un file da mantenere a mano. In Omics il
template carica `/datamart-builder/config.js`, conserva l'oggetto con
`Object.assign` cambiando solo `backendBaseUrl` in `/datamart-builder/api`, poi
carica gli asset dal manifest. Il config senza cache deve precedere ogni modulo
React; verificare nella rete del browser l'URL finale `/datamart-builder/api/me`.

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

Full/upstream non può terminare una sessione posseduta dal proxy e non mostra
quel comando logout. Embedded non presenta mai il login ThothII, neppure per
recuperare un errore di configurazione. Per un server autonomo con login/logout
ThothII usare full/OIDC, non full/upstream.

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.

La [guida upstream](../install/authentication-upstream.md) riporta i vincoli
esatti: `AUTH_MODE=upstream` nel core, nessun `auth.yaml` o runtime projection
contemporaneo, capability Django, quattro header obbligatori/facoltativi, percorso
diretto Omics distinto dal proxy generico a due hop, origine e SSE. Non usare
`tht auth configure --mode oidc` per «completare» l'accesso Omics già funzionante.

## 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 | navigazione, amministrazione e messaggi generali |
| Lingua di interazione | `interaction_language` nel manifest | domande, spiegazioni, scelte e controlli HITL |
| 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` di ripiego. Il CLI riconosce localmente la lingua
della domanda originale e la fissa nel manifest; usa il ripiego per testo troppo
breve, ambiguo o composto soltanto da codice. Un cambio successivo non modifica
quella richiesta. Il gate trasmette la lingua nei widget: anche i controlli HITL
seguono la sessione, mentre la navigazione conserva la lingua UI.
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 della domanda in modo idempotente, usando la lingua del workspace come
ripiego. Le sessioni che hanno già una lingua fissata la conservano.

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

### Acquisire prima le modifiche al repository Omics

Procedura aggiornata il 14 settembre 2026: acquisire il codice Omics da GitHub
e integrarlo con il codice operativo del server. Non è richiesta alcuna replica
del repository su altri servizi; l'eventuale copia è un'attività distinta del
proprietario. Questa indicazione sostituisce le precedenti note di trasporto,
anche se ancora presenti nei documenti storici del branch Omics.

La [consegna corrente a Codex sul server](server-codex-handoff.md) contiene i
comandi esatti di acquisizione, gli SHA, i file da adeguare, la configurazione
embedded/upstream, i test, i gate di rilascio e il rollback. Usarla come procedura
ordinata per l'aggiornamento; le sezioni qui sotto restano il riepilogo tecnico.

Consegna GitHub riverificata: branch `codex/thothii-embedded-shell` di
`https://github.com/Dallavilla-Tiziano/omics_portal.git`, SHA
`fca10901a73666ca257d8f4cc4b77066295c400a`, incluso il commit funzionale
`95154e179144e2453b37ef2a63a65d6f377e4cf8`. Il pull di ThothII non aggiorna
Omics: il checkout del portale, normalmente `/home/chirone/omics_portal`, va
verificato e integrato separatamente preservando le modifiche successive del server.

### Preparare il rilascio coordinato

1. Registrare SHA approvati di **entrambi** i repository, immagini precedenti,
   descriptor ThothII, file Compose/override e progetto realmente in uso. La testa
   del branch di lavoro non è automaticamente una revisione approvata di produzione.
2. In un checkout di revisione separato, integrare Omics con il branch di rilascio
   concordato. Non fare merge nel checkout operativo con modifiche altrui.
   I file Omics da includere sono template Datamart Builder/topbar/base, asset
   fullscreen e cataloghi Django del branch; conservare la verifica server
   esistente in `kokoro/datamart_catalog_views.py` e le location Nginx protette.
3. Eseguire dal checkout Omics i test isolati, non i test contro il database operativo:

   ```bash
   docker build -f test_support/thothii/Dockerfile -t omics-portal:thothii-shell-tests .
   docker run --rm --network none omics-portal:thothii-shell-tests
   ```

4. Predisporre il descrittore ThothII embedded e il core upstream secondo la guida.
   Verificare che Nginx Omics possa raggiungere gli alias privati `thothii-core:8787`
   e `thothii-frontend:8080` e che non esista un ingresso non protetto al core.
   Non sovrascrivere rete, mount o autenticazione usando il Compose locale del Mac.
5. Solo dopo il gate operatore, applicare le revisioni approvate seguendo il
   lifecycle dei due progetti. In Omics i servizi sono `web` e `nginx`: includere
   nel rebuild template, statici e cataloghi, mantenendo tutti gli override del
   server. Verificare la configurazione Nginx con `nginx -t` nel servizio e lo
   stato di entrambi. Non inventare opzioni Compose/progetto: usare quelle
   registrate al punto 1. Gli entrypoint del portale possono avere altri effetti
   operativi: questa modifica non richiede nuove migrazioni DB, ma non autorizza
   a bypassare i controlli del suo rilascio.
6. Dopo l'aggiornamento del frontend, attendere la cache manifest Django (30 s)
   oppure usare l'invalidazione prevista dal portale; ricaricare e controllare
   config/asset/prefisso API prima di giudicare il risultato.
7. Compilare la matrice seguente. In caso di errore ripristinare revisioni,
   immagini e configurazioni registrate, senza cancellare volumi. Il rollback
   deve conservare una coppia compatibile di template Omics e frontend ThothII.

La consegna GitHub è verificata; il deploy della revisione integrata
Omics rimane da confermare dall'operatore. I test locali non attestano lo stato
attuale del server remoto.

### Accettazione dell'integrazione

Usare la [matrice completa full/embedded e autenticazione](../testing/authentication-manual-acceptance.md),
registrando per ogni prova revisione, ambiente e risultato. Non spuntare i casi
IdP/Omics reali soltanto perché passano i test con risposte simulate.

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.