Projection¶

Status: CURRENT

Vue d'ensemble¶

Une projection est une représentation dérivée d'une vérité métier canonique.

Elle permet à une couche consommatrice d'utiliser des données stables sans dépendre des structures internes du Domain Core, du Pipeline ou du stockage technique.

Une projection n'est jamais une seconde vérité métier. Elle peut être supprimée puis reconstruite à partir de ses sources canoniques.

Canonical Identity / Product Domain
                │
                ▼
        Projection Builder
                │
                ▼
       Projection persistée
                │
        ┌───────┼────────┐
        ▼       ▼        ▼
    Frontend   API     Read Services

Responsabilités¶

Une projection est responsable de :

préparer un modèle de lecture adapté à un usage précis ;
agréger des informations déjà validées ;
stabiliser le contrat consommé par le Frontend, les API et les audits ;
réduire les recalculs au moment de la lecture ;
exposer une structure reconstruisible et déterministe.

Elle n'est pas responsable de :

résoudre une identité produit ;
inventer une valeur métier ;
masquer une ambiguïté ou un conflit ;
normaliser les données marchandes ;
décider d'une mutation de qualité ;
appliquer une règle de présentation directement dans le Domain Core.

Source et dérivation¶

La projection consomme uniquement des données déjà produites par les couches responsables de la vérité métier.

Selon le cas, ses sources peuvent inclure :

Canonical Identity ;
Product et ProductVariant ;
offres normalisées ;
attributs enrichis ;
résultats de résolution ;
décisions de qualité explicites ;
métadonnées techniques nécessaires à la traçabilité.

Toute valeur projetée doit pouvoir être reliée à une source ou à une règle de dérivation documentée.

Modèle d'écriture¶

Le calcul d'une projection et sa persistance sont deux responsabilités distinctes.

Sources canoniques
        │
        ▼
Projection Builder
        │
        ▼
Projection calculée
        │
        ▼
Projection Write Service
        │
        ▼
Stockage de lecture

Le builder doit rester déterministe et sans effet de bord.

Les écritures persistantes passent par un Write Service ou un writer explicitement certifié. Un entrypoint CLI, HTTP, admin ou worker ne doit pas écrire directement dans les tables de projection.

Services de projection actuellement certifiés¶

La frontière d'écriture documentée comprend notamment :

CCX_OfferProjectionWriteService pour la persistance des offres normalisées ;
CCX_ProductModelProjectionWriteService pour les Product Models ;
CCX_ProductVariantProjectionWriteService pour les variantes ;
CCX_ProductSpecificationProjectionWriteService pour les spécifications ;
CCX_ProductGalleryProjectionWriteService pour les galeries ;
CCX_ProductModelRebuildOrchestrator pour l'ordre canonique de reconstruction.

L'ordre de reconstruction multi-projection est :

Product Models ;
Variants ;
Specs ;
Gallery.

Les entrypoints et orchestrateurs ne doivent pas contourner ces services pour appeler directement des writers SQL legacy.

Rebuild complet et mise à jour incrémentale¶

Une projection doit pouvoir être reconstruite entièrement à partir des sources canoniques.

Le système peut également supporter une mise à jour incrémentale lorsque le périmètre modifié est connu.

Dans les deux cas :

le résultat final doit être équivalent ;
les opérations doivent être idempotentes ;
un même état source doit produire le même état projeté ;
une reprise après interruption ne doit pas dupliquer les données ;
les compteurs doivent être réconciliables.

Cohérence et atomicité¶

Une reconstruction ne doit pas exposer durablement une projection partiellement incohérente.

Selon le volume et le support de stockage, cette garantie peut être obtenue par :

transaction ;
tables temporaires puis bascule ;
écriture par lots avec état de run explicite ;
versionnement de projection ;
reprise contrôlée à partir d'un curseur stable.

Le mécanisme retenu doit être observable et documenté.

Traçabilité¶

Une opération de projection doit exposer au minimum :

l'identifiant du run ;
le type de projection ;
le périmètre traité ;
les versions ou timestamps des sources ;
le nombre de lignes lues ;
le nombre de lignes écrites ;
le nombre de lignes ignorées ou rejetées ;
les erreurs et codes de raison ;
l'état final du run.

Les métriques doivent permettre de réconcilier le total traité.

Projection et Frontend¶

Le Frontend doit consommer les projections ou des Read Services construits sur ces projections.

Il ne doit pas :

reconstruire une identité produit ;
recalculer la logique de résolution ;
dépendre des tables de Stage ;
appliquer des heuristiques de qualité concurrentes ;
effectuer des écritures persistantes pendant une lecture publique.

Le contrat de projection protège ainsi le Frontend des changements internes du Domain Core et du Pipeline.

Projection et Media Quality¶

Media Quality évalue des preuves liées aux médias et produit des diagnostics explicables.

Par défaut, cette évaluation est audit-first et non destructive.

Elle peut alimenter une projection avec :

un statut de qualité ;
un score ou un niveau de confiance ;
des codes de raison ;
une proposition de remplacement ;
des métriques d'audit.

Elle ne doit pas provoquer implicitement la suppression de image_norm ni une mutation de galerie pendant la construction d'une projection.

Une éventuelle correction persistante doit être :

explicitement activée ;
séparée de l'audit ;
exécutée par un Write Service ;
limitée à un périmètre identifiable ;
traçable et réversible lorsque possible.

Invariants¶

Dérivation uniquement¶

Une projection dérive la vérité métier. Elle ne la redéfinit pas.

Reconstructibilité¶

Toute projection persistée peut être supprimée puis reconstruite à partir des sources canoniques.

Déterminisme¶

À état source identique, le résultat projeté est identique.

Idempotence¶

Rejouer une même opération ne crée ni doublon ni dérive cumulative.

Explicabilité¶

Chaque valeur projetée peut être reliée à une source ou à une règle documentée.

Frontières d'écriture¶

Les écritures passent uniquement par les services de projection certifiés.

Aucune mutation qualité implicite¶

Une évaluation Media Quality ne modifie pas silencieusement les médias projetés.

Tests attendus¶

Les tests de projection doivent couvrir :

le déterminisme du builder ;
l'idempotence du writer ;
l'équivalence entre rebuild complet et incrémental ;
la reprise après interruption ;
la réconciliation des compteurs ;
l'absence d'écriture directe depuis les adapters ;
l'absence de logique métier dans le Frontend ;
l'absence de mutation destructive implicite par Media Quality ;
la reconstruction depuis un état source connu.