vr-app/docs/02-decisions.md

Décisions d'architecture du module VR

Arbitrées le 2026-09-03, à partir du relevé de code de 00-phase1-etat-des-lieux.md. Ne pas rouvrir sans raison technique forte. Les décisions antérieures (Unity vs WebXR, pricing add-on, MDM, types de section) restent dans ../../DOCS/v2/vr-quest-unity-plan.md §6 à §10.

---

D1 — Le contenu VR est un type de section, pas une entité parallèle

Retenu : SectionScene3D, dans une Configuration existante.

Le manifeste de scène est une projection de la section, générée par le serveur, jamais saisie à la main. Conséquences, toutes acquises sans code neuf :

On hérite de	Parce que
La publication	c'est une section, elle part dans /configuration/{id}/export
L'offline	GetReferencedResourceIds(language) est implémenté par sous-type — on l'implémente une fois
Les stats par canal	VisitEvent porte déjà AppType
Le multilingue	List<TranslationDTO> jsonb, comme le reste
Le quota stockage	SUM(SizeBytes) sur les Resource référencées
L'affichage web / mobile	une section est rendue par les 3 clients visiteurs — c'est ce qui rend l'add-on « contenu immersif » vendable sans casque

Corollaire : GeoPoint est l'objet hotspot unique. Il porte déjà Title, Description, ImageResource et Contents (titre + description + Resource audio, multilingue). Il lui manque une position locale (x, y, z) + rotation à côté de son Geometry PostGIS. Pas de nouvel objet POI.

Écarté : une entité VrScene autonome — elle aurait obligé à réécrire publication, versionnement, cache offline, quotas et stats.

Écarté aussi, pour la V1 : rendre les 13 types de section en immersif. Le §8 du plan du 31/08 garde sa validité comme cap (Menu / Video 360 / Slider / Map gagnent vraiment en VR), mais ce n'est pas le périmètre de la V1 : la V1 rend une scène, pas un CMS flottant.

---

D2 — Le placement se fait dans le viewer, au clic

Retenu : le viewer THREE.js est aussi l'éditeur de placement.

Clic dans la scène → raycast sur le sol → position. Poignée de rotation sur l'objet sélectionné, panneau numérique à côté pour ajuster au centimètre. Pas d'éditeur 3D complet, pas de gizmo de translation sur 3 axes.

Coût marginal quasi nul : le viewer doit exister de toute façon pour la preview (§3.6 du cahier des charges). C'est le seul mécanisme où le client voit ce qu'il compose.

⚠️ Ce que ça engage : le viewer cesse d'être en lecture seule. Il lui faut un état d'édition, un undo, et un enregistrement explicite. À ne pas sous-estimer — c'est la moitié de son coût.

Écartés : la mini-carte 2D vue de dessus (il aurait fallu produire un rendu orthographique du monde, et le client place à l'aveugle sur la hauteur) ; les ancrages prédéfinis (composition pauvre, sensation de gabarit — mauvais en démo commerciale).

---

D3 — Un seul viewer, app web autonome, partagé par les quatre fronts

Retenu : le viewer est une application web autonome nourrie par une URL de manifeste. Précisé le 2026-09-03 : il ne sert pas deux fronts mais quatre.

Front	Comment il l'héberge	Mode
manager-app (Flutter Web)	iframe (HtmlElementView) + postMessage	édition
visitapp-web (Next.js)	composant, ou iframe si plus simple	lecture
mymuseum-visitapp (Flutter mobile)	WebView servant le viewer empaqueté dans l'app	lecture, hors ligne
vr-app (Unity/Quest)	❌ pas concerné — Unity a son propre rendu natif	—

Un seul moteur de rendu 3D pour tout l'écosystème. C'est ce qui attaque de front le risque n°2 du plan d'août (« nouvelle stack, zéro mutualisation ») : le rendu 3D n'est pas un quatrième front, c'est un composant partagé.

Sur Flutter mobile, il n'y a pas d'alternative sérieuse : model_viewer_plus, la solution habituelle, est elle-même un WebView autour de <model-viewer> de Google. Autant que ce soit notre viewer dans ce WebView, avec nos hotspots et notre manifeste, qu'un composant tiers qu'on ne contrôle pas.

L'offline mobile : souhaitable, pas bloquant — arbitré le 2026-09-03

mymuseum-visitapp est offline-first, et un WebView pointant sur une URL distante casserait ça. Thomas a tranché : si la 3D hors ligne s'avère trop coûteuse, on l'assume et on le dit au client dans manager-app. C'est acceptable, et surtout c'est déjà la convention de la maison :

• SectionVideo.GetReferencedResourceIds (SectionVideo.cs:25-27) exclut explicitement une vidéo dont la source est une URL http — elle ne part pas hors ligne ;
• SectionWeb ne collecte que sa vignette.

Une scène 3D non disponible hors ligne serait donc le troisième cas d'une règle existante, pas une exception. Rien à inventer, juste à signaler dans l'éditeur.

Ceci dit, c'est probablement faisable, et le coût n'est pas dans le rendu mais dans la plomberie : viewer empaqueté dans les assets Flutter, servi depuis une origine locale, GLB téléchargés dans le dossier documents, URL du manifeste réécrites en chemins locaux. Le pipeline offline fait déjà tout ça pour les médias 2D. À évaluer au moment du portage mobile, pas maintenant.

⚠️ Les trois règles à poser dès la V1 — indépendamment de l'offline

Elles ne coûtent rien maintenant, elles coûtent une réécriture plus tard, et elles sont de toute façon du bon design : un viewer qui ne sait pas d'où viennent ses données est un viewer réutilisable.

1. Le viewer est un jeu de fichiers statiques, embarquable dans les assets d'une app Flutter et servable depuis une origine locale. Pas de build qui suppose un serveur.
2. Aucune URL d'API en dur dans le viewer. Il ne connaît que le manifeste qu'on lui donne — toutes les URL d'assets viennent de assets[].url. C'est ce qui permet de lui passer un manifeste dont les URL ont été réécrites en chemins locaux par l'app, exactement comme le fait déjà le pipeline offline pour les médias.
3. Le manifeste est une entrée, pas un fetch. Le viewer accepte un manifeste injecté (postMessage / paramètre), pas seulement une URL à charger.

Ce que ça débloque au passage

Le 360 et le GLB s'affichent alors en web et en mobile, pas seulement au casque — c'est exactement la part de l'add-on « contenu immersif » qui se vend sans casque, et sur laquelle repose son pricing (vr-quest-unity-plan.md §6).

⚠️ Rappel de contrat : le viewer est un aperçu indicatif — placement, échelle, composition. Pas un rendu final. Alignement à tenir : même tone mapping, même HDRI d'environnement, PBR core glTF uniquement. La validation réelle passe par une publication sur canal de test et un essai au casque.

---

D4 — La borne se réinitialise à la repose du casque

Retenu : détection du retrait (capteur de proximité) → fondu au noir, reset de la scène, retour au menu de sélection dans la langue par défaut.

Précédent direct dans l'écosystème : le retour à l'accueil de la borne tablette après 5 min (DOCS/kanban/done/140-*). Un agent n'a rien à faire, ce qui est cohérent avec l'argument qui avait fait retenir Unity — l'exploitation sans surveillance.

Le timeout d'inactivité reste utile en filet secondaire (casque posé sans être retiré proprement), pas comme mécanisme principal.

---

D5 — La V1 consomme des mondes uploadés ; la génération vient juste après

Retenu : upload manuel d'abord, génération intégrée ensuite.

En V1, le monde est un GLB uploadé dans la médiathèque — produit hors ligne, sur le site de World Labs, par nous, pour les clients pilotes. Le module VR devient alors indépendant du socle Studio et livrable seul, sans attendre les lots 0 / 1 / 3.

La génération in-app (le bouton « Générer un monde » du §3.1 du cahier des charges) arrive quand ces lots existent, sans rien casser : au bout du pipeline, c'est la même Resource GLB référencée par la même section. La seule chose à faire dès maintenant, c'est de ne rien coder qui empêche cette greffe — donc :

• le monde est toujours un ResourceId, jamais un chemin ou une URL en dur ;
• Resource.AiProvenance est prévu dans le manifeste dès la V1, même vide ;
• Marble n'est jamais appelé depuis le code VR : le jour venu, ce sera un IGenerationProvider de plus (ProviderKey = "worldlabs", GenerationKind.World), pas un client HTTP maison.

Écarté : la génération dès la V1 (elle mettait plusieurs semaines de backend V2 devant la première scène visible) et le compromis « lot 0 seul + appel Marble en dur » (il recrée exactement la dette que studio-plan.md cherche à éviter : modèle codé en dur, pas de journal, pas de réservation de crédits).

---

D6 — Personnages 3D : catalogue externe sous licence, mais branché sur la médiathèque dès le jour 1

Retenu : une petite bibliothèque de personnages stylisés sous licence (modèles type Quaternius / Kenney ou un pack payant, animations idle type Mixamo), livrée comme catalogue de départ. Le client choisit, il ne modélise pas.

⚠️ Condition posée par Thomas, et elle est structurante : « il faut quand même prévoir vite d'intégrer ce qu'on génère dans le Studio ». Donc le catalogue n'est pas une liste en dur dans l'APK. Dès la V1 :

• un personnage 3D est un Resource de type Model3D dans la médiathèque, comme n'importe quel autre asset — le catalogue de départ est juste un jeu de ressources pré-chargées, marquées comme telles ;
• Persona.Model3DResourceId pointe dessus. Le jour où le Studio produit un GLB, il remplace la valeur du champ, il ne demande aucune refonte ;
• la licence de chaque modèle du catalogue de départ est tracée dans AiProvenance.rightsHolder (ou son équivalent pour un asset non généré) — sujet droits, pas seulement technique, pour des institutions publiques.

Écartés : le studio 3D sur devis en V1 (aucun pilote ne pourrait composer une scène sans payer d'abord une prestation) et l'absence de personnage en V1 (c'est l'élément le plus démonstratif).

---

Ce qui reste ouvert

Sujet	Où c'est décrit	Ce qui manque pour trancher
KTX2 / Meshopt : où s'exécute la transformation ?	état des lieux F5	Binaires natifs dans l'image Docker vs GLB servi tel quel en V1. Défaut retenu faute d'objection : tel quel en V1, avec le bloc variants par asset posé dans le manifeste dès le départ pour que l'ajout n'y touche pas. À rouvrir dès qu'on aura un vrai poids de monde Marble mesuré
Go/no-go client pilote	vr-quest-unity-plan.md §5	Décision produit, inchangée : ne pas engager l'app Unity complète sans un lieu pilote identifié. D5 réduit l'enjeu — la chaîne technique se prouve sans client