Frontend — Vue d'ensemble

Statut

CURRENT pour la frontière générale et les emplacements runtime actuellement documentés dans le dépôt.

Cette page explique où se situe réellement le Frontend de CMonChoix Platform et, surtout, ce qu'il a le droit de faire.

Le Frontend est une couche de restitution. Il consomme des données déjà préparées par la Platform. Il ne construit ni la vérité métier, ni l'identité canonique, ni les projections.

Rôle du Frontend

Le Frontend transforme des lectures stables en expérience utilisateur :

• routes publiques ;
• navigation ;
• pages catalogue ;
• pages produit ;
• HTML ;
• SEO ;
• composants visuels ;
• interactions de présentation.

Il ne doit pas compenser une incohérence amont par une règle locale cachée.

Flux attendu :

Sources marchands
      ↓
Pipeline / ingestion
      ↓
Domain Core + Vertical Modules
      ↓
Canonical Identity
      ↓
Projections
      ↓
Readers / Read Services
      ↓
Adapter WordPress
      ↓
Frontend public

Le Frontend est donc situé après la décision métier.

Emplacements à ne pas confondre

Le dépôt contient plusieurs répertoires qui peuvent sembler "frontend" mais n'ont pas le même rôle.

Workspace frontend/

Le répertoire :

frontend/

est un workspace de travail pour la documentation, l'organisation de composants et les tests frontend.

Il ne correspond pas, à lui seul, au Frontend WordPress servi en production.

Thème WordPress actif

Le thème WordPress documenté comme partie du runtime frontend est :

wordpress/wp-content/themes/ccx/

Il porte le rendu WordPress et les éléments visuels qui relèvent du thème.

Couche catalogue / navigation du plugin

La couche frontend canonique liée au catalogue se trouve notamment sous :

plugins/ccx-feeds-industrial/includes/frontend/

Cette couche fait partie du plugin WordPress et doit rester un Adapter de restitution, pas une nouvelle couche métier.

site/

Le répertoire :

site/

est la sortie générée de MkDocs.

Il sert à la documentation publiée et n'a aucun rapport avec le runtime Frontend WordPress.

Ne jamais corriger un problème de site public en modifiant site/.

Source canonique de navigation publique

La structure publique de navigation ne doit pas être inventée dans le thème ni dupliquée dans plusieurs renderers.

La source canonique actuelle se trouve dans :

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

La fonction principale est :

ccx_navigation_architecture_registry()

Ce registre définit notamment :

• les grandes sections ;
• leur ordre ;
• les groupes ;
• les feuilles ;
• les verticales associées ;
• certains accessory_types ;
• certains filtres d'exclusion ;
• les éventuels comportements always_visible.

Le fichier précise aussi un invariant important : des feuilles futures peuvent rester déclarées même lorsqu'aucune offre n'existe encore. Leur présence dans l'architecture ne signifie donc pas automatiquement qu'elles doivent être exposées par le Runtime.

Voir :

• Navigation Runtime
• Arbre de navigation publique
• Architecture de l'information publique

Ce que le Frontend peut faire

Le Frontend peut :

• lire une projection ou un payload préparé ;
• choisir un composant visuel selon une donnée déjà décidée ;
• formatter une valeur pour l'affichage ;
• produire les URLs et balises de présentation prévues par le contrat ;
• traduire un état applicatif en HTML, JSON-LD, redirection ou réponse HTTP ;
• masquer un élément lorsque le contrat de présentation l'autorise explicitement.

Exemple : formater 1299.99 en 1 299,99 € est une responsabilité de présentation.

Ce que le Frontend ne doit pas faire

Le Frontend ne doit pas :

• recalculer une Canonical Identity ;
• décider si deux offres représentent le même produit ;
• transformer unknown, ambiguous ou conflict en resolved ;
• choisir arbitrairement une offre comme vérité commerciale ;
• fusionner plusieurs produits ;
• enrichir des données marchand ;
• reconstruire une projection ;
• lire le Stage pour fabriquer un affichage ;
• écrire dans les tables métier pendant une requête publique ;
• copier la structure de navigation canonique dans plusieurs fichiers.

Lorsqu'une vue semble "avoir besoin" d'une de ces opérations, le problème se situe probablement dans une couche amont ou dans le contrat de projection.

Frontend projection-first

Le modèle attendu est projection-first : la vue consomme une représentation déjà adaptée à son besoin.

Projection
    ↓
Reader / Read Service
    ↓
Adapter
    ↓
Renderer

Le renderer ne doit pas effectuer un second Pipeline miniature.

Cette règle réduit :

• les divergences entre pages ;
• les recalculs en requête publique ;
• les comportements impossibles à auditer ;
• les dépendances directes au schéma SQL.

Voir :

• Projections côté Frontend
• Projections
• Read Services

Diagnostic : un affichage est faux

Ne commencez pas par modifier le CSS, le template ou une requête SQL.

Suivez cette séquence.

1. Identifier la donnée affichée

Déterminer précisément :

• quelle valeur est fausse ;
• quelle page la consomme ;
• quelle route est concernée ;
• si le problème touche un seul produit ou une famille entière.

2. Identifier la source lue par la vue

Chercher le Reader, le Read Service, le payload ou la projection alimentant le renderer.

Questions utiles :

• la valeur est-elle déjà fausse avant le rendu ?
• le renderer reçoit-il la bonne structure ?
• existe-t-il un shim ou wrapper legacy entre la projection et la vue ?

3. Comparer avec la projection

Si la projection est correcte mais le HTML faux, inspecter l'Adapter ou le renderer.

Si la projection est déjà fausse, ne corrigez pas le Frontend. Remontez vers :

Projection Builder
      ↓
Domain / Resolver / Vertical Module
      ↓
Source normalisée

4. Vérifier le statut métier

Un rendu prudent peut être normal si le statut est :

• unknown ;
• ambiguous ;
• conflict.

Ne transformez pas un état métier incertain en certitude juste pour rendre la page plus jolie.

Diagnostic : une catégorie manque dans la navigation

Procédure sûre :

1. vérifier qu'elle existe dans ccx_navigation_architecture_registry() ;
2. vérifier les verticales et filtres associés ;
3. vérifier si des offres ou modèles publics satisfont le contrat Runtime ;
4. vérifier la projection / lecture de navigation ;
5. vérifier l'Adapter et le renderer ;
6. seulement ensuite inspecter le HTML/CSS.

Une feuille déclarée dans l'architecture peut être volontairement invisible si le Runtime n'a aucune donnée publique permettant de l'exposer.

À l'inverse, ajouter une entrée seulement dans le thème crée une divergence et doit être évité.

Diagnostic : problème purement visuel

Lorsque les données et la structure sont correctes mais que l'affichage est cassé, l'intervention appartient bien au Frontend.

Exemples :

• z-index ;
• responsive ;
• taille d'image ;
• alignement ;
• espacement ;
• comportement d'un menu ;
• accessibilité visuelle.

Dans ce cas, préserver les contrats de données : ne profitez pas d'un correctif CSS pour introduire une décision métier dans le template.

Écritures pendant une requête publique

Une requête frontend publique doit rester une lecture autant que possible.

Les écritures techniques nécessaires au fonctionnement WordPress doivent être isolées derrière les services ou bootstraps prévus et ne doivent pas être cachées dans un renderer public.

Exemple déjà documenté côté Adapter WordPress : la maintenance des rewrites doit rester hors du rendu public.

Voir :

• WordPress Adapter

Performance

Avant d'optimiser un template :

1. mesurer le coût réel ;
2. identifier la couche responsable ;
3. vérifier si le problème vient d'une lecture SQL, d'une projection mal adaptée, d'un Reader ou du rendu ;
4. optimiser dans la bonne couche.

Une requête publique lente n'autorise pas à réintroduire de logique métier dans le Frontend pour éviter une reconstruction correcte en amont.

Voir :

• Performance Frontend

SEO

Le SEO appartient à la restitution publique, mais il doit utiliser les données déjà consolidées.

Le Frontend peut produire :

• title ;
• meta description ;
• canonical URL ;
• données structurées ;
• balises de présentation.

Il ne doit pas fabriquer une nouvelle identité produit uniquement pour améliorer une URL ou un titre.

Voir :

• SEO

Checklist avant modification Frontend

Avant tout changement :

• [ ] le problème est-il réellement dans le rendu ?
• [ ] la projection source est-elle correcte ?
• [ ] le statut métier est-il compris ?
• [ ] la navigation est-elle modifiée dans sa source canonique ?
• [ ] le changement introduit-il du SQL direct ?
• [ ] le changement introduit-il une règle métier locale ?
• [ ] le Frontend reste-t-il projection-first ?
• [ ] la requête publique reste-t-elle sans mutation métier ?
• [ ] les vues desktop et mobile sont-elles toutes deux vérifiées ?

Invariants

1. Le Frontend consomme la vérité métier ; il ne la décide pas.
2. La navigation publique possède une source canonique unique.
3. Le Frontend ne lit pas le Stage pour reconstruire les données affichées.
4. unknown, ambiguous et conflict restent des résultats métier valides.
5. Une projection fausse se corrige en amont, pas dans le template.
6. Une requête publique ne doit pas cacher une écriture métier.
7. Le thème, le plugin frontend et le workspace frontend/ ne doivent pas être confondus.
8. site/ est une sortie documentaire générée, jamais le runtime WordPress.

Voir aussi

• Navigation Runtime
• Architecture de l'information publique
• Arbre de navigation publique
• Projections côté Frontend
• WordPress Adapter
• Projections
• Database Projections
• Read Services