Moteur de projection du Catalog¶

Statut¶

Documentation canonique du moteur de projection catalogue, adaptée à la transmission du projet.

À quoi sert ce moteur ?¶

Le Catalog Projection Engine transforme les données autoritatives du produit en structures de lecture utilisables par le catalogue.

Il constitue le pont mécanique entre la vérité métier et l'expérience de consultation :

Product Domain
(vérité métier)
        ↓
Moteur de projection
(transformation)
        ↓
Catalog Domain
(structures de lecture)
        ↓
Frontend

Le point essentiel à retenir est qu'une projection est une représentation dérivée. Elle peut être supprimée puis reconstruite à partir des sources autoritatives. Elle ne devient jamais la vérité produit.

Exemple concret¶

Un Product peut contenir une identité canonique, une marque, un modèle, des variantes, des observations et des attributs validés.

Le moteur peut en dériver une représentation plus pratique pour le catalogue :

Product autoritatif
  ├── identité
  ├── marque
  ├── modèle
  ├── attributs
  └── médias
        ↓ projection
CatalogItem
  ├── titre de lecture
  ├── catégorie/navigation
  ├── facettes autorisées
  ├── médias projetés
  └── diagnostics utiles

Le CatalogItem n'est pas une nouvelle vérité métier : c'est une vue adaptée à la consultation.

Responsabilités¶

Le moteur est responsable notamment de :

transformer les agrégats Product en CatalogItem ;
construire les vues et collections du catalogue ;
produire les structures nécessaires aux facettes et filtres ;
transmettre les attributs et médias autorisés aux couches de lecture ;
maintenir la cohérence des projections ;
gérer les reconstructions complètes ;
gérer les mises à jour incrémentales ;
produire les représentations techniques normalisées nécessaires au runtime ;
conserver suffisamment d'explicabilité pour diagnostiquer les choix de projection.

Flux industriel actuellement documenté¶

Dans l'implémentation industrielle décrite par le dépôt, l'écriture normalisée passe notamment par :

projectionWriter
      ↓
ccx_feeds_upsert_items_to_offers_norm()
      ↓
includes/pipeline/90-offers-norm.php

Ces noms sont importants pour retrouver l'implémentation, mais ils ne changent pas la règle d'architecture : le stockage reste une conséquence de la projection, pas la définition de la vérité Product.

Ce que le moteur ne doit pas faire¶

Il ne doit pas :

modifier le Product Domain ;
résoudre lui-même l'identité canonique ;
arbitrer un conflit métier qui appartient au domaine ;
inventer un attribut absent ;
transformer une valeur inconnue en certitude ;
appliquer une règle spécifique à un marchand si cette règle appartient à la normalisation ;
cacher une anomalie de qualité en supprimant silencieusement une donnée ;
dépendre conceptuellement d'une table SQL ou de WordPress comme si ces technologies définissaient le métier.

Une implémentation peut naturellement utiliser SQL ou WordPress comme adaptateurs techniques.

Entrées possibles¶

Le moteur peut consommer en lecture :

Product ;
ProductVariant ;
ProductObservation ;
ProductConflict ;
attributs normalisés ;
décisions validées par les composants autoritatifs ;
diagnostics de qualité autorisés à être exposés.

Il doit consommer des décisions déjà prises au bon niveau plutôt que de refaire ces décisions dans la projection.

Sorties possibles¶

Les sorties peuvent comprendre :

CatalogItem ;
CatalogView ;
CatalogCollection ;
facettes et filtres ;
représentations normalisées d'offres ;
métadonnées de qualité ;
informations d'explicabilité ;
index de lecture reconstruisibles.

Règles essentielles de projection¶

Dérivation¶

Toute valeur projetée doit provenir d'une source autoritative ou d'une règle explicite.

Déterminisme¶

À données et version de règles identiques, le résultat doit être identique.

mêmes entrées + mêmes règles = même projection

Cette propriété rend les anomalies reproductibles et les rebuilds vérifiables.

Reconstruction¶

Une projection doit pouvoir être régénérée intégralement.

Si une table dérivée est corrompue mais que les sources autoritatives sont saines, la stratégie normale est de la reconstruire, pas d'inventer une nouvelle vérité dans cette table.

Convergence¶

Une mise à jour incrémentale doit finir par produire le même état qu'une reconstruction complète effectuée sur les mêmes données et les mêmes règles.

Non-destruction¶

Un signal de mauvaise qualité ne justifie pas la disparition silencieuse d'une valeur projetée.

Explicabilité¶

Une sélection, une exclusion ou une mutation doit pouvoir être reliée à une règle ou à des preuves compréhensibles.

Relation avec la normalisation¶

La normalisation prépare les valeurs comparables et techniques utilisées ensuite par la projection.

Donnée brute marchand
        ↓
Normalisation
        ↓
Donnée exploitable
        ↓
Projection Catalog

Voir : Normalisation.

Après une évolution importante des règles de normalisation, il peut être nécessaire de reconstruire les projections avant de comparer des métriques anciennes et nouvelles.

Relation avec Media Quality¶

Le moteur peut utiliser des décisions ou diagnostics produits par Media Quality, mais il ne doit pas transformer un simple signal de qualité en mutation destructive implicite.

Règles à retenir :

l'audit est le comportement par défaut ;
les preuves et raisons peuvent être projetées pour diagnostic ;
une incohérence ne provoque pas automatiquement une mutation ;
une image principale ne doit pas être vidée pour masquer un problème ;
un remplacement nécessite une politique explicite et une confiance suffisante ;
les mutations doivent être mesurables et traçables ;
une reconstruction doit permettre de retrouver un état cohérent.

Voir : Media Quality Engine.

Reconstruction complète, incrémentale et replay¶

Le moteur doit pouvoir fonctionner selon plusieurs stratégies.

Reconstruction complète¶

Toutes les projections du périmètre sont recalculées depuis les sources autoritatives.

Mise à jour incrémentale¶

Seuls les éléments affectés par un changement sont recalculés.

Replay¶

Un périmètre ou une série de changements est retraité, notamment pour récupération ou backfill.

Le contrat fondamental reste le même : ces stratégies doivent converger vers un résultat cohérent.

Déclencheurs possibles¶

Des changements comme ceux-ci peuvent nécessiter une nouvelle projection :

création ou modification d'un Product ;
changement d'une variante ;
résolution d'un conflit ;
normalisation d'une offre ;
changement des règles de projection ;
changement d'une politique de qualité.

Les noms exacts des événements peuvent évoluer avec l'implémentation.

Observabilité¶

Une exécution sérieuse doit permettre de savoir au minimum :

quel périmètre a été traité ;
quel run a effectué le traitement ;
combien d'éléments ont été lus ;
combien ont été créés, mis à jour ou ignorés ;
quelles erreurs sont survenues ;
pourquoi certains éléments ont été exclus ;
quelle version de règles a été utilisée lorsqu'elle est disponible ;
combien de temps le traitement a pris ;
quel est son statut final.

Pour les traitements Media Quality, il faut distinguer les diagnostics des mutations réellement appliquées.

Workflow opérationnel recommandé¶

sources autoritatives
      ↓
normalisation
      ↓
projection / reconstruction
      ↓
audit qualité
      ↓
analyse des métriques
      ↓
mutation explicite si elle est autorisée
      ↓
validation finale

Ne compare pas aveuglément des métriques si les projections ont été construites avec des versions différentes des règles.

Comment diagnostiquer une projection incorrecte¶

Si un CatalogItem paraît faux :

1. Vérifier le Product autoritatif
        ↓
2. Vérifier les données normalisées utilisées
        ↓
3. Identifier la règle de projection appliquée
        ↓
4. Vérifier le résultat du run / rebuild
        ↓
5. Vérifier l'écriture de la projection
        ↓
6. Vérifier le consommateur frontend

Si la source Product est correcte mais que la projection est fausse, ne modifie pas le Product pour compenser le problème.

Pour la reprise du projet¶

Lorsque tu rencontres une table, un cache ou une structure issue du Catalog, pose immédiatement cette question :

Est-ce une source autoritative ou une projection reconstruisible ?

Dans le Catalog, la réponse est normalement projection reconstruisible.

C'est une distinction essentielle avant toute correction manuelle en base de données.