Vue d'ensemble du Runtime¶

Le Runtime est la couche qui fait exécuter CMonChoix : elle lance les traitements, organise les contextes, reprend les tâches interrompues et expose leur état. Elle n'invente pas les règles métier.

Statut¶

CURRENT — cette page décrit l'architecture Runtime actuellement attendue.

À quoi sert le Runtime ?¶

Le Runtime répond surtout à cette question :

Quand, où et dans quel contexte faut-il exécuter une capacité de la plateforme ?

Il orchestre les composants existants sans devenir propriétaire de leur logique.

Entrée externe
    ↓
Adapter
    ↓
Runtime
    ↓
Application / Pipeline / Projection
    ↓
Persistance + observabilité

Par exemple, le Runtime peut décider qu'un worker doit reprendre une synchronisation interrompue. Il ne doit pas décider lui-même comment reconnaître un smartphone ou résoudre une identité produit.

Les mots importants¶

Adapter¶

Un Adapter est une couche mince qui traduit un contexte extérieur vers les appels attendus par la plateforme.

Exemples :

une commande WP-CLI ;
une requête HTTP ;
une page d'administration ;
un worker ;
le frontend.

Un Adapter valide et transmet. Il ne doit pas contenir le cœur d'un traitement métier.

Worker¶

Un worker est un processus chargé d'exécuter des tâches techniques ou métier en arrière-plan, sans interaction directe d'un utilisateur.

Cron¶

Un cron est une planification automatique. Il permet de déclencher régulièrement une vérification ou un traitement.

Bootstrap¶

Un bootstrap est le code qui charge les composants nécessaires pour un contexte donné.

L'objectif est de ne pas charger toute la plateforme à chaque requête WordPress.

Pourquoi le chargement minimal est important¶

WordPress peut répondre à beaucoup de contextes différents : page publique, administration, WP-CLI, worker, endpoint HTTP, cron, etc.

Une page publique n'a aucune raison de charger tout le Pipeline, les règles de mapping, les verticales et les outils de qualité.

Charger uniquement ce qui est nécessaire :

réduit le coût d'exécution ;
limite les effets de bord ;
rend les dépendances plus faciles à comprendre ;
évite qu'un contexte ait accès à des capacités dont il n'a pas besoin.

Graphe de bootstrap WordPress¶

Le chargement courant suit cette structure :

ccx-feeds.php
    ↓
includes/bootstrap/platform.php
    ↓
includes/bootstrap/plugin.php
    ├── route-maintenance.php
    ├── worker.php
    ├── http.php
    ├── admin.php
    ├── cli.php
    └── frontend.php

Chaque contexte charge ensuite un runtime minimal adapté :

runtime.php pour worker et cron ;
runtime-http.php pour HTTP authentifié ;
runtime-admin.php pour l'administration ;
runtime-cli.php pour WP-CLI.

Les composants lourds comme Pipeline, Mapping, Quality ou les verticales sont chargés seulement quand l'action en a besoin.

Matrice de chargement¶

Contexte	Pipeline	Mapping	Quality	Frontend	Worker	Admin
frontend public	non	non	non	oui	non	non
admin lecture seule	non	non	non	non	non	oui
action admin	ciblé	selon action	selon action	non	non	oui
HTTP health / interdit	non	non	non	non	non	non
HTTP worker autorisé	oui	via Pipeline	selon besoin	non	non	non
CLI simple	non	non	non	non	non	non
CLI sync / taxonomy	ciblé	selon action	selon action	non	non	non
worker / cron	selon job	via Pipeline	selon job	non	oui	non

Cette matrice est une règle d'architecture. Un chargement plus large doit répondre à un besoin réel et documenté.

Ce dont le Runtime est responsable¶

Le Runtime peut :

créer ou reprendre une synchronisation ;
lancer les étapes nécessaires ;
gérer les batches et offsets ;
transmettre les paramètres d'exécution ;
gérer des verrous et reprises ;
enregistrer le succès ou l'échec technique ;
fournir les compteurs et informations de progression ;
déclencher les services applicatifs prévus.

Ce qu'il ne doit jamais faire¶

Il ne doit pas :

normaliser directement une ligne marchand ;
résoudre une identité produit ;
choisir un candidat métier ;
inventer une règle de qualité ;
modifier la vérité du Product Domain ;
construire lui-même une vue catalogue ;
faire dépendre les services partagés du HTML, de headers HTTP ou de WP_CLI.

Si une règle métier apparaît dans un fichier Runtime, c'est un signal d'alerte.

Exemple : exécution d'une synchronisation¶

Le cycle général ressemble à ceci :

Créer / reprendre le run
        ↓
Acquérir le feed
        ↓
Stage
        ↓
Normalisation / classification / qualité
        ↓
Projection des offres
        ↓
Contrôles après projection
        ↓
Finaliser le run

Le Runtime coordonne cette chaîne, mais chaque étape reste réalisée par le composant qui en est propriétaire.

Runs, batches, offsets et reprise¶

Run¶

Un run est une exécution identifiable, par exemple une synchronisation d'un feed marchand.

Batch¶

Un batch est une portion du run.

Offset¶

Un offset est une position de progression permettant de savoir jusqu'où le traitement est arrivé.

Pourquoi c'est important¶

Une synchronisation importante peut durer longtemps. Si le processus s'arrête, il faut pouvoir reprendre depuis un état persistant cohérent au lieu de recommencer arbitrairement.

Le Runtime doit donc s'appuyer sur l'état stocké du run, pas uniquement sur ce que le processus PHP actuel garde en mémoire.

Worker et cron¶

Le worker est le contexte destiné aux jobs automatiques et reprenables.

Les règles importantes sont :

cron_schedules et ccx_runtime_tick sont enregistrés dans includes/runtime/queue-runner.php ;
un cron passif ne charge pas inutilement le Pipeline ;
le Pipeline est chargé uniquement lorsqu'un job réellement exécutable ou reprenable existe ;
le worker ne contient aucun rendu utilisateur.

Signal d'alerte¶

Si une simple visite du frontend commence à charger des modules worker ou Pipeline lourds, il faut vérifier le bootstrap.

Runtime CLI¶

WP-CLI utilise le bootstrap CLI puis runtime-cli.php.

Une commande CLI doit rester mince :

Arguments utilisateur
       ↓
Validation
       ↓
Appel d'une façade / service
       ↓
Résultat
       ↓
Affichage CLI

Elle ne doit pas contenir directement une grosse logique SQL, une normalisation complète ou une migration implicite.

Pour les commandes réelles disponibles et leur invocation, consulter la documentation CLI et vérifier avec wp help.

Projection et Media Quality¶

Le Runtime peut déclencher une projection ou un audit Media Quality, mais ne porte pas leurs règles.

Runtime
   ↓
Service applicatif
   ↓
Projection Writer
   ↓
Offers Norm
   ↓
Audit Media Quality

Media Quality reste audit-first. Le Runtime ne doit jamais transformer un audit en mutation destructive implicite.

Observabilité¶

Une exécution importante doit permettre de savoir :

quel run est concerné ;
quand il a commencé et terminé ;
quel est son état ;
combien de lignes ont été lues, traitées, rejetées et projetées ;
quelles erreurs techniques ont eu lieu ;
quelles métriques métier sont nécessaires au diagnostic ;
comment reprendre le traitement en sécurité.

Les logs sont utiles, mais ils ne remplacent pas l'état persistant du run.

Pourquoi ?¶

Un log peut disparaître, être tronqué ou devenir difficile à rechercher. L'état persistant doit rester la référence permettant de savoir où en est réellement l'exécution.

Isolation et idempotence¶

Une erreur sur un feed ne doit pas corrompre les autres runs.

Une opération reprenable doit être idempotente ou protégée par une clé stable.

En pratique, relancer un batch déjà validé ne doit pas :

créer des doublons ;
appliquer deux fois une mutation destructive ;
faire progresser les compteurs de manière incohérente.

Comment diagnostiquer un problème Runtime¶

Si une synchronisation ne part pas, reste bloquée ou s'arrête :

identifier le run ;
vérifier son état persistant ;
déterminer quel contexte devait l'exécuter : worker, cron, CLI, HTTP ou admin ;
vérifier le bootstrap du contexte ;
vérifier les verrous et la progression batch/offset ;
vérifier les erreurs techniques ;
seulement ensuite analyser le composant métier appelé par le Runtime.

À ne pas faire¶

Ne pas commencer par modifier une règle de normalisation si le vrai problème est simplement que le worker ne lance pas le job.

Tests attendus¶

Les tests d'architecture doivent notamment protéger :

l'absence d'inclusion sauvage entre Adapters ;
l'absence de dépendance transport dans les services partagés ;
le chargement ciblé du Pipeline ;
la matrice de bootstrap ;
l'absence de création de schéma dans un chemin lecture seule ;
l'idempotence des opérations reprenables ;
le caractère non destructif des audits.

Invariants à retenir¶

Les Adapters restent minces et isolés.
Chaque contexte ne charge que ce dont il a besoin.
Le Runtime orchestre ; il ne décide pas la vérité métier.
Toute exécution importante reste identifiable et mesurable.
Un run interrompu peut reprendre depuis un état persistant cohérent.
Une commande de lecture ou un audit ne modifie jamais silencieusement les données.

Pour la personne qui reprend le projet¶

Lorsque quelque chose « ne s'exécute pas », séparez toujours deux questions :

Le Runtime a-t-il correctement lancé le traitement ?
Le traitement lancé a-t-il produit le bon résultat métier ?

Ce sont deux problèmes différents.

Cette distinction évite énormément de fausses pistes : un mauvais résultat produit par une règle métier n'est pas un bug Runtime, et un job qui ne démarre pas n'est pas forcément un bug du Pipeline.