Yuruicamp

inventory_locations

代表一個可存放庫存的地點 * rental_stock_reservations  
預約訂單的數量提前管控表 * product_stock_reservations
商品訂單的數量提前管控表

關聯與資料流

order_items
└─ 1:N product_stock_reservations
     └─ N:1 inventory_locations（inventory_domain = store）

booking_selected_rentals
└─ 1:N rental_stock_reservations
     └─ N:1 inventory_locations（inventory_domain = rental）

inventory_locations
├─ 1:N product_stock_reservations
└─ 1:N rental_stock_reservations

關聯

• product_stock_reservations：以 (order_item_id, variant_id) 複合外鍵連至 order_items，確認保留的規格確實屬於該訂單明細。
• rental_stock_reservations：以 (booking_selected_rental_id, rental_sku_variant_id) 複合外鍵連至 booking_selected_rentals，確認保留的租借規格確實屬於該預約明細。
• product_stock_reservations：以 (location_id, inventory_domain) 複合外鍵連至 inventory_locations，且 inventory_domain 固定為 store。
• rental_stock_reservations：以 (location_id, inventory_domain) 複合外鍵連至 inventory_locations，且 inventory_domain 固定為 rental。
• 所有外鍵均為 ON UPDATE CASCADE ON DELETE RESTRICT；已存在保留帳的訂單、預約或地點不可直接刪除。

資料流程

商城訂單保留：

1. 建立 order_items 後，依選取規格與出貨地點建立 product_stock_reservations。
2. status = active 時，數量仍被暫時保留；可設定 expires_at 供逾時釋放。
3. 取消、付款失敗或逾時時，狀態改為 released 或 expired，並填入 released_at。
4. 訂單履約時，狀態改為 fulfilled，並填入 fulfilled_at。

租借預約保留：

1. 建立 booking_selected_rentals 後，依租借 SKU 規格、取用地點與入住區間建立 rental_stock_reservations。
2. status = active 時，[check_in, check_out) 區間內的可用數量必須扣除該保留數量。
3. 取消時改為 released 並填入 released_at；完成租借時改為 fulfilled 並填入 fulfilled_at。
4. 租借保留沒有 expired 狀態；其有效性依預約業務流程決定。

欄位說明

product_stock_reservations

• id 保留帳流水號 GENERATED BY DEFAULT AS IDENTITY。

• order_item_id 訂單明細識別碼； 與 variant_id 複合外鍵指向 order_items。 idx_product_stock_reservations_order_item ON (order_item_id)

• variant_id 商城商品規格識別碼；必須與訂單明細的規格一致。

• location_id 商城庫存地點； 與 inventory_domain 複合外鍵指向 inventory_locations。

• quantity 保留數量，必須大於 0。
• status 保留狀態：active、released、fulfilled、expired；預設 active。
• idempotency_key 唯一碼，UNIQUE。
• reserved_at 建立保留時間，預設 now()。
• expires_at 到期時間，NULL；若有值，必須晚於 reserved_at。
• released_at 釋放／到期時間，NULL。
• fulfilled_at 履約完成時間，NULL。

• inventory_domain 固定為 store

• status 約束條件 : status released_at fulfilled_at 意義 —– active 必須是 NULL 必須是 NULL 正在保留庫存，尚未結束 released 必填 必須是 NULL 取消／付款失敗，庫存已釋放 expired 必填 必須是 NULL 超過 expires_at，庫存已釋放 fulfilled 可為 NULL 必填 訂單已履約，保留轉為完成

idx_product_stock_reservations_active_lookup ON (variant_id、location_id)，條件：status = active idx_product_stock_reservations_expiry ON (expires_at)，條件：status = active AND expires_at IS NOT NULL

rental_stock_reservations

• id 保留帳流水號 GENERATED BY DEFAULT AS IDENTITY。

• booking_selected_rental_id 預約租借明細識別碼； 與 rental_sku_variant_id 複合外鍵指向 booking_selected_rentals。 idx_rental_stock_reservations_booking_item ON (booking_selected_rental_id)

• rental_sku_variant_id 租借 SKU 規格識別碼；必須與預約租借明細的規格一致。

• location_id 租借庫存地點； 與 inventory_domain 複合外鍵指向 inventory_locations。

• check_in 入住日，日期區間起點（包含）。
• check_out 退房日，日期區間終點（不包含），必須晚於 check_in。
• quantity 保留數量，必須大於 0。
• status 保留狀態：active、released、fulfilled；預設 active。
• idempotency_key 冪等鍵，最長 128 字元，UNIQUE。
• reserved_at 建立保留時間，預設 now()。
• released_at 釋放時間，NULL。
• fulfilled_at 履約完成時間，NULL。

• inventory_domain 固定為 rental，預設 rental。

• status 約束條件 : status released_at fulfilled_at 意義 —– active 必須是 NULL 必須是 NULL 預約租借仍占用該日期區間的庫存 released 必填 必須是 NULL 預約取消，日期區間庫存已釋放 fulfilled 可為 NULL 必填 租借已完成，保留帳結案

idx_rental_stock_reservations_active_range ON (rental_sku_variant_id、location_id、check_in、check_out)，條件：status = active

inventory_locations

• id 庫存地點識別碼，由呼叫端提供。
• code 庫存地點代碼，NIQUE。

• inventory_domain 庫存類型，只允許 store 或 rental。

• type 分類至store/rental 後的狀態 store 只允許 main、branch、inspection、repair、damaged。 rental 只允許 main、campground、inspection、repair、damaged。

• branch_id 所屬門市，NULL；只有 type = branch 且 inventory_domain = store 時必填 type 非 branch 時必須為 NULL。 idx_inventory_locations_branch ON (branch_id)

• name 庫位顯示名稱
• active 是否啟用，預設 true。
• created_at 建立時間，預設 now()。
• updated_at 最後更新時間，預設 now()；DDL 未定義自動更新 Trigger。

CHECK：庫存領域、地點類型，以及門市類型與 branch_id 的相容性。 idx_inventory_locations_domain_type_active ON (inventory_domain、type、active)

運作模式

• 商城結帳暫保庫存 > product_stock_reservations
• 租借預約日期區間暫保庫存 > rental_stock_reservations
• 保留地點領域隔離 > inventory_locations
• 商城可售量判斷 > 現有庫存減去同一規格／地點的 active 保留數量。
• 租借可用量判斷 > 現有庫存減去與查詢日期區間重疊的 active 保留數量。

保留帳終態

• 終態保留帳不可重回 active，以避免庫存稽核鏈被覆寫。
• released、expired 代表數量已歸還可用池；fulfilled 代表該保留已完成業務履約。
• latest_schema.sql 沒有以 Trigger 實作保留帳生命週期；正式後端必須負責狀態轉換、期限與庫存一致性驗證。

程式碼追蹤

pages/checkout.html ↓ js/pages/checkout.js ↓ window.API.orders.create(orderData) ↓ js/api-mock.js ↓ localStorage.mockOrders

• 商城線 C 已由 Checkout Service 寫入與釋放 product_stock_reservations。
• Booking 線 E-4 已由 Booking Checkout Service 寫入 rental_stock_reservations，並依 [check_in, check_out) 重疊條件計算可租量。
• Booking 線 E-6 已在主動取消與逾時排程中，將該預約的 active 租借保留改為 released 並填入 released_at。
• tools/database-validation/validation/validate_inventory.sql 第 24–36 行檢查保留帳是否仍有對應實體庫存列。
• tools/database-validation/validation/p5-data.sql 第 204–207 行檢查兩張表的 inventory_domain 是否固定為正確領域。

可能的問題

• 已處理：商城線 C 與 Booking E-4 都會在建立保留前鎖定對應實體庫存，並於同一交易寫入表頭、明細及保留帳。
• 已處理：Booking E-6 會鎖定 Booking，並在取消／逾時時將租借 active 保留改為 released，與預約狀態及歷程同交易提交。
• 中風險：商城保留帳允許 expires_at 為 NULL；服務層必須定義無到期時間的有效使用情境，避免永久 active 保留。
• 中風險：租借可用性依日期區間重疊計算，必須固定使用 [check_in, check_out) 語意，否則相鄰租期可能被錯誤判定為衝突。
• 低風險：inventory_locations.active 不會自動阻止既有保留帳或新建保留帳；服務層應禁止對停用地點建立新的保留。