Fondations de la plateforme CMonChoix¶

Statut¶

Document de référence pour la transmission du projet.

Pourquoi ce document existe¶

Ce document décrit les idées fondamentales sur lesquelles CMonChoix est construit. Elles sont volontairement plus stables que les technologies utilisées : un conteneur, un plugin ou une implémentation peuvent changer sans que ces principes disparaissent.

Pour quelqu'un qui reprend le projet, ces fondations permettent surtout d'éviter une erreur classique : corriger rapidement un symptôme dans WordPress alors que la vraie responsabilité se trouve plus tôt dans le pipeline ou dans le domaine métier.

Vision simple du système¶

On peut résumer le fonctionnement général ainsi :

Données des marchands
        ↓
Ingestion
        ↓
Normalisation et enrichissement
        ↓
Identification du produit
        ↓
Données canoniques
        ↓
Projections / données adaptées à la lecture
        ↓
Runtime et WordPress
        ↓
Site CMonChoix visible par l'utilisateur

Cette représentation est volontairement simplifiée. Elle sert de carte mentale avant d'entrer dans les documents techniques détaillés.

Les principes fondamentaux¶

1. Le métier avant la technique — « Domain First »¶

Une règle concernant un produit, une offre, une catégorie ou une identité doit être pensée comme une règle métier avant d'être pensée comme une particularité de WordPress, de SQL ou d'un marchand.

Exemple : si deux offres correspondent au même produit, la décision permettant de les rattacher au même produit ne doit pas dépendre uniquement de la manière dont une page WordPress est affichée.

2. Le contrat avant l'implémentation — « Specification First »¶

Avant de changer un comportement important, il faut savoir ce que le système est censé garantir. Les contrats, invariants, tests et documents d'architecture servent à rendre cette attente explicite.

Cela évite qu'une correction locale casse silencieusement une autre partie de la plateforme.

3. L'identifiant avant le libellé — « Identifier First »¶

Le système doit s'appuyer autant que possible sur des identifiants stables plutôt que sur des noms affichés, des titres ou des chaînes de caractères susceptibles de changer.

Un libellé est destiné à être lu par un humain. Un identifiant sert à reconnaître de manière fiable une entité dans le système.

4. Un produit canonique — « Canonical Product »¶

Plusieurs marchands peuvent décrire le même produit de façons différentes. CMonChoix doit pouvoir construire une représentation commune et fiable de ce produit, au lieu de considérer chaque fiche marchand comme un produit indépendant.

Le produit canonique devient alors le point de référence autour duquel les offres et les informations peuvent être organisées.

5. Une responsabilité métier claire — « Business Capability First »¶

Chaque grande capacité doit avoir un responsable identifiable : ingestion, identité, projection, lecture, écriture, navigation, etc.

Quand tu cherches où effectuer une modification, demande-toi d'abord quelle capacité métier est responsable, plutôt que de chercher immédiatement le premier fichier PHP contenant le texte concerné.

6. WordPress est un adaptateur — « WordPress is an Adapter »¶

WordPress est une partie importante du runtime et du site public, mais il ne doit pas devenir la source de vérité de toute la plateforme.

Cela signifie notamment qu'une règle fondamentale d'identité ou de normalisation ne devrait pas exister uniquement parce qu'elle est pratique à implémenter dans un hook WordPress.

7. La documentation fait partie du produit¶

La documentation n'est pas un supplément facultatif. Elle doit expliquer :

pourquoi une architecture existe ;
où se trouve la responsabilité d'une fonction ;
comment diagnostiquer un problème ;
comment effectuer une opération sans mettre la production en danger ;
quelles règles ne doivent pas être contournées.

Pour la transmission du projet, une procédure qui n'existe que dans la mémoire de son créateur est considérée comme incomplète.

Comment utiliser ces principes lors d'une intervention¶

Supposons qu'une catégorie soit incorrecte sur le site. Il serait tentant de modifier directement le rendu de la page. Les fondations imposent plutôt de remonter la chaîne :

Page incorrecte
   ↓
Quelle projection fournit cette information ?
   ↓
Quelle donnée canonique ou normalisée l'alimente ?
   ↓
Quelle règle métier produit cette valeur ?
   ↓
Corriger au niveau responsable
   ↓
Reconstruire / synchroniser si nécessaire
   ↓
Vérifier le résultat public

Cette méthode demande parfois quelques minutes de plus au début, mais elle évite les correctifs contradictoires et les données incohérentes.

Ce qui peut changer sans remettre en cause les fondations¶

Les technologies, versions, conteneurs, commandes, noms de classes et détails d'implémentation peuvent évoluer. Les documents d'exploitation et le code courant doivent être consultés pour connaître leur état exact.

En revanche, changer un principe comme l'identité canonique, la séparation des responsabilités ou le rôle d'adaptateur de WordPress est une décision d'architecture. Elle doit être explicitement étudiée, documentée et testée.

Règle de transmission¶

Si tu reprends CMonChoix et qu'une partie du système te paraît obscure, ne cherche pas à tout mémoriser. Identifie d'abord la responsabilité concernée, lis son document de référence, vérifie l'état réel du runtime, puis effectue une modification petite et vérifiable.

C'est cette discipline — davantage qu'une connaissance exhaustive du code — qui permet de faire évoluer la plateforme sans perdre sa cohérence.