Vue d'ensemble

Cette section documente le système stock & réapprovisionnement fournisseur de la plateforme : un ledger de stock signé qui dit la vérité physique, un moteur de réappro événementiel qui régénère les commandes fournisseur à chaque changement de demande, et un pipeline email en trois temps (stage → review → send) garantissant que ce que l'opérateur relit est exactement ce qui part. Cette page est la carte : les acteurs, le flux de bout en bout, le modèle de données, et où trouver le détail de chaque sous-système.

Les acteurs

La carte du système

Le flux nominal, de la commande boutique jusqu'à l'écriture ledger à la réception :

flowchart TB
  PS["Commande client<br/>(boutique PrestaShop)"]
  PS -->|webhook temps réel| WH["/api/webhooks/prestashop"]
  PS -->|"sync de rattrapage (3 h)"| SYNC["Cron order-sync"]
  WH --> ORD[("Order local")]
  SYNC --> ORD
  BO["Back office marchand"] -->|création / modif / annulation| ORD
  ORD -->|producteurs d'événements| Q{{"File bext<br/>supplier-orders-recalc"}}
  Q -->|sous write-lock| RECALC["recalculateVendorOrdersUnified"]
  RECALC --> SO["Brouillons de commandes<br/>fournisseur (DRAFT)"]
  SO -->|"stage 06:00 (render-only)"| MAIL["File email — review opérateur"]
  MAIL -->|envoi validé| VEND["Fournisseurs (×159)"]
  VEND -->|livraison| RCPT["Réception confirmée"]
  RCPT -->|"StockAction COMPLETED (+)"| LEDGER[("Product.stockLedger")]
  BO -->|"scellé livraison client (−)"| LEDGER

À lire de haut en bas :

1. Entrée de la demande — une commande client arrive deux fois : en temps réel par webhook, et par le cron de sync toutes les 3 h qui rattrape ce que le webhook aurait manqué (les deux chemins convergent sur le même Order local, idempotent).
2. Réappro événementiel — chaque création/modification/annulation/changement de statut de commande client (plus : annulation d'un bon fournisseur, réception, webhook produit) pousse un message dans la file bext supplier-orders-recalc. Le worker recalcule les brouillons du vendor concerné sous le write-lock fournisseur, ce qui le sérialise avec le cron de réappro. Détail : Commandes fournisseur.
3. Email en trois temps — le cron de 06:00 rend l'email de chaque brouillon (render-only, rien ne part), l'opérateur relit et ajuste dans la file de review, puis l'envoi re-rend depuis les items courants et bloque si les quantités ont dérivé depuis le stage. Review == sent.
4. Le stock ne bouge qu'au mouvement physique — la livraison client décrémente, la réception fournisseur incrémente. La sync de commandes ne touche jamais le stock (ce chemin a été supprimé le 2026-06-14). Détail : Chemins d'écriture.

Le modèle de stock à deux colonnes

Depuis le cutover backorder (#2886 « Option B », STOCK_LEDGER_ALLOW_BACKORDER=true en production depuis le 2026-07-09), le stock vit dans deux colonnes aux rôles distincts :

flowchart LR
  MV["recordPhysicalMovement<br/>(chaque mouvement physique)"] --> SA["StockAction COMPLETED<br/>± quantité"]
  SA -->|même transaction| L[("Product.stockLedger<br/>autorité SIGNÉE<br/>négatif = précommande")]
  L -->|"stock = max(0, stockLedger)"| S[("Product.stock<br/>miroir d'affichage bridé")]
  L -->|"trustedStock (garde-fous)"| R["Moteur de réappro"]
  S --> UI["Affichage boutique / back office"]

• Product.stockLedger est l'autorité signée : ouverture + Σ réceptions − Σ livraisons. Il peut passer négatif — c'est un backorder réel (livré au client avant que la réception couvrante soit enregistrée), et la réception suivante le nette. Comme il n'est jamais bridé, le phantom stock (un compteur gonflé par un clamp à 0) est structurellement impossible.
• Product.stock est le miroir d'affichage : l'invariant est stock == max(0, stockLedger). C'est ce que voient la boutique et les listes du back office ; il ne porte aucune décision de réappro.
• Chaque écriture physique passe par StockLedgerService.recordPhysicalMovement (math pure dans packages/services/src/stock/rolling-stock-math.ts) : vérifie manageStock, émet la StockAction et met à jour les deux colonnes dans la même transaction. Aucun site d'écriture ne contourne ce contrat — voir Chemins d'écriture.
• La lecture côté réappro passe par trustedStock() (packages/services-supplier-order/src/utils/supplier-order-utils-new.ts), qui applique les garde-fous : manageStock=false → 0, kill-switch STOCK_LEDGER_PESSIMISTIC → 0 (OFF en production), négatif bridé à 0 (tant que le gate STOCK_TRUST_ALLOW_NEGATIVE n'est pas armé), et un plafond anti-phantom à STOCK_TRUST_MAX_COVER_WEEKS semaines de consommation récente (8 en production). Détail : Ledger et Configuration.

Les StockAction forment le journal : statuts PENDING (projection — p. ex. « entrée virtuelle » attendue d'un bon fournisseur envoyé) / COMPLETED (appliquée au ledger) / CANCELLED ; types INCREMENT / DECREMENT / ADJUSTMENT ; sources MANUAL, ORDER_UPDATE, SUPPLIER_DELIVERY, INVENTORY_ADJUSTMENT, etc. Seules les COMPLETED comptent dans le ledger.

Le rythme quotidien en bref

La chronologie complète, avec les interactions entre crons et les pièges d'alerting, est sur Cycle quotidien.

Les sous-systèmes

Trois invariants à retenir

1. Le ledger dit la vérité physique. Le stock ne bouge qu'à la livraison ou à la réception, jamais à la prise de commande. Un stockLedger négatif est une information (backorder), pas une erreur.
2. On ne commande jamais dans le passé. Le gate SUPPLIER_NO_PAST_SLOTS impose un plancher à maintenant, la causalité (send ≥ création de la commande source), et fait rouler la demande en retard vers le prochain créneau futur.
3. Ce que l'opérateur relit est ce qui part. L'envoi d'un email fournisseur re-rend depuis les items courants et refuse (CONFLICT) si l'empreinte des items a changé depuis le stage. Une commande annulée ne s'envoie jamais.

Pour vérifier la santé du système à tout moment, l'audit d'invariants se lance depuis le dépôt applicatif :

cd apps/app && bun run cli --task stock-ledger-audit \
  --tenantId <tenant> --siteId <site> --strict   # sort non-zéro à la moindre violation

Où aller ensuite

• Vous découvrez le système → lisez Ledger puis Commandes fournisseur : ce sont les deux moitiés du modèle.
• Vous écrivez du code qui touche le stock → Chemins d'écriture d'abord, puis les Filets de sécurité pour savoir quels tests épingler.
• Vous opérez la production → Cycle quotidien pour les horaires, Configuration pour les gates, et Back office pour les surfaces de contrôle.
• Vous déboguez une divergence PrestaShop → Sync PrestaShop.

Voir aussi

• Ledger de stock — le modèle signé en détail
• Commandes fournisseur — réappro événementiel et pipeline email
• Cycle quotidien — les 7 crons heure par heure
• Filets de sécurité — invariants, audit, tests