Rapports de validation¶
Statut¶
Document canonique pour la structure et les invariants des rapports de validation produits après un cycle d'audit ou de simulation.
Un rapport de validation formalise une décision. Il ne remplace ni une documentation d'architecture, ni un ADR, ni les résultats bruts d'un audit.
Rôle¶
Les rapports de validation synthétisent les preuves produites pendant un cycle industriel afin de conclure explicitement sur une évolution.
Ils doivent permettre de répondre à trois questions :
- qu'est-ce qui a été mesuré ;
- avec quelles données et quelles règles ;
- pourquoi la décision finale est-elle justifiée.
Audit / comparaison / simulation
↓
Résultats reproductibles
↓
Rapport de validation
↓
Décision explicite et traçable
Nature du document¶
Un rapport de validation est :
- une synthèse factuelle ;
- une preuve de reproductibilité ;
- un enregistrement de décision ;
- un point d'entrée vers les résultats détaillés.
Il n'est pas :
- un outil d'exécution ;
- un correctif ;
- un journal exhaustif ;
- une copie de la documentation d'architecture ;
- une justification reconstruite après coup.
Entrées minimales¶
Chaque rapport doit identifier clairement :
- le problème ou l'hypothèse étudiée ;
- le périmètre fonctionnel et technique ;
- le jeu de données ou le run analysé ;
- la version du code ou le commit ;
- les commandes exécutées ;
- les paramètres significatifs ;
- les documents canoniques applicables ;
- les résultats bruts ou artefacts associés.
Une métrique sans périmètre, sans dénominateur ou sans version de code ne constitue pas une preuve suffisante.
Structure obligatoire¶
1. Contexte¶
Décrire précisément le problème initial, l'état observé et la raison de l'étude.
Le contexte doit rester compréhensible plusieurs mois plus tard sans dépendre de la mémoire de l'équipe.
2. Hypothèse¶
Formuler une hypothèse testable.
Exemple :
La nouvelle règle de preuve image/couleur doit réduire les faux conflits sans augmenter les mutations ni masquer les cas inconnus.
3. Périmètre¶
Documenter :
- les verticales ;
- les marchands ou feeds ;
- les runs ;
- les tables ou projections lues ;
- les exclusions ;
- les limites connues.
4. Méthode¶
Lister les audits, simulations, comparaisons et vérifications exécutés.
Les commandes doivent être copiables. Pour le runtime WordPress du dépôt, la forme opératoire de référence est :
docker compose exec platform-worker wp ...
La présence d'une commande WP-CLI doit être vérifiée avec wp help ou par parsing du JSON produit par wp cli cmd-dump --format=json. Un simple grep sur le flux JSON n'est pas une preuve fiable.
5. État initial¶
Présenter la baseline avant évolution avec des métriques réconciliées.
Chaque compteur doit avoir :
- un nom stable ;
- une définition ;
- un dénominateur ;
- une source ;
- une période ou un run.
6. Résultats¶
Présenter les observations factuelles, sans mélanger immédiatement l'interprétation.
Exemples :
- lignes scannées ;
- cas vérifiables ;
- cas correspondants ;
- conflits ;
- preuves insuffisantes ;
- inconnus ;
- remplacements proposés ;
- mutations réellement effectuées ;
- temps d'exécution ;
- erreurs et codes de sortie.
7. Analyse¶
Expliquer les résultats et leurs limites :
- causes principales ;
- distribution des familles d'écarts ;
- cas ambigus ;
- dette résiduelle ;
- risques de faux positifs et faux négatifs ;
- conséquences opérationnelles.
Une amélioration globale ne doit jamais masquer une régression sur une sous-population importante.
8. Décision¶
La conclusion doit utiliser un statut explicite :
- VALIDÉ ;
- VALIDÉ AVEC RÉSERVES ;
- REFUSÉ ;
- INCONCLUSIF ;
- INVESTIGATION SUPPLÉMENTAIRE REQUISE.
La décision doit être directement reliée aux critères d'acceptation annoncés.
9. Suites¶
Documenter les actions restantes, leur priorité et leur propriétaire lorsque cela est pertinent.
Un rapport validé avec réserves doit nommer précisément les réserves ; il ne doit pas transformer une incertitude en approbation implicite.
Contrat des métriques¶
Les métriques d'un rapport doivent être :
- définies ;
- réconciliables ;
- stables entre deux exécutions comparables ;
- sérialisables ;
- interprétables sans lire le code ;
- reliées à leur population d'entrée.
Exemple de réconciliation :
scanned
= checked
+ unknown_actual
+ ambiguous
+ excluded
+ errors
La formule exacte dépend du composant, mais les catégories doivent couvrir la population sans double comptage silencieux.
Media Quality¶
Pour Media Quality, le rapport doit distinguer au minimum :
scanned;checked;matched;mismatched;unknown_actual;ambiguous;replacement_found;replacement_not_found;mutations_proposed;mutations_applied.
Le mode par défaut est audit-first et non destructif.
Par conséquent :
mutations_applied = 0
est l'attendu sauf activation explicite, documentée et testée d'une politique de mutation.
Le rapport doit aussi signaler si le jeu de données a été contaminé par un ancien comportement destructif. Une projection historique dans laquelle des image_norm ont déjà été vidées doit être régénérée avant toute conclusion sur la nouvelle implémentation.
Un seuil cible ne remplace pas l'analyse. Par exemple, atteindre un faible nombre de mismatched en déplaçant artificiellement les cas vers unknown_actual n'est pas une validation.
Audit-first et preuve de non-mutation¶
Pour les audits et simulations, le rapport doit inclure une preuve de lecture seule appropriée au risque :
- absence d'appel aux Write Services ;
- compteurs de mutation à zéro ;
- comparaison avant/après des tables sensibles ;
- transaction annulée dans un environnement de test, si applicable ;
- test automatisé de non-écriture.
Le libellé dry-run ne suffit pas à garantir l'absence d'effet de bord. Le comportement réel doit être vérifié.
Traçabilité¶
Chaque rapport doit référencer :
- le commit ou la branche ;
- le run, snapshot ou dataset ;
- les commandes ;
- les sorties brutes ;
- les documents d'architecture concernés ;
- les éventuels ADR ;
- les tests exécutés et leur résultat.
Les valeurs temporaires, noms de conteneurs, préfixes SQL et chemins locaux doivent être présentés comme contexte observé, pas comme constantes universelles, sauf lorsqu'un document opérationnel canonique les définit explicitement.
Reproductibilité¶
Un autre opérateur doit pouvoir reproduire l'étude à partir du rapport.
Le rapport doit donc préciser les préconditions :
- état du dépôt ;
- disponibilité du runtime ;
- état du schéma ;
- état de la projection ;
- configuration requise ;
- restrictions d'environnement ;
- ordre des commandes.
Un résultat non reproductible peut rester utile comme signal, mais ne peut pas suffire seul à valider une évolution.
Garde-fous¶
Un rapport de validation ne doit jamais :
- masquer des résultats défavorables ;
- omettre les erreurs d'exécution ;
- comparer des populations incompatibles ;
- utiliser un pourcentage sans effectif ;
- qualifier de succès un déplacement d'erreurs vers une catégorie non mesurée ;
- présenter une mutation comme un audit ;
- conclure sur des données historiques déjà altérées ;
- recopier des listes de fichiers ou de colonnes susceptibles de devenir rapidement obsolètes lorsqu'un lien vers la source canonique suffit.
Invariants¶
Décision explicite¶
Chaque rapport se termine par un statut non ambigu.
Preuves avant conclusion¶
La décision repose sur des résultats mesurés et reproductibles.
Séparation des responsabilités¶
Le rapport observe et conclut. Il ne corrige pas les données et ne déclenche pas implicitement un Write Service.
Honnêteté des métriques¶
Les populations, exclusions, erreurs et limites restent visibles.
Audit non destructif¶
Pour Media Quality et les autres audits read-only, aucune donnée métier n'est modifiée par défaut.
Traçabilité complète¶
Le code, les données, les commandes et les artefacts utilisés sont identifiables.
Modèle minimal¶
# Validation — <sujet>
## Statut
VALIDÉ | VALIDÉ AVEC RÉSERVES | REFUSÉ | INCONCLUSIF
## Contexte
...
## Hypothèse
...
## Périmètre
- commit : ...
- run/dataset : ...
- verticale/feed : ...
## Méthode
```bash
...
Baseline¶
| Métrique | Valeur | Définition |
|---|---|---|
Résultats¶
| Métrique | Avant | Après | Delta |
|---|---|---|---|
Analyse¶
...
Risques et limites¶
...
Décision¶
...
Suites¶
... ```