Aller au contenu

Frontend

Status

Status: CURRENT Last consolidated by: BC-068D This document describes the current frontend boundary.

Mission

Le Frontend affiche les données préparées par la Platform.

Il fournit l'expérience utilisateur sans contenir la logique métier profonde.

Responsabilités

  • pages catalogue
  • pages produit
  • cartes produit
  • filtres utilisateur
  • navigation
  • SEO
  • performance d'affichage
  • rendu responsive
  • lecture de projections

Le frontend public courant est projection-first :

  • pas de write public ;
  • pas de dépendance Pipeline ;
  • pas de dépendance Runtime ;
  • pas de SQL direct ;
  • pas de dépendance directe aux adapters WordPress depuis src/ReadService.

Ce qui lui appartient

  • templates
  • composants d'affichage
  • UX
  • CSS
  • interactions utilisateur
  • routing de présentation
  • rendu des projections
  • mise en forme SEO

Ce qui lui est interdit

Le Frontend ne doit jamais contenir :

  • résolution d'identité produit
  • classification métier
  • scoring produit
  • sync feed
  • rebuild
  • écriture métier
  • patchs marchands
  • logique SQL de correction
  • décisions de gouvernance

Dépendances autorisées

Le Frontend peut dépendre de :

  • Read Services
  • projections préparées
  • repositories de lecture frontend
  • helpers d'affichage
  • assets

Dans le runtime WordPress, ces dépendances de lecture restent canoniques :

  • src/ reste la source unique des DTO et Read Services ;
  • le plugin WordPress charge l'autoload canonical ;
  • le Frontend historique peut recevoir temporairement un payload shimé DTO -> array pendant la migration.

Dépendances interdites

Le Frontend ne doit pas dépendre de :

  • Pipeline
  • Runtime
  • Write Services
  • Domain Core directement
  • Vertical Modules directement
  • SQL brut
  • patchs legacy
  • sync feed

Entrées

  • projection produit
  • projection catalogue
  • filtres utilisateur
  • paramètres de route
  • données SEO
  • données navigation

Sorties

  • HTML
  • CSS
  • JS
  • pages catalogue
  • pages produit
  • fragments d'affichage
  • balisage SEO

Contrats utilisés

Le Frontend consomme uniquement des contrats de lecture :

  • projection produit
  • projection catalogue
  • projection navigation
  • résultats Read Services
  • états de disponibilité

Organisation cible

frontend/

catalog/
  pages
  cards
  filters
  pagination

product/
  page
  tabs
  price-block
  merchant-offers

navigation/
  menu
  breadcrumbs

seo/
  metadata
  schema

assets/
  css
  js

Frontend Presentation Registry

Le registre frontend est l'unique configuration de présentation des verticales publiques branchées sur les projections Product Models. Il résout une vue par vertical_id ou par route canonique et fournit le Catalog View Context : route, base des fiches, titres, breadcrumbs, facettes, métadonnées de carte et sections de caractéristiques.

Une verticale absente du registre reste explicitement non migrée. La valeur par défaut de filters_enabled est false; elle ne devient vraie que lorsque les facettes déclarées disposent de valeurs projetées fiables.

Generic Catalog Template

Une route enregistrée rend toujours le template catalogue Product Models commun, y compris lorsque sa projection est vide ou indisponible. Dans ce cas, le template affiche son état vide SSR et n'utilise jamais le catalogue legacy comme fallback visuel.

Generic Product Card

Toutes les lignes Product Models utilisent la même carte et construisent leurs liens avec ccx_product_models_build_detail_url(). Les métadonnées secondaires proviennent exclusivement de la projection; leur absence n'est pas compensée par un parsing du titre.

Generic Product Template

Toutes les identités Product Models partagent la galerie, les variantes, les prix, les offres, les CTA et les blocs de rassurance du template produit commun. La verticale ne fournit que le contexte de présentation.

Configurable Facets

Les facettes sont déclaratives (key, label, type, source, multiple). Les types autorisés sont choice, range et boolean. Une facette sans configuration ou sans valeurs projetées réelles n'est pas rendue; une vue sans facette exploitable utilise le layout no-filters.

SSR / Performance / SEO Rules

Les produits, liens, titres, breadcrumbs et états vides sont rendus côté serveur. Le frontend lit les projections sans SQL métier dans les templates et sans dépendance aux Vertical Modules. Les caches sont verticalisés. Le canonical d'une catégorie ignore tri et tracking; une combinaison de filtres arbitraires reçoit noindex,follow et canonicalise vers la catégorie principale.

Legacy Catalog Migration

La migration est progressive. Smartphones et Montres connectées constituent le premier groupe enregistré. Les autres routes restent inventoriées dans la taxonomie publique et ne rejoignent le registre qu'après validation de leur projection. Le legacy n'est supprimé qu'après preuve qu'il n'a plus de consommateurs.

Le router catalogue legacy conserve une responsabilité de compatibilité pendant cette migration. Les URLs préfixées par /catalogue et les anciens chemins de navigation documentés redirigent en 301, avant le rendu Product Models, vers l'URL publique sans préfixe en conservant la query string. Les routes enregistrées restent ensuite rendues et canonisées par Product Models; les autres restent servies par le router legacy.

Sur une page legacy, le canonical omet tri et filtres, la pagination supérieure à 1 reste auto-canonique, le breadcrumb suit Public Navigation et les cartes pointent vers /produits/{canonical-slug}/. Si le slug ou sa table de projection est indisponible, /produit/{ean}/ reste le fallback compatible.

Depuis BC-061C3, la lecture des items paginés, de leur total, des listes de marques/marchands, de la taxonomie visible, de l'existence d'un chemin fallback, des métadonnées de catégorie et des enfants/navigation secondaire ne se trouve plus dans le router. Le frontend construit un CatalogQuery, consomme un CatalogPageProjection complet via CatalogProjectionReader, puis utilise le shim explicite DTO vers array pour alimenter le renderer historique. Le tri, les filtres actifs, la jointure des slugs canoniques, la limite, l'offset, les lectures de facettes, la résolution/metadata et les cinq stratégies enfants appartiennent à l'adapter SQL legacy.

Les facettes brand et merchant utilisent FacetProjection et FacetOptionProjection. Le chemin projeté conserve la priorité historique taxonomy visible -> fallback offers -> inconnu, sans décision HTTP ni URL publique dans le reader. Les enfants projetés conservent l'ordre historique cache groupe -> cache sous-catégorie -> dynamique groupe -> dynamique sous-catégorie -> fallback legacy, les labels, les chemins et les compteurs. Le shim reconstruit la shape legacy des métadonnées (category_norm, subcategory_norm, platform_norm, product_type_norm, canonical_category, total) ainsi que la shape enfants (seo_path_norm, label, total) directement depuis la CatalogPageProjection, sans inventer de compteur par option, sans SQL et sans logique métier. Le router legacy ne contient plus aucune lecture SQL métier et n'orchestre plus plusieurs lectures catalogue distinctes.

Invariants : un template catalogue standard, une carte standard, une fiche standard, configuration par verticale, facettes déclaratives, aucune logique métier frontend, et fichiers canonical/runtime strictement identiques.

Product Canonical Governance Read Model

Depuis BC-061B2, les helpers PHP et le snippet de gouvernance Product Canonical ne lisent plus WordPress directement et ne contiennent plus de SQL.

La chaîne de lecture est :

Product Canonical frontend wrapper
    -> CanonicalProductReadService
    -> CanonicalProductProjectionReader
    -> SqlCanonicalProductProjectionReader
    -> legacy read model
    -> pure governance renderer

Le renderer reçoit des lignes déjà préparées et conserve la shape historique, l'ordre, les libellés et les fallbacks visuels. Il ne compte pas les marchands, ne recalcule pas les économies et ne connaît aucun nom de table.

ccx_pc_table() reste temporairement disponible pour compatibilité, mais délègue au résolveur technique commun ccx_feeds_table() sans accéder à $wpdb.

Global Public Frontend Read Boundary (BC-061D)

Les routes publiques actives sont bornées comme suit :

  • Product Canonical EAN/slug : router WordPress -> CanonicalProductReadService -> adapter SQL legacy -> ProductProjection / OfferProjection -> renderer historique ;
  • Catalog legacy : router WordPress -> CatalogProjectionReader -> SqlLegacyCatalogProjectionReader -> CatalogPageProjection -> FrontendProjectionArrayShim -> renderer historique ;
  • Product Models catalogues/détails : router WordPress -> ProductModelsFrontendReadService -> projections catalogue/produit -> shim array de compatibilité -> renderer historique ;
  • Public Navigation thème : helper thème -> ccx_public_navigation() -> PublicNavigationReadService -> NavigationProjectionReader -> NavigationProjection.

Le frontend public ne porte plus d'écriture persistante de maintenance de routes. Le fingerprint des rewrites Product Models est maintenu hors includes/frontend/, dans un bootstrap technique dédié, afin que les requêtes publiques restent strictement read-only côté WordPress.

Depuis BC-062E, cette frontière publique est considérée globalement certifiée côté WordPress :

  • aucun SQL direct dans includes/frontend/ ;
  • aucun write WordPress dans includes/frontend/ ;
  • aucune dépendance directe au Runtime, au Pipeline, au Worker ou aux action services ;
  • lecture via Read Services, Projection Readers ou wrappers de compatibilité de shape explicitement bornés ;
  • aucun fallback homepage introduit par les adapters publics ;
  • les dettes SEO/compatibilité Product Canonical restantes, si elles existent, relèvent d'une dette legacy de rendu/shape et non d'un retour à une architecture non bornée.

Canonical Catalog Presentation System

Statut : TARGET / CONTRACT.

Les catalogues Product Models convergent vers un système visuel canonique partagé. La géométrie, la sidebar, la toolbar, la grille, les cartes, les CTA et le style des filtres appartiennent au composant de présentation catalogue commun.

Les verticales fournissent uniquement leur contexte : hero, facettes, métadonnées projetées et rares exceptions explicitement justifiées.

La duplication du CSS catalogue entre verticales est interdite. La cible technique est catalog-listing.css, complété par des fichiers verticaux minces.

Voir ADR 0005.