Projection Builder Contract¶

Status: CONTRACT

À quoi sert ce contrat ?¶

Le contrat Projection Builder définit comment une vérité métier déjà résolue est transformée en représentation dérivée exploitable par un consommateur.

Une projection est une vue préparée pour un besoin de lecture : catalogue, Frontend, API, SEO, audit, export, etc. Elle peut réorganiser ou dériver des informations, mais elle ne devient jamais une nouvelle source de vérité métier.

La règle essentielle est :

Le Builder construit en mémoire. Le Write Service persiste.

Canonical Identity
      ↓
Projection Builder
      ↓
Projection DTO / structure dérivée
      ↓
Projection Write Service éventuel
      ↓
Stockage de projection

Pourquoi les projections existent-elles ?¶

Le modèle canonique est conçu pour représenter correctement le métier. Un consommateur n'a pas forcément besoin de toute cette structure ni du même format.

Les projections permettent donc de fournir des vues adaptées sans :

déformer la Canonical Identity ;
faire recalculer le métier dans le Frontend ;
transformer une table de lecture en source de vérité ;
coupler le Domain à WordPress, SQL ou un format d'API.

Une projection doit pouvoir être supprimée puis reconstruite depuis les données canoniques si nécessaire.

Entrées¶

Un Projection Builder peut recevoir :

Canonical Identity ;
variantes et attributs déjà résolus ;
résultats Quality ou Health déjà calculés ;
données d'offre explicitement autorisées par le type de projection ;
contexte de construction immutable ;
version de schéma de projection.

Les entrées doivent être explicites. Le Builder ne doit pas rechercher lui-même des données dans WordPress, SQL, le Runtime ou le Frontend.

Si une donnée manque, il faut corriger la préparation des entrées ou accepter une projection partielle selon le contrat ; il ne faut pas ajouter une lecture cachée dans le Builder.

Sorties¶

Le Builder produit une structure sérialisable adaptée à un contrat de lecture précis, par exemple :

Catalog Item ;
Product Model ;
Product Variant ;
Product Specification ;
Product Gallery ;
projection Frontend ;
projection SEO ;
projection API ou export ;
projection d'audit.

La sortie doit exposer au minimum :

le type et la version de projection ;
les identifiants stables nécessaires au consommateur ;
les champs dérivés ;
les éventuels états unknown, ambiguous ou conflict utiles à la lecture ;
les métadonnées de traçabilité nécessaires au diagnostic.

Responsabilités¶

Le Projection Builder est responsable de :

sélectionner les informations autorisées par le contrat de sortie ;
transformer les valeurs métier en structure de lecture stable ;
garantir un ordre et un format déterministes ;
préserver les états d'incertitude utiles ;
produire une sortie reconstruisible à partir des mêmes entrées.

Il n'est pas responsable de :

résoudre une identité ;
choisir entre plusieurs candidats ;
recalculer une règle métier de verticale ;
modifier une Canonical Identity ;
écrire en base ;
charger un bootstrap WordPress ;
rendre du HTML ;
appliquer une décision d'exploitation.

Séparation Builder / Writer¶

Builder pur
  input métier
  -> projection en mémoire

Write Service
  projection en mémoire
  -> persistance explicite

Le Builder doit rester testable sans base de données.

Le Write Service porte séparément :

transaction ou stratégie d'upsert ;
idempotence de persistance ;
reprise ;
métriques d'écriture ;
gestion des erreurs techniques.

Dans le plugin courant, les écritures de projection passent par des services dédiés, notamment :

CCX_OfferProjectionWriteService ;
CCX_ProductModelProjectionWriteService ;
CCX_ProductVariantProjectionWriteService ;
CCX_ProductSpecificationProjectionWriteService ;
CCX_ProductGalleryProjectionWriteService.

Les entrypoints et orchestrateurs ne doivent pas contourner ces frontières pour appeler directement un writer legacy.

Exemple mental¶

Pour une fiche produit, le Domain peut connaître une identité canonique, ses variantes et ses attributs normalisés.

Le Frontend a plutôt besoin d'une structure directement lisible : titre, variante affichable, spécifications ordonnées, galerie et informations de qualité.

Le Projection Builder prépare cette structure. Il n'a pas le droit de décider à ce moment qu'une autre variante serait « probablement meilleure » : cette décision appartient au métier en amont.

Déterminisme¶

Pour des entrées identiques et une même version de contrat, deux constructions doivent produire une sortie équivalente.

Le résultat ne doit pas dépendre :

de l'heure courante non injectée ;
de l'ordre accidentel des lignes SQL ;
de variables globales WordPress ;
du contexte Frontend, CLI, HTTP ou Worker ;
d'un état mutable caché.

Tout tri nécessaire doit être explicite et stable.

Reconstruction¶

Une projection doit pouvoir être reconstruite intégralement.

Le système doit supporter, selon la famille concernée :

rebuild complet ;
rebuild ciblé ;
mise à jour incrémentale ;
comparaison avant/après ;
réconciliation des compteurs.

La projection stockée n'est jamais la source de vérité métier. En cas de divergence, elle doit être régénérée depuis les sources canoniques.

Avant un rebuild massif, un mainteneur doit privilégier une observation ou simulation ciblée afin de vérifier le périmètre et la différence attendue.

États incomplets et conflits¶

Le Builder ne doit pas inventer une valeur pour masquer l'incertitude.

Lorsque le contrat le permet, il conserve explicitement :

unknown : aucune valeur suffisamment étayée ;
ambiguous : plusieurs valeurs restent plausibles ;
conflict : les preuves disponibles sont incompatibles.

Une projection peut être partielle si le contrat de lecture l'autorise. Cette partialité doit être mesurable et explicable.

Le Frontend ou l'API peuvent ensuite choisir comment présenter cette absence d'information, mais ils ne doivent pas réinterpréter silencieusement l'état métier.

Media Quality¶

Media Quality est un consommateur de preuves et un producteur de diagnostics de qualité. Son mode par défaut est audit-first.

Le Projection Builder :

peut exposer l'image principale, les alternatives et les diagnostics déjà calculés ;
ne doit pas supprimer une image en raison d'un simple doute ;
ne doit pas remplacer une image sans décision explicite et confiance suffisante ;
ne doit pas transformer un résultat d'audit en mutation implicite.

La mutation éventuelle appartient à une policy et à un Write Service séparés.

Versionnement¶

Tout changement incompatible du format de sortie doit être versionné.

Le contrat doit préciser :

la version du schéma ;
les champs obligatoires ;
les champs optionnels ;
les valeurs par défaut autorisées ;
la stratégie de migration ou de rebuild.

Les consommateurs ne doivent pas déduire une nouvelle sémantique d'un champ existant sans évolution contractuelle explicite.

Observabilité¶

Une orchestration de projection doit pouvoir exposer :

nombre d'entrées lues ;
nombre de projections construites ;
nombre de projections écrites ;
créations, mises à jour, inchangées et erreurs ;
projections partielles ;
états unknown, ambiguous et conflict ;
durée ;
version du Builder ;
périmètre du rebuild.

Les compteurs doivent pouvoir être réconciliés avec le périmètre traité.

Comment diagnostiquer une projection incorrecte¶

Procédez de l'amont vers l'aval :

vérifier la Canonical Identity et les données résolues ;
vérifier les entrées réellement données au Builder ;
construire ou observer la projection en mémoire si l'outil le permet ;
comparer la sortie attendue et la sortie construite ;
seulement ensuite vérifier le Write Service et le stockage ;
enfin vérifier le consommateur Frontend/API.

Cette méthode évite de corriger une table de projection alors que l'erreur vient de la vérité canonique, ou de modifier le Builder alors que le défaut se trouve uniquement dans le rendu.

Erreurs fréquentes de maintenance¶

modifier directement une projection stockée pour « réparer » la vérité métier ;
ajouter une requête SQL au Builder ;
recalculer une résolution d'identité pendant la construction ;
masquer unknown, ambiguous ou conflict avec une valeur par défaut trompeuse ;
rendre la sortie dépendante de l'ordre d'arrivée des données ;
faire persister le Builder lui-même ;
contourner un Write Service dédié depuis un entrypoint.

Tests attendus¶

Un Projection Builder doit être couvert par :

tests unitaires sans WordPress ni SQL ;
tests de déterminisme ;
tests de sérialisation ;
tests de champs obligatoires ;
tests de conservation des états incomplets ;
tests d'absence de mutation des entrées ;
tests de compatibilité de version ;
tests d'idempotence au niveau du Write Service ;
tests de rebuild et de réconciliation au niveau orchestration.

Invariants¶

Une projection est dérivée, jamais source de vérité.
Le Builder est pur et n'écrit pas.
La persistance passe par un Write Service explicite.
Une même entrée produit la même sortie pour une même version.
Les conflits et inconnues ne sont pas masqués.
Le Builder ne dépend ni de WordPress, ni du transport, ni du Frontend.
Toute projection persistée peut être reconstruite.
Media Quality reste audit-first et non destructif par défaut.