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.