Aller au contenu

Homepage Projection

Status: CONTRACT

Rôle

La Homepage Projection est un modèle de lecture structuré destiné à alimenter la page d'accueil sans obliger le Frontend à interroger directement le catalogue, les offres ou les feeds bruts.

Elle n'est pas un template. Elle prépare les données ; le Frontend décide uniquement de leur présentation.

Catalogue / produits / offres / navigation
                 ↓
         Projection Builder
                 ↓
        Homepage Projection
                 ↓
              Frontend

Pourquoi cette projection existe

Une page d'accueil agrège plusieurs familles de contenu : catégories, produits, promotions, blocs éditoriaux et navigation.

Sans projection dédiée, le renderer pourrait être tenté de choisir lui-même les produits à mettre en avant, de recalculer des remises ou de reconstruire des URLs. Ces décisions ne doivent pas vivre dans le template.

Entrées

La Homepage Projection peut recevoir des données déjà préparées telles que :

  • catégories éligibles ;
  • produits sélectionnés en amont ;
  • Product Projections ;
  • Offer Projections ;
  • URLs canoniques ;
  • métadonnées SEO déjà préparées ;
  • règles d'ordre explicites ;
  • éléments de navigation autorisés.

Le Builder ne doit pas aller chercher des données de feeds bruts ni décider silencieusement d'une nouvelle règle commerciale.

Sortie documentaire

Le contrat historique couvre notamment :

Page

  • projection_id
  • canonical_url
  • seo_title
  • seo_description
  • projected_at
  • projection_status

Hero

  • title
  • subtitle
  • primary_cta_label
  • primary_cta_url
  • secondary_cta_label
  • secondary_cta_url

Sections

  • section_id
  • section_type
  • title
  • subtitle
  • sort_order
  • items

Éléments catégorie

  • label
  • url
  • image
  • product_count
  • visibility_status

Éléments produit

  • title
  • primary_image
  • price
  • old_price
  • saving_percent
  • merchant_name
  • canonical_url

Cette liste décrit le contrat documentaire historique. Pour une intervention dépendant de la forme exacte du payload actif, vérifier le DTO ou mapper actuellement utilisé dans le dépôt.

Ce que le Frontend peut faire

Le Frontend peut :

  • rendre les sections ;
  • choisir les composants visuels ;
  • appliquer les règles de responsive design ;
  • gérer la présentation d'une section vide si le contrat l'autorise.

Ce qu'il ne doit jamais faire

Le Frontend ne doit pas :

  • choisir les catégories mises en avant ;
  • choisir les produits mis en avant ;
  • recalculer les remises ;
  • reconstruire les URLs métier ;
  • lire directement les offres brutes ;
  • lire directement les feeds ;
  • modifier l'ordre métier ;
  • inventer un fallback commercial qui n'existe pas dans la projection.

Sections vides et données manquantes

Si une section ne possède aucun élément valide, le comportement doit être défini par la règle de projection : section vide explicite ou section absente.

Le template ne doit pas inventer des produits ou catégories de remplacement.

Une donnée inconnue reste inconnue. Les états unknown, ambiguous ou conflict utiles au diagnostic ne doivent pas être transformés en valeurs positives par le rendu.

Déterminisme

À données amont et version de règles identiques, la Homepage Projection doit produire les mêmes sections, le même ordre logique et les mêmes éléments.

Le résultat ne doit pas varier selon :

  • le template chargé ;
  • la requête HTTP courante ;
  • l'ordre accidentel des lignes SQL ;
  • un cache non identifié ;
  • une sélection aléatoire non explicitement contractualisée.

Diagnostic

Si la page d'accueil présente un mauvais produit, une mauvaise catégorie ou un ordre inattendu, vérifier dans cet ordre :

  1. les données amont qui déterminent l'éligibilité ;
  2. les Product / Offer / Navigation Projections consommées ;
  3. la règle de sélection ou d'ordre du Builder ;
  4. la Homepage Projection produite ;
  5. l'adapter éventuel ;
  6. le renderer Frontend.

Ne pas corriger une mauvaise sélection métier directement dans le template.

Reconstruction

La Homepage Projection est dérivée et doit pouvoir être reconstruite.

Lorsqu'elle est persistée, la construction et l'écriture doivent rester séparées :

Builder
  ↓
Homepage Projection en mémoire
  ↓
Write Service éventuel
  ↓
Stockage

Le Frontend ne doit jamais reconstruire ou persister cette projection pendant le rendu public.

Invariants

  1. La Homepage Projection est une vue dérivée.
  2. Elle ne porte pas le rendu HTML.
  3. Le Frontend ne choisit pas les contenus métier.
  4. Les données manquantes ne sont pas inventées.
  5. Le résultat est déterministe.
  6. Une mauvaise sélection se diagnostique en amont du renderer.
  7. Toute persistance éventuelle reste séparée du Builder et du Frontend.

Voir aussi