Stage¶
Status: CURRENT
Vue d'ensemble¶
Le Stage est la zone de réception technique des données marchandes avant leur projection vers le modèle normalisé.
Il conserve une représentation fidèle et traçable de ce qui a été importé afin de permettre :
- l'audit ;
- la reprise ;
- la comparaison entre brut et normalisé ;
- le diagnostic d'une anomalie ;
- le rejeu contrôlé d'un traitement.
Le Stage n'est ni une vérité métier, ni une projection catalogue.
Position dans le Pipeline¶
Source marchande
↓
Acquisition / téléchargement
↓
Lecture du feed
↓
Stage
↓
Normalisation
↓
Enrichissement
↓
Projection des offres normalisées
Dans le plugin WordPress, la lecture des feeds et l'orchestration des runs alimentent la table de staging avant la projection vers ccx_offers_norm_v2.
Modèle opérationnel¶
Le Stage doit conserver au minimum les éléments permettant d'identifier :
- le run ;
- le feed ;
- le marchand ;
- le lot ou batch ;
- la position ou l'offset de lecture ;
- la ligne reçue ;
- son empreinte technique ;
- les métadonnées nécessaires au diagnostic.
La table de staging actuelle est préfixée par WordPress et correspond au modèle ccx_sync_stage_raw_v2.
Le préfixe réel dépend de l'installation. La documentation ne doit donc jamais supposer littéralement wp_ dans les requêtes ou procédures d'exploitation.
Responsabilités¶
Le Stage est responsable de :
- recevoir les lignes lues depuis la source ;
- préserver leur provenance ;
- conserver les valeurs nécessaires au mapping ;
- rendre les lots reprenables et auditables ;
- isoler les erreurs d'acquisition des erreurs de normalisation ;
- fournir une base stable aux projections suivantes.
Il peut contenir des champs techniques préparés par le lecteur, à condition que cette préparation soit structurelle et non métier.
Exemples autorisés :
- décodage du CSV ;
- association colonne → valeur ;
- nettoyage technique d'encodage ;
- métadonnées de ligne ;
- empreinte du payload.
Frontière stricte¶
Le Stage ne doit jamais :
- résoudre une identité produit ;
- choisir une verticale métier finale ;
- calculer un score de qualité ;
- enrichir une couleur, une capacité ou un modèle ;
- choisir une image principale ;
- construire une projection catalogue ;
- corriger silencieusement une donnée marchande ;
- masquer une valeur source invalide.
Toute interprétation métier appartient aux étapes suivantes.
Fidélité des données¶
Le Stage doit distinguer clairement :
valeur reçue
≠
valeur techniquement décodée
≠
valeur normalisée
≠
valeur enrichie
Une transformation technique nécessaire à la lecture ne doit jamais être présentée comme une décision métier.
Lorsqu'une valeur est invalide ou illisible, l'état doit rester explicite plutôt que d'être remplacé par une valeur supposée correcte.
Traçabilité¶
Chaque offre normalisée doit pouvoir être reliée à son origine par un ensemble stable d'identifiants techniques.
Selon le flux concerné, cette chaîne peut inclure :
run_id
→ feed_id / source_feed
→ batch / offset
→ ligne de Stage
→ raw_hash
→ offre normalisée
Cette traçabilité permet de distinguer :
- une anomalie du feed ;
- une erreur du lecteur ;
- une erreur de mapping ;
- une erreur de normalisation ;
- une erreur d'enrichissement ;
- une erreur de projection.
Reprise et idempotence¶
Le Stage participe à la reprise des synchronisations.
Les traitements doivent éviter de créer plusieurs états incohérents pour une même ligne lorsqu'un batch est rejoué.
Les mécanismes d'idempotence peuvent reposer notamment sur :
- le run ;
- la source ;
- l'offset ;
- une clé d'offre ;
- une empreinte brute.
Le choix précis appartient à l'implémentation, mais le résultat doit rester observable et déterministe.
Un rejeu ne doit pas être confondu avec l'exécution d'un ancien run dont les projections ont déjà été mutées. Avant tout audit historique, l'état nécessaire doit être régénéré ou sa validité démontrée.
Relation avec les audits¶
Les Read Services peuvent comparer :
- le Stage ;
- les offres normalisées ;
- les projections produit ;
- les résultats de qualité ;
- les métriques d'un run.
Un audit du Stage reste strictement read-only.
Il peut produire des compteurs, des échantillons et des regroupements d'erreurs, mais il ne doit ni corriger les lignes ni déclencher de projection.
Observabilité¶
Les métriques utiles incluent notamment :
- lignes reçues ;
- lignes décodées ;
- lignes rejetées ;
- lignes écrites au Stage ;
- doublons techniques ;
- batches terminés ;
- offsets repris ;
- erreurs par feed ;
- durée de lecture et d'écriture.
Les compteurs doivent être réconciliables.
Exemple :
lignes reçues
=
lignes écrites au Stage
+ lignes rejetées explicitement
+ doublons explicitement comptés
Sécurité opérationnelle¶
Avant toute intervention manuelle :
- identifier le run et le feed ;
- vérifier si le traitement est actif, terminé, annulé ou reprenable ;
- vérifier les offsets et batches ;
- éviter toute suppression globale sans périmètre ;
- conserver les preuves nécessaires à l'audit ;
- utiliser les services et commandes prévus plutôt qu'une écriture SQL improvisée.
Le Stage ne doit pas être nettoyé uniquement pour améliorer artificiellement des KPI.
Tests attendus¶
Les tests doivent couvrir au minimum :
- la conservation de la provenance ;
- la stabilité des identifiants techniques ;
- le comportement sur ligne invalide ;
- l'absence de logique métier ;
- le rejeu idempotent ;
- la reprise par batch ou offset ;
- la réconciliation des compteurs ;
- l'absence d'écriture lors des audits.
Invariants¶
Fidélité¶
Le Stage préserve ce qui a réellement été reçu.
Traçabilité¶
Toute projection doit pouvoir être reliée à son origine.
Neutralité métier¶
Le Stage ne résout, n'enrichit et ne score rien.
Rejouabilité¶
Les données conservées permettent d'expliquer ou de rejouer un traitement contrôlé.
Idempotence¶
La reprise ne doit pas produire de doublons ou d'états contradictoires.
Observabilité¶
Chaque perte, rejet ou déduplication reste explicitement compté.