Le ledger de stock

Le stock de la plateforme est tenu par un ledger signé : Product.stockLedger est l'autorité (il peut être négatif — une précommande réelle), et Product.stock n'en est que le miroir d'affichage bridé (stock == max(0, stockLedger)). Cette page est la référence du modèle : pourquoi il existe, l'anatomie d'une StockAction, la frontière de confiance trustedStock lue par le réapprovisionnement, et les invariants qui gardent le tout honnête.

Pour la vue d'ensemble du flux complet (stock → réappro → email fournisseur), voir la vue d'ensemble ; pour le détail de chaque site d'écriture, voir les chemins d'écriture.

Le modèle Option B (#2886)

Deux colonnes sur Product, un seul contrat :

Chaque mouvement physique enregistre le vrai delta signé dans le ledger, même quand il le fait passer sous zéro. La réception suivante nette la précommande au lieu d'empiler du stock libre par-dessus un compteur bridé à 0. Le calcul est une fonction pure, partagée par tous les sites d'écriture :

packages/services/src/stock/rolling-stock-math.ts   → computeStockWrite / displayStock
packages/services/src/stock/stock-ledger.service.ts → recordPhysicalMovement

Le comportement signé est gaté par STOCK_LEDGER_ALLOW_BACKORDER (true en production depuis le 2026-07-09T20:00Z). Flag OFF, le calcul retombe octet pour octet sur l'ancien modèle bridé — le correctif n'existe que sous le flag.

Pourquoi un ledger signé — trois générations du même bug

Le modèle actuel est la réponse à une classe d'incidents bien documentée :

1. Mai 2026 — le phantom stock originel. Des StockAction PENDING virtuelles étaient créées pour des produits manageStock=false, avec quantityBefore=0 bouché en dur ; les régénérations de bons fournisseurs annulaient la source sans reverser les incréments COMPLETED déjà appliqués. Résultat : ~912 unités fantômes sur ~57 produits, et des bons fournisseurs sous-commandés (Bio Rennes 2026-05-06 : 6 lignes au lieu de 39+).
2. #2728 — la dérive multi-sources. Product.stock, la quantité synchronisée depuis PrestaShop et Σ(stockAction) divergeaient silencieusement : trois « vérités » incompatibles, aucune fiable.
3. #2886 — le clamp en flux tendu. En rolling sans stock tampon, le stock physique vit à 0 entre deux réceptions. Une livraison client validée à stock 0 était bridée (max(0, 0 − qté) = 0) : la consommation était silencieusement perdue, la réception suivante créait du stock fantôme, et la commande fournisseur suivante était sous-dimensionnée (cas mesuré : Baron 31 → 26). Le piège : ce fantôme passait l'audit, puisque stock == stockLedger == la valeur fictive — cohérent en interne, faux physiquement.

Le ledger signé rend le fantôme par clamp structurellement impossible : le −5 d'une livraison à stock 2 est enregistré en entier (ledger −3), et la réception de 10 atterrit sur 7, pas sur 10.

Anatomie d'une StockAction

Chaque mouvement — réel ou projeté — est une ligne StockAction (packages/db/prisma/schema/order.prisma) :

Seules les lignes COMPLETED comptent dans le ledger : stockLedger est le cache de Σ quantityChange des SA COMPLETED du produit. Les PENDING sont des projections — le réservé-entrant (« Entrée virtuelle » d'un bon fournisseur émis) et le réservé-sortant (« Sortie virtuelle » d'une commande client) — et ne touchent ni stock ni stockLedger.

Cycle de vie et règles de réversibilité

stateDiagram-v2
    [*] --> PENDING : projection créée (bon fournisseur émis, commande client)
    PENDING --> COMPLETED : confirmation au mouvement physique
    PENDING --> CANCELLED : source annulée ou régénérée (aucun effet stock)
    COMPLETED --> [*] : suppression = reverseCompleted (ledger -= quantityChange)
    CANCELLED --> [*]
    note right of COMPLETED
        Seul état qui écrit le ledger.
        quantityBefore/After recalculés
        contre le ledger réel au confirm.
    end note

Les règles, dans l'ordre où elles ont été apprises :

• PENDING → COMPLETED (confirmStockAction / StockLedgerService.transitionToCompleted) : les quantités sont recalculées contre le ledger courant au moment du confirm — on ne fait jamais confiance aux valeurs bouchées de la projection. Sous Option B, la base est stockLedger et Product.stock reçoit le miroir bridé.
• PENDING → CANCELLED : sans effet stock. C'est le sort normal d'une projection dont la source est annulée ou régénérée.
• COMPLETED ne s'annule jamais silencieusement. Supprimer un mouvement passe par reverseCompleted (dans stock-actions.service.ts) : le ledger est décrémenté du quantityChange exact, puis Product.stock est réécrit comme miroir bridé du ledger reversé. La reversion « par delta appliqué » est fausse pour les mouvements qui ont traversé zéro — c'est précisément le bug historique.
• Jamais de quantityBefore=0 bouché. Lire le ledger réel d'abord (incident mai 2026).
• Les statuts PROCESSING, FAILED, PARTIAL, VALIDATED, REJECTED existent dans l'enum mais les trois états ci-dessus portent toute la sémantique du ledger.

La sémantique de manageStock

manageStock sépare les produits suivis des produits non suivis :

La frontière de confiance : trustedStock

Tout le calcul de réapprovisionnement lit le stock à travers une seule fonction, trustedStock() (packages/services-supplier-order/src/utils/supplier-order-utils-new.ts). Elle décide combien d'unités en main sont crédibles pour dimensionner un bon fournisseur :

flowchart TD
    A[Produit] --> B{STOCK_LEDGER_PESSIMISTIC ?}
    B -->|true| Z0["retourne 0 (kill switch)"]
    B -->|false| C{manageStock ?}
    C -->|false| Z0
    C -->|true| D{"fournisseur flux tendu<br/>ET stock non validé marchand ?"}
    D -->|oui| Z0
    D -->|non| E{vendor.useStockLedger ?}
    E -->|oui| F{STOCK_TRUST_ALLOW_NEGATIVE ?}
    F -->|oui| G["brut = stockLedger (signé)"]
    F -->|non| H["brut = max(0, stockLedger)"]
    E -->|non| I["brut = max(0, stock)"]
    G --> J{"data.stockTrusted<br/>(comptage validé) ?"}
    H --> J
    I --> J
    J -->|oui| K[retourne brut]
    J -->|non| L["plafond = conso hebdo × STOCK_TRUST_MAX_COVER_WEEKS<br/>retourne min(brut, plafond)"]

Les gardes, une par une :

• STOCK_LEDGER_PESSIMISTIC — le kill switch (#2728). true ⇒ le stock est ignoré partout (retour 0, sur-commande assumée, les brouillons sont relus avant envoi). OFF en production : le ledger est de confiance depuis que les écritures sont auditées.
• manageStock=false ⇒ 0 — un produit non suivi n'apporte aucune couverture.
• Flux tendu (madeToOrder) ⇒ 0 — un fournisseur sans inventaire n'a pas de stock réel en rayon ; son « en main » est un artefact de validation. Exception #2932 : si le marchand a explicitement validé un comptage (data.stockTrusted), la valeur compte.
• Négatif ⇒ bridé à 0 (#2725) — sauf sous le gate STOCK_TRUST_ALLOW_NEGATIVE (OFF en prod) : une fois activé, un ledger négatif traverse tel quel, et la précommande grossit la commande suivante. Le flip est prévu après ≥ 4 semaines d'invariant I6 vert. Le chemin legacy Product.stock reste toujours bridé.
• Le plafond anti-fantôme — STOCK_TRUST_MAX_COVER_WEEKS (8 en prod) : on ne fait jamais confiance à plus de N semaines de consommation récente (Σ des DECREMENT COMPLETED sur les 8 dernières semaines, attachée par attachRecentWeeklyConsumption). Un produit à 991 en main mais ~1 vente/semaine est presque sûrement du stock PrestaShop gonflé — le plafond l'écrête. Consommation nulle ⇒ plafond 0 ⇒ stock totalement défié : on commande la demande pleine, la direction conservatrice (sur-commander, jamais de rupture).

Les invariants I1–I7

La tâche stock-ledger-audit (packages/scripts/src/tasks/stock-ledger-audit.ts) vérifie le ledger en continu :

# Rapport (lecture seule)
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid>

# Gate CI / sonde — lève une exception à la moindre violation
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid> --strict

# Réparation (annule les orphelins, resynchronise les miroirs, …)
cd apps/app && bun run cli --task stock-ledger-audit --tenantId <uuid> --siteId <uuid> --apply

Sous Option B, la réparation I5 ne resynchronise que le miroir d'affichage — Σ des SA COMPLETED est l'autorité, on n'écrit jamais une SA de remblai pour faire coller le compteur.

Exemple chiffré : la précommande, pas à pas

Le scénario canonique du flux tendu — une livraison client part avant que la réception couvrante soit enregistrée. Suivez les deux colonnes.

quantityBefore = 2        (ledger réel, jamais un stub)
quantityChange = −5       (le VRAI delta — pas de clamp)
quantityAfter  = −3       (ledger signé)
Product.stock  = max(0, −3) = 0

quantityBefore = −3
quantityChange = +10
quantityAfter  = 7
Product.stock  = max(0, 7) = 7

Flags de production

État vérifié sur le tenant de production (voir Configuration pour la matrice complète) :

Voir aussi

• Vue d'ensemble stock & réappro — le flux complet en une page
• Les chemins d'écriture — chaque site qui écrit le ledger
• Commandes fournisseurs — le réappro événementiel qui lit trustedStock
• La journée type — crons 06:00 / 06:30 / 07:15 / 12:01
• Synchronisation PrestaShop — écritures sync intégrées au ledger (#2749)
• Filets de sécurité — audit, replay-diff, tests épinglés, sonde santé
• Back-office — timeline ledger, mouvements manuels, journal des StockActions
• Configuration — la matrice complète des flags