Normalisation¶
Statut¶
Documentation canonique du pipeline de préparation des offres.
Objet¶
La normalisation transforme les données marchandes hétérogènes en une représentation technique commune, stable et exploitable par les composants de résolution, de projection et de qualité.
Elle constitue la frontière entre les données importées et le modèle interne de la Platform.
Elle ne décide pas qu'une offre correspond à un produit canonique. Elle prépare les faits nécessaires à cette décision.
Position dans le pipeline¶
Flux marchand
↓
Ingestion
↓
Stage
↓
Normalisation
↓
Enrichissement et contrôle qualité
↓
Résolution / Domain Core
↓
Projection catalogue
Dans l'implémentation WordPress industrielle, l'écriture de projection alimente la représentation normalisée via :
projectionWriter
↓
ccx_feeds_upsert_items_to_offers_norm()
↓
includes/pipeline/90-offers-norm.php
La table normalisée est une projection technique reconstruisible. Elle n'est pas la source de vérité produit.
Responsabilités¶
La normalisation est responsable de :
- conserver les identifiants et références utiles à la traçabilité ;
- produire des champs normalisés comparables entre marchands ;
- harmoniser les marques, références constructeur, unités, capacités, couleurs et catégories ;
- préparer les attributs utilisés par les règles verticales ;
- préserver les valeurs brutes nécessaires aux audits ;
- fournir une entrée déterministe aux contrôles de qualité et au Domain Core.
Chaque transformation doit être explicable et reproductible.
Limites strictes¶
La normalisation ne doit pas :
- fusionner des produits ;
- choisir un produit canonique ;
- résoudre une ambiguïté d'identité ;
- appliquer une politique d'affichage ;
- considérer une image ou un attribut comme faux sans preuve suffisante ;
- détruire une donnée source afin de masquer une incohérence.
La résolution appartient au Domain Core. La construction des vues appartient au moteur de projection. Les décisions de présentation appartiennent au Runtime.
Déterminisme et idempotence¶
Pour une même entrée, une même version de règles et une même configuration, la normalisation doit produire le même résultat.
Un nouveau passage ne doit pas introduire de dérive cumulative. Les écritures doivent être idempotentes ou disposer d'une stratégie explicite de reconstruction.
Ces propriétés rendent possibles :
- les audits ;
- les replays ;
- les comparaisons entre versions ;
- les simulations ;
- les corrections de règles ;
- les reconstructions complètes de projection.
Traçabilité¶
Toute valeur normalisée doit rester reliée, directement ou indirectement, à :
- sa valeur d'origine ;
- l'offre et le marchand ;
- le flux et le run d'import ;
- la règle ou le composant ayant produit la valeur ;
- la version de pipeline concernée lorsque cette information est disponible.
Une valeur dérivée ne doit jamais devenir impossible à expliquer.
Relation avec les Vertical Modules¶
Le pipeline fournit les mécanismes généraux de normalisation.
Les règles propres à un domaine métier restent dans le Vertical Module concerné, par exemple Smartphone, Photo, Gaming ou Printer.
Le cœur commun ne doit pas contenir de logique métier spécialisée lorsqu'elle peut être exprimée par un module vertical.
Relation avec Media Quality¶
Media Quality intervient après la préparation des champs nécessaires à l'analyse et avant toute mutation éventuelle de la projection.
La source canonique de cette architecture est :
Principes applicables au pipeline :
- le mode par défaut est audit-first ;
- une incohérence détectée produit d'abord des preuves, des raisons et des métriques ;
- une image principale n'est jamais vidée pour masquer un mismatch ;
- une mutation n'est autorisée que par une politique explicite et avec un niveau de confiance suffisant ;
- l'absence de preuve doit rester représentée comme inconnue, et non comme erreur certaine.
L'implémentation canonique se trouve sous :
plugins/ccx-feeds-industrial/includes/media-quality/
engine.php
rules/
10-main-image-color.php
Le fichier historique includes/pipeline/norm/25-image-quality.php doit être traité comme un shim de migration ou du code legacy, pas comme la spécification courante.
Contrôle qualité¶
La normalisation fournit des données au Quality Scorer et aux composants de santé du Domain Core.
Une normalisation incomplète ou instable peut provoquer :
- une baisse de confiance ;
- des ambiguïtés de résolution ;
- des projections incohérentes ;
- des faux positifs dans les règles de qualité ;
- des mutations injustifiées.
Les composants de qualité doivent donc distinguer au minimum :
- donnée confirmée ;
- donnée contradictoire ;
- donnée ambiguë ;
- donnée inconnue ;
- règle non applicable.
Exemple¶
Deux marchands décrivent un même modèle de smartphone :
Apple Iphone16ProMax 256Go Black Titanium
APPLE iPhone 16 Pro Max 256 GB Titane Noir
La normalisation peut produire des attributs comparables :
brand_norm = apple
model_norm = iphone 16 pro max
storage_norm_gb = 256
color_norm = black titanium
Elle ne conclut pas à elle seule que les deux offres représentent le même produit canonique.
Invariants¶
Neutralité¶
La normalisation prépare les faits. Elle ne remplace ni le Resolver ni la politique métier.
Déterminisme¶
Une même entrée, avec les mêmes règles, produit la même sortie.
Non-destruction¶
Une anomalie ou une preuve insuffisante ne justifie pas la suppression silencieuse d'une donnée projetée.
Traçabilité¶
Chaque valeur dérivée doit rester explicable depuis les données sources et les règles appliquées.
Reconstruction¶
Les données normalisées et projetées doivent pouvoir être régénérées à partir des sources autoritatives.
Séparation des responsabilités¶
Les règles communes restent dans le pipeline. Les règles métier restent dans les Vertical Modules. Les vues restent dans la projection.
Exploitation¶
Après une modification de règles, les métriques ne doivent être interprétées qu'après régénération de la projection concernée.
Une exécution historique ayant supprimé ou remplacé des valeurs peut fausser les résultats d'un nouvel audit. Le workflow opérationnel attendu est donc :
régénérer la projection
↓
exécuter l'audit
↓
analyser les raisons et métriques
↓
activer explicitement une mutation si elle est justifiée
↓
valider le résultat