ThothII/docs/reports/2026-09-13-shell-simplification-review.md

# Revisione della semplificazione della shell

Data: 2026-09-13. Oggetto: piano full/embedded, ADR 0021–0022 e contratto
Portal Shell Adapter v1. Questa è una revisione con raccomandazioni: non modifica il
codice applicativo né sostituisce automaticamente i contratti accettati.

## Valutazione

La separazione tra shell, autenticazione e lingua delle sessioni è corretta. La
semplificazione precedente ha però mantenuto un protocollo di comunicazione non
necessario per il montaggio corrente e ha lasciato ambigue alcune condizioni di
compatibilità. Raccomando un adapter che osservi il documento già condiviso con
Omics, riutilizzi l'autenticazione esistente e non imponga un nuovo bridge al portale.

La revisione considera il sorgente locale di ThothII e Omics Portal al commit
`aff7581`, già ottenuto con il pull richiesto. Non certifica quali immagini,
configurazioni o modifiche siano attualmente attive sul server.

## Problemi individuati e correzioni raccomandate

### 1. Il cambio lingua senza ricaricamento non corrisponde a Omics

In `templates/partials/topbar.html:74–87`, Omics usa il form Django `set_language`
con `onchange="this.form.submit()"`. La lingua cambia attraverso una nuova pagina
renderizzata dal server. Il criterio 2 del contratto v1 promette invece aggiornamenti
senza ricaricamento per tutte le preferenze.

Raccomandazione: rispettare il comportamento del portale. In full, lingua e tema
cambiano immediatamente. In embedded, il tema cambia immediatamente e la lingua
segue il normale ricaricamento Omics. Evitare di intercettare il form per cambiare
solo ThothII: lascerebbe header, sidebar e testi Django nella lingua precedente.

Il ricaricamento va verificato durante una sessione attiva e con modifiche non
salvate: deve essere possibile ritrovare la sessione senza avviare una nuova
generazione; eventuali bozze richiedono una protezione dalla navigazione. Lo stato
persistito del workflow non equivale alla conservazione automatica della bozza UI
o del flusso di messaggi in memoria. Questa verifica è necessaria anche mantenendo
il protocollo a eventi del piano precedente.

### 2. Un protocollo ready/state non è necessario nello stesso documento

`templates/kokoro/datamart_builder.html` monta React in `#root`, nello stesso
documento dell'header. L'adapter può ottenere direttamente:

- lingua effettivamente renderizzata: `data-lang` del selettore
  `.omics-language-select`;
- tema: attributo `data-bs-theme` sull'elemento `html`;
- fullscreen: stato del documento e relativo evento del browser.

Un'osservazione limitata all'attributo del tema e un listener del fullscreen
coprono gli aggiornamenti attuali. La lingua viene riletta quando Django restituisce
la pagina. Questi selettori e dettagli devono comparire soltanto dentro
`OmicsPortalAdapter`, con test basati sul template reale.

Attenzione: `templates/base.html:3` contiene oggi `lang="en"` fisso; quell'attributo
non è una fonte attendibile per la lingua Omics. Se in futuro il portale espone la
lingua su un attributo dedicato del punto di montaggio, si modifica soltanto l'adapter.

La proposta elimina due eventi personalizzati, la versione del protocollo, il
timeout di avvio e il rischio che il messaggio iniziale parta prima del listener.
L'osservazione va installata prima di consegnare lo snapshot iniziale; la funzione
di disiscrizione rimuove tutte le risorse. L'assenza dei dati Omics attesi produce
un errore di integrazione comprensibile, senza attivare la shell full.

Il costo accettato è una dipendenza esplicita dal piccolo contratto DOM Omics,
confinata nell'adapter. Un secondo portale potrà fornire gli stessi dati usando
un'altra implementazione, anche con un diverso trasporto. Non occorre costruirla ora.

### 3. `authenticated` duplica uno stato che il server già verifica

`kokoro/datamart_catalog_views.py:49` e `nginx/nginx.conf:69` verificano l'accesso
Omics e trasmettono al backend identità e autorizzazioni normalizzate. ThothII
ottiene già l'utente tramite `/me`. Non serve un ulteriore login né un flag nel
documento che dichiari l'utente autenticato.

Il logout Omics attuale è una navigazione (`topbar.html:118`), non un evento di
revoca. Un click sul link non prova che il logout sia stato completato; inoltre,
un flag inviato una volta non rileva la scadenza della sessione o un logout in
un'altra scheda.

Raccomandazione: togliere `authenticated` dallo snapshot visivo. La verifica
dell'accesso rimane nel percorso di autenticazione esistente. In embedded,
perdita dell'accesso significa chiudere i dati protetti e demandare il rientro
al portale, senza mostrare il form di login ThothII.

Serve verificare la gestione dei rifiuti Omics: l'endpoint di autorizzazione
restituisce attualmente 403 anche quando l'accesso non è disponibile, mentre
`frontend/src/api/client.ts` pulisce automaticamente lo stato su 401. Un 403
ordinario può anche significare che manca il permesso per una sola operazione;
non va trasformato indiscriminatamente in logout. La verifica `/me` deve
distinguere la perdita di accesso all'applicazione dal rifiuto di una sua funzione.

`frontend/src/stream/useSessionStream.ts` esegue già un controllo di autenticazione
quando il collegamento eventi fallisce: riutilizzare quel percorso. Non promettere
revoca istantanea di una connessione già aperta in un'altra scheda sulla sola base
di `auth_request` o di un evento nella pagina corrente. Il contratto deve dichiarare
quando l'accesso viene ricontrollato e verificare anche il ritorno a una scheda
rimasta aperta.

In full sul Mac resta il login locale esistente. Il logout backend esiste già
(`backend/src/auth/routes.ts:355`): il lavoro riguarda il collegamento all'header
e la pulizia della UI. Per installazioni full con OIDC va consentito anche quel
logout; oggi `AuthGate` lo espone soltanto per `mode === "local"`. La revoca della
sessione ThothII non va descritta come logout globale dal fornitore d'identità.

### 4. Il default embedded contraddice l'adapter obbligatorio

Il piano dichiara compatibilità con descrittori senza `shell`, ma il contratto
richiede `adapter` in embedded. Inoltre, pretendere un nuovo bridge renderebbe
inutilizzabile la vecchia pagina Omics finché non fosse aggiornata.

Raccomandazione: risolvere i valori in un unico punto di configurazione:

- assenza di `shell`: embedded con adapter Omics predefinito;
- embedded senza `adapter`: `omics-portal`;
- full: nessun adapter istanziato;
- nome adapter sconosciuto: errore esplicito di configurazione.

L'adapter che legge lo stato già esistente rende questa compatibilità concreta.
Sul Mac rimangono espliciti `mode: full` e `defaultLocale: en`. La proiezione
pubblica può usare il `config.js` già presente; non serve un nuovo servizio di
configurazione. Va verificato anche il prefisso API `/datamart-builder/api` nel
montaggio Omics: il default frontend `/api` non basta a dimostrare che il deploy
funzioni. Prima si aggiorna il lettore del descrittore, poi il file installato,
poiché il lettore corrente rifiuta chiavi sconosciute.

### 5. Fullscreen e dark mode hanno già elementi riutilizzabili

ThothII possiede già token scuri in `frontend/src/index.css:67`, attivati anche da
`data-bs-theme="dark"`. Il lavoro è completarne la copertura e verificare contrasto,
form, menu e finestre, riutilizzando questi token.

Omics cambia la classe `fullscreen-enable` al click (`static/js/app.js:702`)
prima di conoscere il risultato. Il ramo di uscita usa metodi storici e non
contiene `document.exitFullscreen()`. Non va copiato nella shell full: l'icona
deve seguire lo stato effettivo, compresi Esc e richieste rifiutate. La correzione
equivalente dell'header Omics appartiene al suo modulo UI, non a un secondo
controllo fullscreen dentro ThothII embedded.

La fascia vuota sinistra si realizza con una misura CSS condivisa, almeno 20 px,
bilanciata con lo spazio destro. Non richiede un modulo di navigazione vuoto.
Poiché il documento è condiviso, verificare anche che stili globali ThothII e
contenuti sovrapposti non alterino header e sidebar del portale: il template Omics
contiene già correzioni per reset CSS e altezza `100vh`.

## Elementi da conservare

La lingua dell'interfaccia, quella delle domande al revisore e quella dei contenuti
del workspace hanno proprietari e durate diverse. Conservare la separazione di
ADR 0022: semplificarla in un'unica preferenza globale introdurrebbe errori in
ripresa e nei workspace italiani.

Precisare tre regole d'implementazione:

- una nuova sessione salva il locale UI effettivamente risolto, dopo il fallback
  delle traduzioni;
- una sessione esistente conserva la propria lingua anche se un altro revisore
  usa un'interfaccia diversa;
- per manifest precedenti senza campo lingua, usare la lingua del workspace come
  criterio di compatibilità e fissarla alla prima ripresa con un aggiornamento
  idempotente. Non dedurla dalla lingua del browser del nuovo revisore. La lingua
  storica esatta non è ricostruibile se il workspace è stato cambiato nel frattempo.

L'i18n resta il lavoro trasversale principale: include pagine amministrative,
errori, accessibilità e testi deterministici dei widget, anche quelli costruiti
fuori da React. Aggiungere soltanto i cataloghi dell'header non soddisfa la richiesta.
Il modello deve ricevere la lingua dal manifest autorevole, senza tradurre a
posteriori payload delle decisioni, SQL o contenuti del workspace.

## Struttura raccomandata

Un solo controller di shell alimenta l'interfaccia. In full gestisce preferenze
locali e header; in embedded riceve `{ locale, theme, fullscreen }` da un
`PortalAdapter.subscribe(...)`. I componenti applicativi usano quello stato e
non conoscono Omics. Nessun registro dinamico di plugin, protocollo di comandi o
controller separato per ciascun pulsante.

L'autenticazione continua a usare il modulo esistente, con presentazione dell'accesso
coerente con la shell. L'integrazione con un futuro portale richiede anche che il
suo lato server soddisfi il contratto di identità verificata: sostituire una classe
JavaScript non può da solo sostituire l'autenticazione server. Documentare insieme
l'adapter UI e la configurazione server Omics, senza introdurre nuove dipendenze
Omics nel workflow o nelle pagine ThothII.

## Verifiche necessarie prima della consegna

Verificare full sul Mac con default inglese, accesso/logout, tema e fullscreen;
embedded sul template Omics, con preferenze già impostate prima del montaggio,
cambio tema e lingua, Esc, assenza di header ThothII e descrittore precedente.
Verificare nuova sessione, ripresa, manifest precedente, ricaricamento durante
la revisione e perdita dell'accesso con collegamento eventi attivo.

Sono verifiche del comportamento, non motivi per costruire un'infrastruttura
generica. Questa revisione si basa sull'ispezione del sorgente; non sono stati
eseguiti test runtime né modificati i due applicativi.