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.
100 lines
10 KiB
Markdown
100 lines
10 KiB
Markdown
# Full shell, integrazione Omics e interfaccia bilingue
|
|
|
|
## Problem Statement
|
|
|
|
ThothII è utilizzabile nel contenitore di Omics Portal, ma quando viene avviato
|
|
autonomamente deve offrire i comandi generali che oggi appartengono al portale.
|
|
Gli utenti devono poter scegliere italiano o inglese per l'interfaccia e per le
|
|
nuove conversazioni con il modello, senza modificare la lingua dei contenuti del
|
|
workspace. L'integrazione server deve conservare l'accesso già effettuato in Omics.
|
|
|
|
## Solution
|
|
|
|
Due modalità di installazione: Full Thoth Shell con header autonomo e Embedded
|
|
Thoth Shell pilotata dall'header del portale. Sul Mac si installa full con inglese
|
|
predefinito. Un Portal Shell Adapter sostituibile concentra le conoscenze Omics;
|
|
l'autenticazione utilizza i percorsi già esistenti. La lingua di interazione
|
|
rimane fissata per tutta la durata di una sessione, comprese le riprese.
|
|
|
|
## User Stories
|
|
|
|
1. As an operatore, I want scegliere full o embedded durante l'installazione, so that il contenitore corrisponda al luogo di utilizzo.
|
|
2. As an operatore Mac, I want full con inglese predefinito, so that l'applicazione sia autonoma appena aperta.
|
|
3. As an operatore di un'installazione precedente, I want mantenere embedded senza aggiungere configurazioni obbligatorie, so that un aggiornamento non interrompa l'integrazione Omics.
|
|
4. As an utente full, I want un header con lingua, tema, fullscreen e nome utente, so that i comandi generali siano sempre raggiungibili.
|
|
5. As an utente full, I want una fascia sinistra vuota di almeno 20 px bilanciata con lo spazio destro, so that il contenuto abbia margini coerenti.
|
|
6. As an utente full, I want nessuna rotellina amministrativa del portale, so that il contenitore mostri solo i comandi richiesti.
|
|
7. As an utente full, I want aprire il logout dal nome utente, so that possa terminare il mio accesso.
|
|
8. As an utente locale, I want usare le credenziali ThothII esistenti, so that non debba configurare Omics.
|
|
9. As an utente full con OIDC, I want terminare la sessione ThothII, so that il logout non sia limitato al login locale.
|
|
10. As an utente Omics, I want aprire Datamart Builder già autenticato, so that non debba effettuare un secondo accesso.
|
|
11. As an utente embedded, I want un solo header fornito da Omics, so that non compaiano comandi duplicati.
|
|
12. As an utente embedded, I want che login e logout siano gestiti dal portale, so that l'accesso sia coerente con le altre pagine.
|
|
13. As an utente embedded, I want che ThothII recepisca le preferenze già impostate prima dell'apertura, so that lingua e tema siano subito corretti.
|
|
14. As an utente, I want scegliere light o dark, so that la leggibilità corrisponda alle condizioni ambientali.
|
|
15. As an utente, I want leggere form, menu, errori e finestre anche in dark, so that il tema sia completo.
|
|
16. As an utente full, I want entrare in fullscreen del browser, so that il browser lasci spazio all'applicazione.
|
|
17. As an utente, I want vedere l'icona di uscita quando il fullscreen è attivo e l'icona iniziale dopo Esc, so that il comando rappresenti lo stato effettivo.
|
|
18. As an utente, I want un messaggio comprensibile se il browser rifiuta il fullscreen, so that il controllo non mostri uno stato inesistente.
|
|
19. As an utente, I want tutte le label e i testi non generati dal modello in italiano o inglese, so that possa usare l'applicazione nella lingua scelta.
|
|
20. As an utente assistito da lettore di schermo, I want nomi accessibili e messaggi tradotti, so that i controlli siano utilizzabili quanto quelli visivi.
|
|
21. As an utente embedded, I want il cambio lingua segua il normale ricaricamento Omics, so that tutta la pagina condivida la lingua.
|
|
22. As an revisore, I want ritrovare la sessione dopo quel ricaricamento e proteggere le modifiche non salvate, so that non perda il lavoro.
|
|
23. As an revisore, I want le nuove domande e scelte del modello nella lingua UI selezionata, so that l'interazione sia comprensibile.
|
|
24. As an revisore, I want riprendere una sessione nella sua lingua originale, so that le preferenze del nuovo browser non cambino il workflow.
|
|
25. As an revisore di sessioni precedenti, I want una regola stabile per i manifest privi della lingua di interazione, so that le riprese restino prevedibili.
|
|
26. As an responsabile dei dati, I want conservare lingua e contenuto di workspace, SQL, identificatori e valori, so that una preferenza UI non alteri i dati.
|
|
27. As an manutentore, I want aggiungere cataloghi per altre lingue con fallback inglese, so that l'i18n sia estendibile.
|
|
28. As an integratore, I want sostituire OmicsPortalAdapter con un altro adapter della stessa interfaccia, so that un nuovo portale non richieda modifiche alle pagine o al workflow.
|
|
29. As an utente il cui accesso scade, I want che lo stato protetto venga chiuso e il rientro segua il contenitore, so that non compaia un login ThothII in embedded.
|
|
30. As an operatore, I want documentazione accurata di configurazione, autenticazione, adapter, migrazione e verifiche, so that il deploy server sia ripetibile.
|
|
|
|
## Implementation Decisions
|
|
|
|
- La configurazione installata distingue topologia, autenticazione e shell. Shell omessa significa embedded con adapter Omics predefinito; adapter sconosciuti sono errori espliciti. Full non istanzia adapter.
|
|
- La configurazione frontend pubblica contiene soltanto dati non segreti e usa il meccanismo runtime esistente, compreso il prefisso API necessario al montaggio Omics.
|
|
- Un controller di shell espone preferenze e stato; i componenti non accedono direttamente al portale.
|
|
- L'interfaccia PortalAdapter offre una sottoscrizione con snapshot iniziale, aggiornamenti, errori e disiscrizione. Lo snapshot contiene locale, tema light/dark e fullscreen.
|
|
- L'implementazione Omics legge la lingua effettivamente renderizzata dal selettore, osserva il tema sul documento e ascolta il fullscreen del browser. Non introduce handshake, eventi personalizzati o polling per le preferenze. Il contratto DOM è privato dell'adapter.
|
|
- Il montaggio resta nello stesso documento. Nessun header o comando locale di autenticazione/presentazione viene introdotto in embedded.
|
|
- Il server resta autorevole per identità e autorizzazioni. Il bridge UI non trasmette token, utente o flag authenticated. La catena di identità fidata esistente viene conservata.
|
|
- I rifiuti di accesso all'applicazione devono essere distinti dai 403 relativi a una singola operazione. Ricontrollare l'accesso alla riconnessione e al ritorno alla pagina; non promettere revoca istantanea di altre schede tramite il solo proxy.
|
|
- Full riutilizza login e logout esistenti, preserva le protezioni dalle modifiche non salvate e abilita il logout anche per sessioni ThothII OIDC. Il logout globale dall'identity provider non è implicito.
|
|
- Fullscreen è indipendente dalla modalità full. L'icona segue lo stato effettivo e le richieste rifiutate sono gestite. I token dark esistenti vengono completati, con verifica dei contenuti sovrapposti e dell'isolamento degli stili embedded.
|
|
- L'i18n utilizza cataloghi estendibili EN/IT con fallback inglese, comprese label, aiuti, placeholder, accessibilità, errori e widget deterministici. I payload tecnici restano stabili.
|
|
- La lingua di interazione viene scelta dal locale UI risolto, salvata nel manifest e propagata al contesto del modello. Resume non accetta override dal browser.
|
|
- Le sessioni precedenti prive del campo usano la lingua del workspace come compatibilità; il valore viene fissato alla prima ripresa mediante aggiornamento idempotente. Non si pretende di ricostruire una lingua storica non registrata.
|
|
- Il cambio lingua Omics mantiene la navigazione Django. La selezione della sessione deve sopravvivere alla navigazione; le modifiche non salvate devono essere protette, senza avviare una nuova generazione implicitamente.
|
|
|
|
## Testing Decisions
|
|
|
|
I punti di verifica erano già approvati nel piano: comportamento della shell e
|
|
dell'accesso dall'interfaccia, contratto pubblico dell'adapter, creazione/ripresa
|
|
tramite API e CLI del workflow, configurazione d'installazione e integrazione
|
|
Omics. Non si richiede una nuova approvazione degli stessi punti.
|
|
|
|
- Test comportamentali: stato osservabile, testo e controlli accessibili, permessi e lingua persistita; evitare metodi privati o asserzioni sull'organizzazione interna.
|
|
- Riutilizzare i test AuthGate/AppShell con API simulate al confine HTTP, quelli delle route sessioni e quelli pubblici del repository/CLI del workflow.
|
|
- Verificare adapter con un documento equivalente al template reale, preferenze iniziali, aggiornamenti e cleanup; includere montaggio ripetuto.
|
|
- Verificare nuova sessione, resume con lingua UI diversa, manifest precedente e input locale invalido; il contesto fornito al modello deve contenere la lingua persistita.
|
|
- Verificare fullscreen con ingresso, uscita, Esc e rifiuto; entrambe le modalità con dark, form e menu aperti.
|
|
- Verificare accesso embedded senza secondo login, scadenza/403, riconnessione degli eventi e ritorno a una scheda; verificare logout full e protezione dei dati di un utente precedente.
|
|
- Typecheck e test mirati durante lo sviluppo; suite complete alla fine, build documentale e prova browser proporzionata. Non usare chiamate reali al modello per i test deterministici.
|
|
|
|
## Out of Scope
|
|
|
|
- Deploy sul server di produzione o modifica delle credenziali.
|
|
- Seconda implementazione per un portale futuro, iframe e protocollo postMessage.
|
|
- Nuovo sistema di autenticazione, propagazione di token nel browser o logout globale OIDC.
|
|
- Tema system, ingresso automatico in fullscreen, rotellina amministrativa nell'header full.
|
|
- Traduzione di SQL, dati, identificatori o contenuti del workspace; traduzione a posteriori delle decisioni generate dal modello.
|
|
- Persistenza di una trascrizione integrale delle conversazioni.
|
|
|
|
## Further Notes
|
|
|
|
La revisione della semplificazione del 2026-09-13 è stata approvata dall'utente e
|
|
prevale sui dettagli superati del primo contratto a eventi. La specifica consolida
|
|
le decisioni senza riaprire l'intervista. Le modifiche vengono revisionate sui due
|
|
assi Standards/Spec e committate sul branch corrente, preservando i cambiamenti
|
|
preesistenti estranei a questa funzionalità.
|