Quality Scorer Contract¶

Status: CONTRACT

À quoi sert ce contrat ?¶

Le Quality Scorer mesure la qualité et la fiabilité d'une identité, d'un candidat ou d'une projection à partir d'évidences observables.

Il répond à une question différente de celle du Resolver : « quelle est la qualité de ce que nous savons ? » et non « quelle identité devons-nous retenir ? ».

Il ne résout pas l'identité, ne modifie pas la vérité produit et ne remplace ni le Resolver ni les politiques de conflit.

Données normalisées / identité / projection
                  ↓
           Quality Scorer
                  ↓
Score + niveau de confiance + raisons + diagnostics

Pourquoi séparer qualité et résolution ?¶

Une donnée peut être de bonne qualité sans suffire à résoudre une identité, et une identité peut être résolue tout en restant incomplète sur certains attributs.

Cette séparation évite plusieurs erreurs dangereuses :

utiliser un score élevé comme autorisation automatique de fusion ;
masquer un conflit parce que la majorité des autres signaux sont bons ;
confondre complétude et certitude ;
déclencher une mutation destructive uniquement à partir d'un score.

Le Quality Scorer fournit donc une mesure explicable que d'autres composants peuvent consulter selon leurs propres contrats.

Responsabilités¶

Le contrat impose un cadre commun pour :

produire un score interprétable ;
exposer les raisons ayant influencé ce score ;
distinguer qualité, confiance et complétude ;
garantir un comportement déterministe ;
permettre l'audit et la comparaison entre verticales ;
conserver les critères métier dans les Vertical Modules.

Ce que le scorer ne fait jamais¶

Le Quality Scorer ne doit jamais :

fusionner des produits ;
sélectionner un candidat ;
résoudre une identité ;
masquer un conflit ;
corriger ou réécrire les données évaluées ;
écrire directement dans le stockage ;
appliquer une mutation destructive ;
dépendre de WordPress ou d'une structure SQL particulière.

Entrées¶

Un scorer peut recevoir un ou plusieurs des éléments suivants :

Canonical Identity ;
Candidate ;
Identifiers ;
attributs normalisés ;
résultats du Resolver ;
observations marchandes ;
conflits connus ;
projection de catalogue ;
évidences et diagnostics produits par un moteur qualité spécialisé.

Les entrées doivent être traitées en lecture seule.

Sortie attendue¶

La sortie doit être explicite et structurée.

score
confidence_level
reasons[]
warnings[]
evidence[]
metrics{}

Score¶

Le score est numérique et borné par le contrat d'implémentation, par exemple de 0 à 100.

Il exprime un niveau de qualité relatif, pas une certitude absolue.

Niveau de confiance¶

Le niveau de confiance qualifie la robustesse du score, par exemple :

low ;
medium ;
high.

Un score élevé produit à partir de peu d'évidences ne doit pas automatiquement être considéré comme hautement fiable.

Raisons¶

Chaque facteur significatif doit être exposé sous une forme compréhensible et stable.

Exemples :

identifiant constructeur cohérent ;
attribut critique absent ;
conflit de couleur détecté ;
candidat unique ;
sources contradictoires ;
projection incomplète.

Avertissements¶

Les avertissements signalent les situations où le résultat reste exploitable mais doit être interprété avec prudence.

Modèle d'évidence¶

Le scorer s'appuie sur des évidences, et non sur des effets de bord.

Une évidence doit idéalement contenir :

un type ;
une source ;
une valeur observée ;
une règle ou un critère ;
un poids ou une importance ;
une conclusion ;
un niveau de confiance.

Le scorer agrège ces évidences sans modifier les données d'origine.

Qualité, confiance et complétude¶

Ces trois notions ne sont pas interchangeables :

qualité : appréciation globale selon les critères du scorer ;
confiance : robustesse de cette appréciation compte tenu des preuves disponibles ;
complétude : quantité ou proportion d'informations attendues effectivement présentes.

Par exemple, un produit peut avoir des attributs très cohérents mais peu nombreux : la qualité des données présentes peut être bonne, tandis que la complétude reste faible et que la confiance globale doit rester prudente.

Critères génériques¶

Les critères communs peuvent notamment couvrir :

qualité des identifiants ;
cohérence des attributs ;
complétude ;
stabilité de l'identité ;
qualité et diversité des sources ;
présence de conflits ;
richesse de la projection ;
qualité des médias ;
fraîcheur des observations.

La pondération exacte n'appartient pas à ce contrat.

Critères propres aux verticales¶

Les Vertical Modules définissent les critères métier spécifiques.

Exemples :

Smartphone¶

génération ;
capacité ;
couleur ;
réseau ;
variante régionale.

Photo¶

monture ;
focale ;
ouverture ;
compatibilité boîtier.

Gaming¶

plateforme ;
édition ;
région ;
format.

Ces règles restent confinées dans les verticales et exposent leurs résultats au format commun du contrat.

Relation avec le Resolver¶

Le Resolver décide si une identité peut être retenue. Le Quality Scorer décrit la qualité des éléments disponibles.

Un score peut être fourni au Resolver comme un signal si le contrat de résolution le prévoit, mais :

il ne remplace jamais les évidences ;
il ne supprime jamais un conflit fort ;
il ne transforme pas automatiquement unknown ou ambiguous en resolved.

Relation avec Media Quality¶

Le moteur Media Quality est un producteur d'évidences spécialisées.

Il peut signaler :

une image principale cohérente ;
une couleur d'image contradictoire ;
une valeur réelle inconnue ;
une ambiguïté ;
une image de remplacement suffisamment fiable.

Le Quality Scorer peut intégrer ces évidences dans son calcul, mais il ne doit pas reproduire les règles du moteur Media Quality.

La politique de mutation Media Quality reste indépendante du scoring. Par défaut, l'audit est non destructif et aucune image n'est supprimée uniquement parce qu'un score ou une règle signale une incohérence.

Déterminisme et versionnement¶

Pour une même version de règles et les mêmes entrées, le scorer doit produire la même sortie.

Toute évolution affectant le résultat doit être traçable par :

version de règle ;
version du modèle ;
configuration ;
critères activés ;
pondérations utilisées.

Sans cette traçabilité, une comparaison de scores avant/après ne permettrait pas de savoir si la donnée a changé ou si l'algorithme a changé.

Auditabilité¶

Un score seul n'est pas suffisant.

L'audit doit permettre de répondre à :

quelles données ont été évaluées ;
quelles règles ont été exécutées ;
quelles évidences ont été retenues ;
quelles pénalités ou contributions ont été appliquées ;
pourquoi le niveau de confiance a été attribué ;
quelle version du scorer a produit le résultat.

Métriques minimales¶

Toute implémentation doit exposer au minimum :

nombre d'éléments évalués ;
distribution des scores ;
distribution des niveaux de confiance ;
nombre de résultats avec avertissements ;
nombre d'entrées incomplètes ;
nombre de conflits observés ;
nombre d'évidences par type ;
durée d'exécution ;
erreurs et éléments ignorés.

Les moteurs spécialisés peuvent ajouter leurs propres métriques, par exemple matched, mismatched, unknown_actual, ambiguous ou replacement_not_found pour Media Quality.

Comment diagnostiquer un score surprenant¶

Avant de modifier une pondération :

identifier la version du scorer et sa configuration ;
inspecter les évidences réellement reçues ;
vérifier les raisons et avertissements produits ;
distinguer un défaut de donnée d'un défaut de règle ;
vérifier si le critère appartient au Core ou à un Vertical Module ;
comparer sur un échantillon stable avant/après modification.

Un score inattendu peut venir d'une normalisation incorrecte, d'une évidence absente ou d'une règle verticale, pas nécessairement du calcul d'agrégation.

Erreurs fréquentes de maintenance¶

traiter score = 100 comme une preuve absolue ;
confondre score, confiance et complétude ;
dupliquer dans le scorer les règles du Resolver ;
ajouter des règles propres à une verticale dans le Core générique ;
modifier les données évaluées pendant le calcul ;
déclencher une suppression ou une fusion depuis le scorer ;
changer une pondération sans versionner ni comparer les résultats.

Garde-fous¶

Lecture seule¶

Le calcul du score ne modifie jamais l'objet évalué.

Absence de décision cachée¶

Une règle ne doit pas prendre silencieusement une décision de résolution, de fusion ou de suppression.

Explicabilité¶

Toute contribution significative doit être représentée dans les raisons ou les évidences.

Séparation des responsabilités¶

Le contrat définit le format et les invariants.

Les Vertical Modules définissent les critères métier.

Les moteurs spécialisés produisent leurs évidences.

Le Resolver décide de l'identité.

La Projection construit les vues de catalogue.

Le Runtime orchestre l'utilisation des résultats selon les politiques applicables.

Exemple¶

Canonical Identity
      ↓
Quality Scorer
      ↓
score: 92
confidence_level: high
reasons:
  - identifiants cohérents
  - candidat unique
  - attributs critiques complets
warnings:
  - image principale de couleur inconnue
evidence:
  - identifier_consistency: positive
  - resolver_uniqueness: positive
  - media_color_actual: unknown

Cet exemple décrit une sortie de scoring. Il ne signifie pas qu'une écriture, une fusion ou un remplacement d'image est autorisé.

Invariants¶

Le scorer évalue ; il ne décide pas de l'identité.
Les données d'entrée restent en lecture seule.
Le résultat est déterministe pour une même version de règles.
Le score est toujours accompagné d'éléments explicatifs.
La confiance et la qualité sont deux notions distinctes.
Les critères métier restent dans les Vertical Modules.
Les moteurs spécialisés ne sont pas dupliqués dans le scorer.
Aucune mutation destructive ne peut être déclenchée uniquement par un score.
Toute évolution de règle est versionnée et auditable.

État d'implémentation¶

Ce document est un CONTRACT : il fixe la cible commune à respecter. Il ne faut pas en déduire que toutes les implémentations historiques exposent déjà exactement cette structure ou toutes ces métriques.

Les implémentations historiques peuvent être conservées temporairement comme adaptateurs, mais elles doivent progressivement converger vers :

un modèle d'évidence commun ;
une sortie structurée ;
des métriques standardisées ;
une séparation stricte entre scoring, résolution et mutation.

Lors d'un diagnostic runtime, vérifiez donc l'implémentation réellement appelée avant d'affirmer qu'un champ ou une métrique de ce contrat est déjà disponible en production.