# Piano — Full shell e integrazione con il portale

Stato: implementazione completata e installata sul Mac; deploy server non eseguito.

Esiti e limiti del collaudo: [rapporto di verifica](../reports/2026-09-13-full-shell-implementation.md).

Specifica consolidata: [Full shell, integrazione Omics e interfaccia bilingue](2026-09-13-full-shell-spec.md),
pubblicata come [specifica su Gitea](https://git.tylconsulting.it/mptyl/ThothII/issues/32).
Ticket approvati: [Full sul Mac](https://git.tylconsulting.it/mptyl/ThothII/issues/33),
[Embedded Omics](https://git.tylconsulting.it/mptyl/ThothII/issues/34),
[Sessioni bilingui](https://git.tylconsulting.it/mptyl/ThothII/issues/35),
[Traduzione completa](https://git.tylconsulting.it/mptyl/ThothII/issues/36),
[Consegna verificata](https://git.tylconsulting.it/mptyl/ThothII/issues/37).
Le dipendenze sono registrate anche nativamente sul tracker.

## Obiettivo

Aggiungere una shell autonoma `full` mantenendo compatibile l'integrazione corrente `embedded`
con Omics Portal. La complessità del portale deve restare confinata a un `PortalAdapter`.

## Regole definitive

- `embedded` è il default e non renderizza alcun header ThothII.
- La configurazione installata su questo Mac imposta `shell.mode: full` e
  `shell.defaultLocale: en`.
- Il deploy server imposta `shell.mode: embedded` e `shell.adapter: omics-portal`.
- `full` renderizza header, rail sinistro vuoto di almeno 20 px e logout locale.
- Fullscreen è uno stato separato dalla shell: il pulsante entra/esce dalla Fullscreen API e
  l'icona riflette anche l'uscita con `Esc`.
- Full include lingua, tema `light/dark`, fullscreen e nome utente; non include la rotellina
  amministrativa.
- Embedded riceve dal portale solo `locale`, `theme` e `fullscreen`; il server verifica l'accesso.
- Login e logout embedded restano responsabilità di Omics Portal.
- La lingua UI è separata dalla lingua di interazione fissata nella sessione.

## Sequenza di implementazione

### 1. Configurazione e stato shell

- Aggiungere `shell.mode`, `shell.defaultLocale` e `shell.adapter` al descrittore di
  installazione, mantenendo `embedded` come default quando `shell` non è presente.
- Proiettare nel runtime frontend solo configurazione non segreta.
- Centralizzare lo stato shell in un controller; i componenti non devono leggere direttamente
  il portale.

### 2. Adapter e bridge Omics

- Implementare `PortalAdapter` con la sola API `subscribe`.
- Implementare `OmicsPortalAdapter` osservando il documento condiviso, secondo il contratto rivisto.
- Leggere il locale dal selettore renderizzato da Django, osservare il tema e ascoltare il fullscreen.
- Conservare il cambio lingua tramite reload Omics e il percorso server di autenticazione esistente.
- Validare snapshot e cleanup; in caso di errore mostrare un messaggio di integrazione in
  embedded, senza fallback a controlli locali.

### 3. i18n e lingua del modello

- Introdurre cataloghi UI estendibili, inizialmente `it` e `en`, con fallback inglese.
- Usare il locale corrente per le nuove sessioni.
- Persistire nel manifest la lingua di interazione e usarla per domande, spiegazioni e scelte
  del revisore; una ripresa conserva quella lingua.
- Non tradurre SQL, identificatori o contenuti del workspace.

### 4. Shell full

- Renderizzare header solo in `full`.
- Collegare selettore lingua, tema, fullscreen, nome utente e logout alle funzioni già esistenti
  o equivalenti del frontend/backend.
- Implementare il cambio icona e la sincronizzazione con `fullscreenchange`.
- Applicare il rail sinistro vuoto con larghezza base semplice e non inferiore a 20 px.

### 5. Verifica

- Unit test per validazione adapter, cambio stato, fallback locale e regole di sessione.
- Test frontend per entrambe le shell, logout full e fullscreen con `Esc`.
- Test backend per il passaggio della lingua nelle nuove sessioni e la conservazione in resume.
- Test di integrazione Omics per preferenze iniziali, tema, fullscreen, locale dopo reload e accesso.
- Build frontend/backend, suite harness e build documentale.

## Fuori ambito

- Cambiare il proxy/authentication chain già operativo.
- Passare a iframe o introdurre `postMessage`.
- Trasferire token o oggetti utente nel browser bridge.
- Aggiungere una shell `system` per il tema o un terzo tema.
- Implementare un adapter per un secondo portale: deve solo essere possibile sostituire quello
  Omics tramite la stessa interfaccia.

## Gate di approvazione

L'implementazione è approvabile quando il codice rispetta il [contratto v1](../contracts/portal-shell-adapter-v1.md),
la modalità embedded non mostra header proprio e la modalità full non dipende da Omics Portal.