[Nom de la Route]

[Nom de la Route]

Documentation technique

Type de ressource : Route Astro (Page SSG / Page SSR / Endpoint API)
Fichier source : src/pages/[chemin].astro ou src/pages/api/[endpoint].ts
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de cette route dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. afficher la liste des articles de blog]
• [Bénéfice pour l’utilisateur final]

1.3. Caractéristiques

Propriété	Valeur
URL publique	/[chemin]
Mode de rendu	[SSG / SSR / Hybride]
Type	[Page HTML / Endpoint JSON / Redirect]
Méthode HTTP	[GET / POST / Les deux]
Authentification requise	[Oui / Non / Preview uniquement]
Cache	[Voir §6]

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Requête utilisateur]
     │
     ▼
[Cloudflare Pages / Edge]
     │  • Middleware global (CSP, cookies)
     │  • Routage vers Astro
     ▼
[Astro Route]
     │  • getStaticPaths (si SSG dynamique)
     │  • Récupération des données (Sanity / local)
     │  • Rendu du composant
     ▼
[Réponse HTML / JSON]

2.2. Composants impliqués

Composant	Rôle	Couche
Fichier .astro ou .ts	Définition de la route	L2 (Astro)
getSanityClient()	Récupération des données CMS	L2 (Astro)
Composants UI	Rendu visuel	L2 (Astro)
Layout	Structure HTML globale	L2 (Astro)
Middleware Cloudflare	Sécurité + Preview cookie	L3 (Cloudflare)

3. Implémentation (CODE)

3.1. Code de la route1/2

3.1. Code de la route2/2

src/pages/[chemin].astro

---
import BaseLayout from '../layouts/BaseLayout.astro';
import { getSanityClient } from '../lib/sanity';
import type { [TypeName] } from '../types/sanity';

// Configuration du rendu
export const prerender = true; // ou false pour SSR

// Génération des chemins statiques (si SSG dynamique)
export async function getStaticPaths() {
  const client = getSanityClient(/* ... */);
  const items = await client.fetch(`*[_type == "[type]" && status == "published"]{
    slug
  }`);

  return items.map(item => ({
    params: { slug: item.slug.current },
  }));
}

// Récupération des données
const { slug } = Astro.params;
const client = getSanityClient(Astro);
const data = await client.fetch<[TypeName]>(`*[_type == "[type]" && slug.current == $slug][0]{
  ...,
  author->{name, image},
  categories[]->{title, slug}
}`, { slug });

// Gestion du 404
if (!data) {
  return Astro.redirect('/404');
}
---

<BaseLayout title={data.title} description={data.seo?.metaDescription}>
  <!-- Contenu de la page -->
</BaseLayout>

3.2. Requêtes GROQ (si applicable)

*[_type == "[type]" && slug.current == $slug][0]{
  ...,
  author->{name, image},
  categories[]->{title, slug}
}

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (URL / Query / Body)

Paramètre	Type	Source	Validation
slug	string	URL params	Format valide
query	string	Query string	Validation Zod

4.2. Outputs (HTML / JSON)

Élément	Type	Description
title	string	Titre de la page
description	string	Meta description
content	object	Données du contenu

4.3. Codes de réponse

Code	Condition	Description
200	Succès	Page rendue correctement
404	Non trouvé	Redirection vers /404
500	Erreur serveur	Erreur interne

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
getStaticPaths	Génération des chemins	Liste de params valide
Récupération données	Requête GROQ	Données typées correctement
Gestion 404	Données manquantes	Redirection vers 404

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux SSG	Sanity + Astro	Build complet	Pages générées
Mode preview	Middleware + Cookie	Draft affiché	Contenu draft visible

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Navigation	Utilisateur → Route	Accès à la page	Page affichée correctement

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Layout	L2	Structure HTML	Import et wrapper
Composants UI	L2	Rendu visuel	Import et utilisation
getSanityClient	L2	Données CMS	Import et appel
Middleware	L3	Sécurité	Cookie/header

6.2. Points d’attention

• Le mode de rendu (SSG/SSR) doit être configuré correctement
• Les requêtes GROQ doivent utiliser les projections explicites
• Le 404 doit être géré correctement

6.3. Vérification de cohérence

• La route fonctionne en développement et production
• Les données sont récupérées correctement
• Le mode preview fonctionne (si applicable)
• Les tests E2E passent

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Middleware Cloudflare applique les CSP
• ✅ Validation des paramètres d’URL
• ✅ Protection contre les injections XSS

7.2. Règles de sécurité

• ✅ Ne jamais exposer de données sensibles dans le HTML
• ✅ Valider tous les paramètres d’entrée
• ✅ Utiliser les en-têtes de sécurité appropriés

8. Performance et limites

8.1. Stratégie de cache

Mode	Cache	Description
SSG	Statique	Généré au build, servi par CDN
SSR	Edge	Mis en cache par Cloudflare Edge
Preview	Désactivé	Contenu draft non caché

8.2. Limitations

• ❌ SSG : régénération requise pour mise à jour
• ❌ SSR : plus lent que SSG

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Page blanche	Erreur de récupération des données	Vérifier les logs et la requête GROQ
404 en production	getStaticPaths incorrect	Vérifier la génération des chemins
Contenu draft non visible	Cookie preview absent	Vérifier le middleware

9.2. Commandes de debug

# Build local
npm run build

# Preview du build
npm run preview

10. Bonnes pratiques

10.1. Architecture

• ✅ Utiliser des layouts pour la cohérence
• ✅ Séparer la logique de données du rendu
• ✅ Typer toutes les données avec TypeScript

10.2. Code

• ✅ Gérer les erreurs avec try/catch
• ✅ Utiliser des composants réutilisables
• ✅ Optimiser les images et les assets

10.3. Maintenance

• ✅ Documenter les changements dans ce fichier
• ✅ Tester les modifications en local avant déploiement

11. Évolutions et roadmap

11.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]

11.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

12. Ressources liées

• Documentation Astro : Routing
• DAT L2 : §5 - Architecture et Structure du Projet
• Layouts concernés : [Liste]
• Composants utilisés : [Liste]

13. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

[Nom de la Route]

1. 1. Vue d’ensemble (DOC)3
2. 1.1. Description4
3. 1.2. Objectif5
4. 1.3. Caractéristiques6
5. 2. Architecture et flux (DOC)7
6. 2.1. Diagramme de flux8
7. 2.2. Composants impliqués9
8. 3. Implémentation (CODE)10
9. 3.1. Code de la route11
10. 3.2. Requêtes GROQ (si applicable)13
11. 4. Contrats d’Entrée/Sortie (SPEC)14
12. 4.1. Inputs (URL / Query / Body)15
13. 4.2. Outputs (HTML / JSON)16
14. 4.3. Codes de réponse17
15. 5. Tests attendus (TEST)18
16. 5.1. Tests unitaires19
17. 5.2. Tests d’intégration20
18. 5.3. Tests E2E21
19. 6. Intégration (INTÉG)22
20. 6.1. Intégration avec les composants23
21. 6.2. Points d’attention24
22. 6.3. Vérification de cohérence25
23. 7. Sécurité26
24. 7.1. Mécanismes de sécurité27
25. 7.2. Règles de sécurité28
26. 8. Performance et limites29
27. 8.1. Stratégie de cache30
28. 8.2. Limitations31
29. 9. Débogage et troubleshooting32
30. 9.1. Problèmes courants33
31. 9.2. Commandes de debug34
32. 10. Bonnes pratiques35
33. 10.1. Architecture36
34. 10.2. Code37
35. 10.3. Maintenance38
36. 11. Évolutions et roadmap39
37. 11.1. Améliorations planifiées40
38. 11.2. Limitations connues41
39. 12. Ressources liées42
40. 13. Historique des modifications43