[WIP] Add inventory reservation and hold system

[Copilot]

• Analyze existing codebase structure and patterns
• Understand existing inventory, checkout, and order services
• Verify project builds successfully
• Add InventoryReservation model to Prisma schema with ReservationStatus enum
• Create InventoryReservationService with reserve/release/consume methods
• Add POST /api/inventory/reserve endpoint (batch reservation with validation)
• Add POST /api/inventory/release endpoint (manual release)
• Add automatic expiration job support (sweeper)
• Integrate with Order creation to convert reservation → decrement
• Add audit log entries for reservation actions
• Update low stock alert logic to exclude reserved quantity
• Run type-check, lint, and build to validate changes
• Run code review
• Run CodeQL security check

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Phase 1] Inventory Reservation & Hold System</issue_title>
<issue_description>## Priority: P0 (Critical)
Phase: 1 - E-Commerce Core
Epic Link: Product / Checkout (#15, #19, Order Processing placeholder #24)
Estimate: 3 days
Type: Story

Context

Implement short-lived inventory reservations to prevent overselling between cart and final payment, enabling accurate stock display and reducing race conditions under concurrent demand.

Scope

• InventoryReservation model (productId / variantId, quantity, storeId, cart/session reference, expiresAt)
• API: POST /api/inventory/reserve (batch reservation with validation)
• API: POST /api/inventory/release (manual release)
• Automatic expiration job (sweeper) every minute
• Integration with Order creation to convert reservation → decrement

Acceptance Criteria

• Reservation creation fails if insufficient available stock (currentStock - activeReservations >= requested)
• Expired reservations released (stock availability recalculated) within < 60s of expiry
• Order creation consumes reservations atomically (transaction) & prevents double decrement
• Reservation TTL configurable (default 15 minutes)
• Ability to extend reservation once (e.g. payment delay)
• Audit log entry: action: inventory_reservation_created / released / consumed
• Low stock alert logic excludes reserved quantity for proactive alert accuracy

Data Model (Draft)

model InventoryReservation {
  id          String   @id @default(cuid())
  storeId     String
  productId   String
  variantId   String?
  quantity    Int
  status      ReservationStatus @default(ACTIVE)
  cartId      String? // if cart session
  orderId     String? // set when consumed
  expiresAt   DateTime
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@index([storeId, productId])
  @@index([expiresAt])
}

enum ReservationStatus {
  ACTIVE
  CONSUMED
  EXPIRED
  RELEASED
}

Dependencies

• Blocks: Accurate stock display, prevents oversell incidents
• Blocked By: [Phase 1] Inventory Management #18 Inventory Management implementation
• Enhances: Multi-channel sync ([Phase 3] Epic: Multi-Channel Sales #35) future deduplication

Metrics

• Overselling incidents reduced to 0/month
• Reservation latency < 150ms p95
• Expiration sweep accuracy > 99%

Testing Checklist

• Concurrent reservations for same product (race-free)
• Expiration release job frees stock
• Conversion on order creation removes reservation & decrements stock once
• Extension updates expiresAt

Risk

High integrity risk if absent (score: 16). Supports scaling & channel sync.

References

• docs/GITHUB_ISSUES_COMPARISON_ANALYSIS.md
• Industry pattern: cart hold / soft allocation
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Phase 1] Inventory Reservation & Hold System #64

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
stormcomui	Ready	Preview	Comment	Nov 25, 2025 2:31am