Inventory Module - Feature List

1. Feature Overview

Inventory uses a mixed execution model:

• synchronous admin APIs for read + manual operations
• asynchronous stock lifecycle processing for order-driven reserve/finalize/release

The module currently targets physical product inventory safety and admin operational visibility.

2. Surface Ownership Matrix

3. Admin Feature Matrix

4. Stock Lifecycle Feature Matrix

5. Runtime Rules

5.1 Reserve

• uses row lock + transaction
• rejects insufficient stock when oversell disabled
• auto-creates zeroed row if missing (current behavior)

5.2 Finalize

• uses row lock + transaction
• requires existing row
• validates reserved/total sufficiency before deduction

5.3 Release

• uses row lock + transaction
• missing row is safe no-op
• no-reserved state is safe no-op

5.4 Adjust

• supports positive/negative adjustment
• prevents negative resulting quantities
• creates inventory row when missing

5.5 Sync

• reconciles one product or all products
• updates only inconsistent rows

6. Data Model Feature Coverage

Implemented in product_inventory:

• one-row-per-product
• total/reserved/available quantities
• low-stock threshold
• track-inventory switch
• allow-oversell switch
• non-negative DB check constraints

7. Error Feature Coverage

Defined but currently not emitted:

• INVENTORY_ALREADY_FINALIZED
• INVENTORY_ALREADY_RELEASED

8. Queue and Worker Feature Coverage

Implemented consumers:

• orders_reservations
• orders_stock_finalize
• orders_stock_release
• inventory

Current queue mismatch:

• orders_stock is registered and owned by dispatcher, but has no processor consumer.

9. Integration Feature Coverage with Order

Implemented outbox emission points:

• order create emits stock.reserve
• payment success emits stock.finalize
• cancel/payment_failed/expired emits stock.release

Quantity source:

• order integration uses order_items.quantity

10. Test Coverage Snapshot

Implemented inventory tests include:

• unit tests for InventoryService
• unit tests for reserve/release processors
• integration test for reserve flow

Observed status:

• targeted inventory test suite passes in current workspace run

11. Missing/Partial Features (Production Gaps)

11.1 Audit logging

• Mongo AuditLog writes for inventory mutations are expected by plan but not implemented in service logic.

11.2 Cache integration

• inventory cache env keys exist but service does not use cache yet.

11.3 Queue contract hygiene

• orders_stock queue has no active consumer.

11.4 Admin DTO semantics

• bulk-sync request currently requires trigger but runtime does not use it.

12. Release Checklist

• Admin APIs enforce permissions and return consistent ResponseDto envelopes.
• Reserve/finalize/release lifecycle is fully wired through outbox -> dispatcher -> queue -> processor -> service.
• Stock adjustments cannot push totals below zero.
• Low-stock view reflects threshold correctly.
• Queue registration and processor coverage are aligned (remove or implement orders_stock).
• Inventory mutation audit trail requirement is satisfied (Mongo audit logging).
• Inventory env contract includes only keys actually used in runtime.

13. Before-Payment Readiness Gate (Inventory Perspective)

Must be true before Stripe/payment rollout:

• finalize/release inventory transitions are stable across payment success/failure retries
• refund and return strategy is defined for stock compensation (if required)
• stale legacy queue/job/config entries are cleaned or explicitly retained
• inventory docs and order docs agree on stock lifecycle ownership

14. Integration Flows

14.1 Reserve flow (checkout/buy-now)

1. order path writes outbox stock.reserve
2. dispatcher enqueues orders_reservations
3. reserve processor calls InventoryService.reserveStock
4. service mutates available and reserved

14.2 Finalize flow (payment success)

1. payment-success path writes outbox stock.finalize
2. dispatcher enqueues orders_stock_finalize
3. finalize processor calls InventoryService.finalizeStock
4. service mutates reserved and total

14.3 Release flow (cancel/failure/expire)

1. order path writes outbox stock.release
2. dispatcher enqueues orders_stock_release
3. release processor calls InventoryService.releaseStock
4. service returns reserved quantities to available safely

15. File Ownership Map

• apps/api/src/modules/inventory/admin/* - admin API surface
• apps/api/src/modules/inventory/shared/* - stock domain logic
• apps/api/src/modules/inventory/processors/* - queue workers
• apps/api/src/modules/order/* - lifecycle event emitters and dispatcher ownership
• packages/db/src/schema/inventory/* - schema contracts
• packages/jobs/src/index.ts - queue and job contracts

See Also

• Inventory - API & Integration Guide
• Inventory - Backend Documentation
• Order - Feature List

16. Operational Acceptance Scenarios

16.1 Stock reservation safety

• creating two overlapping orders for same SKU does not oversell when allowOversell=false
• second reservation path returns INVENTORY_INSUFFICIENT_STOCK with no negative values persisted
• row-level locking ensures only one reservation mutation wins per transaction boundary

16.2 Payment reconciliation behavior

• duplicate payment success callbacks do not double-deduct totalQuantity
• payment failure after prior success does not produce invalid inventory transitions
• expired-payment release only restores quantities that are still reserved

16.3 Manual adjustment operations

• positive adjustment increases totalQuantity and availableQuantity equally
• negative adjustment respects non-negative invariants
• adjustment API remains role-gated by Inventory_UPDATE

16.4 Bulk sync reconciliation

• sync updates only drifted rows (available != total - reserved)
• already-correct rows are returned unchanged
• reconciliation is safe to rerun repeatedly

17. Monitoring and Runbook Signals

Track these signals before declaring inventory complete for production:

• queue depth and failure counts for orders_reservations, orders_stock_finalize, orders_stock_release, and inventory
• rate of INVENTORY_INSUFFICIENT_STOCK errors by product and hour
• count of rows where available != total - reserved after scheduled sync
• ratio of reserve events to finalize/release events (stuck reservations detector)

Runbook checks:

• if reserve jobs spike in failures, inspect low-stock products and allowOversell state first
• if finalize jobs stall, inspect payment callback health and outbox dispatch lag
• if release jobs lag, verify cancel/payment-failure handlers are still emitting outbox events
• if drift count grows, run admin bulk-sync and inspect mutation sources

18. Deferred Work (Explicitly Out of Current Scope)

• dedicated inventory history API powered by Mongo AuditLog
• realtime customer stock push events
• return/refund stock compensation policy automation beyond existing order refund status flow
• inventory cache read-through integration for admin list/detail paths