Portal Shell Adapter v1

Contratto minimo della presentazione embedded. La revisione approvata il 2026-09-13 sostituisce il precedente trasporto a eventi personalizzati con l'osservazione del documento condiviso. Non trasferisce identità, token o stato di autenticazione.

Configurazione

Sul Mac:

shell:
  mode: full
  defaultLocale: en

Sul server Omics:

shell:
  mode: embedded
  adapter: omics-portal

Se shell o mode sono omessi, la modalità è embedded. L'adapter embedded predefinito è omics-portal; un nome sconosciuto è un errore di configurazione. Questi default sono normalizzati dal CLI prima della proiezione. Nel browser, shell interamente omessa ha gli stessi default, ma un oggetto shell parziale senza mode o defaultLocale viene rifiutato: non scrivere proiezioni a mano. Full non istanzia adapter. defaultLocale inizializza full; in embedded il locale proviene dal portale. L'autenticazione si configura separatamente dalla shell.

API applicativa

export type PortalSnapshot = {
  locale: string;
  theme: "light" | "dark";
  fullscreen: boolean;
};

export interface PortalAdapter {
  subscribe(
    onState: (state: PortalSnapshot) => void,
    onError: (error: Error) => void,
  ): () => void;
}

Una sottoscrizione installa gli osservatori e consegna lo snapshot iniziale senza richiedere messaggi all'altro applicativo. Gli aggiornamenti contengono snapshot completi e validati. La disiscrizione elimina tutti i listener e osservatori. La lingua viene risolta tramite i cataloghi UI, con fallback inglese.

Implementazione Omics

L'integrazione monta React nel documento Django, non in un iframe.

Dato	Fonte privata dell'adapter	Aggiornamento
Locale	`data-lang` del selettore `.omics-language-select`	nuova pagina Django dopo `set_language`
Tema	`data-bs-theme` su `html`	osservazione limitata a quell'attributo
Fullscreen	stato effettivo del documento	evento del browser, inclusa uscita con Esc

Il template Omics aggiornato allinea anche html lang alla lingua Django, ma la fonte dell'adapter rimane select.omics-language-select[data-lang]. Leggere il valore renderizzato evita di anticipare un cambio lingua prima che il form abbia successo. Cambiare soltanto select.value o data-lang senza il normale reload non è un trasporto runtime implementato per la lingua.

L'assenza del contesto host atteso produce un errore di integrazione; non abilita controlli locali. Non si introducono eventi ready/state, handshake, timeout, versioni dei messaggi o comandi duplicati. Selettori e dettagli Omics non devono essere letti dai componenti applicativi.

Proprietà per modalità

Funzione	Full	Embedded
Header	ThothII	solo Omics
Lingua	selettore locale	selettore Omics, normale reload Django
Tema	toggle locale light/dark	stato Omics
Fullscreen	controllo locale, stato reale	controllo Omics, stato reale
Login/logout	ThothII local/OIDC; upstream non offre logout locale	autenticazione Omics esistente
Nome utente	header ThothII	header Omics
Rotellina amministrativa	mai	eventuale comando del portale

Accesso e continuità

Il server Omics verifica l'accesso a Datamart Builder e il proxy trasmette i principal header normalizzati al backend ThothII. La UI usa /me; non effettua un secondo login. Un altro portale deve soddisfare anche questo contratto server, oltre a fornire una nuova implementazione dell'adapter UI.

Il contratto upstream specifica header, origine, rete e configurazioni incompatibili. Lo snapshot non può contenere authenticated, utente, ruoli, cookie o token; un evento browser non autorizza una richiesta API. Il prefisso API viene configurato separatamente prima del caricamento React, non viene dedotto dall'adapter.

Il logout del portale segue la sua navigazione. Una perdita di accesso rilevata dal server chiude lo stato protetto; un 403 di una singola operazione non equivale automaticamente a logout. La riconnessione degli eventi e il ritorno alla pagina ricontrollano l'accesso. Non si garantisce revoca istantanea di una connessione aperta in un'altra scheda attraverso il solo controllo iniziale del proxy.

Il cambio lingua può ricaricare la pagina: conservare la selezione della sessione, proteggere le modifiche non salvate e non avviare una nuova generazione al reload. Non si conserva una trascrizione integrale nel browser. La lingua della sessione rimane quella registrata nel manifest, secondo ADR 0022.

Sostituzione e verifiche

Un nuovo adapter può usare un diverso documento o trasporto, ma deve rispettare la stessa sottoscrizione e mantenere la conoscenza del portale nella propria implementazione. Oggi ShellProvider istanzia direttamente OmicsPortalAdapter: per sostituirlo aggiornare quel punto e i nomi accettati in tools/tht/internal/config/shell.go e frontend/src/api/runtime-config.ts. Non è disponibile il caricamento dinamico di classi da una stringa YAML. Non occorre implementare ora iframe o un secondo portale.

La nuova implementazione deve pubblicare uno snapshot iniziale completo, poi gli aggiornamenti; segnalare contesto invalido; liberare tutti i listener alla disiscrizione. Locale ben formato ma non tradotto significa fallback inglese; locale assente/malformato e tema diverso da light/dark sono errori di integrazione. Non cambiare componenti applicativi o workflow per aggiungere selettori specifici del nuovo portale.

Verificare snapshot prima/dopo il montaggio, tema, fullscreen con Esc, cleanup, contesto host mancante, assenza di header ThothII embedded, accesso singolo, locale dopo reload e compatibilità del prefisso API. Full deve funzionare senza alcun elemento Omics presente.

Vedere anche architettura del rendering e matrice di accettazione.

5.9 KiB Raw Blame History