PD-226 — Retour d'expérience¶

1. Résumé exécutif¶

La User Story PD-226 visait à établir la configuration initiale d'un projet Astro pour le site vitrine ProbatioVault, avec des contraintes strictes de génération statique et de sécurité CSP. L'implémentation a produit un site fonctionnel avec Astro 5.16, des polices locales (@fontsource) et une structure de pages complète. Cependant, deux écarts majeurs ont été identifiés : l'absence de verrouillage explicite du mode statique dans la configuration et l'absence du fichier _headers pour la CSP. Verdict : ACCEPTÉ AVEC RÉSERVES.

2. Points fluides¶

• Installation et configuration initiale d'Astro 5.16 sans difficulté
• Intégration des polices Inter et Space Grotesk via @fontsource (ressources locales)
• Structure de projet claire et conforme aux conventions Astro
• Configuration i18n native d'Astro fonctionnelle dès le départ
• BaseLayout.astro bien structuré avec SEO, OpenGraph et hreflang
• Build statique fonctionnel produisant des fichiers HTML/CSS purs
• Aucune dépendance à un framework JavaScript client (React, Vue, etc.)

3. Points difficiles¶

• Configuration implicite vs explicite : Astro utilise output: 'static' par défaut, ce qui a conduit à ne pas le spécifier explicitement dans astro.config.mjs. Cette omission crée un risque de régression si un développeur ajoute un adapter par mégarde.

• Headers de sécurité non implémentés : Le fichier public/_headers prévu dans le plan d'implémentation n'a pas été créé. La configuration CSP, COOP/COEP et Referrer-Policy est absente.

• Scripts de validation absents : Le script validate-static.sh prévu pour la CI n'a pas été implémenté. Aucune vérification automatisée du mode statique.

4. Hypothèses révélées tardivement¶

• Support _headers par GitLab Pages : L'hypothèse que GitLab Pages supporte le format _headers (style Netlify/Cloudflare) n'a pas été vérifiée. GitLab Pages utilise un mécanisme différent pour les headers HTTP.

• Comportement par défaut d'Astro : La valeur par défaut output: 'static' a été considérée comme suffisante, alors que la spec exigeait un verrouillage explicite et vérifiable.

5. Invariants complexes¶

6. Dette technique¶

7. Risques résiduels¶

8. Améliorations processus¶

• Valider les hypothèses d'infrastructure avant l'implémentation (ex: support _headers par GitLab Pages)
• Rendre explicites les valeurs par défaut même quand elles correspondent au comportement souhaité
• Créer les scripts de validation CI en même temps que le code, pas après
• Tester le déploiement réel pour valider les headers HTTP effectifs

9. Enseignements clés¶

1. Les valeurs par défaut ne sont pas des garanties — Un output: 'static' implicite peut être écrasé. L'explicite est toujours préférable pour les invariants critiques.

2. Les headers HTTP dépendent de l'infrastructure — GitLab Pages ne supporte pas _headers comme Netlify. Il faut vérifier la documentation de la plateforme cible.

3. La validation automatisée doit précéder le code — Sans script de validation en CI, les invariants ne sont que des promesses.

4. Le plan d'implémentation doit être un contrat — Tous les fichiers listés dans le plan doivent être créés, pas seulement ceux "essentiels".

5. Un site fonctionnel n'est pas un site conforme — Le build passe, le site fonctionne, mais les exigences de sécurité (CSP) ne sont pas satisfaites.

10. Addendum — Résolution des écarts¶

[2025-12-21] — Mise à jour suite à acceptation finale¶

Les écarts E-01 et E-02 identifiés lors de la revue initiale ont été corrigés :

Verdict final : ✅ ACCEPTÉ (2025-12-20)