Adapters¶

Status: CURRENT

Rôle¶

Les Adapters relient CMonChoix Platform aux technologies et surfaces d'exécution extérieures au cœur métier : WordPress, HTTP, CLI, workers, cron, importeurs ou autres interfaces.

Un Adapter traduit un contexte technique vers un contrat applicatif, puis traduit le résultat obtenu vers le format attendu par ce contexte.

Il ne décide pas de la vérité métier.

Monde extérieur
    ↓
Adapter
    ↓
Application / Read Service / Write Service
    ↓
Domain Core et services métier

Pourquoi cette couche existe¶

Sans séparation explicite, les détails techniques finissent facilement mélangés avec la logique métier : accès à $_GET, $wpdb, WP_CLI, headers HTTP, hooks WordPress, JSON, redirects ou cron.

Cette dépendance rend ensuite le système difficile à tester, à migrer et à comprendre.

La frontière Adapter permet au contraire de garder :

le Domain Core indépendant de WordPress, HTTP, SQL et CLI ;
les services applicatifs indépendants du transport ;
les Read Services et Write Services testables sans interface utilisateur ;
les technologies remplaçables sans réécrire les règles métier.

Ce qu'un Adapter fait¶

Selon son contexte, un Adapter peut :

lire et valider des paramètres techniques ;
vérifier une authentification, une capability ou un nonce ;
convertir des valeurs de transport vers des Value Objects ou DTO attendus ;
appeler un Read Service, un Write Service ou une façade applicative ;
traduire le résultat en HTML, JSON, code de sortie CLI, redirect ou statut HTTP ;
enregistrer des routes, hooks ou commandes propres au runtime concerné.

Ce qu'un Adapter ne doit jamais faire¶

Un Adapter ne doit jamais :

résoudre une Canonical Identity ;
choisir un candidat du Resolver ;
recalculer une règle de scoring ;
reconstruire une règle de Vertical Module ;
inventer une valeur métier manquante ;
masquer unknown, ambiguous ou conflict ;
écrire directement en base lorsqu'un Write Service ou une infrastructure dédiée existe ;
devenir la source canonique d'une projection ;
mélanger lecture read-only et mutation implicite ;
dupliquer une logique déjà portée par l'Application ou le Domain Core.

Familles d'Adapters dans CMonChoix¶

WordPress¶

WordPress est actuellement un runtime et une surface d'intégration majeure. Il expose notamment :

le Frontend public ;
l'administration ;
HTTP ;
WP-CLI ;
worker et cron ;
certains bootstraps techniques.

La page WordPress Adapter décrit cette frontière plus précisément.

CLI¶

Une commande CLI doit rester un adapter mince :

arguments CLI
    ↓
validation
    ↓
service applicatif
    ↓
résultat structuré
    ↓
texte / JSON / exit code

La présence d'une commande ne prouve pas qu'elle est read-only : son service délégué doit être inspecté.

HTTP¶

Un Adapter HTTP porte le transport :

route ;
authentification ;
validation ;
mapping ;
statut HTTP ;
sérialisation JSON.

Il ne porte ni SQL métier ni décision de domaine.

Worker / Cron¶

Un Adapter worker ou cron déclenche une orchestration explicite dans un contexte adapté.

Il ne doit pas charger inutilement Frontend ou Admin et ne doit pas déclencher le Pipeline par simple bootstrap passif.

Adapter, Application et Infrastructure : ne pas les confondre¶

Ces trois couches ont des responsabilités différentes.

Couche	Question principale
Adapter	Comment le monde extérieur appelle-t-il la Platform ?
Application	Dans quel ordre les capacités sont-elles orchestrées ?
Infrastructure	Comment un détail technique est-il réellement exécuté ?

Exemple :

WP-CLI
  ↓ Adapter
commande + arguments
  ↓ Application
façade / service
  ↓ Infrastructure
SQL, filesystem, lock ou état technique si nécessaire

Le Domain Core reste en dehors de ces détails.

Adapter et Read Service¶

Un Adapter de lecture peut exposer un Read Service, mais il ne doit pas absorber son calcul.

HTTP / CLI / Admin
        ↓
Adapter
        ↓
Read Service
        ↓
Projection / résultat d'audit

Si le callback HTTP ou CLI contient les règles de rapprochement, de scoring ou de comparaison, la frontière est cassée.

Adapter et Write Service¶

Une mutation doit être encore plus explicite :

requête technique
    ↓
Adapter
    ↓
validation de transport
    ↓
Write Service / façade d'action
    ↓
persistance contrôlée

L'Adapter ne doit pas appeler directement un writer SQL legacy lorsqu'un service d'écriture dédié existe.

Bootstrap technique¶

Un bootstrap sélectionne et charge les dépendances adaptées au contexte.

Il ne doit pas :

exécuter une migration par simple chargement ;
déclencher un Pipeline sans action explicite ;
écrire dans les données métier ;
devenir un second orchestrateur applicatif.

Le principe est : charger le minimum nécessaire au contexte courant.

Comment diagnostiquer un problème d'Adapter¶

Lorsqu'un comportement diffère entre Frontend, Admin, HTTP, CLI ou Worker, vérifier dans cet ordre :

le bon Adapter est-il chargé pour ce contexte ?
les paramètres techniques sont-ils correctement validés et mappés ?
l'Adapter appelle-t-il le bon Read Service, Write Service ou service applicatif ?
le résultat métier est-il correct avant sa traduction transport ?
l'erreur vient-elle du formatage, du code HTTP, du renderer ou de la sortie CLI ?
une logique métier a-t-elle été dupliquée dans l'Adapter ?
un bootstrap charge-t-il trop de dépendances ou déclenche-t-il un effet de bord ?

Cette séquence évite de modifier le Domain Core pour un problème qui appartient uniquement à une interface.

Erreurs fréquentes¶

Corriger le Frontend alors que la projection est fausse¶

Le renderer doit afficher ce qu'il reçoit. Si le payload est incorrect, il faut remonter vers le Reader, la Projection ou le Domain Core selon l'origine du problème.

Ajouter du SQL dans un callback¶

Un accès SQL dans un Adapter crée rapidement une seconde source de comportement difficile à auditer.

Considérer WordPress comme le Domain¶

WordPress doit rester remplaçable. Les règles métier ne doivent donc pas dépendre de ses hooks, globals ou tables par défaut.

Confondre bootstrap et action¶

Charger un fichier ne doit pas suffire à écrire ou migrer des données.

Vérification après modification¶

Après une évolution d'Adapter, vérifier au minimum :

que les tests du service applicatif restent indépendants du transport ;
que le contexte concerné charge uniquement les dépendances attendues ;
que les autres contextes ne chargent pas cet Adapter par accident ;
qu'aucun nouvel accès SQL ou write direct n'est introduit ;
que les sorties transport restent compatibles ;
que unknown, ambiguous et conflict restent visibles lorsqu'ils font partie du contrat lu.

Invariants¶

Un Adapter traduit ; il ne décide pas de la vérité métier.
Les globals et détails de transport restent confinés aux Adapters.
Le Domain Core ne dépend d'aucun Adapter.
Les services applicatifs restent transport-neutral.
Les écritures passent par une frontière explicite.
Un bootstrap ne déclenche pas de mutation implicite.
Chaque contexte charge le minimum nécessaire.
Le Frontend consomme des projections et ne reconstruit pas la logique métier.