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

### Acquisire prima le modifiche al repository Omics

Procedura concordata il 13 settembre 2026: **Mac → GitHub → server → Gitea PSD**.
Il Mac pubblica il branch Omics `codex/thothii-embedded-shell` su
`https://github.com/Dallavilla-Tiziano/omics_portal.git`; l'operatore lo recupera
dal server e lo pubblica su `ssh://git@localhost:2222/aritmolab/omics_portal.git`.
Il secondo passaggio è un **push** a Gitea, non un pull. Questa scelta evita di
richiedere al Mac credenziali Gitea PSD. Non cambia l'origine Gitea TYL di ThothII.

Consegna GitHub verificata il 13 settembre 2026:
`fca10901a73666ca257d8f4cc4b77066295c400a`, che include il commit funzionale
`95154e1` e la guida per il server. Per questa consegna lo SHA acquisito sul
server deve coincidere esattamente. Eventuali consegne successive richiedono un
nuovo SHA comunicato e approvato, non l'accettazione implicita della testa del branch.

I comandi completi sono nella
[guida del repository Omics](https://github.com/Dallavilla-Tiziano/omics_portal/blob/codex/thothii-embedded-shell/docs/thothii-integration.md#consegna-via-github-e-pubblicazione-su-gitea-psd).
Sul server, per recuperare il branch e leggere la guida senza cambiare i file
del portale in esecuzione:

```bash
cd /home/chirone/omics_portal
git status --short --branch
git fetch --no-tags https://github.com/Dallavilla-Tiziano/omics_portal.git \
  refs/heads/codex/thothii-embedded-shell:refs/remotes/github-relay/codex/thothii-embedded-shell
git rev-parse refs/remotes/github-relay/codex/thothii-embedded-shell
git show refs/remotes/github-relay/codex/thothii-embedded-shell:docs/thothii-integration.md
```

Confrontare lo SHA con la consegna dal Mac prima di procedere con il push
documentato nella guida. Non usare `git pull` nel checkout condiviso né
`git push origin`: quest'ultimo può avere due destinazioni. Non cambiare
`master` o riavviare Omics durante il trasferimento. L'integrazione e il deploy
richiedono una successiva approvazione, con revisione/immagini di rollback
registrate e rilascio coordinato con ThothII embedded/upstream.

Dopo il confronto positivo con
`fca10901a73666ca257d8f4cc4b77066295c400a`, il trasferimento verso Gitea si
completa **sempre dal repository Omics sul server** con:

```bash
cd /home/chirone/omics_portal
git ls-remote ssh://git@localhost:2222/aritmolab/omics_portal.git \
  HEAD refs/heads/codex/thothii-embedded-shell
git push ssh://git@localhost:2222/aritmolab/omics_portal.git \
  refs/remotes/github-relay/codex/thothii-embedded-shell:refs/heads/codex/thothii-embedded-shell
git ls-remote ssh://git@localhost:2222/aritmolab/omics_portal.git \
  refs/heads/codex/thothii-embedded-shell
git status --short --branch
git rev-parse HEAD
```

Lo SHA Gitea deve coincidere; branch, HEAD e modifiche del checkout devono
rimanere quelli registrati prima del fetch. Se diverge o il push viene rifiutato,
fermarsi senza force push, reset, modifica di credenziali o merge improvvisato.
Questo passaggio non pubblica ThothII, non cambia `master` e non fa deploy.

### 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 push Gitea PSD e il deploy del nuovo branch
Omics rimangono 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.