Périmètre de la Golden Path - Phase 0

Documentation technique

Date : 2026-09-04
Projet : Réarchitecture du Site Web (Vitrine, Blog, Portfolio, Documentation)
Version : 1.0

1. Définition de la Golden Path

La Golden Path (parcours minimal viable) est l’ensemble des fonctionnalités critiques qui doivent être implémentées et stabilisées en priorité absolue avant d’aborder les fonctionnalités annexes.

Objectif : Livrer un site fonctionnel et testable qui démontre la viabilité de l’architecture complète, avec un retour sur valeur immédiat pour les utilisateurs et les contributeurs.

2. Composants de la Golden Path

2.1. Page d’accueil (vitrine SSG + Sanity)1/4

Slice associé : Slice 1

Description : La page d’accueil est le premier point d’entrée des utilisateurs. Elle doit être générée en SSG (Static Site Generation) à partir du contenu Sanity, avec un PageBuilder flexible pour les sections marketing.

2.1. Page d’accueil (vitrine SSG + Sanity)2/4

Prérequis :

Schéma Sanity page avec PageBuilder
Blocs PageBuilder (hero, features, testimonials, cta, richText, imageGallery)
Route Astro index.astro (SSG)
Layout MainLayout.astro
Utilitaire getSanityClient()
Middleware Cloudflare (pour preview)

2.1. Page d’accueil (vitrine SSG + Sanity)3/4

Critères d’acceptation :

La page d’accueil s’affiche correctement en production (SSG)
Les blocs PageBuilder sont rendus correctement
Les métadonnées SEO sont injectées (title, description, OG)
Le mode Preview permet de voir les brouillons de page
Le cache Edge fonctionne correctement
La page est indexée par Pagefind

2.1. Page d’accueil (vitrine SSG + Sanity)4/4

Tests E2E :

Navigation sur la page d’accueil
Affichage des différents blocs PageBuilder
Vérification des métadonnées SEO
Test du mode Preview (via Sanity Studio)

2.2. Article de blog (SSG + Sanity + Portable Text)1/4

Slice associé : Slice 2

Description : Un article de blog complet avec contenu Portable Text, métadonnées, et références vers l’auteur et les catégories. Il démontre la gestion des contenus chronologiques et des relations dans Sanity.

2.2. Article de blog (SSG + Sanity + Portable Text)2/4

Prérequis :

Schémas Sanity post, author, category
Route Astro blog/index.astro (listing)
Route Astro blog/[slug].astro (détail)
Layout BlogLayout.astro
Génération de types TypeScript (sanity-typegen)
Middleware Cloudflare (pour preview)

2.2. Article de blog (SSG + Sanity + Portable Text)3/4

Critères d’acceptation :

La liste des articles s’affiche correctement
Un article individuel s’affiche avec son contenu Portable Text
Les références (auteur, catégories) sont résolues
Le mode Preview fonctionne pour les articles
Les métadonnées SEO sont injectées
La pagination fonctionne (si applicable)
Les articles sont indexés par Pagefind

2.2. Article de blog (SSG + Sanity + Portable Text)4/4

Tests E2E :

Navigation vers la liste des articles
Navigation vers un article individuel
Affichage du contenu Portable Text
Affichage de l’auteur et des catégories
Test du mode Preview (via Sanity Studio)

2.3. Recherche Pagefind (indexant au moins ces 2 pages)1/4

Slice associé : Slice 2 + Slice 8

Description : La recherche unifiée indexe le contenu Sanity (page d’accueil, articles de blog) et permet aux utilisateurs de trouver rapidement l’information. Pagefind est exécuté au build et génère un index statique.

2.3. Recherche Pagefind (indexant au moins ces 2 pages)2/4

Prérequis :

Pagefind intégré dans le pipeline de build
Page d’accueil et articles de blog générés en HTML
Configuration des règles d’indexation
Interface de recherche dans le header

2.3. Recherche Pagefind (indexant au moins ces 2 pages)3/4

Critères d’acceptation :

Pagefind indexe la page d’accueil
Pagefind indexe les articles de blog
La barre de recherche fonctionne correctement
Les résultats sont pertinents et triés
Les résultats sont distingués par type (Page, Blog)
L’index est régénéré à chaque build

2.3. Recherche Pagefind (indexant au moins ces 2 pages)4/4

Tests E2E :

Recherche d’un terme présent sur la page d’accueil
Recherche d’un terme présent dans un article
Vérification de la pertinence des résultats
Test de l’affichage des badges de type

2.4. Mode Preview (pour les contributeurs)1/4

Slice associé : Slice 1 + Slice 2

Description : Le mode Preview permet aux contributeurs marketing de visualiser les contenus en brouillon (draft) avant publication. Il est activé via un secret token depuis Sanity Studio et géré par le Middleware Cloudflare.

2.4. Mode Preview (pour les contributeurs)2/4

Prérequis :

Middleware Cloudflare déployé
Route /api/preview dans le middleware
Secret de preview configuré
Utilitaire getSanityClient() avec détection du cookie
Route /api/exit-preview pour sortir du mode preview

2.4. Mode Preview (pour les contributeurs)3/4

Critères d’acceptation :

Le bouton “Open Preview” dans Sanity Studio fonctionne
Le secret de preview est validé par le middleware
Le cookie sanity-preview est posé correctement
Le client Sanity bascule en mode previewDrafts
Les contenus draft s’affichent dans le vrai design
La route /api/exit-preview supprime le cookie
Le cache Edge est bypassé en mode preview

2.4. Mode Preview (pour les contributeurs)4/4

Tests E2E :

Activation du mode preview depuis Sanity Studio
Affichage d’un contenu draft
Sortie du mode preview
Vérification que le contenu draft n’est pas visible sans le cookie

2.5. Webhook de rebuild (déclenchement automatique du build)1/4

Slice associé : Slice 6

Description : Le webhook Sanity déclenche automatiquement le rebuild du site lorsqu’un contenu est publié. Cela permet aux contributeurs de publier sans intervention technique.

2.5. Webhook de rebuild (déclenchement automatique du build)2/4

Prérequis :

Worker cms-webhook-receiver déployé
Validation HMAC-SHA256 des signatures
KV webhook-lock-kv pour debounce
Pipeline CI/CD configuré avec deploy hook
Configuration webhook dans Sanity Studio

2.5. Webhook de rebuild (déclenchement automatique du build)3/4

Critères d’acceptation :

La publication d’un contenu déclenche le webhook
La signature webhook est validée cryptographiquement
Le debounce évite les rebuilds multiples (2 min)
Le deploy hook est appelé correctement
Le build se lance automatiquement
Le nouveau contenu est visible après le build
Une alerte est envoyée en cas d’échec de rebuild

2.5. Webhook de rebuild (déclenchement automatique du build)4/4

Tests E2E :

Publication d’un article depuis Sanity Studio
Vérification du déclenchement du webhook
Vérification du lancement du build
Vérification de l’apparition du nouveau contenu

3. Périmètre Hors Golden Path

Les fonctionnalités suivantes sont explicitement hors périmètre de la Golden Path et ne doivent pas être abordées avant sa stabilisation :

3.1. Portfolio (Slice 3)

Galerie de projets
Projets mis en avant
Filtres par technologie

3.2. Formulaire de contact (Slice 4)

Page de contact
Worker form-handler
Intégration CRM
Protection Turnstile

3.3. Upload de médias (Slice 5)

Worker media-upload
URLs présignées R2
Cloudflare Stream
Intégration Sanity Studio

3.4. Backup & Cleanup (Slice 7)

Worker sanity-backup
Worker media-cleanup
Cron triggers
Safety locks

3.5. Documentation technique (Slice 8)

Intégration Starlight
Fichiers Markdown/MDX
Navigation hiérarchique

4. Critères de validation du Golden Path

Le Golden Path est considéré comme stabilisé lorsque tous les critères suivants sont validés :

4.1. Critères fonctionnels

La page d’accueil est fonctionnelle en production
Au moins un article de blog est publié et visible
La recherche Pagefind indexe et retourne des résultats
Le mode Preview fonctionne pour les pages et articles
Le webhook de rebuild déclenche les builds automatiquement

4.2. Critères techniques

Tous les tests E2E passent (Playwright)
Le score Lighthouse est ≥ 90 pour toutes les pages
Le build SSG se termine sans erreur
Les types TypeScript sont générés correctement
Aucune erreur dans les logs Cloudflare

4.3. Critères de sécurité

Le secret de preview n’est pas exposé
Les signatures webhook sont validées
Le cache Edge fonctionne correctement
Les en-têtes CSP sont appliqués

4.4. Critères de documentation

Toutes les fiches d’objets du Golden Path sont complètes
Les ADR sont rédigés si nécessaire
Le README du projet est à jour
Les commandes de déploiement sont documentées

5. Plan de validation du Golden Path

Étape 1 : Implémentation (Slices 1, 2, 6)

Durée estimée : 5-8 jours
Livrables :
- Slice 1 : Page d’accueil + Preview
- Slice 2 : Blog + Preview
- Slice 6 : Webhook de rebuild

Étape 2 : Tests E2E

Durée estimée : 1-2 jours
Scénarios :
- Navigation complète (accueil → blog → article)
- Mode Preview (activation → visualisation → sortie)
- Recherche Pagefind (indexation → requête → résultats)
- Webhook (publication → rebuild → vérification)

Étape 3 : Stabilisation

Durée estimée : 1-2 jours
Actions :
- Correction des bugs identifiés
- Optimisation des performances
- Validation des scores Lighthouse
- Documentation des ajustements

Étape 4 : Déploiement en production

Durée estimée : 1 jour
Actions :
- Déploiement du middleware Cloudflare
- Déploiement du site Astro
- Déploiement du worker webhook
- Configuration des webhooks Sanity
- Validation du pipeline complet

6. Indicateurs de succès

Indicateurs techniques

Temps de build : < 5 minutes
Score Lighthouse : ≥ 90 (Performance, Accessibility, Best Practices, SEO)
Taux d’erreur : < 1% sur les requêtes
Temps de rebuild : < 10 minutes après publication

Indicateurs business

Autonomie des contributeurs : Les équipes marketing peuvent publier sans intervention technique
Visibilité du contenu : Le contenu est indexé par Pagefind et les moteurs de recherche
Expérience contributeur : Le mode Preview fonctionne de manière fluide

7. Risques et mitigations

Risque 1 : Complexité du mode Preview

Description : Le mode Preview nécessite une coordination entre le middleware, le client Sanity, et les cookies.

Mitigation :

Documenter précisément le flux dans les fiches d’objets
Tester le mode Preview en local avec wrangler dev
Fournir un guide de troubleshooting aux contributeurs

Risque 2 : Échec du webhook de rebuild

Description : Le webhook peut échouer si le pipeline CI/CD est indisponible.

Mitigation :

Implémenter l’alerting en cas d’échec
Documenter la procédure de rebuild manuel
Surveiller les logs du worker webhook

Risque 3 : Indexation Pagefind incomplète

Description : Pagefind peut ne pas indexer correctement certains contenus.

Mitigation :

Configurer les règles d’exclusion précisément
Tester l’indexation avec différents types de contenu
Surveiller les logs de build Pagefind

8. Transition post-Golden Path

Une fois le Golden Path stabilisé, l’équipe peut :

Célébrer la livraison : Le site est fonctionnel et testable
Collecter du feedback : Obtenir l’avis des contributeurs marketing
Prioriser les slices suivants : Déterminer quelles fonctionnalités annexes sont prioritaires
Continuer le développement : Reprendre le cycle DOC → SPEC → CODE → TEST → INTÉG pour les slices restants

9. Checklist de validation du Golden Path1/3

Avant de considérer le Golden Path comme terminé :

9. Checklist de validation du Golden Path2/3

9. Checklist de validation du Golden Path3/3

Historique des modifications

Date	Version	Description	Auteur
2026-09-04	1.0	Définition du périmètre de la Golden Path	AMN