Audits¶

Statut¶

Source canonique du contrat d'audit read-only de CMonChoix Platform.

Rôle¶

Un audit est un Read Service qui observe un état réel, calcule des indicateurs et explique des écarts sans modifier la Platform.

Il sert à répondre à une question précise, par exemple :

pourquoi deux offres ne convergent pas vers la même identité ;
pourquoi une projection est incomplète ;
pourquoi un score ou un statut diffère ;
pourquoi une règle Media Quality produit une catégorie donnée ;
si un correctif améliore réellement les KPI sans régression.

Un audit ne corrige rien. Il produit les preuves nécessaires à une décision.

Position dans l'architecture¶

Sources persistées / projections / événements
                    ↓
              Read Service
                    ↓
           Résultat d'audit
                    ↓
      Décision humaine ou automatisée

La CLI, l'admin ou un rapport peuvent exposer le résultat, mais le calcul d'audit reste transport-neutral.

Contrat read-only¶

Un audit peut :

lire des tables et projections existantes ;
agréger, comparer et classer des résultats ;
produire des métriques, raisons et échantillons ;
générer un rapport sérialisable ;
rejouer un calcul déterministe sur un snapshot identifié.

Un audit ne doit jamais :

écrire dans une table métier ou technique ;
déclencher un Write Service ;
reconstruire silencieusement une projection ;
corriger une identité, une image ou un attribut ;
modifier le runtime pour rendre le résultat plus favorable ;
confondre observation et mutation dans une même commande.

Une opération qui installe un schéma, crée des tables temporaires persistantes, met à jour un snapshot ou réécrit des offres n'est pas un audit read-only, même si sa commande s'appelle audit.

Démarche industrielle¶

Question
   ↓
Périmètre et snapshot
   ↓
Mesure reproductible
   ↓
Classification des causes
   ↓
Échantillons explicables
   ↓
Décision
   ↓
Simulation ou correctif séparé
   ↓
Nouvel audit de validation

Le snapshot, le run, la verticale, le feed et les filtres doivent être explicites afin qu'un résultat puisse être reproduit.

Familles d'audits¶

Comparaison¶

Compare deux implémentations, deux snapshots ou deux versions de politique.

Les compteurs doivent être réconciliables :

total = identiques + différences + non comparables

Résolution et identité¶

Explique les candidats, identifiants, conflits, raisons de rejet et niveaux de confiance utilisés pour construire une identité.

Projection¶

Vérifie la cohérence entre la vérité source et les vues dérivées : lignes absentes, doublons, attributs incomplets, ordre de reconstruction et fraîcheur.

Qualité¶

Mesure la complétude, la cohérence et la force des preuves disponibles. Le résultat doit séparer le score, la classe, les raisons et les avertissements.

Media Quality¶

Media Quality fonctionne par défaut en audit-first :

observation
→ extraction des preuves
→ classification
→ score et raisons
→ métriques

L'audit ne vide pas image_norm et ne remplace pas une image. Toute mutation éventuelle appartient à une politique d'écriture distincte, explicitement activée et suffisamment confiante.

Les métriques utiles incluent notamment :

lignes scannées et éligibles ;
lignes effectivement évaluées ;
preuves disponibles ou manquantes ;
catégories matched, mismatched, unknown_actual, ambiguous ;
remplacement proposé, accepté ou introuvable ;
mutations demandées et réellement appliquées.

Les compteurs d'une exécution historique ne sont pas fiables si une ancienne version destructive a déjà effacé des images. La projection doit alors être régénérée avant comparaison.

Validation¶

Confirme qu'un objectif mesurable est atteint et qu'aucune régression importante n'est introduite. Il doit publier les seuils, le résultat et les échecs, pas seulement un KPI global.

Modèle de résultat¶

Un résultat d'audit devrait être sérialisable sous une forme proche de :

AuditResult
- audit_name
- version
- snapshot_or_run_id
- started_at
- completed_at
- filters
- counters
- ratios
- reason_counts
- warnings
- samples
- status

status doit distinguer au minimum :

succès technique avec résultat conforme ;
succès technique avec écarts détectés ;
entrée invalide ;
données insuffisantes ;
échec technique.

Explicabilité¶

Un bon audit ne livre pas seulement des totaux. Il fournit :

la définition exacte de chaque compteur ;
des raisons stables et regroupables ;
un échantillon représentatif des écarts ;
les limites connues ;
les données non évaluées et leur cause.

Les catégories inconnues ne doivent pas être fusionnées avec les erreurs. unknown, ambiguous, not_applicable et technical_failure décrivent des situations différentes.

Reproductibilité¶

À données, configuration et version identiques, un audit doit produire le même résultat logique.

Le rapport doit donc identifier :

le run ou snapshot observé ;
la version de l'audit ou de la règle ;
les filtres et limites ;
les options modifiant le calcul ;
les éventuels échantillonnages.

Les timestamps d'exécution peuvent varier ; les métriques métier ne doivent pas varier sans cause documentée.

Interface CLI¶

La CLI est un adapter mince : parsing, validation, délégation et formatage.

Forme opératoire du projet :

docker compose exec platform-worker wp --allow-root --path=/var/www/html ...

La présence d'une commande doit être vérifiée par wp help ou en analysant réellement la sortie JSON de wp cli cmd-dump --format=json. Un simple grep dans le dump complet n'est pas une preuve fiable.

Les sorties humaines et JSON doivent exposer les mêmes compteurs fondamentaux. Une commande d'audit ne doit pas changer de comportement selon le format choisi.

Performance et sécurité¶

Un audit volumineux doit prévoir :

pagination ou traitement par batch ;
limites explicites ;
mémoire bornée ;
délais observables ;
absence de verrous métier prolongés ;
annulation sans données partielles persistées.

L'optimisation ne doit pas supprimer les raisons, les inconnues ou les échantillons nécessaires au diagnostic.

Tests attendus¶

Chaque audit important doit être couvert par :

tests du calcul pur ;
tests de réconciliation des compteurs ;
tests read-only garantissant l'absence d'écriture ;
tests sur données manquantes et ambiguës ;
tests de stabilité des reason codes ;
tests de l'adapter CLI séparés du Read Service ;
un cas de non-régression sur un échantillon réel anonymisé ou fixture représentative.

Invariants¶

Un audit ne modifie aucune donnée.
Une question d'audit possède un périmètre explicite.
Tous les compteurs principaux sont définis et réconciliables.
Les données non évaluées restent visibles.
Les raisons sont stables, explicables et regroupables.
La CLI n'héberge pas le calcul métier.
Un correctif et sa validation sont deux étapes distinctes.
Media Quality reste non destructif par défaut.
Un snapshot contaminé par une ancienne mutation doit être reconstruit avant comparaison.
Un audit échoué ne doit jamais laisser une écriture partielle.