Media Quality Engine¶

Statut¶

Document canonique de référence pour le moteur de qualité média.

Ce document décrit le comportement effectif du runtime WordPress situé dans :

plugins/ccx-feeds-industrial/includes/media-quality/

Les autres documents doivent renvoyer vers cette page plutôt que recopier la politique de décision.

Finalité¶

Le Media Quality Engine contrôle la cohérence des médias associés aux offres normalisées dans ccx_offers_norm_v2.

Il est :

limité à un source_feed et un run_id ;
indépendant du marchand par défaut ;
non bloquant pour l'offre ;
idempotent ;
audit-first ;
non destructif par défaut.

Une incohérence média ne doit jamais provoquer le rejet d'une offre.

Position dans le pipeline¶

Feed source
    ↓
Stage
    ↓
Projection / normalisation des offres
    ↓
ccx_offers_norm_v2
    ↓
Normalisation de la galerie
    ↓
Media Quality Engine
    ↓
Validation et publication

Le point d'entrée public est :

ccx_media_quality_run($source_feed, $run_id, $norm_table);

L'appel canonique est effectué après la normalisation de la galerie par :

includes/pipeline/norm/20-image-gallery.php

Architecture¶

engine.php
    ↓ orchestre
rules/
    ↓ applique une politique métier isolée
evidence/
    ↓ collecte et qualifie les indices
scoring policy
    ↓ agrège les indices et calcule la confiance
decision
    ↓ resolved | unknown | ambiguous
optional mutation

Structure actuelle :

includes/media-quality/
├── engine.php
├── evidence/
│   └── color-evidence.php
└── rules/
    └── 10-main-image-color.php

Le moteur possède l'orchestration, l'isolation des erreurs, les temps d'exécution et les métriques globales.

Une règle possède une seule responsabilité média et reçoit le contexte suivant :

[
  'source_feed' => $source_feed,
  'run_id' => $run_id,
  'norm_table' => $norm_table,
]

Contrat d'une règle¶

Une règle est un callable enregistré par ccx_media_quality_rules().

Elle doit :

limiter toutes ses lectures et écritures au source_feed et au run_id courants ;
rester idempotente ;
ne jamais rejeter une offre à cause d'un média ;
conserver les cas insuffisamment prouvés dans un état unknown ;
signaler une ambiguïté au lieu de forcer une décision ;
lever une exception en cas d'échec opérationnel afin que le moteur puisse l'isoler ;
retourner des compteurs numériques stables et exploitables.

Règle `main_image_color`¶

La première règle vérifie la cohérence entre :

la couleur canonique de l'offre dans color_norm ;
la couleur réellement démontrée par les indices disponibles pour image_norm.

Principe fondamental¶

L'absence de preuve n'est pas une incohérence.

Le moteur distingue donc trois résultats :

resolved   preuve suffisante pour déterminer une couleur
unknown    preuve insuffisante ou score trop faible
ambiguous  preuves fortes contradictoires

Seul un résultat resolved peut être comparé à color_norm.

Politique de preuves¶

Les indices sont collectés par familles et pondérés selon leur fiabilité.

Preuves fortes¶

Les preuves fortes peuvent contribuer à une résolution :

couleur explicite dans un nom de fichier exploitable ;
information fournisseur explicitement structurée ;
concordance forte dans une image de galerie ;
autre source explicitement classée comme forte par la politique centrale.

Preuves faibles¶

Les preuves faibles servent au diagnostic mais ne suffisent pas seules à résoudre une couleur :

chemin technique d'URL ;
paramètres de requête ;
tokens génériques présents dans une URL complète ;
identifiants CDN ou marchands non qualifiés.

Une URL complète ne constitue donc pas automatiquement une preuve forte. Cette règle protège notamment contre les tokens techniques ou commerciaux sans rapport avec la couleur réelle du produit.

Décision conservatrice¶

La politique centrale doit préférer :

unknown

à un faux positif.

Les décisions typiques sont :

weak_evidence_only : uniquement des indices faibles ;
low_score : score global inférieur au seuil de résolution ;
score_conflict : preuves fortes contradictoires ;
resolved : couleur déterminée avec une confiance suffisante.

Politique de mutation¶

Le mode par défaut est un audit sans mutation.

Les mutations ne sont activées que lorsque :

define('CCX_MEDIA_QUALITY_MUTATE', true);

ou lorsqu'un filtre explicite active :

ccx_media_quality_mutations_enabled

Même lorsque les mutations sont activées :

une image n'est jamais vidée ;
une incohérence sans remplacement sûr laisse image_norm inchangé ;
le remplacement est limité à une image de galerie correspondant à la couleur attendue ;
la confiance du candidat doit atteindre mutation_minimum_confidence ;
le motif IMAGE_COLOR_REPLACED est ajouté lorsque la colonne de traçabilité existe.

La valeur cleared doit donc rester à 0 avec l'implémentation audit-first.

Algorithme de décision¶

Pour chaque offre possédant color_norm et image_norm :

incrémenter scanned ;
résoudre la couleur attendue depuis color_norm ;
collecter les preuves relatives à l'image principale ;
appliquer la politique de scoring ;
classer le résultat en resolved, unknown ou ambiguous ;
ne comparer les couleurs que lorsque le résultat est resolved ;
si les couleurs correspondent, incrémenter matched ;
si elles diffèrent, incrémenter mismatched ;
rechercher un candidat de galerie à haute confiance ;
en mode audit, enregistrer le candidat sans modifier la ligne ;
en mode mutation, remplacer uniquement si le seuil de confiance est atteint.

Métriques¶

Métriques globales du moteur¶

media_quality_rules_run
media_quality_rules_failed
media_quality_elapsed_ms

Métriques par règle¶

media_quality_<rule_id>_elapsed_ms
media_quality_<rule_id>_status

Métriques de couleur d'image¶

scanned
checked
matched
mismatched
unknown_expected
unknown_actual
ambiguous_actual
unknown_weak_evidence
unknown_low_score
ambiguous_conflict
replacement_not_found
replacement_candidate
replaced
cleared
mutation_skipped
evidence_from_filename
evidence_from_path
evidence_from_query
evidence_from_gallery
evidence_from_vendor
evidence_from_url

Elles sont exposées dans le journal de synchronisation avec le préfixe :

image_color_

Interprétation¶

scanned : lignes éligibles examinées ;
checked : lignes dont la couleur réelle a été résolue ;
matched : couleur résolue identique à color_norm ;
mismatched : couleur résolue différente de color_norm ;
unknown_actual : image non résolue faute de preuve suffisante ;
ambiguous_actual : preuves contradictoires ;
replacement_candidate : candidat de galerie suffisamment fiable ;
mutation_skipped : candidat détecté mais mutation désactivée ;
replaced : remplacement réellement écrit ;
cleared : compteur conservé pour compatibilité, attendu à zéro ;
evidence_from_* : couverture diagnostique par famille de preuves.

Un nombre élevé de unknown_actual n'est pas nécessairement une régression. Il peut refléter une politique plus sûre qui refuse de transformer des indices faibles en certitudes.

Feature flags¶

Le moteur reconnaît :

enable_media_quality
enable_media_quality_main_image_color

Ces flags sont indépendants de enable_quality_checks, qui concerne les contrôles de qualité des verticales pendant le mapping.

Workflow d'exploitation recommandé¶

régénérer la projection du run étudié ;
exécuter la synchronisation ou le moteur sur ce run ;
inspecter les métriques du journal de synchronisation ;
analyser séparément unknown, ambiguous et mismatched ;
enrichir les adaptateurs ou familles de preuves lorsque la couverture est insuffisante ;
ne considérer l'activation des mutations qu'après validation d'un échantillon représentatif.

Exemple :

docker compose exec platform-worker \
  wp ccx sync start \
  --feed=samsung \
  --force \
  --batch-size=250

Le moteur ne nécessite pas --enable-quality-checks=1.

Ajout d'une règle¶

ajouter un fichier numéroté sous includes/media-quality/rules/ ;
isoler les extracteurs de preuves dans includes/media-quality/evidence/ lorsque nécessaire ;
définir une politique de décision explicite ;
enregistrer le callable dans ccx_media_quality_rules() ;
retourner des compteurs numériques stables ;
documenter les sources, seuils, ambiguïtés, mutations et invariants ;
valider sur un run contrôlé ;
vérifier l'idempotence et l'absence de suppression destructive.

Invariants industriels¶

Une preuve faible seule ne devient jamais une certitude.
Une ambiguïté reste visible.
Une image valide n'est jamais supprimée faute de remplacement.
Les mutations sont désactivées par défaut.
Toute mutation exige un candidat de remplacement à haute confiance.
Les métriques permettent de reconstruire la décision.
Le traitement reste limité au run courant.
Le moteur ne rejette jamais une offre.

Dette de migration connue¶

La règle main_image_color s'appuie encore sur le shim historique :

includes/pipeline/norm/25-image-quality.php

L'orchestration canonique passe néanmoins par le Media Quality Engine. Le shim ne doit pas être appelé directement par une nouvelle intégration.

La prochaine étape d'architecture consiste à déplacer définitivement l'implémentation de décision hors du pipeline historique, sans modifier le contrat public ni les métriques.