Aller au contenu

PD-233 — Retour d'expérience

📚 Navigation User Story | Document | | | ---------- | -- | | 📋 [Spécification](PD-233-specification.md) | | | 🛠️ [Plan d'implémentation](PD-233-plan.md) | | | ✅ [Critères d'acceptation](PD-233-acceptability.md) | | | 📝 **Retour d'expérience** | *(ce document)* | [← Retour à site-vitrine](../PD-225-epic.md) · [↑ Index User Story](index.md)

1. Résumé exécutif

Objectif : Implémenter un cadre de validation automatisé garantissant que toute communication publique sur le site vitrine respecte les règles pré-INPI (pas de divulgation de procédés techniques, termes interdits, descriptions procédurales).

Résultat : Le script validate-content.ts est opérationnel avec détection des termes interdits (E001), des séquences procédurales (E002), et des placeholders non remplis (E004). La validation CI/CD est intégrée et bloquante. Le TextExactMatcher (E003) est implémenté mais désactivé en raison de faux positifs.

Verdict : US acceptée avec une dette technique identifiée (TextExactMatcher à affiner).

2. Points fluides

  • Architecture modulaire : Séparation claire des responsabilités (ForbiddenTermsDetector, SequencePatternDetector, PlaceholderChecker) facilitant la maintenance
  • Intégration CI/CD : Pipeline GitLab configuré avec job validate-content bloquant sur main et MR
  • Gestion bilingue : Détection automatique de la langue (FR/EN) et application des règles correspondantes
  • Gestion des exceptions contextuelles : Les pages how-it-works et les annexes copywriting peuvent utiliser les patterns "Étape/Step" (contenu marketing légitime)
  • Messages d'erreur explicites : Format structuré avec code, fichier, ligne, contexte et action suggérée
  • Termes ambigus (W001) : "racine"/"root" génèrent des warnings (revue humaine) et non des erreurs bloquantes

3. Points difficiles

  • TextExactMatcher (E003) désactivé : L'extraction de texte visible des fichiers Astro génère trop de faux positifs (classes CSS, attributs HTML, titres de page). Le validateur existe mais est commenté dans validateFile().

  • Patterns de séquence trop stricts : Les regex initiales bloquaient du contenu marketing légitime ("Étape 1: Déposez", "Step 2: Verify"). Nécessité d'ajouter des exceptions explicites pour les pages how-it-works et les annexes.

  • Gestion des apostrophes typographiques : Les textes sources utilisent ' (apostrophe typographique) tandis que le code contient parfois ' (apostrophe droite). Le normalizeText() harmonise les deux.

  • Portée CI initiale incomplète : Le job CI ne scannait que les .astro, omettant les .md. Corrigé en alignant sur le pre-commit (*.astro + *.md).

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

Hypothèse initiale Réalité découverte
Les textes Astro sont facilement extractibles Les fichiers Astro mélangent JSX, TypeScript, HTML et expressions. L'extraction fiable du texte visible est complexe.
Les annexes copywriting couvrent toutes les pages Les pages how-it-works ont été ajoutées après la création des annexes, nécessitant une mise à jour.
Les patterns de séquence sont universellement interdits Le marketing utilise légitimement des numérotations ("3 étapes simples"). Distinction nécessaire entre séquence technique et séquence marketing.
Un seul format de placeholder suffit Plusieurs variantes existent ([À RENSEIGNER], [TO BE PROVIDED], [TBD], [TODO]).

5. Invariants complexes

Invariant Difficulté
INV-1 : Texte affiché = texte annexe La correspondance exacte est difficile à vérifier automatiquement car les fichiers Astro transforment le contenu (composants, slots, interpolations).
INV-2 : Pas de séquence procédurale La frontière entre séquence technique interdite et séquence marketing autorisée nécessite une analyse contextuelle.
INV-3 : Termes interdits = 0 L'exhaustivité de la liste FR/EN doit être maintenue manuellement. Pas de mécanisme de synchronisation automatique.

6. Dette technique

Dette Impact Priorité
TextExactMatcher désactivé Pas de vérification automatique de conformité annexe ↔ code. Contrôle manuel requis. Haute
Pas de pre-commit hook Husky La validation locale repose sur l'exécution manuelle de npx tsx scripts/validate-content.ts. Le plan prévoyait .husky/pre-commit. Moyenne
Absence d'AuditTrail Le plan prévoyait docs/audit/content-reviews.md pour journaliser les validations. Non implémenté. Basse
Checklist manuelle assets Les images/PDF avec texte intégré ne sont pas analysables. Checklist manuelle non formalisée. Basse

7. Risques résiduels

Risque Probabilité Impact Mitigation actuelle
Texte non-conforme à l'annexe publié Moyenne Élevé (incohérence éditoriale) Revue MR manuelle
Bypass validation locale Faible Élevé CI/CD bloquant en dernier recours
Terme interdit dans asset binaire Moyenne Critique Aucune (checklist manuelle absente)
Nouvelle page sans entrée annexe Moyenne Moyen Validation silencieusement ignorée si route non trouvée
Traduction EN incomplète des termes interdits Faible Moyen Liste maintenue manuellement

8. Améliorations processus

Amélioration Bénéfice attendu
Implémenter extraction AST Astro Permettrait un TextExactMatcher fiable sans faux positifs
Ajouter Husky + lint-staged Validation automatique avant chaque commit local
Créer une checklist assets Markdown Formaliser la revue manuelle des images/PDF
Générer les listes de termes depuis un fichier YAML Faciliter la synchronisation FR/EN et l'ajout de termes
Ajouter test E2E de validation Vérifier que la validation CI fonctionne sur des exemples réels

9. Enseignements clés

  1. L'extraction de texte depuis des fichiers hybrides (Astro/JSX) est plus complexe qu'anticipé. Une approche basée sur l'AST serait plus fiable que les regex.

  2. Les règles de contenu doivent prévoir des exceptions légitimes. Le marketing utilise des patterns (numérotation, étapes) qui ressemblent à des séquences techniques interdites.

  3. La double validation (local + CI) est essentielle. Le pre-commit peut être contourné, le CI est le garde-fou final.

  4. Les annexes copywriting doivent évoluer avec le site. Chaque nouvelle page (how-it-works) nécessite une mise à jour des annexes.

  5. Un validateur désactivé est une dette visible. Le commentaire // TODO: Re-enable when E003 is fixed documente le compromis accepté.

Document généré le 2025-12-22