Merchant Synchronization Playbook

Status: CURRENT + TARGET / OPERATIONS

Objet

Cette page définit la stratégie de synchronisation multi-marchands et distingue explicitement le mécanisme CURRENT du Runtime cible.

L'objectif industriel est de supporter plusieurs dizaines puis plusieurs centaines de marchands, avec plusieurs refreshs quotidiens, sans dupliquer le pipeline ni rendre WordPress propriétaire de l'exécution.

Principes invariants

1. Un marchand possède une source/configuration/adapter, pas son propre moteur métier.
2. Les données convergent vers un pipeline canonique commun.
3. Une panne d'un marchand ne bloque pas les autres.
4. Les traitements volumineux sont batchés et reprenables.
5. Les mutations sont idempotentes ou protégées contre la double application.
6. Les refreshs ciblent le périmètre réellement affecté lorsque cela est sûr.
7. Le full reconciliation/rebuild reste disponible pour recovery et certification.
8. Aucun scheduler ne contient mapping, classification, SQL métier ou credentials.

Modèle logique cible

Merchant scheduler
      ↓
FeedRun
      ↓
Download / source read
      ↓
Batches
      ↓
Canonical ingestion
      ↓
Normalization
      ↓
Classification / Identity / Quality si nécessaire
      ↓
Persistence
      ↓
Scoped projection refresh
      ↓
Cache/search invalidation ciblée

Isolation

Chaque run doit pouvoir être rattaché au minimum à :

• merchant_id ;
• feed_id ;
• feed_run_id ;
• batch_id lorsque le run est découpé ;
• job_id lorsqu'une queue est utilisée.

Un run Acer en erreur ne doit pas empêcher Samsung, Darty ou un autre marchand d'être traité.

Les limites de concurrence doivent empêcher un feed extrêmement volumineux de monopoliser toutes les ressources.

Fréquence par type de donnée

La fréquence ne doit pas être pensée comme « rebuild complet X fois par jour ».

La cible est de distinguer :

Donnée / traitement	Stratégie
prix	refresh fréquent et ciblé
disponibilité / stock	refresh fréquent et ciblé
nouvelles offres	plusieurs fois par jour selon source
changement produit	traitement des produits impactés
classification	uniquement si les preuves concernées changent
identity resolution	uniquement pour périmètre affecté
projections	scoped refresh rapide après mutation
full reconciliation	périodique / recovery
gros audits qualité	périodes creuses ou jobs dédiés

La fréquence exacte est un paramètre de capacité mesuré, pas une constante architecturale.

Batches

Un feed de plusieurs millions de lignes ne doit pas être un unique job monolithique.

Exemple :

FeedRun #92837
  batch 0001 : 1 - 5 000
  batch 0002 : 5 001 - 10 000
  ...

La taille optimale des batches est mesurée selon mémoire, débit DB, coût de normalisation et temps de reprise.

Idempotence et reprise

Après un crash, la plateforme doit savoir :

• ce qui a déjà été appliqué ;
• ce qui reste pending ;
• ce qui peut être rejoué ;
• ce qui a définitivement échoué ;
• quelles projections restent à rafraîchir.

Un retry ne doit pas dupliquer une offre ni annuler une mutation déjà commitée.

Les impacts de projection post-commit doivent rester rejouables indépendamment de la mutation source.

Refresh incrémental

Le modèle cible est :

changed offers
   ↓
affected identities
   ↓
affected canonical products
   ↓
affected read projections

Le scoped canonical refresh actuellement certifié sur la branche constitue une étape importante de cette direction.

Le full rebuild doit rester disponible pour vérifier :

incremental final state == full rebuild final state

CURRENT — scheduling via WP-CLI

Le Runtime courant peut encore utiliser systemd + le conteneur worker + WP-CLI :

systemd timer
    ↓
merchant service
    ↓
docker exec ccx-platform-worker
    ↓
wp ccx sync start --feed=<merchant>
    ↓
CCX Sync Runner

Ce mécanisme est CURRENT / TRANSITIONAL.

Il est autorisé pour exploiter le système aujourd'hui, mais il ne signifie pas que WordPress possède le moteur de synchronisation. Les responsabilités métier appelées par cette entrée doivent progressivement converger vers src/.

La cible est qu'un worker Platform puisse lancer le même use case sans charger WordPress. WP-CLI pourra alors rester un adapter opérateur facultatif.

Commande CURRENT

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync start --feed=<merchant>

Les services planifiés ne doivent pas utiliser --force par défaut.

Avant de modifier ces commandes, vérifier la documentation CLI CURRENT et le Runtime réellement déployé.

Scheduling

Les schedules marchands doivent être décalés ou pilotés par une politique de concurrence afin d'éviter des pics simultanés inutiles.

Les unités systemd ne doivent contenir que l'intention d'exécution et les paramètres non secrets nécessaires.

Interdit dans un scheduler :

• URL avec credentials ;
• téléchargement métier direct ;
• SQL ;
• mapping ;
• classification ;
• logique verticale ;
• refresh de projection implémenté localement.

Préconditions d'activation d'un marchand

Avant une première planification :

1. source/configuration définie hors secrets Git ;
2. adapter/mapping certifié ;
3. fixtures représentatives ;
4. run manuel contrôlé ;
5. volume attendu documenté ;
6. erreurs/skips compris ;
7. identité/classification observées ;
8. projections cohérentes ;
9. comportement retry/replay compris ;
10. isolation par rapport aux autres marchands vérifiée ;
11. monitoring et health lisibles ;
12. rollback de l'activation connu.

Validation CURRENT

Selon les commandes disponibles dans la révision :

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync status --feed=<merchant> --limit=1

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync doctor --feed=<merchant>

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx health projections

Ces commandes sont des adapters opérationnels CURRENT. Elles ne constituent pas la cible de dépendance du Core.

Métriques marchands

L'exploitation doit progressivement exposer par marchand :

last_success
feed_age
run_duration
source_rows
processed_rows
changed_offers
rejected_offers
error_count
identity_unknown/conflict
classification_unknown/review
projection_lag
queue_pending
retry_count

Un dashboard doit permettre de repérer rapidement un marchand en dérive sans lire les logs de tous les autres.

Fairness et backpressure

À mesure que le nombre de marchands augmente, le Runtime doit gérer explicitement :

• concurrence globale ;
• concurrence par marchand ;
• priorité ;
• taille de batch ;
• retries avec backoff ;
• backlog ;
• capacité DB ;
• backpressure lorsque les consommateurs n'absorbent plus le débit.

Ajouter plus de workers n'est pas une solution correcte si MariaDB ou l'I/O est déjà le goulot.

Full reconciliation

Un traitement complet peut être programmé moins fréquemment pour :

• détecter une disparition d'offre ;
• réconcilier un état incrémental ;
• vérifier les invariants ;
• rebuild les projections ;
• certifier la convergence.

Ce mécanisme de sécurité complète l'incrémental ; il ne doit pas redevenir le chemin normal de chaque petite mise à jour.

Sécurité

Les credentials et URLs sensibles ne sont jamais commités dans Git ni copiés dans la documentation.

Les commandes opérateur, logs et métriques doivent éviter de révéler des secrets.

Checklist

[ ] marchand identifié et configuré
[ ] secrets hors Git
[ ] adapter source isolé
[ ] pas de logique merchant dispersée dans le Core
[ ] fixture/contract tests disponibles
[ ] run manuel validé
[ ] batch/retry/replay compris
[ ] projection health validée
[ ] métriques du marchand lisibles
[ ] schedule ne contient aucune logique métier
[ ] concurrence avec les autres marchands maîtrisée
[ ] rollback connu
[ ] documentation CURRENT/TARGET cohérente

Voir aussi

• Vision
• Roadmap
• Frontière WordPress
• Performance
• Migration