CLI — Vue d'ensemble¶

Statut¶

Source canonique pour les principes d'architecture et d'exploitation de la couche WP-CLI de CMonChoix Platform.

Rôle¶

La CLI est l'interface opérateur de la Platform.

Elle expose des opérations reproductibles pour :

auditer l'état du système ;
inspecter les runs et leurs métriques ;
lancer ou reprendre des traitements ;
reconstruire des projections ;
simuler des changements ;
produire des rapports de validation ;
exécuter des opérations techniques explicitement documentées.

La CLI orchestre. Elle ne porte ni la vérité métier, ni les règles de normalisation, ni les accès SQL métier.

Opérateur
   ↓
WP-CLI adapter
   ↓
Application facade / use case
   ↓
Domain, Read Service ou Write Service
   ↓
Infrastructure

Commande d'exécution canonique¶

Depuis la racine du dépôt sur le VPS :

docker compose exec platform-worker wp --allow-root --path=/var/www/html <commande>

Exemple :

docker compose exec platform-worker wp --allow-root --path=/var/www/html ccx sync status

L'utilisation de docker exec avec un nom de conteneur figé n'est pas la convention canonique du dépôt. Docker Compose doit résoudre le service platform-worker.

Frontière d'architecture¶

Une commande CLI saine reste un adapter mince. Elle est limitée à :

lire et valider les arguments ;
vérifier les préconditions opérateur ;
charger seulement les capacités nécessaires ;
déléguer à une façade applicative ;
traduire le résultat en sortie console et code de retour.

Elle ne doit pas contenir :

de SQL direct ;
de calcul métier ;
de normalisation locale ;
de résolution d'identité ;
de règles Media Quality ;
de rendu HTML ou de dépendance au frontend ;
de lecture directe de paramètres HTTP ;
de chargement global du Pipeline sans nécessité.

Chargement ciblé¶

Le contexte WP-CLI est léger par défaut.

ccx-feeds.php
   ↓
bootstrap/platform.php
   ↓
bootstrap/plugin.php
   ↓
bootstrap/cli.php
   ↓
runtime-cli.php

Le Pipeline, le mapping, la qualité, les verticales et les capacités de schéma sont chargés à la demande par la commande qui en a réellement besoin.

Une commande de lecture simple ne doit pas charger le Pipeline complet.

Classification des commandes¶

Toute commande doit annoncer son niveau d'effet.

Lecture seule¶

Elle observe l'état existant sans écriture persistante.

Exemples de familles :

statut d'un run ;
santé du runtime ;
lecture de métriques ;
diagnostics ;
rapports d'audit.

Simulation¶

Elle calcule un résultat sans l'appliquer.

Une simulation peut utiliser des tables temporaires ou préparer un plan, mais tout effet technique doit être documenté. Le terme dry-run ne garantit pas automatiquement l'absence totale d'écriture technique.

Écriture explicite¶

Elle modifie un état persistant, reconstruit une projection, reprend un run ou applique une décision.

Ces commandes doivent rendre visibles :

la cible ;
la portée ;
les préconditions ;
les compteurs ;
le résultat final ;
les erreurs partielles ;
le moyen de reprise ou de vérification.

Destructif ou sensible¶

Une opération irréversible, coûteuse ou susceptible d'affecter le catalogue doit exiger une intention explicite et disposer d'une procédure de validation ou de rollback lorsque cela est possible.

Famille `ccx sync`¶

La famille ccx sync est séparée en lectures et actions applicatives.

CLI adapter
   ├── cli-sync-runtime-read.php
   └── cli-sync-runtime-actions.php
             ↓
       sync-runtime-actions.php

Les commandes de statut, santé, snapshots et lots lents délèguent à la façade de lecture.

Les commandes de démarrage, reprise, annulation, tick, maintenance et profilage délèguent à la façade d'actions. L'adapter ne doit pas appeler directement le runner ou un writer legacy.

Projection et reconstruction¶

Une commande de reconstruction ne doit pas écrire directement dans les tables de projection.

Elle délègue aux services de write ou à l'orchestrateur documenté. Pour la famille Product Models, l'ordre canonique est :

Product Models
   ↓
Variants
   ↓
Specifications
   ↓
Gallery

Une reconstruction doit être déterministe et relançable.

Media Quality¶

Media Quality fonctionne en mode audit-first.

Une commande d'audit doit :

analyser les évidences disponibles ;
produire les diagnostics et compteurs ;
distinguer matched, mismatched, unknown_actual et ambiguous ;
ne jamais effacer une image uniquement parce qu'un mismatch est détecté ;
ne proposer une mutation que lorsqu'une politique distincte et un niveau de confiance suffisant l'autorisent.

Audit, décision de mutation et écriture sont trois responsabilités séparées.

Sorties et codes de retour¶

La sortie doit être exploitable par un humain et, lorsque la commande le permet, par un script.

Une commande doit privilégier :

des compteurs nommés et stables ;
un résumé final non ambigu ;
des identifiants de run ou de cible ;
des messages d'erreur actionnables ;
un code de sortie non nul en cas d'échec opérationnel.

La présence d'une commande ne doit pas être vérifiée avec un simple grep sur la sortie brute de wp cli cmd-dump --format=json. Cette commande renvoie un arbre JSON unique. Utiliser un parseur JSON ou wp help <commande>.

Exemples :

docker compose exec platform-worker wp --allow-root --path=/var/www/html help ccx

docker compose exec platform-worker wp --allow-root --path=/var/www/html cli cmd-dump --format=json | jq '.. | objects | select(.name? == "sync")'

Sécurité opérationnelle¶

Avant une commande d'écriture :

confirmer le bon environnement ;
confirmer la cible et le run ;
vérifier que la projection source est à jour ;
capturer l'état initial et les métriques ;
éviter deux exécutions concurrentes sur la même cible ;
prévoir la vérification post-exécution.

Une métrique obtenue sur une projection historiquement altérée n'est pas une preuve fiable du comportement actuel. La projection doit être régénérée avant comparaison.

Observabilité minimale¶

Une commande opératoire doit, selon son rôle, exposer :

run_id ;
cible ou feed ;
volume lu ;
volume traité ;
volume ignoré ;
volume écrit ;
erreurs ;
durée ;
statut final ;
raisons principales de décision.

Les métriques doivent rester comparables entre deux exécutions équivalentes.

Tests attendus¶

La couche CLI doit être protégée par :

des tests d'enregistrement des commandes ;
des tests de parsing et validation ;
des tests de délégation vers les façades ;
des tests de codes de sortie ;
des tests d'absence de SQL et de logique métier dans les adapters ;
des tests de bootstrap garantissant le chargement ciblé ;
des tests de non-régression pour les opérations sensibles.

Invariants¶

La CLI est un adapter, jamais un moteur métier.
Une commande de lecture simple ne charge pas le Pipeline complet.
Toute écriture est explicite dans le nom, l'aide ou le workflow documenté.
Les writers et orchestrateurs dédiés sont les seuls propriétaires des écritures de projection.
Un audit Media Quality n'efface pas d'image.
Les sorties et codes de retour sont déterministes pour un même état d'entrée.
Toute commande opératoire produit assez d'informations pour être auditée et rejouée.
Le contexte CLI ne dépend ni du frontend ni des transports HTTP/Admin.