Aller au contenu

Navigation Projection

Status: CONTRACT

Rôle

La Navigation Projection est le modèle de lecture utilisé pour exposer une arborescence de navigation stable aux consommateurs de la Platform.

Elle permet au Frontend de rendre menus, catégories et relations parent/enfant sans reconstruire la taxonomie ni interroger des catégories de feeds bruts.

Une Navigation Projection est une vue dérivée. Elle n'est pas la source de vérité du catalogue.

Architecture de navigation / taxonomie canonique
                  ↓
          Projection Builder
                  ↓
        Navigation Projection
                  ↓
       Frontend / API / adapters

Source canonique à ne pas confondre

La navigation publique de CMonChoix possède une source canonique d'architecture dans :

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

La projection sert à exposer une vue de lecture de cette architecture et des données autorisées qui l'enrichissent. Modifier une projection ou un template ne doit pas devenir un moyen détourné de redéfinir l'architecture canonique.

Pourquoi cette projection existe

Sans cette frontière, le Frontend pourrait être tenté de :

  • reconstruire les relations parent/enfant ;
  • décider quelles catégories sont visibles ;
  • recalculer des compteurs ;
  • lire directement des catégories marchandes ;
  • créer sa propre logique de navigation.

Cela produirait plusieurs architectures concurrentes selon le consommateur.

Entrées

La construction peut recevoir des données déjà validées telles que :

  • architecture canonique de navigation ;
  • identifiants de catégories ;
  • libellés et slugs ;
  • relations parent/enfant ;
  • ordre d'affichage ;
  • visibilité ;
  • compteurs de produits lorsqu'ils font partie du contrat ;
  • éléments visuels déjà préparés.

Les données marchandes brutes ne doivent pas être interprétées directement par le renderer.

Sortie documentaire

Le contrat historique couvre notamment :

Arbre

  • navigation_id
  • root_items
  • children
  • depth
  • sort_order

Élément

  • item_id
  • label
  • slug
  • url
  • parent_id
  • product_count
  • visibility_status

Affichage

  • title
  • short_label
  • icon
  • image
  • badge_label

Traçabilité

  • projected_at
  • source_version
  • projection_status

La forme exacte du DTO actif doit être vérifiée dans les contrats canoniques courants sous src/Contracts/Projection/Navigation lorsqu'une intervention dépend de détails d'implémentation.

Ce que le Frontend peut faire

Le Frontend peut :

  • parcourir l'arbre exposé ;
  • rendre des menus ;
  • appliquer des règles visuelles ;
  • choisir le composant HTML adapté au niveau de profondeur.

Ce qu'il ne doit jamais faire

Le Frontend ne doit pas :

  • reconstruire la taxonomie ;
  • décider la visibilité métier d'une catégorie ;
  • recalculer les relations parent/enfant ;
  • recalculer des compteurs métier ;
  • lire des catégories marchandes brutes ;
  • modifier la structure canonique ;
  • inventer une destination lorsqu'un élément est inconnu ou indisponible.

Données manquantes et visibilité

Une catégorie absente, cachée ou non résolue doit rester explicite selon le contrat utilisé.

Le Frontend ne doit pas déduire qu'un élément est visible simplement parce qu'il possède un libellé ou une URL partielle.

Déterminisme

À architecture canonique et données amont identiques, la projection doit produire le même arbre logique et le même ordre.

Le résultat ne doit pas dépendre de :

  • l'ordre des lignes SQL ;
  • l'ordre des feeds ;
  • la route HTTP courante ;
  • un état global caché du thème ;
  • un tri implicite non documenté.

Diagnostic

Si une catégorie est absente, mal placée ou visible au mauvais endroit, vérifier dans cet ordre :

  1. l'architecture canonique dans navigation-architecture.php ;
  2. les données de catalogue/taxonomie utilisées en amont ;
  3. le Builder de projection ;
  4. la projection obtenue ;
  5. l'adapter qui la livre ;
  6. le renderer Frontend.

Un problème d'arborescence canonique ne doit pas être corrigé avec du CSS ou une condition de template.

Reconstruction

Comme toute projection, cette vue doit pouvoir être reconstruite à partir des sources qui font autorité.

Une reconstruction persistante doit rester séparée de la construction en mémoire et passer par un mécanisme d'écriture explicite lorsqu'un stockage est utilisé.

Invariants

  1. La Navigation Projection est dérivée.
  2. L'architecture canonique ne réside pas dans le Frontend.
  3. Les relations et règles de visibilité ne sont pas recalculées dans le template.
  4. Le résultat est stable et déterministe.
  5. Les données absentes ne sont pas inventées.
  6. Une erreur de navigation est diagnostiquée depuis la source canonique vers le renderer, pas l'inverse.

Voir aussi