Real Sample Comparison¶

Status: CURRENT

À quoi sert ce Read Service ?¶

Le Real Sample Comparison est un Read Service de diagnostic qui compare, sur un échantillon de produits réels, ce que CMonChoix produit avec ce qui est attendu ou avec une référence explicitement définie.

Son rôle est qualitatif : il aide à comprendre pourquoi une résolution, une projection ou une classification diffère sur des cas concrets.

Il ne remplace pas les audits statistiques globaux. Il les complète.

Échantillon réel
      ↓
Données observées + résultat Platform + référence
      ↓
Real Sample Comparison
      ↓
Écarts expliqués + familles + exemples

Pourquoi il existe¶

Un KPI global peut dire qu'un taux de résolution baisse ou qu'un nombre de conflits augmente, sans expliquer les causes.

Le Real Sample Comparison permet de revenir à des cas lisibles par un humain :

quelles données marchandes ont été observées ;
quelle Canonical Identity a été produite ;
quel statut de résolution a été obtenu ;
quelle projection a été construite ;
quelle différence est réellement constatée ;
quelles évidences expliquent cette différence.

Il est particulièrement utile pendant l'industrialisation d'une verticale, avant toute modification du Resolver ou d'un Vertical Module.

Position dans le cycle de travail¶

Audit global
    ↓
Sélection d'un échantillon représentatif
    ↓
Real Sample Comparison
    ↓
Classification des écarts
    ↓
Hypothèse
    ↓
Simulation / Virtual Patch
    ↓
Nouvelle comparaison

Le service observe. Il ne corrige rien.

Entrées¶

Une comparaison reproductible doit identifier au minimum :

l'échantillon utilisé ;
la manière dont cet échantillon a été sélectionné ;
le run, snapshot ou dataset observé ;
la verticale et les feeds concernés ;
la version de code ou de règles ;
la référence utilisée pour juger le résultat attendu ;
les champs effectivement comparés.

La référence doit être explicite. Une intuition humaine non documentée n'est pas une baseline suffisante.

Ce qui peut être comparé¶

Selon l'objectif, le service peut examiner :

status de résolution ;
Canonical Identity ;
marque, famille, modèle et variante ;
identifiants normalisés ;
attributs métier ;
projection de catalogue ;
score et niveau de confiance ;
conflits et reason codes ;
informations promotionnelles ou médias si elles appartiennent au périmètre étudié.

Les statuts canoniques restent :

resolved ;
unknown ;
ambiguous ;
conflict.

Ces états ne doivent pas être remplacés par des catégories ad hoc propres au rapport.

Sorties attendues¶

Le résultat doit permettre, pour chaque cas, de relier :

entrée observée
→ résultat Platform
→ référence
→ différence
→ raison
→ classification

Une sortie utile contient notamment :

identifiant stable du cas ;
données principales observées ;
résultat courant ;
résultat attendu ou de référence ;
type de différence ;
reason codes ;
niveau de confiance si pertinent ;
notes ou limites ;
lien vers la famille d'écart éventuelle.

Lecture seule¶

Le Real Sample Comparison est strictement read-only.

Il peut :

lire les données existantes ;
reconstruire en mémoire une représentation destinée à la comparaison ;
produire des métriques et exemples ;
exporter un rapport.

Il ne doit jamais :

modifier une Canonical Identity ;
écrire une projection ;
relancer un Pipeline ;
appeler un Write Service ;
modifier un feed ;
remplacer une image ;
supprimer une donnée parce qu'elle paraît incorrecte.

Si une reconstruction persistée est nécessaire avant comparaison, elle doit être exécutée séparément et explicitement.

Construire un échantillon utile¶

Un échantillon n'est pas représentatif uniquement parce qu'il contient beaucoup de lignes.

Il doit couvrir les familles de situations importantes :

cas resolved simples ;
cas unknown ;
cas ambiguous ;
cas conflict ;
identifiants forts présents et absents ;
plusieurs marchands ;
variantes fréquentes et cas limites ;
données incomplètes ;
familles de produits à risque.

Une comparaison limitée aux cas déjà faciles peut donner une impression artificiellement favorable.

Classifier les écarts¶

Chaque différence doit être classée avec une catégorie stable.

Exemples :

donnée marchande insuffisante ;
normalisation incorrecte ;
règle générique insuffisante ;
règle verticale manquante ;
conflit légitime ;
référence attendue incorrecte ;
projection obsolète ;
bug probable ;
cas encore non expliqué.

Le but de la classification est de faciliter le diagnostic, pas de transformer une hypothèse en certitude.

Ce qu'il ne faut pas déduire¶

Un Real Sample Comparison réussi ne prouve pas à lui seul que toute la verticale est correcte.

Inversement, quelques différences dans l'échantillon ne prouvent pas nécessairement une régression globale.

Pour conclure, il faut croiser :

la comparaison qualitative ;
les KPI globaux ;
les audits de familles ;
les résultats de simulation ;
le rapport de validation final.

Diagnostic d'un écart surprenant¶

Avant de modifier le code, vérifier :

la référence attendue est-elle réellement correcte ?
le cas comparé appartient-il au même run ou snapshot ?
la projection est-elle à jour ?
les données marchandes brutes contiennent-elles l'information attendue ?
la normalisation a-t-elle transformé correctement cette information ?
le Resolver a-t-il reçu les bons candidats et évidences ?
le statut unknown, ambiguous ou conflict est-il en réalité légitime ?

Cette séquence évite de corriger le Domain Core pour compenser un problème situé en amont.

Reproductibilité¶

Le même échantillon, les mêmes données et la même version de règles doivent produire le même résultat logique.

Le rapport doit donc conserver :

les identifiants de cas ;
le run ou snapshot ;
les filtres ;
la version de code ;
les règles actives ;
la définition de la référence.

Tests attendus¶

Les composants utilisés par ce service doivent être couverts par :

tests read-only ;
tests de déterminisme ;
tests de stabilité des reason codes ;
tests de gestion des cas absents ou incomplets ;
tests sur resolved, unknown, ambiguous et conflict ;
fixtures représentatives de cas réels.

Invariants¶

Le service est read-only.
L'échantillon et la référence sont explicitement définis.
Les cas sont identifiables et reproductibles.
Les statuts canoniques restent visibles.
Une différence est expliquée avant d'être corrigée.
Une comparaison qualitative ne remplace pas les KPI globaux.
Le service n'applique jamais un correctif.