Exposer GET /routes/:id et /routes/:id/timeline, stocker computed #36

Contexte

Epic : #9
Maquette : sans objet — API ; la fiche E-05 qu'elle alimente est validée depuis le 2026-09-23
API › Fiche parcours · API › Choix tranchés (#393) · Modele-de-Donnees (routes.unpublished_at) · Orchestration · Ecrans › E-05 · E-05 · D-002 · D-088 · D-093

Débloqué le 2026-10-14 par D-088 (décision d'Ilan sur #378) : computed et steps.transition n'enregistrent que nos estimations ; à chaque GET /v1/routes/:id, l'API demande à Mapbox Directions les trajets exacts et leur géométrie pour cette réponse seulement, sans rien enregistrer ni mettre en cache (direction_cache reste vide) ; si Mapbox ne répond pas, la réponse porte l'estimation (estimated: true), sans géométrie.

Contrat écrit le 2026-10-16 par D-093 (décision d'Ilan sur #393) : la section API › Fiche parcours fait foi. Point de départ : le schéma RouteDetail de packages/shared/src/schemas/route-detail.ts (PR #390, #37), étendu par #508 (highlights, photos des étapes complètes) ; l'endpoint tient ce schéma partagé, sans seconde définition.

Comportement attendu

Accès (tableau « Qui obtient quoi » de la page API) :

• published, needs_fix : 200 pour tous. private : 404 sans jeton, 200 avec ?token= valide (sharedBy). pending ou changes_requested jamais publié : 200 avec le jeton (sharedBy), 404 sans. pending ou changes_requested déjà publié (un needs_fix corrigé et resoumis) : 404, même avec le jeton. draft, rejected : 404. Inexistant ou supprimé avec le compte de son auteur : 404. Jeton faux ou d'un autre parcours : 404, jamais 403. Identifiant mal formé : 400 validation_error. Jeton Firebase invalide : 401.
• L'auteur connecté a toujours droit à son propre parcours (200 sur ses parcours private, pending, changes_requested, et parcours Premium en entier, fiche et programmation) : canAccessRoute(route, viewer, now) (apps/api/src/access/route-access.ts) est étendu à l'auteur, règle unique déjà lue par la recherche et la programmation.
• Pas d'exception de rôle (un modérateur passe par GET /admin/routes/:id).

Réponse 200 de GET /v1/routes/:id : RouteDetail tel que décrit dans la page API (identité de la card, status, description, chiffres issus de computed, startAccess, creator, sharedBy, reviews (3 derniers), timeline du départ conseillé, steps complètes ou LockedStep, vérification et lieux signalés), plus ce que le schéma de #390 ne porte pas encore :

• geometry de chaque trajet (transition.geometry) : polyline encodée, précision 5 (ce que apps/api/src/directions/mapbox.ts demande déjà), null sans tracé ; pour le tracé de Tracer le parcours sélectionné le long des rues (E-04) #154 ;
• myReport (D-057) : date et statut du signalement de l'utilisateur connecté s'il date de moins de 7 jours et n'est pas tranché, null sinon ; absent ou null sans jeton ;
• « À prévoir » : lignes du créateur (routes.tips) et suggestions calculées non masquées (computed, moins routes.tips_hidden), D-048, D-050, lues par E-06 ;
• photos en objets photo { url, credit } (le type Photo de Servir « À ne pas manquer » et les photos d'étape avec leur crédit (snapshot du Go, fiche) #508, credit à null pour une photo de créateur) : photoUrls et place.photoUrl cessent d'être de simples URL ;
• timezone de la ville (fuseau IANA, comme PlannedRouteSnapshot) : « Ouvert aujourd'hui » se lit à l'heure de Paris.
• Aucun warnings ni errors de cohérence dans la fiche (Q10).

Trajets : la fiche calcule durée, distance, marche, effort et sa timeline sur les trajets de la réponse (exacts quand Mapbox répond) ; paliers et filtres restent sur l'enregistré (Q6). Profils walking, cycling, driving ; métro toujours estimé, sans tracé. Repli, jamais une erreur : Mapbox en échec, au-delà de 4 s ou quota atteint → estimation enregistrée, estimated: true, geometry: null. Piste : une requête par profil et par parcours, les étapes en points de passage (25 au plus), pour tenir la limite de 300 requêtes par minute.

Query : token, trips=estimated (nos estimations seules, sans appel à Mapbox ni tracé, réponse cachable comme /timeline : lecture du site /r/:id, Q9) ; toute autre clé : 400 validation_error.

Parcours Premium sans droit (isLocked, D-014, D-075) : étape 1 complète, étapes suivantes en LockedStep strict (id, position, category, durationMin, transition) ; aucun appel à Mapbox, trajets estimés, geometry: null partout ; conflits de la timeline vides sur les étapes verrouillées (Q7).

Parcours retiré (unpublished) : 410 route_removed à tout appelant, avec ou sans jeton, details: { removedAt, near } et rien d'autre du parcours (ni titre, ni auteur, ni étapes, ni motif).

• removedAt : nouvelle colonne routes.unpublished_at (timestamptz, migration additive), posée par l'écrivain unique du statut (moveRoute) à chaque passage en unpublished, remise à null à la republication.
• near : coordonnées du départ arrondies à 0,01° (deux décimales), jamais le point exact.
• ApiError avec apiCode explicite (410 n'a pas de code par défaut dans codeByStatus) ; RouteRemovedDetails (packages/shared) gagne near.

En-têtes et limites :

• Réponse 200 de GET /routes/:id : Cache-Control: no-store, sans ETag (Q8) ; sauf avec trips=estimated, cachable comme /timeline.
• 60 requêtes par minute et par IP sur GET /routes/:id, 429 rate_limited au-delà.
• Erreurs (400, 401, 402, 404, 410, 429) jamais mises en cache.

GET /v1/routes/:id/timeline?startsAt= :

• startsAt obligatoire (ISO 8601 avec décalage, comme POST /me/planned), token pour un parcours privé ; clé inconnue ou valeur invalide : 400.
• Mêmes règles d'accès que la fiche (404, 410, jeton). Parcours Premium sans droit : 402 premium_required, details.reason: premium_route.
• RouteTimeline pour ce départ (horaires valables à la date demandée, conflits compris), calculée sur nos estimations, celles que POST /me/planned fige, sans appel à Mapbox (D-093, qui amende D-088).
• Cache : public (60 s, ETag) sans Authorization ni token ; private, no-cache et Vary: Authorization avec un jeton Firebase ; private, no-store avec un token de lien privé.

Contenu par étape et pour le parcours (D-013, D-014, D-048, D-050, D-052, D-056) : horaires du jour et statut ouvert, coût, réservation (bookingRequired, bookingUrl, bookingProvider, bookingNote, bookingIsAffiliate), endsOn, transitionNote, conseil du créateur, vérification { confirmations, lastConfirmedAt, reports }, verificationStatus et verifiedAt du lieu, lieux signalés ; nombre d'avis, trois derniers avis, nombre de parcours publiés par le créateur.

Budget (D-032, D-066, Q11) : budgetPerPersonEur est la somme exacte par personne, comme sur la card de /routes/search, et budgetBucket dérive de cette somme ; l'API n'arrondit pas, l'arrondi d'affichage reste la fonction de l'app partagée avec la card.

Recalcul : computed recalculé et stocké à chaque modification d'étapes (service recomputeRoute), sur nos estimations seulement (D-088), remplaçant les valeurs manuelles du seed.

Critères d'acceptation

• Tests d'intégration de l'accès, une ligne par case du tableau « Qui obtient quoi » : publié, needs_fix, privé avec et sans jeton, pending jamais publié avec jeton, pending déjà publié (404 même avec jeton), draft et rejected, jeton faux (404), identifiant mal formé (400)
• Test : l'auteur connecté lit son parcours private sans jeton, et son propre parcours Premium en entier sans abonnement ; canAccessRoute reste l'unique règle (recherche, programmation et fiche)
• Le seed v0.2 est recalculé par le moteur et reste cohérent
• Test : parcours access = premium sans droit → étape 1 complète, étapes suivantes en LockedStep, aucun appel à Mapbox, geometry: null partout, conflits vides sur les étapes verrouillées ; avec droit → fiche complète ; compte premium dont plan_expires_at est passé → fiche réduite (D-075)
• Test : les transitions portent la géométrie demandée à Mapbox (polyline, précision 5) ; rien de Mapbox n'est écrit en base (computed, steps.transition, direction_cache) ; Mapbox indisponible → estimations, estimated: true, sans géométrie
• Test : ?trips=estimated → aucun appel à Mapbox, geometry: null, réponse cachable ; toute autre clé de query → 400
• Test : parcours retiré → 410 route_removed avec details.removedAt (lu dans routes.unpublished_at) et details.near arrondi à 0,01°, sans autre donnée du parcours ; unpublished_at posé par moveRoute au retrait et remis à null à la republication
• La réponse porte geometry, myReport, « À prévoir », les photos en objets { url, credit }, timezone, et tous les champs par étape et pour le parcours listés ci-dessus, lieux signalés compris ; aucun avertissement de cohérence
• La réponse est validée par le schéma partagé route-detail.ts, étendu des champs ci-dessus dans packages/shared, tel que décrit dans API › Fiche parcours
• Test : réponse 200 en Cache-Control: no-store, sans ETag ; la 61e requête d'une minute depuis la même IP reçoit 429 rate_limited
• Test : /timeline?startsAt= sans appel à Mapbox, sur les mêmes estimations que POST /me/planned ; 402 premium_required pour un parcours Premium sans droit ; 400 sans startsAt ; en-têtes de cache des trois cas
• Test : budgetPerPersonEur exact (23 € reste 23), égal à celui de la card du même parcours, et budgetBucket dérivé de la somme exacte ; aucun arrondi dans l'API
• Le lien de réservation de chaque étape vient de resolveBookingLink (packages/shared/src/booking-link.ts) : lien du créateur d'abord, lien partenaire sinon, bookingIsAffiliate vrai pour un lien partenaire (test API)

Notes techniques

• Niveau 2 attendu : migration additive (routes.unpublished_at), extension d'une règle d'accès (canAccessRoute), limite de débit, appels sortants à Mapbox ; revue OWASP ciblée (A01 accès par statut et jeton, A04 limite de débit et coût des appels tiers).
• Hors de ce ticket : la traduction (route_translations, D-076) ; l'état « déjà programmé » de la barre (D-035), lu sur GET /me/planned ; la lecture d'un déblocage fait sans compte (question ouverte par D-096, portée par Décider comment la fiche reconnaît un parcours débloqué sans compte #531, needs-design).