Aller au contenu

Navigation Runtime

Statut

CURRENT — guide de transmission du runtime de navigation publique.

Cette page explique comment la navigation publique est déclarée, filtrée puis consommée par le Frontend.

Elle ne redéfinit pas l'arbre public. La source exécutable canonique est :

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

et plus précisément :

ccx_navigation_architecture_registry()

Pourquoi cette page existe

Quand une catégorie est absente du menu, mal placée ou incohérente avec les offres disponibles, il est dangereux de commencer par modifier le thème.

Il faut d'abord déterminer à quel niveau se situe le problème :

architecture publique déclarée
        ↓
contrat de visibilité Runtime
        ↓
projection / cache / reader
        ↓
adapter WordPress
        ↓
renderer Frontend

Le Frontend est le dernier maillon. Il ne doit pas inventer une catégorie absente du contrat public.

Source canonique actuelle

Le registre ccx_navigation_architecture_registry() décrit la structure publique de long terme :

  • univers ;
  • groupes ;
  • feuilles ;
  • labels ;
  • ordre ;
  • verticales associées ;
  • filtres accessory_types ou exclude_accessory_types lorsqu'ils sont nécessaires ;
  • éventuel always_visible.

Le commentaire du fichier précise deux règles essentielles :

  1. une feuille future peut rester déclarée même lorsqu'aucune offre n'existe encore ;
  2. le Runtime ne doit l'exposer que lorsqu'elle est soutenue par des offres ou modèles publics, sauf always_visible explicite.

Une feuille déclarée mais invisible n'est donc pas automatiquement un bug.

Ce que le Runtime doit faire

Le Runtime transforme la déclaration canonique en une représentation réellement consommable par les surfaces publiques.

Conceptuellement :

navigation-architecture.php
        ↓
contrat de visibilité
        ↓
projection / cache de navigation
        ↓
reader
        ↓
Frontend

Le Runtime peut filtrer une feuille lorsque :

  • aucune donnée publique ne satisfait son contrat ;
  • la verticale correspondante n'est pas représentée ;
  • un accessory_type attendu n'est pas présent ;
  • un exclude_accessory_types exclut le produit ;
  • un autre garde-fou de visibilité publique s'applique.

Il ne doit pas modifier arbitrairement l'architecture déclarée.

Responsabilités du Frontend

Le Frontend peut :

  • rendre les univers, groupes et feuilles fournis ;
  • appliquer la présentation responsive ;
  • produire les liens et états visuels ;
  • rendre les breadcrumbs à partir des données reçues ;
  • fournir un fallback technique documenté si la lecture échoue.

Il ne doit pas :

  • ajouter une catégorie en dur parce qu'elle “manque” visuellement ;
  • reconstruire l'arbre depuis les offres ;
  • décider qu'une feuille future doit devenir visible ;
  • convertir une catégorie marchand en catégorie publique ;
  • recalculer la classification métier.

Déclaration ≠ visibilité

C'est le point le plus important pour le diagnostic.

Exemple conceptuel :

Feuille déclarée : oui
Offres publiques correspondantes : non
always_visible : non

=> feuille correctement absente du rendu Runtime

À l'inverse :

Feuille déclarée : oui
Offres publiques correspondantes : oui
Contrat de filtrage satisfait : oui

=> si elle reste absente, rechercher un problème de projection, cache, reader ou renderer

Comment diagnostiquer une catégorie absente

1. Vérifier la déclaration canonique

Chercher d'abord la feuille dans :

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

Questions :

  • le slug existe-t-il ?
  • le label est-il correct ?
  • la verticale attendue est-elle la bonne ?
  • des accessory_types sont-ils imposés ?
  • des exclusions sont-elles présentes ?

2. Vérifier les données publiques

Observer ensuite si des produits/offres publics correspondent réellement au contrat.

Ne pas conclure uniquement à partir d'une catégorie marchand ou d'une ligne Stage.

3. Vérifier la projection ou le cache

Si le contrat est satisfait mais que la feuille reste absente, inspecter la représentation dérivée utilisée par le Frontend.

Une projection ou un cache peut être obsolète sans que la déclaration canonique soit fausse.

4. Vérifier le Reader / Adapter

Confirmer que la structure fournie au thème contient bien la feuille attendue.

Si elle disparaît à cette étape, le problème est dans la couche de lecture ou d'adaptation, pas dans le CSS.

5. Vérifier le renderer

Modifier le thème uniquement si la donnée correcte arrive jusqu'au renderer mais n'est pas affichée correctement.

Toutes les surfaces publiques doivent converger vers la même architecture publique.

Elles ne doivent pas maintenir chacune leur propre liste de catégories.

Le principe est :

une architecture publique
        ↓
une ou plusieurs représentations de lecture compatibles
        ↓
plusieurs renderers

Un renderer peut présenter moins d'éléments selon son espace disponible, mais il ne doit pas créer une taxonomie parallèle.

Performance

La navigation est lue sur de nombreuses pages publiques.

Le Frontend ne doit donc pas :

  • scanner les offres à chaque rendu du header ;
  • effectuer des jointures métier lourdes ;
  • reconstruire la hiérarchie à partir du Stage ;
  • appeler le Pipeline.

La lecture doit s'appuyer sur une représentation préparée : projection, cache ou Reader dédié selon l'implémentation CURRENT.

Fallback

Un fallback de navigation est une mesure de continuité technique.

Il ne doit jamais devenir une seconde source de vérité.

Si un fallback est nécessaire :

  • il reste minimal ;
  • il ne réintroduit pas d'anciennes catégories supprimées ;
  • il ne décide pas de nouvelles catégories ;
  • il doit être rapproché du registre canonique dès que possible.

Erreurs fréquentes

Modifier header.php pour ajouter une catégorie

Mauvais réflexe si la donnée ne sort pas du Runtime.

Le correctif masque le problème et crée une divergence avec homepage, footer et breadcrumbs.

Considérer toute feuille déclarée comme visible

Faux.

Le registre contient volontairement des feuilles futures qui peuvent rester masquées faute de données publiques correspondantes.

Utiliser la taxonomie marchand comme navigation publique

Interdit architecturalement.

Les marchands fournissent des signaux de classification ; ils ne gouvernent pas l'arbre public.

Utiliser une ancienne documentation comme autorité

Les anciens arbres documentaires peuvent être utiles historiquement, mais la source CURRENT est le registre PHP exécutable.

Intervention sûre

Avant de modifier la navigation :

  1. observer le registre canonique ;
  2. observer les données publiques correspondantes ;
  3. observer projection/cache/Reader ;
  4. vérifier le payload reçu par le Frontend ;
  5. seulement ensuite modifier le renderer si nécessaire ;
  6. reconstruire ou invalider explicitement les données dérivées si l'opération le demande ;
  7. vérifier header, homepage, footer et breadcrumbs.

Vérification après changement

Contrôler au minimum :

  • la feuille attendue ;
  • son parent ;
  • son ordre ;
  • les URLs générées ;
  • l'absence de doublon ;
  • l'absence de catégorie legacy réintroduite ;
  • la cohérence entre plusieurs surfaces publiques ;
  • le comportement lorsque la catégorie n'a aucune donnée publique.

Historique

Une ancienne version de cette page décrivait un design Public Navigation Tree -> Navigation Taxonomy -> Navigation Projection -> Frontend Consumers et des étapes de certification BC-049.*.

Ces éléments restent utiles pour comprendre l'évolution du système, mais ne doivent plus être utilisés comme source de vérité CURRENT lorsqu'ils contredisent le registre exécutable.

Voir aussi