Projection Builder Contract¶

Status: CONTRACT

Purpose¶

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 n'est jamais une nouvelle vérité métier. Elle est une vue déterministe, reconstruisible et explicable.

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

Le Builder construit. Le Write Service persiste. Ces deux responsabilités restent séparées.

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.

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.

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.

É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.

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é.

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.