Define vertical slice technical plan

2026-08-07 15:44:33 +02:00
1 parent c38e09a663
commit 9d4a89f355
@@ -85,4 +85,5 @@ Test d'intégration du POC B :
 - Objectifs et protocole du POC B : docs/POC_B.md
 - Bilan technique du POC B : docs/POC_B_TECHNICAL_BASELINE.md
 - Barrières techniques de production : docs/ENGINEERING_GUARDRAILS.md
 - Cadrage technique de la verticale : docs/VERTICAL_SLICE_TECHNICAL_PLAN.md
 - Décisions d'architecture : docs/adr/
@@ -6,13 +6,15 @@
 - Nature : plan directeur de conception et de production
 - Version : 0.3
- État : POC A et POC B validés ; cadrage de la verticale à préparer
+- État : POC A et POC B validés ; cadrage technique de la verticale proposé
 - Titre : titre de travail, à valider juridiquement avant toute annonce publique
 - Prix commercial : volontairement non défini à ce stade
 Les baselines techniques consolidées sont conservées dans
 [POC_A_TECHNICAL_BASELINE.md](POC_A_TECHNICAL_BASELINE.md) et
 [POC_B_TECHNICAL_BASELINE.md](POC_B_TECHNICAL_BASELINE.md).
 Le périmètre et l'architecture proposés pour le prochain jalon sont décrits dans
 [VERTICAL_SLICE_TECHNICAL_PLAN.md](VERTICAL_SLICE_TECHNICAL_PLAN.md).
 ## Pitch
@@ -0,0 +1,596 @@
 # Verticale jouable — Cadrage technique proposé
 ## Statut
 - Date : 7 août 2026.
 - État : proposition à valider avant le premier code de production.
 - Jalon : verticale jouable, après validation des POC A et B.
 - Durée directrice du plan général : quatre à six mois.
 - Moteur figé pour le jalon : Godot 4.7.1.
 - Références : baselines techniques des POC A et B.
 Ce document définit ce que la verticale doit prouver, les frontières de son
 implémentation et l'ordre de construction. Il ne remplace ni le game design
 général ni les baselines des prototypes.
 ## 1. Question à valider
 La verticale doit répondre à une seule question principale :
 > Piloter, chercher une épave réellement cachée, l'identifier, récupérer une
 > preuve et revenir sous contrainte forme-t-il une boucle claire et assez
 > satisfaisante pour porter une campagne ?
 Les POC ont validé séparément le véhicule et le langage du sonar. La verticale
 doit vérifier leur combinaison dans une mission complète avec préparation,
 objectif, conséquence et progression.
 ## 2. Parcours joueur retenu
 La verticale utilise le premier navire de la campagne : le bâtiment de
 prospection contemporain du précédent opérateur.
 1. Consulter un message de contrat et une fiche de secteur.
 2. Accepter la mission avec un équipement imposé ou très limité.
 3. Déployer le mini-sous-marin à proximité de la zone probable.
 4. Suivre le relief tout en surveillant oxygène, propulsion et coque.
 5. Utiliser manuellement le sonar bathymétrique pour trouver un accès masqué.
 6. Découvrir l'épave sans marqueur posé directement sur elle.
 7. Observer deux indices permettant de confirmer son identité.
 8. Dégager ou ouvrir un accès avec une interaction contextuelle simple.
 9. Récupérer une caisse ou un journal lié à la piste du U-Boot.
 10. Calculer la marge de retour et remonter au bateau.
 11. Consulter le débriefing, conserver la preuve et vendre un objet secondaire.
 12. Acheter une première amélioration dont l'effet est vérifiable en replongeant.
 Durée cible initiale : 15 à 25 minutes pour une première réussite, hors reprise
 après échec. Ce nombre sera corrigé par playtest.
 ## 3. Périmètre obligatoire
 ### Plongée
 - POV intérieur et hublot circulaire.
 - Pilotage inertiel avec retour immédiat des commandes.
 - Oxygène, batterie de propulsion, profondeur et intégrité.
 - Alarmes texte, couleur et son.
 - Estimation de retour compréhensible.
 - Sonar manuel progressif, compact et agrandissable.
 - Un terrain conçu à la main avec une route sûre et une route plus risquée.
 - Une épave identifiable et une anomalie secondaire optionnelle.
 - Une interaction d'ouverture et une récupération.
 - Retour réussi, abandon volontaire et perte du véhicule.
 ### Métajeu minimal
 - Un écran de contrat.
 - Une fiche historique courte.
 - Un écran de préparation limité.
 - Un débriefing.
 - Une vente ou restitution.
 - Une amélioration achetable.
 - Une sauvegarde locale versionnée.
 ### Qualité minimale
 - Clavier-souris remappable.
 - Textes français structurés pour une future localisation anglaise.
 - Taille du texte et réduction des mouvements accessibles depuis les réglages.
 - Chargement, sauvegarde et reprise d'une session sans état incohérent.
 - Barrière qualité reproductible sur macOS, puis Windows et Linux avant la fin
  du jalon.
 ## 4. Hors périmètre ferme
 - Deuxième grande épave.
 - Carte maritime complète et pilotage de surface.
 - Trois ports ou marchés dynamiques.
 - Relations de personnages complètes.
 - Dialogue à embranchements complexe.
 - Plusieurs classes de coque.
 - Plusieurs outils de salvage simulés.
 - Intérieur complet de l'épave.
 - Véritable grotte à plusieurs niveaux ou surplomb complexe.
 - Génération procédurale de site majeur.
 - Corruption surnaturelle avancée.
 - Doublage, cinématique ou art final.
 - Manette certifiée, succès, cloud ou intégration de boutique.
 - Import d'une sauvegarde de démo.
 Une idée hors périmètre peut être inscrite dans le backlog. Elle ne peut entrer
 dans la verticale sans retirer un élément de coût comparable et mettre à jour ce
 document.
 ## 5. Critères de réussite
 ### Compréhension humaine
 - Au moins 8 testeurs sur 10 trouvent l'accès à l'épave en 5 à 10 minutes après
  l'arrivée dans la zone de recherche, sans aide orale.
 - Au moins 8 sur 10 comprennent le rapport entre bleu, vert, jaune et hauteur.
 - Au moins 8 sur 10 identifient la caisse ou l'anomalie sur le sonar.
 - Aucun testeur ne confond oxygène et batterie après le tutoriel.
 - Les alarmes sont comprises avant la première perte.
 - Au moins 4 testeurs sur 5 souhaitent essayer une seconde mission.
 ### Boucle de jeu
 - Une enquête attentive réduit la recherche locale à moins de dix minutes.
 - Le joueur peut expliquer les deux indices ayant confirmé l'épave.
 - Le retour est une décision anticipable et non une surprise punitive.
 - Une première erreur ne rend jamais la mission principale impossible.
 - L'amélioration achetée produit un changement visible lors d'une seconde sortie.
 ### Technique
 - La barrière qualité reste verte à chaque tranche.
 - Aucun code de production ne dépend des dossiers des POC.
 - Une seule source de vérité existe pour chaque ressource et progression.
 - Une sauvegarde V1 peut être chargée après redémarrage du jeu.
 - Les références de contenu invalides sont refusées par des tests de contrat.
 - Le jeu tient 60 FPS à 1080p sur la machine macOS ARM64 disponible, avec mesure
  séparée du coût du sonar.
 - Aucun `ERROR`, `SCRIPT ERROR`, avertissement ou objet Godot fuité n'est accepté
  dans les parcours automatisés.
 ## 6. Architecture de production
 La verticale suit `docs/ENGINEERING_GUARDRAILS.md` et les ADR acceptés.
 ```text
 game/
  domain/
    dive/
    sonar/
    mission/
    inventory/
    economy/
    upgrades/
  application/
    dive/
    sonar/
    mission/
    port/
    interfaces/
  world/
    submarine/
    sonar/
    sites/
    interactions/
  presentation/
    cockpit/
    sonar/
    briefing/
    debriefing/
    settings/
  infrastructure/
    input/
    save/
    audio/
    localization/
  composition/
    vertical_slice/
 content/
  wrecks/
  contracts/
  evidence/
  items/
  upgrades/
  sites/
  localization/
 ```
 Le dossier `application/interfaces/` contient les contrats abstraits vers les
 adaptateurs externes. Le dossier `application/port/` orchestre les écrans et cas
 d'usage du port maritime.
 ## 7. Propriétaires des états
 | État | Propriétaire unique | Lecteurs principaux |
 |---|---|---|
 | Oxygène, batterie, coque, profondeur autorisée | `DiveSession` du domaine | HUD, alarmes, débriefing, sauvegarde |
 | Transform, vitesses et collisions | `SubmarineActor` dans `world` | télémétrie, caméra, capteur |
 | Commande de propulsion | cas d'usage de pilotage | adaptateur physique |
 | Scan courant et précédent | service applicatif sonar | renderer, HUD, sauvegarde si retenue |
 | Échantillons physiques bruts | adaptateur sonar du monde | service applicatif sonar |
 | Objectifs et preuves observées | `MissionProgress` du domaine | HUD, fiche, débriefing |
 | Cargaison du panier | `DiveInventory` du domaine | HUD, récupération, débriefing |
 | Argent et améliorations | `CampaignState` du domaine | port, préparation, sauvegarde |
 | Écran ouvert et sélection locale | présentation concernée | aucune règle de gameplay |
 | Réglages joueur | service de réglages | input, caméra, audio, présentation |
 La profondeur affichée est calculée à partir de la position physique, puis
 transmise à `DiveSession` par un échantillon de télémétrie. Le HUD ne la recalcule
 jamais depuis un nœud 3D.
 ## 8. Premiers contrats typés
 Les noms ci-dessous sont des responsabilités proposées. Leur API exacte sera
 validée par tests avant toute scène complète.
 ### `VehicleCommand`
 - poussée longitudinale normalisée ;
 - gouvernail normalisé ;
 - commande verticale normalisée ;
 - forte poussée active ou non ;
 - tick ou instant logique.
 Produit par l'infrastructure d'entrée, validé par l'application et consommé par
 l'acteur physique.
 ### `VehicleTelemetry`
 - position et orientation mondiales ;
 - vitesse linéaire et angulaire ;
 - profondeur en mètres ;
 - effort de propulsion normalisé ;
 - intensité de la dernière collision ;
 - tick logique.
 Snapshot immuable produit par le monde. Aucune référence de nœud n'en sort.
 ### `DiveSnapshot`
 - identifiant de session ;
 - oxygène restant ;
 - batterie restante ;
 - intégrité ;
 - profondeur nominale et critique ;
 - coût de retour estimé ;
 - niveau d'alarme ;
 - état terminal éventuel.
 Produit par le domaine après application d'un tick et d'une télémétrie.
 ### `SonarSample`
 - ligne et colonne ;
 - position et normale dans un repère déclaré ;
 - distance en mètres ;
 - intensité normalisée ;
 - catégorie de matériau ;
 - élévation ou profondeur ;
 - temps de révélation ;
 - statut observé ou inconnu.
 Il remplace les dictionnaires implicites du POC B.
 ### `SonarScan`
 - identifiant unique ;
 - transform du capteur à l'émission ;
 - portée et ouvertures ;
 - durée ;
 - dimensions de grille ;
 - collection typée de `SonarSample` ;
 - état : demandé, actif, terminé ou remplacé.
 Le résultat stocke le repère de capture. La présentation peut ainsi orienter la
 carte sans relire un acteur mutable.
 ### `MissionProgress`
 - contrat actif ;
 - objectifs connus ;
 - preuves observées ;
 - identité proposée ou confirmée ;
 - interaction d'accès ;
 - objet principal récupéré ;
 - résultat de mission.
 ### Définitions de contenu
 - `WreckDefinition` : identité, époque, dimensions, preuves et références.
 - `ContractDefinition` : donneur, site, objectifs, paiement et prérequis.
 - `EvidenceDefinition` : type d'observation, cible et texte de fiche.
 - `ItemDefinition` : volume, catégorie, valeur et caractère essentiel.
 - `UpgradeDefinition` : coût, prérequis et effet typé.
 - `DiveSiteDefinition` : scène, profondeur, limites et contenu autorisé.
 Chaque définition possède un ID stable et ne référence jamais une ressource par
 un texte libre destiné au joueur.
 ## 9. Flux principaux
 ### Démarrage de mission
 ```text
 Briefing UI
  → AcceptContract
  → CampaignState valide les prérequis
  → StartDive crée DiveSession et MissionProgress
  → Composition charge le DiveSite
  → World reçoit uniquement les paramètres nécessaires
 ```
 ### Pilotage
 ```text
 InputAdapter
  → VehicleCommand
  → PilotUseCase
  → SubmarineActor
  → VehicleTelemetry
  → TickDive
  → DiveSnapshot
  → cockpit et alarmes
 ```
 ### Scan sonar
 ```text
 Action F
  → RequestSonarScan
  → validation état/cooldown
  → WorldSonarAdapter capture les retours
  → SonarScanService structure le scan
  → progression déterministe
  → SonarPresentationSnapshot
  → renderer compact et agrandi
 ```
 La petite et la grande vue consomment la même sortie du renderer. Elles ne
 maintiennent jamais deux reconstructions indépendantes.
 ### Observation et récupération
 ```text
 Interaction monde
  → ObserveEvidence ou RecoverItem
  → MissionProgress / DiveInventory
  → résultat explicite
  → snapshot UI et sauvegarde éventuelle
 ```
 L'acteur d'épave ne décide pas qu'une mission est terminée. Il décrit le contact
 observé ; le domaine applique les règles du contrat.
 ### Retour et débriefing
 ```text
 Zone de retour atteinte
  → CompleteDive
  → résultat immuable
  → transfert autorisé de cargaison
  → calcul économique
  → sauvegarde atomique
  → Debriefing UI
 ```
 ## 10. Scènes de production minimales
 | Scène | Responsabilité |
 |---|---|
 | `vertical_slice_root.tscn` | composition et transitions du parcours |
 | `dive_site_survey_wreck.tscn` | environnement, limites et points d'injection |
 | `submarine_actor.tscn` | physique et adaptateurs du véhicule |
 | `survey_wreck.tscn` | géométrie, collisions et points observables |
 | `cockpit_hud.tscn` | télémétrie et alertes |
 | `sonar_display.tscn` | affichage compact et agrandi partagé |
 | `briefing_screen.tscn` | contrat, fiche et départ |
 | `debriefing_screen.tscn` | résultat, cargaison et progression |
 | `workshop_screen.tscn` | une amélioration et son installation |
 Ces scènes reçoivent leurs dépendances depuis la composition. Aucun autoload de
 gameplay n'est introduit pour éviter cette injection.
 ## 11. Sauvegarde V1 minimale
 La sauvegarde existe avant le métajeu complet afin d'empêcher une architecture
 reposant sur des nœuds sérialisés.
 Contenu V1 :
 - version du format ;
 - ID de campagne et date technique non utilisée par le gameplay ;
 - contrat actif ou terminé ;
 - argent ;
 - améliorations acquises et installées ;
 - preuves principales sécurisées ;
 - dernier résultat de plongée ;
 - réglages joueur séparés de la campagne.
 La position arbitraire du sous-marin, les particules, les collisions et le
 maillage sonar dynamique ne sont pas sauvegardés dans cette verticale.
 Procédure : sérialiser dans un fichier temporaire, relire et valider, puis
 remplacer atomiquement la sauvegarde précédente. Conserver une fixture V1 et un
 test de round-trip dès la première implémentation.
 ## 12. Stratégie de tests
 ### Unitaires
 - consommation des trois ressources ;
 - seuils de profondeur et dégâts ;
 - estimation du retour ;
 - transitions terminales ;
 - validation et progression temporelle d'un scan ;
 - remplacement d'un seul scan précédent ;
 - classification des matériaux ;
 - ajout idempotent d'une preuve ;
 - conditions d'identification ;
 - capacité de cargaison ;
 - résultat de mission ;
 - vente, restitution et achat d'amélioration.
 ### Contrats
 - IDs de contenu uniques ;
 - références résolues ;
 - contrat principal terminable ;
 - deux preuves valides pour l'épave ;
 - objet principal invendable ou récupérable selon la règle ;
 - effet d'amélioration reconnu ;
 - sauvegarde V1 aller-retour ;
 - rejet d'une version inconnue ;
 - textes visibles munis d'une clé de localisation.
 ### Intégration
 - entrée abstraite vers mouvement et télémétrie ;
 - collision vers dégâts uniques ;
 - sonar monde vers `SonarScan` puis maillage ;
 - rotation du véhicule vers orientation de la carte ;
 - vue compacte et agrandie partageant la même texture ;
 - observation monde vers progression de mission ;
 - récupération vers inventaire ;
 - retour vers débriefing et sauvegarde ;
 - chargement d'une sauvegarde vers écran correct.
 ### Parcours automatisés
 1. Succès nominal avec deux preuves et retour.
 2. Retour sans preuve principale : mission non terminée.
 3. Abandon volontaire : perte appliquée, campagne encore jouable.
 4. Batterie vide : pas de mort instantanée, oxygène continue.
 5. Sauvegarde après débriefing puis redémarrage.
 Les parcours utilisent des adaptateurs déterministes, pas une simulation de
 plusieurs minutes en temps réel.
 ### Tests humains
 - compréhension du pilotage sans aide orale ;
 - lecture du relief dans les deux tailles sonar ;
 - découverte de l'accès ;
 - compréhension des indices ;
 - anticipation du retour ;
 - désir de relancer une mission.
 Chaque session note les interventions verbales du testeur. Une réussite obtenue
 après explication ne satisfait pas le critère d'autonomie.
 ## 13. Budgets techniques initiaux
 | Budget | Cible de départ |
 |---|---:|
 | Framerate de validation locale | 60 FPS à 1080p |
 | Budget total par frame | 16,7 ms |
 | Sonar, coût CPU moyen pendant scan | ≤ 3 ms |
 | Sonar, pic CPU exceptionnel | ≤ 8 ms sur une frame |
 | Durée de chargement du site sur SSD | ≤ 3 s |
 | Écriture de sauvegarde | ≤ 100 ms hors blocage visible prolongé |
 | Barrière qualité locale | ≤ 60 s avant croissance du contenu |
 | Erreurs ou avertissements Godot acceptés | 0 |
 Ces budgets sont des alarmes, pas des promesses commerciales. Une mesure doit
 indiquer la machine, le renderer, la résolution, le build et la scène.
 Le renderer Forward+ reste la cible de production. Son adoption pour la
 verticale nécessite un ADR et un test immédiat sur les machines disponibles ;
 elle ne doit pas attendre la phase de finition graphique.
 ## 14. Tranches d'implémentation
 ### Tranche 0 — fondations exécutables
 - Créer les sous-dossiers nécessaires, sans architecture vide exhaustive.
 - Définir horloge, IDs et premiers types de résultat.
 - Porter `DiveSession` comme règle pure avec tests.
 - Créer une composition minimale et un écran de diagnostic.
 Sortie : état de plongée déterministe, testable sans scène, affiché par une scène
 de production qui ne dépend pas des POC.
 ### Tranche 1 — véhicule de production
 - Réécrire le contrôleur derrière `VehicleCommand` et `VehicleTelemetry`.
 - Reproduire les sensations validées du POC A à partir de sa baseline.
 - Intégrer caméra intérieure et hublot.
 - Ajouter les tests de mouvement et de dégâts prioritaires.
 Sortie : parcours de pilotage court avec ressources et retour immédiat lisible.
 ### Tranche 2 — sonar de production
 - Définir `SonarSample` et `SonarScan`.
 - Séparer acquisition, reconstruction et présentation.
 - Reproduire la bathymétrie validée sans importer le POC B.
 - Mesurer le coût et passer à une mise à jour incrémentale.
 Sortie : relief inconnu révélé manuellement, lisible dans les deux vues, avec
 rotation et remplacement d'un relevé.
 ### Tranche 3 — site et découverte
 - Construire le terrain graybox et l'épave contemporaine.
 - Ajouter une entrée masquée simple, sans surplomb complexe.
 - Définir deux preuves et une anomalie secondaire.
 - Organiser le premier playtest de recherche.
 Sortie : 8 testeurs sur 10 trouvent l'épave dans la fenêtre cible ou une porte de
 décision est déclenchée.
 ### Tranche 4 — interaction et retour
 - Ajouter une interaction d'ouverture bornée.
 - Ajouter la caisse, le panier et l'objet principal.
 - Ajouter zone de retour, succès, abandon et perte.
 - Automatiser les parcours nominaux et d'échec.
 Sortie : boucle de plongée complète sans métajeu.
 ### Tranche 5 — contrat, économie et sauvegarde
 - Ajouter briefing, fiche, débriefing et atelier.
 - Ajouter une vente/restitution et une amélioration.
 - Écrire Save V1 et ses tests de contrat.
 Sortie : boucle verticale complète et rejouable après redémarrage.
 ### Tranche 6 — présentation et validation
 - Remplacer les éléments graybox nécessaires à la compréhension.
 - Ajouter audio moteur, sonar, alarmes et ambiance.
 - Ajouter réglages d'accessibilité retenus.
 - Profiler, tester sur trois OS et conduire le playtest final.
 Sortie : décision documentée de poursuivre, corriger ou réduire le projet.
 ## 15. Risques et portes de décision
 | Risque | Détection précoce | Réponse prévue |
 |---|---|---|
 | Sensations perdues pendant la réécriture | test véhicule dès tranche 1 | comparer aux mesures POC A, ajuster avant sonar |
 | Sonar lisible seul mais confus en mission | playtest tranche 3 | réduire relief parasite ou resserrer la zone probable |
 | Ouverture impossible à représenter | site graybox dédié | ajouter surfaces locales ; ne pas revenir aux voxels globaux |
 | États dupliqués entre monde et HUD | tests de propriétaire et snapshots | supprimer la copie, rétablir un flux unidirectionnel |
 | Scènes fortement couplées | contrôle d'architecture | déplacer l'assemblage vers `composition` |
 | Sauvegarde conçue trop tard | Save V1 tranche 5 au plus tard | bloquer le métajeu tant que le round-trip échoue |
 | Contenu lent à produire | mesure sur l'épave contemporaine | réduire preuves et interactions avant d'ajouter une épave |
 | Performance du maillage sonar | profil tranche 2 | buffers incrémentaux, fréquence bornée ou travail distribué |
 | Palette inaccessible | tests contraste/daltonisme | palette alternative et indices de forme |
 | Portée verticale excessive | revue à chaque tranche | retirer une fonctionnalité de coût comparable |
 Une porte de décision produit une conclusion écrite. Elle ne devient pas une
 suite indéfinie de corrections sans critère de sortie.
 ## 16. Décisions à formaliser après validation de ce cadrage
 Une fois ce document approuvé, créer des ADR séparés pour :
 1. le renderer de production de la verticale ;
 2. les contrats `VehicleTelemetry`, `DiveSnapshot` et `SonarScan` ;
 3. la sauvegarde V1 et sa stratégie atomique ;
 4. l'absence initiale d'autoload de gameplay ;
 5. le modèle hybride retenu si le site exige une surface non bathymétrique.
 Les noms de classes peuvent évoluer pendant la tranche 0. Les responsabilités,
 les propriétaires et les directions de dépendance ne changent qu'avec un ADR.
 ## 17. Première action après approbation
 La première implémentation ne sera ni le sous-marin ni le sonar. Elle créera une
 tranche verticale minuscule :
 1. `DiveSession` pur avec horloge injectée ;
 2. `VehicleTelemetry` minimal fourni par un faux adaptateur ;
 3. `DiveSnapshot` affiché dans une scène de diagnostic ;
 4. tests de consommation, profondeur et état terminal ;
 5. ajout de cette suite à `scripts/quality_gate.sh`.
 Cette tranche prouvera le chemin complet domaine → application → présentation
 et la discipline de tests avant de porter un comportement complexe.