Quality Scorer Contract¶

Statut¶

Contrat d’architecture — source de vérité pour tout composant de scoring qualité.

Objectif¶

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

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

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.

Sorties¶

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.

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 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¶

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.

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.

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 applique les politiques d’exposition.

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

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¶

Le contrat sert de cible commune aux implémentations existantes et futures.

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.

Voir aussi¶

Media Quality Engine
Normalisation
Catalog Projection Engine
Identity Resolver
Conflict Policy
Domain Core
Vertical Modules