Codex
d8a29bfbdd
Implement approved specification #32 and tickets #33-#37. Keep host authentication server-verified and pin session interaction language. Compile scoped base selectors for browser compatibility and retain full gutters during CSS pruning.
111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
shell:
|
|
mode: full
|
|
defaultLocale: en
|
|
```
|
|
|
|
Sul server Omics:
|
|
|
|
```yaml
|
|
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.
|
|
Full non istanzia adapter. `defaultLocale` inizializza full; in embedded il locale
|
|
proviene dal portale. L'autenticazione si configura separatamente dalla shell.
|
|
|
|
## API applicativa
|
|
|
|
```ts
|
|
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 |
|
|
|
|
L'attributo `lang` storicamente fisso a `en` nel template base non deve essere
|
|
usato come surrogato della lingua selezionata. Leggere il valore renderizzato dal
|
|
server evita anche di anticipare un cambio lingua prima che il form abbia successo.
|
|
|
|
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 | autenticazione ThothII configurata | 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 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. Non occorre implementare ora iframe o un secondo 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.
|