Présentation du Pipeline¶

Status: CURRENT

Rôle¶

Le Pipeline transforme les données marchandes hétérogènes en représentations cohérentes, traçables et persistables.

Il ne constitue ni le Domain Core, ni le Runtime, ni le Frontend.

Sa responsabilité est limitée à l'exécution ordonnée des étapes de traitement nécessaires pour produire des offres normalisées et préparer les projections consommées par la Platform.

Source marchand
      ↓
Téléchargement / localisation
      ↓
Lecture et staging
      ↓
Mapping
      ↓
Normalisation
      ↓
Classification / enrichissement ciblé
      ↓
Projection des offres
      ↓
Contrôles de qualité

Implémentation actuelle¶

Le runtime WordPress actuellement actif s'appuie principalement sur :

plugins/ccx-feeds-industrial/

Points d'entrée structurants :

ccx-feeds.php : point d'entrée du plugin ;
includes/bootstrap/pipeline.php : chargement 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 : transformation ligne source vers item normalisé ;
includes/pipeline/90-offers-norm.php : persistance dans la projection normalisée ;
includes/media-quality/engine.php : moteur Media Quality audit-first.

Le Pipeline ne doit pas être chargé globalement dans tous les contextes WordPress. Son bootstrap est déclenché uniquement par les actions qui en ont besoin : worker, HTTP autorisé, commandes CLI ciblées ou actions admin explicites.

Frontières¶

Le Pipeline peut¶

lire les données source et de staging ;
appliquer les mappings de feed ;
normaliser les valeurs ;
exécuter les règles de classification ;
appeler des composants métier ou verticaux explicitement autorisés ;
produire des résultats de projection ;
exposer des métriques détaillées d'exécution.

Le Pipeline ne doit pas¶

contenir de logique d'affichage ;
écrire directement dans des surfaces Frontend ou Admin ;
décider de l'identité produit hors des services prévus à cet effet ;
masquer une ambiguïté par une valeur arbitraire ;
charger toutes les verticales et toutes les familles legacy par défaut ;
exécuter une mutation destructive depuis un audit ;
devenir propriétaire du scheduling ou du transport.

Le Runtime décide quand exécuter. Le Pipeline définit et exécute la transformation demandée.

Étapes opérationnelles¶

1. Acquisition¶

Le flux est téléchargé ou localisé à partir de la configuration du feed.

L'acquisition doit conserver suffisamment de contexte pour identifier :

le feed ;
le marchand ;
le run ;
la source physique ;
la date d'observation.

2. Staging¶

Les lignes sont conservées dans une représentation rejouable avant la projection finale.

Le staging sert notamment à :

reprendre un traitement ;
auditer les données reçues ;
comparer plusieurs versions d'une règle ;
éviter de dépendre à nouveau de la source distante.

Le staging n'est pas une vérité produit canonique.

3. Mapping¶

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

Les règles spécifiques à une source restent confinées dans les composants de mapping et ne doivent pas contaminer les règles génériques de normalisation.

4. Normalisation¶

La normalisation harmonise les valeurs sans résoudre l'identité produit.

Elle couvre notamment :

les identifiants ;
les marques ;
les modèles ;
les capacités et unités ;
les catégories ;
les couleurs ;
les URLs et médias ;
les attributs utilisés par les verticales.

Le contrat détaillé est documenté dans normalisation.md.

5. Classification et enrichissement¶

La classification sélectionne une verticale ou un type probable à partir des données disponibles.

Les règles verticales doivent être chargées de manière ciblée. Une détection légère ne doit pas entraîner le chargement systématique de tous les modules métier.

Un enrichissement ne doit jamais effacer la valeur source ni transformer une hypothèse en fait certain sans niveau de confiance et raisons explicites.

6. Projection¶

La projection convertit le résultat du traitement en état persisté exploitable par les lecteurs et services aval.

La frontière d'écriture doit passer par les services de projection certifiés lorsque ceux-ci existent. Les adapters et orchestrateurs ne doivent pas appeler directement des writers legacy dispersés.

La projection doit être :

déterministe ;
idempotente ;
reconstruisible ;
traçable par run ;
compatible avec une reprise par batch.

7. Qualité¶

Les contrôles de qualité produisent des observations et métriques sur les résultats.

Media Quality fonctionne en mode audit-first :

l'évaluation produit des évidences ;
les divergences sont comptabilisées et expliquées ;
aucune image n'est effacée implicitement ;
toute mutation éventuelle doit être une action distincte, explicitement activée et suffisamment confiante.

La documentation canonique est ../architecture/media-quality-engine.md.

Runs, batches et reprise¶

Une exécution doit être identifiable par un run_id ou identifiant équivalent.

Le traitement par batches doit permettre :

la progression par offset ou curseur ;
la reprise d'un run interrompu ;
l'annulation explicite ;
le suivi des compteurs ;
la distinction entre erreur transitoire et erreur définitive.

Une reprise ne doit pas dupliquer les projections déjà finalisées ni produire un état différent à entrée inchangée.

Observabilité¶

Chaque étape importante doit exposer des métriques 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 matched, mismatched, unknown ou ambiguous ;
mutations demandées, appliquées ou refusées.

Les totaux doivent pouvoir être rapprochés du nombre de lignes entrantes. Une métrique globale sans ventilation exploitable n'est pas suffisante pour certifier un run.

Sécurité opérationnelle¶

Avant toute validation d'une nouvelle règle sur un run historique, il faut vérifier que les données projetées n'ont pas été modifiées par une ancienne implémentation destructive.

Lorsqu'un run historique a déjà perdu des valeurs, la projection doit être régénérée avant comparaison. Sinon, les métriques mesurent un état altéré et non le comportement réel de la nouvelle implémentation.

Les commandes opérateur sont exécutées avec la forme canonique :

docker compose exec platform-worker wp ...

La présence d'une commande WP-CLI doit être vérifiée avec wp help ou en analysant réellement le JSON produit par wp cli cmd-dump --format=json. Un simple grep sur le dump brut n'est pas une preuve fiable.

Tests attendus¶

Le Pipeline doit être couvert 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 entre adapters, application et infrastructure ;
tests de non-mutation pour les audits ;
tests de réconciliation des métriques ;
tests d'intégration sur échantillons réels ;
tests de chargement ciblé par contexte WordPress.

Invariants¶

Une même entrée et une même configuration produisent le même résultat.
Chaque transformation reste explicable à partir de la source, du run et des règles appliquées.
Le Pipeline n'est chargé que lorsqu'une action en a réellement besoin.
Les règles spécifiques aux feeds et verticales restent confinées dans leurs composants dédiés.
Les adapters ne contiennent ni SQL métier ni orchestration profonde.
Les écritures persistantes sont explicites et passent par une frontière d'écriture identifiable.
Un audit ne déclenche aucune mutation.
Media Quality ne vide jamais image_norm implicitement.
Une projection historique altérée est régénérée avant toute comparaison fiable.
Les compteurs d'un run sont réconciliables avec son volume d'entrée.