ThothII/docs/plans/2026-09-13-full-shell-and-portal-integration.md

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.

Specifica consolidata: Full shell, integrazione Omics e interfaccia bilingue, pubblicata come specifica su Gitea. Ticket approvati: Full sul Mac, Embedded Omics, Sessioni bilingui, Traduzione completa, Consegna verificata. 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, la modalità embedded non mostra header proprio e la modalità full non dipende da Omics Portal.