Platform Core Contract V1¶

Status: CONTRACT

À quoi sert ce contrat ?¶

Le Platform Core Contract V1 fixe les frontières entre les grandes couches de CMonChoix. Son but est d'empêcher qu'une responsabilité métier soit déplacée par facilité dans WordPress, SQL, un script CLI ou un composant d'infrastructure.

La règle à retenir est simple :

La Platform orchestre. Le Domain décide.

Autrement dit, le Domain Core porte les règles métier génériques et les décisions qui doivent rester vraies quel que soit le mode d'exécution. La Platform organise l'utilisation de ces règles sans les remplacer.

Pourquoi cette frontière existe-t-elle ?¶

CMonChoix peut être exécuté depuis plusieurs contextes : Runtime, worker, CLI, tâches planifiées, API ou WordPress. Sans frontière explicite, la même règle métier pourrait être recopiée dans plusieurs de ces contextes et finir par produire des résultats différents.

Ce contrat sert donc à garantir que :

la logique métier reste testable sans WordPress ni base de données ;
les technologies peuvent évoluer sans redéfinir le métier ;
un mainteneur sait dans quelle couche intervenir ;
une orchestration ne devient pas accidentellement une seconde source de vérité métier ;
les dépendances restent orientées vers les contrats et le Domain, pas vers les détails techniques.

Position des couches¶

Runtimes externes / entrypoints
        ↓
Application Engine / orchestration
        ↓
Domain Core + Vertical Modules
        ↓
Contracts / ports
        ↓
Adapters
        ↓
Infrastructure / technologies concrètes

Ce schéma décrit des responsabilités, pas nécessairement l'organisation physique définitive de tous les fichiers PHP actuels.

Domain Core¶

Le Domain Core contient les concepts et règles métier génériques : identité canonique, candidats, résolution, conflits, invariants, etc.

Il ne doit connaître ni WordPress, ni SQL, ni HTTP, ni Docker.

Vertical Modules¶

Les Vertical Modules complètent le Domain Core avec les règles propres à une famille de produits. Le Core peut dépendre d'un contrat générique exposé par une verticale, mais il ne doit pas dépendre d'une verticale concrète.

Application Engine¶

L'Application Engine orchestre un cas d'usage : il prépare les entrées, appelle les composants métier appropriés, coordonne les services et collecte les résultats.

Il ne doit pas inventer une règle métier qui appartient au Domain.

Adapters¶

Les Adapters traduisent entre le modèle de CMonChoix et une technologie ou un système externe. Un adapter peut par exemple convertir une ligne SQL, une réponse HTTP ou une structure WordPress vers un contrat compris par la Platform.

Infrastructure¶

L'Infrastructure contient les détails techniques nécessaires à l'exécution : stockage, réseau, filesystem, services externes, configuration d'environnement, etc.

Elle exécute les choix techniques ; elle ne définit pas la vérité métier.

Runtime et WordPress¶

Le Runtime orchestre l'exécution concrète. WordPress est considéré comme un adapter ou un runtime externe selon le contexte.

Ils peuvent déclencher un cas d'usage et fournir des dépendances techniques, mais ils ne doivent pas devenir l'endroit où une décision métier canonique est définie.

Règles absolues¶

Domain ne dépend jamais de WordPress.
Domain ne dépend jamais de SQL.
Domain ne dépend jamais de HTTP.
Domain ne dépend jamais de Redis, Docker ou filesystem.
Application orchestre uniquement.
Adapters traduisent les technologies.
Infrastructure exécute les détails techniques.
WordPress est un adapter/runtime externe.
Les contrats et la documentation d'architecture définissent les frontières à respecter.

Ces règles sont des garde-fous de conception. Si une modification semble nécessiter de les contourner, il faut d'abord vérifier si le code est placé dans la bonne couche.

Exemple de mauvais placement¶

Supposons qu'une commande CLI doive résoudre l'identité d'un produit.

Mauvaise approche :

CLI
  -> requête SQL
  -> comparaison de chaînes
  -> décision resolved/conflict
  -> écriture

La CLI devient alors une seconde implémentation du métier.

Approche conforme :

CLI
  -> Application Engine
  -> données préparées via Adapter/Repository
  -> Resolver du Domain
  -> décision explicite
  -> Write Service éventuel

La CLI reste un point d'entrée. La décision reste dans la couche métier prévue pour cela.

Namespace canonique actuel¶

Le namespace canonique actuellement chargé pour la Platform est :

CMonChoix\Platform\

Il pointe vers :

src/

Un namespace tel que CMonChoix\Domain, CMonChoix\Application ou CMonChoix\Infrastructure ne doit pas être considéré comme actif simplement parce qu'il paraît plus conforme à l'architecture cible. Il reste legacy ou expérimental tant que le chargement Composer et l'implémentation courante ne prouvent pas le contraire.

Cette distinction est importante pendant la migration : l'architecture logique peut être plus avancée que l'organisation physique du code.

Décision de migration — Phase 1¶

La Phase 1 interdit un déplacement PHP massif uniquement pour faire correspondre les répertoires à l'architecture cible.

La stratégie est :

stabiliser les contrats et les responsabilités ;
vérifier les dépendances réelles ;
migrer progressivement les composants ;
conserver les tests et les entrypoints fonctionnels à chaque étape.

Un renommage de namespace ou un déplacement de fichiers n'est donc pas, à lui seul, une amélioration architecturale.

Comment intervenir sans risque¶

Avant de modifier un composant :

identifier s'il prend une décision métier, orchestre un cas d'usage ou traduit une technologie ;
vérifier ses dépendances réelles et ses appelants ;
rechercher si un contrat ou un service existe déjà pour cette responsabilité ;
éviter d'ajouter une dépendance WordPress/SQL/HTTP dans le Domain ;
tester le comportement depuis le contexte le plus indépendant possible ;
vérifier ensuite l'intégration dans le Runtime ou l'entrypoint concerné.

Une intervention qui ajoute une écriture doit en plus respecter la frontière des Write Services et les garde-fous audit-first.

Signaux d'alerte pendant un diagnostic¶

Un mainteneur doit se méfier lorsqu'il rencontre :

une décision resolved, unknown, ambiguous ou conflict calculée directement dans un controller ou une commande ;
une requête SQL au milieu d'un objet de Domain ;
un appel WordPress nécessaire pour exécuter un test métier ;
une règle verticale codée directement dans le Core générique ;
une écriture déclenchée implicitement par un composant présenté comme read-only ;
deux implémentations différentes d'une même décision selon le Runtime utilisé.

Ces symptômes indiquent généralement une frontière contournée ou une dette de migration à isoler.

Invariants de transmission¶

Le Domain décide ; la Platform orchestre.
Les technologies concrètes restent derrière des contrats ou des Adapters.
Le Runtime ne devient jamais une source de vérité métier.
WordPress reste extérieur au Domain Core.
Une architecture cible ne doit pas être confondue avec un namespace réellement chargé.
Les migrations structurelles se font progressivement et avec vérification.
Toute écriture métier passe par une frontière explicite de Write Service.