Vue d'ensemble des Projections¶

Status: CURRENT

À quoi sert la couche Projection ?¶

Une Projection est une représentation de lecture dérivée de la vérité métier déjà construite par la Platform.

Elle existe pour fournir au Frontend, aux adapters Runtime, aux APIs et aux autres consommateurs une structure stable, sérialisable et directement exploitable, sans leur demander de recalculer les décisions métier.

Une projection n'est donc jamais une nouvelle source de vérité.

Sources marchandes
      ↓
Pipeline / normalisation / enrichissement
      ↓
Domain Core + Vertical Modules
      ↓
Canonical Identity / Product / Offer
      ↓
Projection Builder
      ↓
Projection de lecture
      ↓
Frontend / API / adapter Runtime

Si une projection diverge de la vérité métier, on corrige la cause en amont puis on reconstruit la projection. On ne traite pas la projection comme l'endroit où inventer une nouvelle décision métier.

Pourquoi cette couche existe¶

Sans couche de projection, chaque consommateur serait tenté de reconstruire lui-même :

les titres ;
les slugs ;
les prix affichés ;
les remises ;
la meilleure offre ;
la navigation ;
les relations parent/enfant ;
les champs de catalogue ;
les états d'incertitude.

Cela créerait plusieurs vérités concurrentes.

La couche Projection impose au contraire une frontière simple :

la Platform décide et prépare ; le consommateur lit et affiche.

Ce qu'une Projection reçoit¶

Une Projection Builder consomme des données déjà préparées par les couches amont.

Selon la famille concernée, il peut recevoir :

une Canonical Identity ;
un Product ;
des variants ;
des Offer data normalisées ;
des informations de catalogue ;
des résultats de qualité déjà calculés ;
un snapshot ou contrat neutre dédié à la projection.

Le Builder ne doit pas aller chercher directement des données dans un feed brut, un template WordPress ou un contexte HTTP.

Lorsqu'une projection consomme des données applicatives, la dépendance doit passer par un contrat ou snapshot neutre. Le Builder ne doit pas devenir couplé à un DTO d'implémentation de l'Application Engine si un contrat canonique existe.

Ce qu'une Projection produit¶

Une projection produit une structure orientée lecture, par exemple :

Product Projection ;
Offer Projection ;
Navigation Projection ;
Homepage Projection ;
Search Projection ;
Comparison Projection ;
Catalog Path Projection ;
Catalog Child Projection ;
Catalog Page Projection.

Cette structure doit être :

déterministe ;
reconstruisible ;
stable pour ses consommateurs ;
sérialisable ;
indépendante du moteur de rendu ;
explicite sur les données manquantes ou incertaines.

Ce que la couche Projection ne doit jamais faire¶

Une Projection ne doit jamais :

modifier l'état d'un Product ;
résoudre une identité ;
choisir entre plusieurs candidats ;
lire un feed brut ;
porter une règle métier propre à une verticale ;
produire du HTML ;
dépendre d'un template WordPress ;
masquer un unknown, un ambiguous ou un conflict venant de l'amont ;
créer une nouvelle vérité métier pour satisfaire le Frontend.

Une donnée absente reste absente ou explicitement indisponible. Le Frontend ne doit pas être forcé d'inventer un fallback métier.

Frontière avec le Frontend¶

Le Frontend consomme les projections.

Il peut :

afficher les champs fournis ;
appliquer des décisions purement visuelles ;
produire le HTML, les balises, les composants et le layout.

Il ne doit pas :

reconstruire l'identité produit ;
recalculer une remise ;
sélectionner la meilleure offre ;
fusionner des offres marchandes ;
reconstruire les titres ou slugs métier ;
interroger les feeds bruts ;
déplacer une règle métier dans un template.

Les compatibility shims qui transforment une projection en ancien tableau WordPress sont des responsabilités d'adapter. Ils ne doivent pas contaminer les Read Services ou le Domain Core.

Frontière Builder / Write Service¶

Le Builder construit une projection en mémoire.

Le Write Service la persiste lorsqu'une persistance est nécessaire.

Données métier
     ↓
Projection Builder
     ↓
Projection en mémoire
     ↓
Write Service explicite
     ↓
Stockage de projection

Cette séparation est importante car une reconstruction de projection est une écriture technique, même si la projection elle-même reste une donnée dérivée.

Le dépôt documente notamment les services dédiés suivants :

CCX_OfferProjectionWriteService ;
CCX_ProductModelProjectionWriteService ;
CCX_ProductVariantProjectionWriteService ;
CCX_ProductSpecificationProjectionWriteService ;
CCX_ProductGalleryProjectionWriteService.

Pour les Product Models, l'ordre de reconstruction documenté reste :

Product Models
    ↓
Variants
    ↓
Specifications
    ↓
Gallery

Un orchestrateur ne doit pas contourner ces services pour écrire directement dans une table de projection lorsqu'un Write Service dédié existe.

Ownership actuel des DTO de projection¶

L'architecture certifiée du dépôt place les DTO canoniques publics sous src/Contracts/Projection.

Familles documentées :

Contracts\Projection\Catalog\* ;
Contracts\Projection\Product\* ;
Contracts\Projection\Offer\OfferProjection ;
Contracts\Projection\Navigation\NavigationProjection ;
Contracts\Projection\Navigation\NavigationItemProjection.

Les anciens noms concrets sous src/Projection restent des wrappers de compatibilité lorsqu'ils existent.

Cette distinction est importante pour un futur mainteneur :

src/Contracts/Projection = ownership contractuel canonique ;
src/Projection = compatibilité historique, pas nouvelle source d'autorité.

Ne pas introduire une nouvelle dépendance vers les wrappers legacy lorsqu'un contrat canonique existe déjà.

Le Frontend WordPress public consomme des lectures adossées aux projections pour les stacks actives documentées, notamment navigation, produit canonique, catalogue legacy et Product Models.

Les besoins de compatibilité WordPress ne changent pas la règle architecturale :

Projection canonique
      ↓
Adapter / compatibility shim
      ↓
Payload historique éventuel
      ↓
Renderer WordPress

La persistance des routes, rewrites ou autres opérations de bootstrap technique n'appartient pas à la couche Projection.

Déterminisme¶

Pour le même état amont et la même version de règles, une projection doit produire le même résultat logique.

Il faut donc éviter :

les tris SQL implicites ;
l'heure courante non injectée ;
les variables globales WordPress ;
l'état mutable caché ;
les décisions différentes selon que l'appel vient du Frontend, de la CLI ou d'un worker.

Tout ordre significatif doit être explicite et stable.

Reconstruction et diagnostic¶

Une projection doit pouvoir être reconstruite depuis ses sources autorisées.

Lorsqu'un rendu public est incorrect, diagnostiquer dans cet ordre :

la vérité métier amont est-elle correcte ?
le Projection Builder produit-il la bonne structure ?
le Write Service a-t-il persisté la bonne version ?
la projection persistée est-elle fraîche et complète ?
l'adapter transforme-t-il correctement la projection ?
le Frontend affiche-t-il fidèlement les champs reçus ?

Ne pas corriger le template si la projection elle-même est erronée. Ne pas corriger la projection si le problème vient de la vérité métier amont.

Données manquantes et états d'incertitude¶

Une projection doit conserver l'incertitude utile.

Les états canoniques restent :

resolved ;
unknown ;
ambiguous ;
conflict.

Toutes les projections n'exposent pas nécessairement ces quatre champs tels quels, mais elles ne doivent pas convertir silencieusement une incertitude métier en valeur certaine.

Une projection partielle est préférable à une donnée inventée.

Vérification après modification¶

Après une évolution de projection :

tester le Builder sans Frontend lorsque possible ;
vérifier le déterminisme ;
vérifier la sérialisation du contrat ;
reconstruire explicitement le périmètre concerné si nécessaire ;
comparer les compteurs avant/après ;
vérifier qu'aucune autre projection n'a régressé ;
vérifier ensuite seulement le rendu consommateur.

Une reconstruction large doit suivre les garde-fous des Write Services : périmètre explicite, métriques, reprise et rollback lorsque pertinent.

Invariants¶

Une projection est dérivée, jamais source de vérité métier.
Le Builder prépare ; le Write Service persiste.
Le Frontend consomme ; il ne reconstruit pas les décisions métier.
Les projections sont déterministes et reconstruisibles.
Les données manquantes ne sont pas inventées.
Les états d'incertitude ne sont pas masqués.
Les adapters de compatibilité restent hors du Domain Core et des Read Services.
Les DTO canoniques de projection appartiennent à src/Contracts/Projection lorsqu'un contrat correspondant existe.
Une erreur de rendu doit être diagnostiquée couche par couche avant modification.