CLI — Audits¶

Status: CURRENT

À quoi sert cette page ?¶

Cette page décrit la posture d'exploitation des audits CLI de CMonChoix Platform.

L'architecture des Read Services reste documentée dans :

La CLI n'est qu'un Adapter : elle expose une capacité d'audit existante, valide les arguments, délègue au service concerné puis affiche le résultat.

Règle fondamentale¶

Un audit CLI observe et explique l'état de la Platform sans modifier la vérité métier, une projection ou la configuration runtime.

Opérateur
   ↓
Adapter WP-CLI
   ↓
Read Service / service d'audit
   ↓
Lectures
   ↓
Métriques + raisons + échantillons

Un audit sert notamment à :

établir une baseline reproductible ;
comparer deux runs ou deux implémentations ;
expliquer les différences résiduelles ;
qualifier les cas unknown, ambiguous ou conflict ;
vérifier une hypothèse avant toute mutation ;
produire les preuves nécessaires à une décision opérationnelle.

Invocation canonique¶

Depuis la racine du dépôt :

docker compose exec platform-worker wp --allow-root --path=/var/www/html <commande>

Avant d'utiliser une commande comme preuve de Runtime actuel, vérifier son enregistrement réel :

docker compose exec platform-worker wp --allow-root --path=/var/www/html help <commande>

ou parser proprement :

docker compose exec platform-worker wp --allow-root --path=/var/www/html cli cmd-dump --format=json

Un simple grep dans le flux JSON brut n'est pas une preuve fiable de présence de commande.

Ce qu'un audit peut faire¶

Un audit peut :

lire des données source, de Stage, normalisées ou projetées ;
exécuter des comparaisons déterministes ;
calculer des métriques et des preuves ;
produire des reason codes ;
sortir des échantillons pour revue manuelle ;
écrire un artefact de rapport uniquement si cette sortie est explicitement demandée.

Écrire un fichier de rapport n'est pas équivalent à modifier l'état métier de la Platform, mais cet effet doit rester explicite.

Ce qu'un audit ne doit pas faire¶

Un audit read-only ne doit jamais :

mettre à jour une offre ou une identité ;
vider ou remplacer une image ;
reconstruire implicitement une projection ;
installer ou migrer un schéma ;
modifier une option runtime ;
toucher à la queue ;
prendre ou modifier un lock persistant ;
basculer silencieusement vers un mode correctif.

Attention aux commandes nommées `audit` ou `dry-run`¶

Le nom d'une commande ne garantit pas son innocuité.

Certaines surfaces techniques, notamment Taxonomy V2, peuvent avoir des effets techniques même lorsqu'elles exposent un mode audit ou dry-run, par exemple installation de schéma ou création de tables temporaires.

Il faut donc vérifier le comportement réel de la commande avant de la classer comme strictement read-only.

Modèle de preuve attendu¶

Un audit industriel ne doit pas se résumer à un pourcentage global.

Selon son rôle, il doit exposer :

population totale considérée ;
population éligible ;
lignes effectivement évaluées ;
résultats positifs et négatifs ;
cas ignorés regroupés par raison ;
cas unknown ;
cas ambiguous ;
cas conflict lorsque le domaine concerné le produit ;
distribution de confiance lorsqu'elle existe ;
remplacements ou corrections proposés ;
mutations demandées ;
mutations réellement appliquées ;
run_id, feed, verticale ou version de règle.

Les compteurs doivent être réconciliables : aucune ligne scannée ne doit disparaître silencieusement des catégories terminales.

Media Quality¶

Media Quality reste audit-first et non destructif par défaut.

Flux attendu :

offre normalisée / projection fraîche
        ↓
collecte des évidences
        ↓
évaluation des règles
        ↓
classification + raisons
        ↓
rapport

L'audit peut conclure à un état comme :

matched ;
mismatched ;
unknown_actual ;
ambiguous.

Il peut éventuellement proposer un candidat de remplacement, mais il ne doit jamais vider image_norm uniquement parce qu'un mismatch a été détecté.

Une mutation éventuelle appartient à une politique distincte et explicitement activée.

Si une ancienne implémentation a déjà altéré les images d'une projection, cette projection doit être régénérée avant de comparer les métriques du comportement actuel.

Workflow recommandé¶

Baseline
   ↓
Audit de comparaison
   ↓
Classification des familles d'écarts
   ↓
Analyse de résolution ou d'évidences
   ↓
Simulation / Virtual Patch
   ↓
Nouvel audit sur données fiables
   ↓
Rapport de validation

La règle importante est de ne pas mélanger observation, hypothèse, mutation et validation dans une seule commande.

Choisir le bon outil¶

Question	Page
Comparer un comportement réel	Real Sample Comparison
Regrouper les écarts par cause	Difference Family Audit
Comprendre les statuts du Resolver	Resolution Status Audit
Voir ce qu'il reste après évolution	Remaining Audit
Auditer le catalogue	Catalog Audit
Tester une hypothèse sans écriture métier	Simulation / Virtual Patch
Inspecter les candidats	Candidate Dump / Virtual Candidates Dump
Conclure le cycle	Validation Report

Sorties et codes de retour¶

La sortie humaine doit rester actionnable. Lorsqu'une commande expose un format structuré, celui-ci doit porter les mêmes compteurs fondamentaux.

Le code de retour doit distinguer au minimum :

exécution réussie et critères satisfaits ;
résultat valide mais critère de validation non atteint ;
invocation invalide ;
données insuffisantes ;
échec technique.

Une commande ne doit pas retourner un succès simplement parce qu'elle a fini de s'exécuter si son seuil explicite de validation a échoué.

Reproductibilité¶

Tout audit utilisé pour prendre une décision doit conserver suffisamment de contexte pour être reproduit :

commande et arguments ;
commit Git ;
version plugin/runtime si distincte ;
run ou feed ;
verticale et filtres ;
version de règle ;
configuration et seuils ;
horodatage ;
éventuel échantillonnage.

Diagnostic d'un résultat surprenant¶

Avant de modifier du code :

vérifier la commande réellement enregistrée ;
vérifier le run, feed et périmètre ;
vérifier que les données observées sont fraîches et non contaminées par une ancienne mutation ;
réconcilier les compteurs ;
distinguer unknown, ambiguous, conflict d'une erreur technique ;
vérifier si l'effet vient du Read Service ou uniquement du formatage CLI ;
seulement ensuite investiguer la règle métier ou le Pipeline.

Invariants¶

Un audit est read-only par défaut.
Toute mutation appartient à une action séparée et explicitement documentée.
Les compteurs se réconcilient avec la population évaluée.
Une preuve inconnue n'est jamais présentée comme un match réussi.
Un KPI global ne masque pas des cas critiques non résolus.
Une baseline contaminée est régénérée avant comparaison.
L'Adapter CLI ne porte ni calcul métier ni persistance.
Un audit CLI ne dépend pas du frontend public.