Frontend — Projections et compatibilité de lecture¶

Statut¶

CURRENT pour la frontière d’architecture et de compatibilité décrite ici.

Cette page explique comment le Frontend consomme les projections sans devenir propriétaire de la logique métier ni du format canonique interne.

Elle remplace l’ancienne lecture centrée sur les certifications BC-* par un guide de transmission exploitable.

Rôle¶

Le Frontend ne reconstruit pas les décisions métier.

Il consomme des représentations de lecture déjà préparées :

Domain Core / Vertical Modules
        ↓
Projection Builder
        ↓
Write Service / persistence
        ↓
Projection Reader / Read Service
        ↓
Adapter WordPress
        ↓
Frontend

Une projection est une représentation dérivée, optimisée pour la lecture et reconstruisible. Elle n’est pas une nouvelle source de vérité métier.

Le Frontend doit donc rester un consommateur passif de cette représentation.

Pourquoi une frontière de compatibilité ?¶

Le code interne peut évoluer sans que le HTML public, les routes ou les clés historiques consommées par le thème changent immédiatement.

La Platform maintient pour cela une frontière explicite entre :

les DTO/projections canoniques ;
les Read Services ;
les adapters WordPress ;
les payloads historiques encore attendus par certaines vues.

Cette frontière permet de moderniser les couches internes sans forcer un big-bang côté Frontend.

Propriété canonique des projections¶

Le modèle de propriété documenté par la refonte Platform place les DTO de projection canoniques sous :

src/Contracts/Projection/

Des wrappers ou formes compatibles peuvent subsister pour préserver les consommateurs historiques.

Important :

un wrapper de compatibilité n’est pas la nouvelle source de vérité ;
un tableau legacy n’est pas un contrat métier autonome ;
la présence d’une clé historique dans le thème ne justifie pas de recalculer la donnée dans le Frontend.

Lorsqu’un détail CURRENT précis est nécessaire, vérifier le code chargé par Composer avant d’affirmer quel FQCN ou wrapper est réellement actif.

Read Service et Adapter¶

Le Read Service prépare une réponse de lecture cohérente.

L’Adapter WordPress peut ensuite traduire cette réponse vers une forme compatible avec le thème.

Exemple conceptuel :

NavigationProjection
        ↓
PublicNavigationReadService
        ↓
Adapter WordPress
        ↓
FrontendProjectionArrayShim
        ↓
tableau historique consommé par le thème

Le shim de compatibilité sert uniquement à traduire une représentation.

Il ne doit pas :

résoudre une identité ;
classifier un produit ;
décider si une offre est valide ;
recalculer une projection ;
interroger directement des tables métier pour compléter un payload manquant.

La navigation est un cas important parce qu’elle relie architecture publique et rendu Frontend.

La source canonique CURRENT de l’architecture déclarée est :

plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php

via :

ccx_navigation_architecture_registry()

Le Frontend ne doit pas redéfinir cet arbre dans header.php, la homepage ou un composant local.

La chaîne attendue reste :

registre canonique
    ↓
filtrage de visibilité Runtime
    ↓
projection / représentation de lecture
    ↓
Reader / Adapter
    ↓
rendu Frontend

Une feuille déclarée mais sans offre ou modèle public satisfaisant son contrat peut être absente du rendu sans que le registre soit incorrect.

Product Models et vues produit¶

Le même principe s’applique aux pages et listings produit.

Le Frontend peut recevoir des représentations pour :

catalogue ;
facettes ;
modèle produit ;
variantes ;
spécifications ;
galerie ;
offres.

Mais il ne doit jamais utiliser une vue partielle pour réinventer la décision qui appartient au Domain Core, à un Vertical Module ou à un Projection Builder.

Si une donnée manque dans le rendu :

vérifier la projection ;
vérifier le Reader ;
vérifier l’Adapter ou le shim ;
seulement ensuite vérifier le template.

Ajouter une règle métier dans le template parce qu’un champ manque masque généralement le vrai défaut.

Builder, Writer, Reader : ne pas les confondre¶

Trois responsabilités distinctes doivent rester visibles.

Projection Builder¶

Décide quelle représentation dérivée doit être produite à partir des décisions métier déjà établies.

Write Service / writer¶

Persiste explicitement cette représentation.

Une reconstruction de projection est une mutation contrôlée.

Reader / Read Service¶

Lit la représentation persistée sans la modifier.

Le Frontend se situe après cette dernière frontière.

Compatibilité legacy¶

Une compatibilité legacy est acceptable lorsqu’elle permet une migration progressive.

Elle devient dangereuse lorsqu’elle commence à :

porter une logique métier ;
diverger silencieusement du DTO canonique ;
être utilisée comme nouvelle donnée source ;
empêcher la suppression d’un ancien chemin ;
masquer une incohérence de projection.

Pour chaque shim important, un mainteneur doit pouvoir répondre à :

quel consommateur en dépend ?
quelle représentation canonique traduit-il ?
pourquoi existe-t-il encore ?
peut-on le supprimer sans changer le contrat public ?

Diagnostic d’un problème de rendu¶

Cas 1 — valeur fausse partout¶

Suspecter en priorité :

source ;
normalisation ;
Resolver ;
Vertical Module ;
Projection Builder.

Ne pas commencer par le CSS ou le template.

Cas 2 — projection correcte, HTML faux¶

Vérifier :

Reader ;
Adapter ;
shim de compatibilité ;
mapping des clés ;
template.

Vérifier dans cet ordre :

registre ccx_navigation_architecture_registry() ;
contrat de la feuille (verticals, accessory_types, exclusions) ;
présence de données publiques satisfaisantes ;
projection/cache de navigation ;
Reader/Adapter ;
rendu du thème.

Cas 4 — un correctif Frontend « marche » mais seulement localement¶

C’est souvent un signal qu’une décision a été placée dans la mauvaise couche.

Comparer le même produit ou la même catégorie dans les autres consommateurs : homepage, menu, breadcrumb, listing, sitemap ou page produit.

Garde-fous¶

Ne jamais :

utiliser le Frontend comme moteur de résolution ;
lire les tables de Stage directement depuis un template ;
modifier une projection pendant une requête publique ;
utiliser un cache comme vérité métier ;
créer une seconde taxonomie dans le thème ;
transformer un unknown, ambiguous ou conflict en resolved pour simplifier l’affichage ;
ajouter une requête SQL lourde dans le header pour compenser une projection insuffisante.

Intervention sûre¶

Avant de modifier le Frontend :

reproduire le défaut sur une URL ou un échantillon précis ;
capturer la représentation lue avant le rendu ;
identifier la première couche où la donnée devient incorrecte ;
corriger cette couche, pas la couche suivante ;
reconstruire la projection si la correction le nécessite ;
vérifier plusieurs consommateurs ;
confirmer qu’aucune écriture n’a été introduite sur une requête publique.

Invariants¶

Le Frontend consomme des projections ; il ne décide pas la vérité métier.
Les projections canoniques appartiennent aux contrats Platform, pas au thème.
Les adapters et shims traduisent les formats ; ils ne recalculent pas le métier.
Une projection est dérivée et reconstruisible.
Toute reconstruction est une opération d’écriture explicite.
La navigation publique n’est jamais redéfinie localement par un template.
Les statuts resolved / unknown / ambiguous / conflict conservent leur sens jusqu’au rendu.