Présentation du Pipeline¶

Le Pipeline est la chaîne qui transforme les données brutes des marchands en données suffisamment propres, structurées et traçables pour être utilisées par CMonChoix.

Statut¶

CURRENT — cette page décrit le fonctionnement actuellement visé et observé du Pipeline.

Pourquoi le Pipeline existe¶

Chaque marchand envoie ses données à sa manière : noms de colonnes différents, formats différents, catégories différentes, titres marketing, unités incohérentes, informations manquantes, etc.

Le Pipeline sert à absorber cette diversité sans laisser chaque partie du site réinterpréter les données marchandes de son côté.

En langage simple :

Donnée marchand brute
        ↓
On la lit
        ↓
On la met en forme commune
        ↓
On la normalise
        ↓
On la classe et l'enrichit
        ↓
On prépare les projections
        ↓
On contrôle le résultat

Le Pipeline ne constitue ni le Domain Core, ni le Runtime, ni le Frontend.

le Runtime décide quand et comment exécuter ;
le Pipeline réalise la transformation demandée ;
le Domain Core porte les décisions métier génériques ;
le Frontend affiche les projections préparées.

Exemple concret¶

Imaginons deux marchands qui décrivent le même téléphone :

Marchand A : "Samsung Galaxy S26 256GB Black"
Marchand B : "Galaxy S26 Noir - 256 Go"

Le Pipeline peut notamment :

lire les deux lignes ;
conserver leur origine ;
convertir 256GB et 256 Go vers une représentation commune ;
normaliser la marque et certains attributs ;
classer les lignes comme smartphones probables ;
préparer les données nécessaires au moteur d'identité et aux projections.

Il ne doit pas simplement décider « ces deux lignes sont le même produit » parce que leurs titres se ressemblent. Cette décision appartient à la frontière métier prévue pour l'identité.

Le chemin complet d'une ligne¶

Source marchand
      ↓
Acquisition
      ↓
Staging
      ↓
Mapping
      ↓
Normalisation
      ↓
Classification / enrichissement
      ↓
Projection
      ↓
Contrôles de qualité

1. Acquisition¶

Le feed est téléchargé ou localisé selon sa configuration.

À ce stade, il faut conserver suffisamment de contexte pour savoir :

de quel feed vient la donnée ;
quel marchand l'a fournie ;
à quel run elle appartient ;
quelle source physique a été utilisée ;
quand elle a été observée.

Sans cette traçabilité, il devient très difficile d'expliquer un problème plusieurs jours plus tard.

2. Staging¶

Le staging est une zone intermédiaire où les données reçues sont conservées avant leur transformation finale.

Il sert notamment à :

rejouer un traitement sans retélécharger le feed ;
reprendre une exécution interrompue ;
comparer plusieurs versions d'une règle ;
auditer ce qui a réellement été reçu.

Le staging n'est pas la vérité produit. C'est une photographie technique de données en cours de traitement.

3. Mapping¶

Le mapping convertit le schéma propre au marchand vers une structure intermédiaire commune.

Exemple :

merchant_product_name  → title
product_brand          → brand
product_url            → url

Les noms ci-dessus sont illustratifs. Le principe important est que les particularités du marchand restent confinées dans le mapping au lieu de se répandre dans toute la plateforme.

4. Normalisation¶

La normalisation harmonise les valeurs.

Elle peut par exemple uniformiser :

marques ;
modèles ;
unités ;
capacités ;
couleurs ;
catégories ;
URLs ;
médias ;
identifiants.

Normaliser n'est pas résoudre une identité.

Transformer 256GB en 256 Go est de la normalisation. Décider que deux offres représentent exactement le même produit est une décision métier différente.

Voir Normalisation.

5. Classification et enrichissement¶

La classification cherche à déterminer quelle famille de produit est concernée afin de charger les règles adaptées.

Par exemple, une ligne peut être reconnue comme smartphone, produit photo ou appareil électroménager.

Les règles spécialisées doivent être chargées uniquement quand elles sont utiles. Le Pipeline ne doit pas charger toutes les verticales pour chaque ligne.

Un enrichissement peut compléter une donnée lorsqu'il dispose de preuves suffisantes. Il ne doit pas transformer une hypothèse en certitude sans raison explicite.

6. Projection¶

Une projection est une représentation préparée pour un usage aval : catalogue, offre, produit, navigation, frontend, etc.

La construction de la projection et son écriture en base sont deux responsabilités distinctes.

Une projection correcte doit être autant que possible :

déterministe ;
idempotente ;
reconstruisible ;
traçable par run ;
compatible avec un traitement par lots.

7. Contrôles de qualité¶

Les contrôles de qualité servent à mesurer et expliquer le résultat du traitement.

Media Quality fonctionne en mode audit-first, c'est-à-dire qu'il observe avant de modifier :

il produit des constats ;
il explique les divergences ;
il expose des métriques ;
il ne supprime aucune image implicitement ;
une correction éventuelle utilise une action d'écriture séparée.

Voir Media Quality Engine.

Où se trouve l'implémentation actuelle¶

Le runtime WordPress actif s'appuie principalement sur :

plugins/ccx-feeds-industrial/

Points d'entrée structurants :

ccx-feeds.php : point d'entrée principal du plugin ;
includes/bootstrap/pipeline.php : bootstrap ciblé du Pipeline ;
includes/feeds-pipeline.php : agrégateur legacy chargé à la demande ;
includes/runtime/feed-reader.php : lecture et préparation des lignes ;
includes/application/sync-runner.php : orchestration des runs et batches ;
includes/mapping/row-to-item-core.php : façade historique de transformation d'une ligne vers un item ;
includes/pipeline/90-offers-norm.php : façade de l'orchestrateur de projection normalisée ;
includes/media-quality/engine.php : moteur Media Quality.

Certains de ces fichiers sont des façades de compatibilité et délèguent aujourd'hui vers des modules plus petits. Il faut donc suivre les require/compositions avant de conclure qu'un gros fichier contient encore toute l'implémentation.

Le Pipeline ne doit pas être chargé globalement dans tous les contextes WordPress. Il est activé seulement par les actions qui en ont besoin : worker, commande CLI ciblée, HTTP autorisé ou action admin explicite.

Runs et batches¶

Un run représente une exécution identifiable d'un traitement.

Un batch est une portion de ce run traitée séparément afin de ne pas devoir tout charger ou traiter d'un seul coup.

Une exécution doit disposer d'un run_id ou d'un identifiant équivalent.

Le traitement par batches doit permettre :

de connaître la progression ;
de reprendre après une interruption ;
d'annuler explicitement ;
de suivre les compteurs ;
de distinguer une erreur temporaire d'une erreur définitive.

Exemple¶

Si un feed possède 100 000 lignes, le système peut les traiter en lots successifs plutôt qu'en une seule opération énorme.

En cas de redémarrage après 40 000 lignes, il faut pouvoir reprendre proprement sans dupliquer les écritures déjà finalisées.

Ce que le Pipeline a le droit de faire¶

Il peut :

lire les données source et de staging ;
appliquer les mappings ;
normaliser les valeurs ;
exécuter les règles de classification ;
appeler les composants métier explicitement autorisés ;
préparer des projections ;
produire des métriques d'exécution.

Ce qu'il ne doit jamais faire¶

Il ne doit pas :

contenir de logique d'affichage ;
devenir propriétaire du scheduling ;
décider localement d'une identité hors des services prévus ;
masquer une ambiguïté avec une valeur arbitraire ;
charger toutes les verticales par défaut ;
déclencher une mutation destructive depuis un audit ;
écrire directement dans une surface Frontend/Admin pour contourner les frontières applicatives.

Comment savoir si un run s'est bien passé¶

Une exécution sérieuse doit produire des compteurs réconciliables.

Exemples :

lignes lues ;
lignes acceptées ;
lignes rejetées ;
lignes projetées ;
lignes ignorées ;
erreurs par code ;
verticales détectées ;
éléments audités ;
résultats par état ;
écritures demandées, appliquées ou refusées.

Pourquoi « réconciliable » ?¶

Si le feed contient 10 000 lignes, les compteurs doivent permettre d'expliquer ce qu'il est arrivé à ces 10 000 lignes.

Un total vague du type « 9 532 produits traités » n'est pas suffisant si personne ne sait ce qui est arrivé aux 468 autres.

Sécurité lors des comparaisons historiques¶

Un piège important existe lors des tests sur d'anciens runs : les données persistées peuvent avoir été modifiées par une ancienne implémentation.

Si l'on compare une nouvelle règle à un état historique déjà altéré, on ne mesure pas réellement la nouvelle règle.

Il peut donc être nécessaire de régénérer la projection avant comparaison.

Toujours vérifier l'état de la donnée de référence avant de tirer une conclusion à partir d'un ancien run.

Commandes opérateur¶

La forme canonique actuelle pour exécuter WP-CLI dans l'environnement Docker est :

docker compose exec -T platform-worker wp --allow-root --path=/var/www/html ...

Selon la commande et le contexte, certains anciens documents peuvent montrer une forme abrégée. Pour une procédure de production, suivre la documentation opérationnelle actuelle et vérifier la commande disponible avec wp help.

La simple présence d'un texte dans un dump CLI ne prouve pas qu'une commande est réellement disponible et correctement câblée.

Comment diagnostiquer un problème Pipeline¶

Si un produit ou une offre semble incorrect :

identifier le marchand et le feed ;
retrouver le run concerné ;
inspecter la donnée source ou de staging ;
vérifier le mapping ;
vérifier la normalisation ;
vérifier la classification/verticale choisie ;
vérifier les décisions métier ;
inspecter la projection produite ;
seulement ensuite regarder le Frontend.

Cette méthode évite de réparer l'affichage alors que l'erreur est née plusieurs étapes en amont.

Tests attendus¶

Le Pipeline doit être protégé par plusieurs familles de tests :

tests unitaires des normaliseurs et règles ;
tests de mapping par feed ;
tests d'idempotence ;
tests de reprise ;
tests de frontières architecturales ;
tests garantissant qu'un audit n'écrit pas ;
tests de réconciliation des métriques ;
tests d'intégration sur échantillons réels ;
tests de chargement ciblé par contexte WordPress.

Invariants à retenir¶

À entrée et configuration identiques, le résultat reste identique.
Une transformation doit pouvoir être expliquée depuis la source et le run.
Le Pipeline n'est chargé que lorsqu'il est nécessaire.
Les règles spécifiques aux feeds et verticales restent dans leurs composants dédiés.
Les adapters ne deviennent pas des moteurs métier ou des writers SQL cachés.
Les écritures persistantes passent par une frontière identifiable.
Un audit ne déclenche aucune mutation.
Media Quality ne vide jamais une image implicitement.
Un état historique altéré doit être régénéré avant comparaison fiable.
Les compteurs d'un run doivent expliquer son volume d'entrée.

Pour la personne qui reprend le projet¶

Les trois réflexes les plus importants sont :

retrouver la donnée le plus en amont possible avant de corriger ;
ne pas confondre normalisation et décision métier ;
ne jamais lancer une écriture pour comprendre ce qui se passe.

Si vous savez identifier à quelle étape une information devient incorrecte, vous avez déjà fait une grande partie du diagnostic.