Orchestration

Orchestration

Statut : 🟢 Validé le 2026-09-25 · Màj : 2026-10-14 · Tickets : #34 #35 #36 #40 #42 #56 #154 #378

L'orchestration est le moteur qui rend un parcours cohérent sans effort du créateur ni de l'utilisateur. Elle vit côté API, dans un module isolé (packages/orchestration), testable sans base de données. Elle est appelée à la création, à chaque modification d'étape, à la programmation (recalcul avec une date) et périodiquement pour les parcours publiés (horaires et fermetures).

Entrées

• Liste ordonnée d'étapes, chacune avec un lieu (coordonnées, horaires facultatifs, catégorie, intérieur/extérieur), une durée conseillée, un coût estimé par personne, un indicateur de réservation.
• Mode de déplacement de chaque trajet, choisi par le créateur (proposé selon la distance : à pied jusqu'à 1,5 km, métro au-delà). Le transport du parcours en est dérivé : le mode qui couvre le plus de distance (D-048).
• Départ choisi par le créateur (routes.suggested_start) ; vide, il est calculé : l'heure la plus proche de 10:00 (14:00 pour une demi-journée) où chaque lieu est ouvert à l'arrivée (D-050).
• Dates de fin des lieux et étapes éphémères (ends_on).
• Facultatif : date et heure de départ, nombre de personnes.

Calculs

Transitions

Pour chaque paire d'étapes consécutives : distance et durée de trajet selon le mode choisi pour ce trajet.

• Enregistré : nos estimations, jamais une réponse de Mapbox Directions (D-088), dont les conditions interdisent de conserver les résultats. Distance à vol d'oiseau multipliée par un coefficient, à une vitesse par mode :

  • à pied : × 1,3 à 4,5 km/h ;
  • métro : × 1,4 à 20 km/h, plus 8 min ; le transport en commun précis est hors MVP ;
  • vélo : × 1,3 à 15 km/h (à confirmer) ;
  • voiture : comme le métro, × 1,4 à 20 km/h plus 8 min (à confirmer).

  Ces estimations alimentent tout ce qui est enregistré ou calculé sans qu'une personne regarde : steps.transition, agrégats, filtres et avertissements de computed, recherche, cards, règles de cohérence, recalcul de nuit.

• Exact, à l'ouverture d'un parcours : à pied, à vélo et en voiture, l'API demande à Mapbox Directions (profils walking, cycling, driving) les distances, durées et tracés dans les rues de la fiche, pour cette réponse seulement : rien n'est enregistré ni mis en cache (direction_cache reste vide). Si Mapbox ne répond pas, la fiche montre l'estimation, marquée estimated = true, sans tracé.

• Mapbox Directions n'est appelé qu'en réponse à l'action d'une personne (ouvrir un parcours, le créer ou le modifier), jamais par une tâche planifiée.

Agrégats

• Distance totale, temps de trajet total, temps de marche total (transitions à pied uniquement).
• Durée totale = somme des durées d'étapes + somme des transitions.
• Budget par personne = somme des coûts estimés. Affiché « ≈ 25 € par pers. », jamais « env. » : somme arrondie aux 5 € les plus proches, « ≈ 5 € » pour une somme non nulle qui s'arrondirait à zéro, « Gratuit » si elle est nulle ; plus de fourchette. Lecteur d'écran : « environ 25 euros par personne ». À confirmer : le palier de budget se calcule sur la somme exacte, l'arrondi ne servant qu'à l'affichage.
• Effort : easy si marche < 3 km et dénivelé négligeable ; moderate < 7 km ; intense au-delà. Le dénivelé n'est pas calculé au MVP.
• Filtres dérivés : budget, duration, no_booking, indoor / outdoor (voir Filtres-et-Recherche).

Accès et À prévoir (D-050)

• Accès : station de transport la plus proche de la première étape, depuis les données ouvertes d'Île-de-France Mobilités, rangée dans computed.
• Suggestions « À prévoir » calculées (réservation, fermeture proche, météo, etc.), rangées dans computed ; celles que le créateur désactive sont dans routes.tips_hidden.

Timeline

À partir d'une heure de départ (par défaut : le départ conseillé du parcours s'il est renseigné, sinon 10 h pour une journée, 14 h pour une demi-journée, maintenant pour Go), chaque étape reçoit une heure d'arrivée et de départ. Pour chaque étape avec horaires connus :

• Arrivée après la fermeture ou avant l'ouverture : conflit closed_at_arrival.
• Jour de fermeture : conflit closed_that_day.
• Fin d'étape après la fermeture : avertissement closes_during_step.
• Sans horaires connus : avertissement discret hours_unknown, incitation à vérifier ; pas d'avertissement pour un lieu « Accessible à toute heure » (places.always_open, D-049).

Règles de cohérence

Les règles s'appliquent à l'éditeur (E-12) et à la modération. Une règle bloquante empêche la soumission, pas l'enregistrement en brouillon ou en privé.

Code	Règle	Niveau
min_steps	Au moins 2 étapes	bloquant
max_steps	Au plus 10 étapes	bloquant
step_has_place	Chaque étape a un lieu géolocalisé	bloquant
step_has_duration	Chaque étape a une durée entre 10 min et 6 h	bloquant
transition_too_long	Transition > 30 min à pied ou > 45 min autre mode	avertissement, bloquant au-delà du double
total_too_long	Durée totale > 14 h	bloquant
too_many_transitions	Temps de trajet > 40 % de la durée totale	avertissement
duplicate_place	Même lieu deux fois	avertissement
closed_at_arrival	Horaires incompatibles avec la timeline par défaut	avertissement, avec proposition d'une heure de départ qui rend le parcours compatible (D-049)
unverified_place	Lieu jamais vérifié ou signalé ouvert	avertissement, visible en modération
missing_photo	Aucune photo sur le parcours	bloquant pour la publication
missing_step_photo	Une étape sans photo, ni de l'étape ni du lieu	bloquant pour la publication, pas pour un parcours privé (D-049)
missing_description	Description < 80 caractères	bloquant pour la publication
back_and_forth	L'ordre des étapes allonge le trajet de plus de 50 % par rapport à un ordre optimisé	avertissement, avec proposition « Réordonner » : ordre par plus proche voisin, annulable (D-049)

Les seuils de ces règles (2 et 10 étapes, 10 min et 6 h, 30 et 45 min, 14 h, 40 %, 80 caractères, 50 %) sont conservés ; ils vivent dans settings, réglables sans déploiement.

Le score de cohérence affiché en modération est le nombre d'avertissements restants ; il n'est pas montré à l'utilisateur final.

Ce que voit l'utilisateur final

• Fiche : durée, budget, distance, marche, effort, nombre d'étapes, transport, et pour chaque transition « 8 min à pied · 600 m », exacte à l'ouverture du parcours, estimée si Mapbox ne répond pas (D-088).
• Cards et recherche : durées estimées (D-088), qui peuvent différer de quelques minutes de celles de la fiche. À confirmer : arrondi de la durée affichée sur les cards.
• Timeline suggérée avec les horaires d'ouverture du jour, avertissement si un lieu est fermé à l'heure prévue.
• Programmation : la même timeline recalculée pour la date choisie, plus la checklist des réservations.
• Go : plus de lien Google Maps unique pour tout le parcours. Depuis le parcours en cours (E-07), « Itinéraire » ouvre Google Maps à pied jusqu'à l'étape suivante, étape par étape (D-029).

Recalcul périodique

Une tâche planifiée (Cloud Scheduler → endpoint interne) recalcule chaque nuit les parcours publiés dont un lieu a changé ou dont un lieu ou une étape éphémère a passé sa date de fin (règles ended_place et ended_step : le lieu éphémère sort de Widoo, le parcours passe « à corriger », l'auteur est prévenu ; programmer après la date le signale dans E-06, D-050) ; (horaires, coordonnées, fermeture). Un parcours qui viole une règle bloquante reste publié, marqué « à corriger » (needs_fix), et son auteur est notifié. Il n'est dépublié que si l'un de ses lieux est fermé définitivement, avec la même notification. Ce recalcul n'appelle jamais Mapbox Directions : il n'utilise que nos estimations (D-088).

Hors MVP

Optimisation automatique de l'ordre (le MVP propose seulement un réordonnancement simple par plus proche voisin), transports en commun précis, dénivelé, génération de parcours (mode Surprise), prise en compte de l'affluence.