Catalog Projection Engine¶

Statut¶

Documentation canonique du moteur de projection catalogue.

Objet¶

Le Catalog Projection Engine transforme la vérité produit et les observations d'offres en structures de lecture destinées au catalogue.

Il constitue la couche mécanique entre :

Product Domain (Truth)
        ↓
Projection Engine
        ↓
Catalog Domain (Experience)

Une projection est dérivée, reconstruisible et remplaçable. Elle ne devient jamais la source de vérité produit.

Responsabilités¶

Le moteur est responsable de :

transformer les agrégats produit en CatalogItem ;
construire les vues et collections du catalogue ;
produire les structures de facettes ;
maintenir la cohérence des projections ;
gérer les reconstructions complètes et mises à jour incrémentales ;
transmettre aux couches de lecture les attributs, médias et diagnostics autorisés ;
écrire les représentations techniques normalisées nécessaires à l'exploitation.

Dans l'implémentation industrielle actuelle, le flux d'écriture normalisée est notamment :

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

Frontières strictes¶

Le moteur de projection ne doit pas :

modifier le Product Domain ;
résoudre l'identité produit ;
arbitrer un conflit métier ;
inventer un attribut absent ;
appliquer une logique de prix qui appartient à un autre domaine ;
interpréter directement les règles spécifiques d'un marchand ;
dépendre conceptuellement de WordPress ou d'une structure SQL particulière ;
supprimer une donnée projetée uniquement pour masquer un signal de mauvaise qualité.

Une implémentation peut utiliser WordPress ou SQL comme adaptateurs techniques, sans faire de ces technologies une règle d'architecture.

Modèle d'entrée¶

Les entrées possibles comprennent :

Product ;
ProductVariant ;
ProductObservation en lecture seule ;
ProductConflict en lecture seule ;
attributs normalisés ;
décisions déjà validées par le Domain Core ;
diagnostics de qualité destinés à la projection.

Le moteur ne doit consommer que des décisions déjà prises par les composants autoritatifs.

Modèle de sortie¶

Les sorties comprennent notamment :

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

Règles de projection¶

Un produit peut produire zéro, un ou plusieurs CatalogItem selon la stratégie de catalogue.
Toute donnée projetée doit être dérivée d'une source autoritative ou d'une règle explicite.
Une projection doit être déterministe pour une même entrée et une même version de règles.
Une projection doit pouvoir être reconstruite intégralement.
Une mise à jour incrémentale doit converger vers le même état qu'une reconstruction complète.
Les diagnostics ne doivent pas être confondus avec la vérité produit.
Une valeur inconnue doit rester inconnue plutôt que d'être convertie en erreur certaine.

Relation avec la normalisation¶

La normalisation prépare les champs comparables et techniques utilisés par la projection.

Source canonique :

../../pipeline/normalisation.md

La table ou structure normalisée constitue une projection de travail, pas un registre métier autoritatif.

Après une évolution des règles de normalisation ou de qualité, une reconstruction peut être obligatoire avant toute comparaison de métriques.

Relation avec Media Quality¶

Media Quality évalue la cohérence des médias associés aux attributs projetés.

Source canonique :

../../architecture/media-quality-engine.md

Le moteur de projection doit respecter les règles suivantes :

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 jamais être vidée comme mécanisme de correction ;
un remplacement n'est autorisé qu'avec une politique explicite et une confiance suffisante ;
les mutations doivent être mesurables, traçables et réversibles par reconstruction.

L'ancienne logique destructive ne constitue pas un contrat supporté.

Modèle de cohérence¶

Le moteur supporte :

reconstruction complète ;
mise à jour incrémentale ;
replay d'un périmètre ;
mise à jour événementielle lorsque l'infrastructure le permet.

Le résultat final d'une mise à jour incrémentale doit être équivalent au résultat d'une reconstruction complète sur les mêmes données et règles.

Événements de déclenchement¶

Exemples d'événements pouvant déclencher une projection :

ProductCreated ;
ProductUpdated ;
ProductVariantChanged ;
ProductConflictResolved ;
OfferNormalised ;
ProjectionRulesChanged ;
QualityPolicyChanged.

Les noms exacts dépendent de l'implémentation. Le contrat important est l'idempotence du traitement.

Observabilité¶

Une exécution doit exposer au minimum :

périmètre et identifiant de run ;
nombre d'éléments lus, créés, mis à jour et ignorés ;
erreurs et raisons d'exclusion ;
nombre de mutations de médias demandées et appliquées ;
distribution des résultats de qualité ;
version des règles lorsque disponible ;
durée et statut final.

Pour Media Quality, les métriques doivent distinguer les états tels que matched, mismatched, ambiguous, unknown_actual, replacement_found, replacement_not_found et les mutations effectivement appliquées.

Invariants¶

Vérité immuable¶

La projection ne modifie jamais la vérité du Product Domain.

Reconstruction¶

Toute projection peut être régénérée à partir des sources autoritatives.

Déterminisme¶

Les mêmes entrées et règles produisent le même résultat.

Convergence¶

Une mise à jour incrémentale converge vers le résultat d'un rebuild complet.

Non-destruction¶

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

Explicabilité¶

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

Workflow opérationnel recommandé¶

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

Les métriques d'un audit ne sont pas fiables si la projection contient encore les effets destructifs d'une ancienne version de règles.

Décision¶

Le Catalog Projection Engine est la couche centrale de transformation entre la vérité produit et l'expérience catalogue.

Son contrat repose sur quatre propriétés : dérivation, déterminisme, reconstruction et non-altération de la vérité.