Principes de design¶

Status: TARGET / GOVERNANCE

Cette page décrit les règles à respecter lorsqu’on conçoit ou fait évoluer un composant de CMonChoix Platform.

Elle ne décrit pas automatiquement l’état du Runtime actuel. Lorsqu’une règle de cette page n’est pas encore réalisée dans le code, elle reste une cible d’architecture et ne doit pas être présentée comme une capacité CURRENT.

Principe central¶

Le design précède une modification structurante du code.

Avant de créer, déplacer ou réécrire une responsabilité durable, il faut pouvoir répondre clairement à quatre questions :

quelle responsabilité change ?
quelle couche doit la porter ?
quelles dépendances sont autorisées ?
comment prouver que le comportement attendu reste correct ?

Une migration de fichiers sans réponse à ces questions n’est pas une amélioration architecturale.

Hiérarchie de décision¶

La hiérarchie utile est :

Architecture et invariants
        ↓
Contracts
        ↓
Design cible
        ↓
ADR si décision durable
        ↓
Plan de migration
        ↓
Code
        ↓
Validation et documentation

Cette hiérarchie n’impose pas qu’un document soit créé pour chaque petite correction. Elle rappelle surtout qu’un changement de frontière ne doit pas être décidé implicitement au milieu d’un refactoring.

Distinguer CURRENT et TARGET¶

Un futur mainteneur doit toujours séparer :

CURRENT : comportement réellement vérifié dans la révision déployée ou inspectée ;
TARGET : architecture souhaitée ou contrat à atteindre ;
CONTRACT : règle stable que les implémentations doivent respecter ;
HISTORICAL : ancienne décision, certification ou étape de migration conservée pour contexte.

Une page de design peut donc être juste sans être encore implémentée.

Frontières fondamentales¶

Le design cible conserve les frontières suivantes :

le Domain Core porte la logique métier générique ;
les Vertical Modules portent la connaissance propre aux familles de produits ;
les Read Services observent sans mutation persistante ;
les Write Services portent les mutations explicites ;
le Runtime orchestre, mais ne décide pas de la vérité métier ;
les Adapters isolent WordPress, CLI, HTTP, SQL et autres transports ;
le Frontend consomme des projections et ne reconstruit pas la vérité métier ;
une Projection est dérivée et reconstructible, jamais la source de vérité métier.

Toute proposition qui brouille ces frontières doit être justifiée explicitement ou rejetée.

Une seule source d’autorité par décision¶

Une responsabilité critique ne doit pas posséder plusieurs implémentations concurrentes présentées comme canoniques.

Exemples :

l’architecture publique de navigation CURRENT est déclarée dans plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php ;
l’activation des feeds dépend de la configuration Runtime et de ccx_feed_runtime_active_feeds() ;
la présence d’une donnée persistée ou d’une entrée de registre ne suffit pas à lui donner autorité métier.

Lorsqu’une ancienne source est conservée pour compatibilité, elle doit être clairement identifiée comme telle.

Déterminisme et explicabilité¶

À entrées, configuration et version de règles identiques, un composant métier doit produire le même résultat.

Les décisions importantes doivent pouvoir être expliquées par :

les preuves utilisées ;
les règles appliquées ;
les reason codes ou diagnostics pertinents ;
les statuts resolved, unknown, ambiguous ou conflict lorsqu’ils s’appliquent.

Une heuristique qui améliore un KPI mais masque l’incertitude est un mauvais design.

Lecture avant mutation¶

Une évolution sur les données doit privilégier la séquence :

Observation
→ Audit
→ Simulation
→ Validation
→ Write Service explicite
→ Persistance
→ Vérification

Un dry-run ou une commande nommée audit ne prouve pas à lui seul l’absence d’effet technique. Les effets réels doivent être vérifiés dans l’implémentation.

Migration par petites étapes¶

Une architecture cible ne justifie pas un déplacement massif immédiat.

Une migration saine :

protège d’abord le comportement actuel par des tests ou des audits ;
introduit les nouveaux Contracts ou frontières sans casser les consommateurs ;
conserve temporairement les wrappers de compatibilité lorsque nécessaire ;
déplace une responsabilité à la fois ;
vérifie après chaque étape ;
retire les compatibilités seulement lorsqu’elles ne sont plus nécessaires.

Critères d’un bon composant¶

Un composant bien conçu possède :

une responsabilité courte à expliquer ;
des entrées et sorties explicites ;
des dépendances orientées dans le bon sens ;
une stratégie d’erreur et d’incertitude ;
des tests ou audits adaptés au risque ;
une documentation indiquant où observer, diagnostiquer et intervenir ;
aucune écriture implicite cachée dans une couche de lecture.

Questions avant intervention¶

Avant une évolution structurante, vérifier :

Quel document ou fichier fait autorité aujourd’hui ?
Le comportement observé est-il CURRENT, TARGET ou historique ?
Quelle couche possède réellement la décision ?
Le changement touche-t-il une source de vérité ou seulement une projection ?
Peut-on mesurer le résultat sans écrire ?
Quelle vérification prouvera que l’intervention est correcte ?
Comment revenir en arrière si la mutation échoue ?