SRV-13 — Inventory module

SummaryCopy Anchor Link

Warehouses, stock levels, reservations and deductions by order status, automatic restock on cancellation and on return reception, movement ledger, thresholds and alerts, inventory sessions. Resellers only ever see availability.

DescriptionCopy Anchor Link

Stock must be exact in the back-office and never exposed as a number to resellers or guests (STK-01…STK-08, cahier §4.3, §8, §12; 17 Oct decisions 1 and 10). This task implements warehouses (global or per warehouse), StockLevel with physical, reserved and available (= physical − reserved) quantities and alert thresholds, and the StockMovement ledger for every change (RECEIPT, ADJUSTMENT, INVENTORY, RESERVATION, RESERVATION_RELEASE, SHIPMENT, RETURN, transfers). Order hooks reserve at stock.reserveOn (default VALIDATED) and deduct at stock.deductOn (default SHIPPED); cancellation and refusal release reservations automatically, cancellation after deduction re-enters quantities, and return reception posts RETURN movements automatically (consumed by SRV-20). No order is validated beyond available stock unless an authorised override is recorded (STK-08). It projects availability (IN_STOCK/OUT_OF_STOCK) to the catalog, raises low/out-of-stock alerts, and runs inventory sessions. Out of scope: stock UI (DSH-05) and V2 stock-system sync (SRV-37).

SubtasksCopy Anchor Link

DeliverablesCopy Anchor Link

• apps/server/src/modules/inventory/{stock.service.ts,order-hooks.ts,availability.ts,inventory-sessions.service.ts,router.ts,events.ts}
• packages/contracts/src/admin/stock.ts
• Stock rules table in /docs/srs/lifecycles-and-statuses confirmed against the implementation

Acceptance criteriaCopy Anchor Link

• With reserveOn = VALIDATED, validating an order reserves each line; refusing or cancelling it writes RESERVATION_RELEASE and restores available (STK-03)
• Reaching SHIPPED writes SHIPMENT (physical −qty, reserved −qty); cancelling after that re-enters the quantities with a movement
• Validation beyond available stock fails with 422 STOCK_INSUFFICIENT unless the caller has the override permission and gives a reason (STK-08)
• Every change of physical or reserved has exactly one StockMovement with its reference (order, return, inventory session) (STK-04)
• When available reaches 0 the variant becomes OUT_OF_STOCK in the catalog and a stock.out alert is emitted (STK-05, CAT-04)
• No reseller or delegate endpoint returns a quantity (STK-07)

Requirements coveredCopy Anchor Link

ScreensCopy Anchor Link

API surfaceCopy Anchor Link

Test measuresCopy Anchor Link

• DB concurrency test: 50 parallel validations competing for the last 10 units never oversell
• Ledger invariant test: physical = sum of movements per variant/warehouse after a random sequence of operations
• Unit tests for the reserveOn/deductOn hook matrix (SUBMITTED vs VALIDATED reservation)

RisksCopy Anchor Link

• Deadlocks between concurrent multi-line orders — lock rows in a deterministic order and keep transactions short
• Physical stock in HOCO's existing system diverges from the platform — initial import in LCH-01 and inventory sessions; API sync is V2 (STK-09)

KPICopy Anchor Link

• Delivered by Sun 18 Oct 2026 within 1 person-day(s).
• Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
• Zero open critical defects, permission gaps or data-integrity regressions at sign-off.

---

Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.