DOCS/guided-path-types.md

Types d'expériences visiteur — SectionParcours

Guide de référence pour comprendre les possibilités offertes aux clients lors de la configuration de leur contenu.

---

Les 4 types de sections

Section	Ce que le client pense	Carte	Questions
SectionMap	"Je crée une carte interactive de mon lieu"	Toujours	Non
SectionParcours	"Je guide mes visiteurs"	Optionnelle	Optionnelles
SectionGame	"Je crée un puzzle image"	Non	Non
SectionEvent	"Je crée un événement temporel"	Optionnelle	Non

---

SectionParcours — tous les cas d'usage

Propriétés clés

Intention produit — ShowMap est le commutateur « géolocalisé ou pas » (précisé le 2026-08-05). Ce n'est pas seulement « afficher une carte » :

• ShowMap = true → parcours géolocalisé : le visiteur se déplace physiquement, les étapes ont une position, la carte les montre. Extérieur ou grand site.
• ShowMap = false → suite d'énigmes non géolocalisée, dans une pièce ou un espace restreint. Pas de GPS, pas de position sur les étapes, pas de carte. Le GPS n'aurait de toute façon aucune fiabilité en intérieur (précision 10-50 m).

Conséquence : les champs géo d'une étape (Geometry, IsGeoTriggered, ZoneRadiusMeters) n'ont de sens que si ShowMap = true, et doivent être masqués dans manager-app sinon.

Propriété	Type	Défaut	Rôle
ShowMap	bool	true	Parcours géolocalisé (carte + positions d'étapes) vs suite d'énigmes en salle
BaseSectionMapId	string?	null	SectionMap existante pour les GeoPoints de contexte — fond de carte optionnel, ne conditionne pas l'affichage de la carte
IsGameMode	bool	false	Active l'écran de démarrage + message de victoire
GameMessageDebut	TranslationAndResource[]	null	Message d'intro si IsGameMode
GameMessageFin	TranslationAndResource[]	null	Message de victoire si IsGameMode
GuidedPaths	GuidedPath[]	[]	Un ou plusieurs itinéraires au choix du visiteur

Propriétés GuidedPath

Propriété	Type	Défaut	Rôle
Title	Translation[]	—	Titre du parcours (multilingue)
Description	Translation[]	—	Description avant de démarrer
ImageResourceId	string?	null	Image de couverture
IsLinear	bool	true	true = le visiteur doit suivre l'ordre des étapes · false = il navigue librement entre les étapes, dans l'ordre qu'il veut
RequireSuccessToAdvance	bool	false	Doit valider le défi pour passer à l'étape suivante
HideNextStepsUntilComplete	bool	false	Cache les étapes futures

Ces 3 booléens ne sont plus saisis directement (2026-08-06). Le client répond à une seule question — « Comment le visiteur progresse-t-il ? » — et manager-app en dérive les valeurs (Parcours/progression_mode.dart) :

Choix client	IsLinear	RequireSuccessToAdvance	HideNextStepsUntilComplete
Libre — choisit ses étapes dans l'ordre qu'il veut	false	false	false
Dans l'ordre — suit la séquence, peut revenir en arrière	true	false	false
Étape par étape — chaque étape se débloque en réussissant la précédente	true	true	case à cocher

Comportement visiteur implémenté (2026-08-06), identique mobile et web :

• Navigation libre (IsLinear = false) : le visiteur atteint n'importe quelle étape — pins de la carte tapables, segments de la barre de progression cliquables.
• Sinon : il ne peut revenir que sur les étapes déjà atteintes (relire une étape vue n'est pas de la triche). Les étapes non atteintes s'affichent verrouillées.
• Retour arrière : toujours disponible dès la 2ᵉ étape, dans tous les modes.
• HideNextStepsUntilComplete masque les étapes au-delà de la progression, en mode carte et en mode contenu (avant, seul le mode carte l'appliquait).

Propriétés GuidedStep

Propriété	Type	Rôle
Title	Translation[]	Titre de l'étape
Description	Translation[]	Contenu de l'étape
ImageResourceId	string?	Image de l'étape
Geometry	Geometry?	Position / zone de l'étape — coordonnées en [lat, lng], pas en GeoJSON [lng, lat] (miroir du map_geometry_picker de manager-app). Uniquement si ShowMap = true
IsGeoTriggered	bool	Active le déblocage de l'étape à l'entrée dans la zone. Uniquement si ShowMap = true
ZoneRadiusMeters	double?	Rayon de déclenchement en mètres (1-500)
IsStepTimer	bool	Active un compte à rebours sur l'étape
TimerSeconds	int?	Durée du timer
TimerExpiredMessage	Translation[]?	Message si timer expiré
QuizQuestions	QuizQuestion[]?	Défi à valider (QCM, texte libre, digicode, puzzle)

Supprimés le 2026-08-06 (migration RemoveDeadGuidedStepFlags) :

• IsStepLocked — redondant avec RequireSuccessToAdvance, et son implémentation rendait l'étape définitivement infranchissable (_canAdvance renvoyait false même après réussite du défi). Le verrouillage est désormais dérivé de la progression réelle du visiteur.
• IsHiddenInitially — aucun consommateur dans aucune app, redondant avec HideNextStepsUntilComplete.
• FactContent — persisté en base, jamais édité ni affiché.

---

Types de questions (QuizQuestion)

Entité partagée entre SectionQuiz et GuidedStep.

⚠️ Corrigé le 2026-08-05 — l'enum réel (QuizQuestion.cs:78-83) ne contient que 3 valeurs : Simple, MultipleChoice, Puzzle. Il n'existe ni SimpleChoice, ni TextLibre, ni Digicode, ni SlidingPuzzle, ni champ ExpectedAnswer.

ValidationQuestionType	Validation	Usage typique
Simple	Texte libre — la réponse attendue est Responses[0].label (donc traduisible), comparaison insensible à la casse et aux accents	Escape game — « Quel est le nom du coupable ? »
MultipleChoice	Choix parmi plusieurs (Responses[].isGood)	Quiz pédagogique
Puzzle	Puzzle complété — jigsaw, ou glissant si IsSlidingPuzzle = true	Escape game — reconstituer une image

Digicode : ce n'est pas un type de question. Si la réponse attendue d'une question Simple est purement numérique, les apps visiteur affichent automatiquement un pavé 0-9 façon cadenas à la place du champ texte (guided_step_challenge.dart _isDigicode, ParcoursSection.tsx isDigicodeAnswer). Rien à configurer dans manager-app.

Puzzle utilise PuzzleImageId, PuzzleRows, PuzzleCols, IsSlidingPuzzle sur QuizQuestion. Ces champs ne sont proposés dans manager-app que si IsGameMode = true sur le parcours.

⚠️ Ces 3 types ne sont disponibles que dans un GuidedStep. Une SectionQuiz autonome utilise un éditeur plus ancien (new_update_question_quizz.dart, modèle QuestionDTO) qui ne fait que du QCM.

---

Cas d'usage concrets

1. Visite de façades (parcours simple)

Configuration :

• ShowMap = true
• IsGameMode = false
• IsLinear = true
• Étapes : chaque façade avec photo + description
• Pas de questions

Expérience visiteur : carte avec les façades numérotées, tap sur chaque étape pour voir la description et la photo.

---

2. Parcours thématique libre

Configuration :

• ShowMap = true
• IsGameMode = false
• IsLinear = false
• Étapes : points d'intérêt à découvrir dans n'importe quel ordre

Expérience visiteur : tous les pins visibles sur la carte dès le départ, le visiteur explore à son rythme.

---

3. Parcours pédagogique (visite scolaire)

Configuration :

• ShowMap = true ou false
• IsGameMode = false
• RequireSuccessToAdvance = true
• Étapes : contenu + questions SimpleChoice ou TextLibre

Expérience visiteur : progression étape par étape, doit répondre correctement pour continuer.

---

4. Escape game indoor

Configuration :

• ShowMap = false — pas de déplacement physique
• IsGameMode = true
• GameMessageDebut : mise en scène narrative
• GameMessageFin : message de victoire
• RequireSuccessToAdvance = true
• HideNextStepsUntilComplete = true
• Étapes : énigmes avec des questions Simple (texte libre, ou digicode si la réponse est numérique)
• Pas de géométrie ni de IsGeoTriggered sur les étapes — un escape indoor n'est pas géolocalisé

Expérience visiteur : écran de démarrage immersif → suite d'énigmes à résoudre → écran de victoire.

✅ Résolu le 2026-08-06 : le mode contenu applique désormais les mêmes règles de progression que le mode carte (verrouillage dérivé, masquage des étapes non atteintes, navigation libre), sur mobile et sur web. Voir parity-manager-visitapp.md M7/W6/W7.

---

5. Chasse au trésor / Escape game outdoor

Configuration :

• ShowMap = true
• BaseSectionMapId = carte du lieu (avec ses points de repère)
• IsGameMode = true
• RequireSuccessToAdvance = true
• HideNextStepsUntilComplete = true
• Étapes : position géographique (Geometry + ZoneRadiusMeters) + énigme

Expérience visiteur : carte avec les zones à atteindre, déclenchement automatique à l'approche d'une zone, énigme à résoudre pour passer à la suivante.

---

6. Guide de visite linéaire (sans carte)

Configuration :

• ShowMap = false
• IsGameMode = false
• IsLinear = true
• Étapes : contenu riche (texte, image, audio)

Expérience visiteur : séquence de contenus à consommer dans l'ordre. Proche d'un audioguide interactif.

---

SectionEvent — cas carnaval

SectionEvent n'est pas un parcours, mais peut en contenir (via GuidedPath.SectionEventId).

Configuration type (carnaval) :

1. Créer une SectionMap "Carte du carnaval" avec les scènes, parkings, points de restauration
2. Créer un SectionEvent "Carnaval de Marche" lié à cette SectionMap (BaseSectionMapId)
3. Ajouter des ProgrammeBlocks (horaires, activités) avec leurs annotations sur la carte
4. Optionnellement, ajouter des GuidedPaths à la SectionEvent pour "Suivez le cortège"

Expérience visiteur : SectionEvent apparaît en hero sur le home screen → tap → infos générales de l'événement, carte du cortège, programme avec horaires.

---

SectionMap — carte pure

Utilisé seul, sans parcours. Points d'intérêt avec catégories, vue liste/carte.

Peut être référencé en BaseSectionMapId par une SectionParcours ou une SectionEvent pour fournir les GeoPoints de contexte.