Aller au contenu

Offer Projection

Status: CONTRACT

Rôle

La Offer Projection expose une représentation de lecture stable des informations commerciales propres à une offre marchande.

Une Offer Projection représente une proposition commerciale rattachée à un produit. Elle n'est ni le Product lui-même, ni le feed brut du marchand.

Feed marchand
      ↓
Stage / normalisation / enrichissement
      ↓
Offer data préparée
      ↓
Projection Builder
      ↓
Offer Projection
      ↓
Frontend / API / adapters

Pourquoi elle existe

Le Frontend ne doit pas interpréter directement les feeds marchands pour déterminer un prix, une disponibilité ou une promotion.

La Offer Projection fournit donc des données déjà préparées pour la lecture et stabilise le contrat entre les couches métier et les consommateurs.

Entrées

La projection peut être construite à partir de données déjà traitées en amont, notamment :

  • identifiant d'offre ;
  • produit associé ;
  • marchand et source ;
  • prix normalisé ;
  • disponibilité ;
  • informations promotionnelles déjà validées ;
  • données de traçabilité ;
  • états de qualité ou d'incertitude utiles.

Le Builder ne doit pas interroger un feed brut ni recalculer une règle métier qui appartient au Pipeline, au Domain Core ou à une verticale.

Sortie documentaire

Le contrat historique couvre notamment :

Identité

  • offer_id
  • product_id
  • merchant_id
  • source_feed_id

Affichage

  • offer_title
  • condition_label
  • merchant_product_reference

Prix

  • price
  • old_price
  • saving
  • saving_percent
  • currency

Disponibilité

  • availability
  • stock_status
  • delivery_label

Marchand

  • merchant_name
  • merchant_logo
  • merchant_url
  • offer_url

Promotion

  • promotion_label
  • promotion_code
  • promotion_status

Traçabilité

  • observed_at
  • projected_at
  • source_name
  • projection_status

Pour la forme exacte du DTO actif, vérifier le contrat canonique courant sous src/Contracts/Projection et le code consommateur concerné.

Prix et remise

La projection peut exposer un prix courant, un prix de référence, une économie et un pourcentage de remise lorsque ces valeurs ont été correctement préparées en amont.

Le Frontend ne doit pas recalculer la vérité commerciale.

Si old_price, saving ou saving_percent sont absents, le consommateur doit respecter cette absence plutôt que d'inventer une promotion.

Promotions

Une information promotionnelle affichée doit provenir d'un traitement explicite en amont.

Le Frontend peut afficher :

  • un libellé ;
  • un code ;
  • un statut ;
  • les autres champs prévus par le contrat.

Il ne doit pas déduire lui-même qu'une promotion est valable à partir de données incomplètes.

Lecture seule côté consommateur

Un consommateur de Offer Projection peut afficher et formater les données reçues.

Il ne doit jamais :

  • modifier l'offre source ;
  • recalculer le prix métier ;
  • déduire une remise absente ;
  • transformer une disponibilité inconnue en disponibilité positive ;
  • fusionner plusieurs offres pour fabriquer une nouvelle offre ;
  • masquer un unknown, ambiguous ou conflict utile au diagnostic.

Déterminisme

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

L'ordre des feeds, l'ordre SQL ou le contexte du template ne doivent pas modifier la valeur projetée.

Reconstruction

La Offer Projection est une donnée dérivée et doit pouvoir être reconstruite depuis les informations amont qui font autorité.

En cas de divergence entre la projection et la source préparée :

  1. observer la donnée normalisée ;
  2. vérifier les règles d'enrichissement ;
  3. observer l'entrée du Projection Builder ;
  4. comparer la sortie construite et la projection persistée ;
  5. utiliser le Write Service approprié pour toute réécriture ;
  6. vérifier ensuite le consommateur.

Diagnostic

Si un prix ou une disponibilité semble faux, éviter de corriger directement le template.

Vérifier plutôt :

  1. la valeur observée chez le marchand ;
  2. la normalisation ;
  3. les règles promotionnelles ou commerciales ;
  4. le Builder ;
  5. la projection persistée ;
  6. l'adapter ;
  7. le rendu Frontend.

Cette séquence permet d'intervenir dans la bonne couche.

Invariants

  1. Une Offer Projection est une vue dérivée.
  2. Elle ne remplace ni le feed brut ni le Product Domain.
  3. Les calculs commerciaux sont préparés avant le Frontend.
  4. Les données manquantes restent explicites.
  5. La projection est déterministe et reconstruisible.
  6. Le Builder ne porte pas la persistance.
  7. Toute réécriture persistante passe par un Write Service explicite lorsqu'il existe.

Voir aussi