Adapter WordPress¶

Status: CURRENT

Cette page décrit la frontière WordPress Adapter actuellement visée et consolidée dans CMonChoix Platform.

WordPress expose les capacités de la Platform au monde extérieur, mais ne porte jamais la vérité métier. Il reste une couche d’intégration remplaçable autour de la Platform.

Pourquoi cette frontière existe¶

Sans frontière claire, un plugin WordPress peut facilement accumuler :

SQL métier ;
règles de résolution ;
logique de projection ;
orchestration Runtime ;
effets de bord pendant le chargement ;
dépendances croisées entre frontend, admin, CLI et worker.

C’est précisément ce que l’architecture actuelle cherche à éviter.

La règle générale est :

WordPress Adapter
    ↓ traduit
Application / Read Services / Write Services
    ↓ délèguent
Domain Core / Infrastructure / Runtime

WordPress traduit un contexte technique WordPress vers un contrat applicatif. Il ne décide pas du résultat métier.

Packaging de la Platform¶

Le plugin ne contient pas une copie de la Platform.

Topologie de référence :

plugins/ccx-feeds-industrial/
        ↓
bootstrap Platform
        ↓
/opt/cmonchoix-platform/vendor/autoload.php
        ↓
/opt/cmonchoix-platform/src

Conséquences :

ne pas charger les classes CMonChoix\Platform une par une avec des require_once ;
ne pas recopier src/ dans le plugin WordPress ;
ne pas créer une seconde source de vérité de classes sous wordpress/ ;
conserver les fallback legacy uniquement lorsqu’ils sont explicitement documentés comme compatibilité transitoire.

Point d’entrée et bootstraps¶

Le point d’entrée du plugin reste volontairement mince :

ccx-feeds.php
  -> bootstrap/platform.php
  -> bootstrap/plugin.php

Puis bootstrap/plugin.php sélectionne les bootstraps adaptés au contexte :

bootstrap/plugin.php
  -> bootstrap/route-maintenance.php
  -> bootstrap/worker.php
  -> bootstrap/http.php
  -> bootstrap/admin.php
  -> bootstrap/cli.php
  -> bootstrap/frontend.php

Bootstraps runtime spécialisés :

bootstrap/admin.php  -> bootstrap/runtime-admin.php
bootstrap/http.php   -> interfaces/http/bootstrap.php
                      -> bootstrap/runtime-http.php
bootstrap/cli.php    -> bootstrap/runtime-cli.php
bootstrap/worker.php -> bootstrap/runtime.php

Le principe important n’est pas le nom exact du fichier, mais le chargement minimal par contexte.

Un frontend public ne doit pas charger inutilement l’admin, la CLI ou le Pipeline. Une page admin read-only ne doit pas charger tout le Runtime. Un simple bootstrap CLI ne doit pas déclencher une opération métier.

Matrice des contextes¶

Contexte	Responsabilité principale	Pipeline
frontend public	routing, canonical, rendu à partir de lectures	non
admin read-only	vues et façades read-only	non
admin action	validation + délégation vers action explicite	ciblé si nécessaire
HTTP health	auth + façade health	non
HTTP worker autorisé	transport HTTP vers action worker	ciblé
CLI simple	parsing, validation, output	non
CLI sync/taxonomy	délégation vers façades applicatives	ciblé selon commande
worker / cron	exécution runtime	oui si nécessaire

Cette matrice sert de garde-fou : lorsqu’un composant charge plus que son contexte ne nécessite, il faut vérifier qu’une frontière n’a pas été contournée.

Frontend public¶

Le frontend WordPress public peut :

enregistrer routes et query vars ;
résoudre redirect, canonical et template ;
appeler un Read Service ou un Reader ;
rendre HTML et SEO à partir de projections ;
adapter un payload historique si un shim de compatibilité est encore nécessaire.

Il ne doit jamais :

écrire pendant une requête publique ;
recalculer une identité ;
choisir une offre métier ;
reconstruire une projection ;
requêter directement les feeds bruts ;
effectuer un flush_rewrite_rules() en plein trafic public ;
transformer un renderer en service métier.

Le frontend reste projection-first.

Product Canonical et lectures publiques¶

La lecture Product Canonical suit la séparation :

CanonicalProductReadService
        ↓
CanonicalProductProjectionReader
        ↓
SqlCanonicalProductProjectionReader

Le SQL et les détails de persistance appartiennent au reader/adapteur SQL. Les helpers et renderers WordPress ne doivent pas accéder directement à $wpdb pour reconstruire cette logique.

Admin¶

Un adapter admin WordPress doit rester limité à :

l’enregistrement des hooks ;
les vérifications de capability ;
la validation nonce ;
la lecture et la normalisation des inputs ;
la délégation vers une façade ou un service ;
les redirects et notices ;
le rendu HTML.

Pour la page Sync Runtime, la séparation actuelle est :

interfaces/admin/sync-runtime.php
        ↓
application/admin-sync-runtime-read.php
application/admin-sync-runtime-actions.php
        ↓
interfaces/admin/sync-runtime-view.php

La vue ne porte ni SQL, ni runner, ni Pipeline, ni décision métier.

HTTP¶

Un adapter HTTP s’occupe de :

détecter la route ;
authentifier ;
valider la requête ;
mapper les paramètres ;
déléguer ;
traduire le résultat en JSON et statut HTTP.

Il ne doit pas appeler directement les mécanismes internes de queue, de rebuild ou de health lorsque des façades applicatives existent.

Endpoint Health¶

Pour ?ccx_health=1, la frontière documentée est :

includes/ccx-health.php
  -> détection + validation + mapping + réponse

includes/application/http-health.php
  -> rate-limit technique
  -> lecture du contexte health
  -> décision OK / WARNING / CRITICAL

Le transient ccx_health_lock_v5_<md5(feed:limit)> et sa fenêtre de 10 secondes font partie du comportement technique historique documenté.

CLI WordPress¶

La CLI WordPress est un Adapter.

Elle peut gérer :

parsing des arguments ;
validation ;
format JSON ou humain ;
exit codes ;
délégation vers les services applicatifs.

Elle ne doit pas contenir :

SQL métier inline ;
orchestration Runtime construite directement dans les callbacks ;
logique de résolution ;
logique de projection ;
logique de migration non encapsulée.

Pour ccx sync, les lectures passent par includes/application/cli-sync-runtime-read.php et les actions par les façades d’actions Sync.

Pour ccx taxonomy-v2, includes/interfaces/cli/taxonomy-v2.php doit rester un adapter de transport, tandis que includes/application/taxonomy-v2-actions.php porte l’orchestration.

Attention : `audit` et `dry-run` ne signifient pas toujours read-only¶

Dans Taxonomy V2, certaines commandes nommées audit ou dry-run peuvent installer un schéma ou créer des tables temporaires via l’infrastructure.

Il ne faut donc jamais déduire l’absence d’écriture du seul nom de la commande.

Toujours vérifier le code réel et les effets techniques.

Worker et Cron¶

Les workers et le cron déclenchent le Runtime, mais ils restent des Adapters techniques.

Ils ne doivent pas :

réimplémenter les règles Domain Core ;
recalculer la vérité métier hors services dédiés ;
charger les interfaces admin ou CLI ;
charger le Pipeline lors d’un cron passif ou d’une queue vide sans raison explicite.

Le Pipeline n’est chargé qu’après preuve d’une action réelle ou d’un run reprenable.

Écritures techniques WordPress¶

Certaines écritures WordPress restent nécessaires, par exemple :

options techniques ;
transients ;
named locks ;
maintenance de rewrites ;
schéma et migrations techniques.

Ces écritures ne doivent pas être dispersées dans les consumers.

La frontière consolidée fait passer ces accès par des services techniques ou l’infrastructure, notamment :

includes/infrastructure/technical-state.php ;
CCX_CronScheduleService ;
CCX_RewriteMaintenanceService ;
CCX_SchemaInstallService ;
CCX_MigrationRunner ;
CCX_TemporarySchemaService.

Un renderer, un callback HTTP ou une vue admin ne doit pas contenir directement ces effets de bord.

Isolation des contextes¶

Les dépendances transport doivent rester confinées :

$_GET, $_POST, $_REQUEST, $_SERVER dans les adapters HTTP/admin ;
WP_CLI dans les adapters CLI ;
headers, redirects et réponses JSON dans HTTP/admin ;
HTML dans les renderers/vues ;
worker/cron séparé du frontend, de l’admin et de la CLI.

Les services partagés doivent rester transport-neutral.

Un fichier applicatif qui commence à produire une réponse HTTP, un notice admin ou du HTML est probablement au mauvais niveau.

Ce que WordPress ne doit jamais devenir¶

WordPress ne doit jamais devenir :

la source de vérité métier ;
le propriétaire du Resolver ;
le propriétaire des projections ;
un second Domain Core ;
un second Runtime ;
une copie locale de src/ ;
un endroit où l’on ajoute du SQL métier “parce que c’est plus pratique”.

Comment diagnostiquer un problème WordPress¶

Avant de modifier le code, identifier le niveau réel du problème.

1. Problème d’affichage¶

Vérifier :

projection reçue ;
mapper/shim ;
renderer ;
template ;
CSS/JS.

Ne pas modifier le Domain Core si la projection est correcte.

2. Donnée incorrecte mais projection correcte par rapport à sa source¶

Remonter vers :

Read Service ;
Builder ;
Domain Core ;
Vertical Module ;
Pipeline.

Ne pas corriger le renderer.

3. Contexte WordPress trop lourd¶

Inspecter les bootstraps réellement chargés.

Chercher notamment :

Pipeline chargé sur frontend public ;
admin chargé en CLI ;
Runtime générique chargé pour un simple read ;
dépendances croisées entre adapters.

4. Effet de bord inattendu¶

Chercher :

update_option() ;
set_transient() ;
accès $wpdb ;
GET_LOCK / RELEASE_LOCK ;
installation de schéma ;
tables temporaires ;
flush rewrite ;
appel à un Write Service.

Puis vérifier si cet effet appartient bien au contexte courant.

Erreurs fréquentes¶

Ajouter une règle métier dans un hook WordPress¶

Mauvais niveau. La règle appartient au Domain Core, à un Vertical Module ou à l’Application selon sa nature.

Charger tout le Runtime “pour être sûr”¶

Cela masque les dépendances réelles et augmente les risques d’effets de bord.

Ajouter du SQL dans un renderer¶

Le renderer doit consommer un modèle de lecture, pas reconstruire une projection.

Confondre compatibilité legacy et architecture cible¶

Un wrapper historique peut rester nécessaire sans devenir la nouvelle référence architecturale.

Déduire qu’une commande est read-only à partir de son nom¶

Toujours vérifier l’implémentation réelle.

Vérification après modification¶

Après une évolution de la frontière WordPress :

vérifier le contexte concerné uniquement ;
confirmer qu’aucune dépendance supplémentaire n’est chargée inutilement ;
vérifier l’absence de SQL ou d’écriture au mauvais niveau ;
tester frontend, admin, CLI, HTTP ou worker selon le périmètre ;
contrôler les projections et résultats applicatifs indépendamment du transport ;
exécuter les tests et audits de non-régression concernés.

Une modification WordPress correcte ne doit pas changer la vérité métier si elle ne concerne que l’Adapter.

Historique de certification¶

Les identifiants BC-061*, BC-062*, BC-063*, BC-064* et BC-068D correspondent à des étapes historiques de consolidation de cette frontière.

Ils restent utiles pour retrouver l’origine d’une décision, mais ils ne doivent plus structurer la lecture principale de cette page.

La règle de transmission est de retenir l’état consolidé ci-dessus, puis de consulter l’historique uniquement lorsqu’une investigation exige de comprendre l’évolution de la frontière.

Invariants¶

WordPress est un Adapter remplaçable.
Le plugin ne contient pas une copie de la Platform.
Les bootstraps chargent seulement les capacités nécessaires au contexte.
Les adapters traduisent ; ils ne portent pas la vérité métier.
Le frontend public reste projection-first et sans écriture persistante.
Les interfaces admin, HTTP et CLI restent minces.
Les effets techniques sont isolés derrière services ou infrastructure explicites.
Les contextes frontend, admin, CLI, HTTP et worker restent isolés.
Aucun renderer ne contient SQL, orchestration Runtime ou règles Domain Core.
Une capacité nommée audit ou dry-run n’est considérée read-only qu’après vérification réelle.