Aller au contenu

Constitution de CMonChoix Platform

Status: NORMATIVE / CONSTITUTION

Objet

Ce document définit les règles qui doivent rester vraies même si le code, le nombre de marchands, l'infrastructure, le CMS ou les technologies changent.

En cas de contradiction entre une note historique, un README local, un ancien plan de migration et cette constitution, la constitution et les contrats normatifs CURRENT priment.

1. CMonChoix est une plateforme, pas un plugin WordPress

CMonChoix est une plateforme indépendante d'ingestion, de normalisation, d'identification, de qualification, de projection et de distribution de données commerciales multi-marchands.

WordPress est uniquement un CMS, une couche SEO, un adaptateur de présentation publique et, lorsque nécessaire, une interface d'administration éditoriale.

La règle de dépendance est :

WordPress -> src/ : autorisé
src/ -> WordPress : interdit

La suppression complète de WordPress ne doit pas empêcher : ingestion, synchronisation marchands, normalisation, classification, identité produit, variantes, qualité, scoring, gestion des offres, prix, disponibilité, projections, indexation, workers, queues, audits, migrations métier et rebuilds.

2. src/ porte la plateforme indépendante

Toute responsabilité qui n'est pas intrinsèquement liée à WordPress appartient à la Platform et doit converger vers src/ dans la couche appropriée.

Le plugin plugins/ccx-feeds-industrial/ peut conserver temporairement des implémentations historiques pendant une migration certifiée. Cette présence est un état CURRENT ou TRANSITIONAL, jamais la cible architecturale.

3. Une vérité métier n'a qu'un propriétaire

Les données marchands sont des observations, pas la vérité canonique.

Une décision importante — identité, classification, qualité, score, variante, état d'offre ou projection — possède un propriétaire autoritatif unique. Les autres composants peuvent lire, transporter, mettre en cache ou afficher cette décision, mais ne doivent pas la recalculer silencieusement.

4. Les marchands sont isolés, le pipeline métier est commun

La plateforme doit pouvoir supporter plusieurs dizaines puis plusieurs centaines de marchands sans créer un moteur métier différent par marchand.

Chaque marchand peut posséder un adapter, une configuration, des credentials, un mapping de source et des capacités propres. Les données convergent ensuite vers un pipeline canonique commun.

Une panne, un feed invalide ou un traitement coûteux d'un marchand ne doit pas bloquer les autres marchands.

5. Les traitements de volume sont bornés, idempotents et rejouables

Les imports, synchronisations, projections et traitements asynchrones doivent être conçus pour être batchés, repris après échec, rejoués sans corruption et observés précisément.

Un job critique doit autant que possible être :

  • borné ;
  • idempotent ;
  • retryable ;
  • observable ;
  • checkpointable ;
  • rejouable.

Un unique processus monolithique non reprenable pour des millions de lignes n'est pas la cible industrielle.

6. L'incrémental est la voie normale, le rebuild complet reste la voie de récupération

Un changement de prix ou de stock ne doit pas provoquer par défaut la reconstruction de tout le catalogue.

Les refreshs ciblent les offres, identités, produits et projections réellement impactés. Les rebuilds complets restent disponibles comme mécanisme de convergence, certification et disaster recovery.

Le résultat d'un traitement incrémental doit rester équivalent au résultat canonique attendu après rebuild complet.

7. Les projections servent la lecture et restent reconstruisibles

Les calculs coûteux doivent être effectués lorsque les données changent, pas à chaque visite utilisateur.

Le Frontend consomme principalement des projections et read models préparés.

Une projection est une donnée dérivée. Elle ne devient jamais la source de vérité du Domain et doit pouvoir être reconstruite depuis un état amont certifié.

8. Les dépendances techniques sont remplaçables

Le Domain Core ne doit pas être réécrit pour :

  • remplacer WordPress ;
  • remplacer MariaDB ;
  • remplacer Redis ;
  • remplacer le moteur de recherche ;
  • déplacer des workers sur une autre machine ;
  • changer de transport HTTP, CLI ou queue.

Les technologies sont des adapters et des détails d'infrastructure autour de contrats stables.

9. Single-node aujourd'hui, distributed-ready demain

L'exploitation peut rester volontairement simple sur un VPS unique tant que les mesures le permettent.

L'architecture doit cependant permettre de déplacer ou multiplier séparément le Web, les workers, la base, Redis, la recherche et l'observabilité sans réécrire les règles métier.

La montée en charge doit principalement consister à ajouter ou déplacer des ressources, pas à refaire l'architecture applicative.

10. La persistance durable et les caches ont des rôles différents

Une donnée métier durable ne doit jamais exister uniquement dans un cache ou une queue éphémère.

Redis peut accélérer, coordonner et transporter du travail ; il ne remplace pas la source durable de vérité métier.

Une réplication n'est pas un backup. Les sauvegardes doivent être restaurables et une stratégie de reprise doit exister indépendamment de la disponibilité du VPS courant.

11. L'observabilité fait partie du produit

Un flux critique doit exposer assez d'information pour répondre à :

  • quel marchand ?
  • quel run ?
  • quel batch ?
  • quel job ?
  • combien d'éléments ?
  • combien de changements ?
  • combien d'erreurs ?
  • quel retard de projection ?
  • quelle raison de décision ?

Les métriques infrastructure, application et métier doivent rester distinguables.

12. L'exploitation est gouvernée par des objectifs mesurables

Disponibilité, latence, fraîcheur des offres, projection lag, débit de traitement, erreurs, sauvegardes et temps de reprise doivent progressivement être gouvernés par des SLO ou seuils explicites.

Une optimisation sans baseline ni mesure après changement n'est pas une certification de performance.

13. CURRENT, TARGET, TRANSITIONAL, HISTORICAL et DEPRECATED sont différents

La documentation ne doit jamais présenter une dette historique comme une architecture cible.

  • CURRENT décrit ce qui est réellement actif ;
  • TARGET décrit la destination ;
  • TRANSITIONAL décrit une compatibilité temporaire ;
  • HISTORICAL conserve le contexte ;
  • DEPRECATED indique qu'un élément ne doit plus recevoir de nouvelles responsabilités.

Toute exception à la cible doit être enregistrée dans la dette technique avec critères de sortie.

14. Les grandes décisions sont durables et vérifiables

Une décision qui modifie une frontière fondamentale doit être documentée par un ADR ou une évolution explicite des documents normatifs.

Une règle critique doit être protégée autant que possible par des tests d'architecture, tests de contrats, certifications runtime ou guards automatisés.

La connaissance orale ne constitue pas un garde-fou industriel.

15. Principe de transmission

Un nouveau mainteneur doit pouvoir comprendre la direction du projet sans connaître son historique.

Avant toute évolution importante, il doit pouvoir retrouver :

  1. la responsabilité propriétaire ;
  2. la source de vérité ;
  3. la frontière de dépendance ;
  4. l'état CURRENT et la cible TARGET ;
  5. les tests ou certifications ;
  6. le rollback ou mécanisme de récupération lorsqu'il existe.

Références normatives