[Nom de la Pages Function]

Documentation technique

Type de ressource : Cloudflare Pages Function (Endpoint SSR Astro / API Route)
Fichier source : src/pages/api/[endpoint].ts ou functions/[path].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 Pages Function dans l’architecture SSR du site]

1.2. Objectif

[Objectif principal : ex. fournir un endpoint SSR pour le mode Preview Sanity]
[Bénéfice pour l’architecture : ex. exécution Edge sans infrastructure serveur dédiée]

1.3. Caractéristiques

Propriété	Valeur
Type	[Endpoint API / Route SSR / Middleware]
Méthode HTTP	[GET / POST / PUT / DELETE / Les deux]
Route publique	`/api/[endpoint]` ou `/[path]`
Mode de rendu	SSR (Server-Side Rendering)
Cache	[Voir §7]
Authentification	[Aucune / Cookie / Token / Les deux]

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Requête client]
     │
     ▼
[Cloudflare Pages]
     │  • Routage vers la Pages Function
     │  • Injection des bindings (Env)
     ▼
[Pages Function]
     │  • Validation des entrées
     │  • Logique métier
     │  • Interaction avec les bindings (KV, R2, Queue)
     ▼
[Services tiers / Storage]
     │  • Sanity API / CRM / R2 / KV
     ▼
[Réponse HTTP]

2.2. Composants impliqués

Composant	Rôle	Type
Pages Function	Endpoint SSR	Cloudflare Pages
Middleware Global	Sécurité + Preview cookie	Worker L3
Bindings Cloudflare	KV / R2 / Queue	Services Cloudflare
Astro SSR	Rendu des pages dynamiques	Framework

3. Configuration (CODE)

3.1. Emplacement des fichiers

# Option 1 : Routes API Astro (recommandé)
src/pages/
├── api/
│   ├── preview.ts
│   ├── exit-preview.ts
│   └── contact.ts

# Option 2 : Functions directory
functions/
├── api/
│   ├── webhook.ts
│   └── [autre-endpoint].ts

3.2. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
[Variable]	[Description]	[✅/❌]	[Valeur]

4. Implémentation (CODE)

4.1. Endpoint API (TypeScript)

import type { APIRoute } from 'astro';

export const prerender = false; // SSR

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();

  // Validation
  if (!data.field) {
    return new Response('Missing field', { status: 400 });
  }

  // Logique métier
  const result = await processSomething(data);

  return new Response(JSON.stringify(result), {
    headers: { 'Content-Type': 'application/json' },
  });
};

4.2. Route SSR (Astro)

---
export const prerender = false; // SSR

const data = await fetchData();
---

<html>
  <!-- Rendu SSR -->
</html>

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

5.1. Inputs (Requête HTTP)

Paramètre	Type	Source	Validation
`body`	`object`	Request body	Validation Zod
`headers`	`Headers`	Request headers	Validation des en-têtes

5.2. Outputs (Réponse HTTP)

Code HTTP	Condition	Description
200	Succès	Opération réussie
400	Erreur client	Requête invalide
500	Erreur serveur	Erreur interne

6. Tests attendus (TEST)

6.1. Tests unitaires

Scénario	Description	Résultat attendu
Endpoint valide	Requête valide	Réponse 200
Validation	Requête invalide	Erreur 400

6.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux complet	Bindings + Services	Opération end-to-end	Succès

7. Intégration (INTÉG)

7.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Astro	L2	Rendu SSR	Route Astro
Middleware	L3	Sécurité	Cookie/header

7.2. Points d’attention

Le mode SSR doit être explicitement configuré
Les bindings doivent être accessibles
Le cache doit être configuré correctement

7.3. Vérification de cohérence

La fonction se déploie correctement
Les bindings sont accessibles
Les tests passent

8. Sécurité

8.1. Mécanismes de sécurité

✅ Validation des entrées
✅ Middleware global
✅ HTTPS forcé

8.2. Règles de sécurité

✅ Valider toutes les entrées
✅ Ne jamais exposer de secrets
✅ Utiliser les en-têtes de sécurité

9. Performance et limites

9.1. Stratégie de cache

Mode	Cache	Description
SSR	Edge	Mis en cache par Cloudflare

9.2. Limitations

❌ SSR plus lent que SSG
❌ Limitations CPU/memory

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Fonction non appelée	Route incorrecte	Vérifier le chemin
Binding inaccessible	Configuration manquante	Vérifier wrangler.toml

10.2. Commandes de debug

# Build local
npm run build

# Preview
npm run preview

11. Bonnes pratiques

11.1. Architecture

✅ Séparer les endpoints par fonctionnalité
✅ Valider toutes les entrées
✅ Gérer les erreurs

11.2. Code

✅ TypeScript strict
✅ Logs structurés
✅ Documentation

12. Évolutions et roadmap

12.1. Améliorations planifiées

[Évolution 1]
[Évolution 2]

12.2. Limitations connues

❌ [Limitation 1]
❌ [Limitation 2]

13. Ressources liées

Documentation Cloudflare : Pages Functions

14. Historique des modifications

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