5.9 KiB
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.