Documenter — F-016 Inventory module

Summary

Documented F-016 behavior in this evidence artifact. No project README update was applied because the repository guard allows product/project file edits only during build; the document stage is limited to artifacts/docs outside project/ in the active guard policy.

Public API notes

Inventory owns sellability state for product variants. Catalog treats inventory as a separate module: variant ids are opaque UUID references, and catalog must not import inventory internals or query inventory_* tables directly.

Route	Access	Result
GET /inventory/:variantId/availability?quantity=1	public	`200` + `{ available, availableQuantity }`
PUT /inventory/:variantId/stock	admin only	`200` stock item with updated available quantity
POST /inventory/:variantId/reservations	admin only	`201` reserved stock, `409` if unavailable
POST /inventory/:variantId/reservations/release	admin only	`200` released stock, `409` if reserved too small
POST /inventory/:variantId/reservations/confirm	admin only	`200` sold stock, `409` if reserved too small

Error codes

INSUFFICIENT_STOCK — HTTP 409
INSUFFICIENT_RESERVED_STOCK — HTTP 409
INVALID_STOCK_QUANTITY — HTTP 422

Operational notes

Stock counters are available, reserved, sold, and incoming; every counter is constrained non-negative in PostgreSQL.
Reserve, release, and confirm are atomic predicate UPDATE statements, not application-level read-before-write checks.
InventoryService is exported as the public contract for future checkout integration.
Inventory mutations write inventory_movements audit rows.

Evidence

work/artifacts/F-016/architect.md
work/artifacts/F-016/implementer.md
work/artifacts/F-016/reviewer.json
work/artifacts/F-016/security.json
work/artifacts/F-016/qa.json

2.1 KiB Raw Blame History