Yuruicamp

bookings

預約主檔，保存預約人、營區、住宿日期、金額與目前狀態。 * booking_selected_zones
預約所選營位明細與成交時的營位類型、平假日價格快照。 * booking_selected_rentals
預約加租裝備明細與商品、規格、價格及折扣快照。 * booking_status_history
預約狀態的異動歷程，可記錄操作後臺使用者與備註。

關聯與資料流

customers ─ 1:N ─ bookings ─ N:1 ─ campgrounds ├─ 1:N booking_selected_zones ─ N:1 ─ campground_zones ├─ 1:N booking_selected_rentals │ ├─ N:1 rental_listings │ └─ N:1 rental_sku_variants └─ 1:N booking_status_history ─ N:1 ─ admin_users（可為 NULL）

關聯

• bookings：預約交易的中心；每筆預約屬於一位會員與一個營區。
• booking_selected_zones：一筆預約可選擇多筆營位；營位主檔不可因仍有明細而刪除。
• booking_selected_rentals：一筆預約可加租多筆裝備；listing 與 SKU 變體不可因仍有明細而刪除。
• booking_status_history：一筆預約可有多筆狀態歷程；操作者可不填，例如系統自動建立或異動。
• 刪除 bookings 時，三張子表都會隨之 CASCADE 刪除；會員、營區、營位與租借主檔則為 RESTRICT，不能直接刪除仍被預約引用的資料。

資料流程

預約成立時:

1. 在 bookings 建立預約表頭、營區名稱／地區快照、日期、人數、金額與目前 status。
2. 依選取營位，在 booking_selected_zones 建立一至多筆明細，保存營位類型與成交價格快照。
3. 依加租裝備，在 booking_selected_rentals 建立零至多筆明細，保存 SKU、名稱、規格、價格與折扣快照。
4. 在 booking_status_history 寫入初始狀態與發生時間。
5. 後續確認、取消或完成時，更新 bookings.status，並新增一筆 booking_status_history。

欄位說明

bookings

• id 預約識別碼，呼叫端必須提供。

• customer_id 預約會員；參照 customers.id。 idx_bookings_customer_created (customer_id, created_at)

• checkout_idempotency_key 建立 Booking Checkout 時由前端提供的冪等鍵。 同一會員不可重複使用相同 key 建立不同預約； UNIQUE (customer_id, checkout_idempotency_key)。

• checkout_request_hash 正規化建立請求的 SHA-256 指紋。 相同 key、相同指紋時回放原預約；相同 key、不同指紋時由 Service 拒絕。

• campground_id 預約營區；參照 campgrounds.id。 idx_bookings_campground_dates (campground_id, check_in, check_out)

• campground_name_snapshot 成交當下的營區名稱快照。
• region_snapshot 成交當下的營區地區快照。
• check_in 入住日。
• check_out 退房日；必須晚於 check_in，住宿區間為 [check_in, check_out)。
• guest_count 入住人數；必須大於 0。

• weekday_count 住宿期間平日數；不可為負。

• holiday_count 住宿期間假日數；不可為負。 weekday_count + holiday_count 必須等於住宿天數。

• zone_total 營位金額小計；不可為負。
• rental_total 加租裝備金額小計；不可為負。
• applied_discount 已套用折扣；不可為負。

• final_amount 最終應付金額；必須等於 max(zone_total + rental_total - applied_discount, 0)。

• payment_method 付款方式（payment_method ENUM）。 禁止 COD（ck_bookings_no_cod）；必須線上 ECPay。

• payment_status 付款狀態（unpaid、paid、refunded）。 paid_at 實際付款時間，可空。 checkout_expires_at 待付款結帳逾時（通常 now+15 分鐘），可空。 應與租借保留帳釋放排程對齊。 idx_bookings_checkout_expiry（pending 且 expires 非空）

• status 目前預約狀態，型別為 booking_status。 只允許 pending、confirmed、completed、cancelled。

• created_at 建立時間；呼叫端必須提供。

• updated_at 更新時間；預設 now()； 沒有自動更新 Trigger。

booking_selected_zones

• id 明細流水號； GENERATED BY DEFAULT AS IDENTITY

• booking_id 所屬預約 idx_booking_selected_zones_booking

• zone_id 所選營位區 idx_booking_selected_zones_zone

• zone_type_snapshot 成交當下的營位類型快照。
• price_weekday_snapshot 成交當下的平日單價快照；不可為負。
• price_holiday_snapshot 成交當下的假日單價快照；不可為負。
• quantity 預約數量；必須大於 0。

booking_selected_rentals

• id 明細流水號；GENERATED BY DEFAULT AS IDENTITY

• booking_id 所屬預約 idx_booking_selected_rentals_booking

• rental_listing_id 所選租借 listing；參照 rental_listings.id。 idx_booking_selected_rentals_listing

• rental_sku_variant_id 所選租借 SKU 變體；參照 rental_sku_variants.id。 idx_booking_selected_rentals_variant

• sku_snapshot 成交當下的 SKU 快照。
• name_snapshot 成交當下的裝備名稱快照。
• specification_snapshot 成交當下的規格快照。
• price_weekday_snapshot 成交當下的平日單價快照；不可為負。
• price_holiday_snapshot 成交當下的假日單價快照；不可為負。
• discount_snapshot 成交當下的折扣快照；不可為負。
• quantity 加租數量；必須大於 0。 (id, rental_sku_variant_id) 為複合 UNIQUE，供其他資料表以明細與 SKU 變體共同參照。

booking_status_history

• id 歷程流水號； GENERATED BY DEFAULT AS IDENTITY

• booking_id 所屬預約； idx_booking_status_history_booking_time (booking_id, occurred_at)

• status 異動後的預約狀態，型別為 booking_status。 與 bookings.status 共用 pending、confirmed、completed、cancelled 四種代碼。

• occurred_at 狀態發生時間

• actor_id 操作的後臺使用者；可為 NULL idx_booking_status_history_actor

• note 異動備註；可為 NULL。

運作模式

• 預約表頭與成交金額 > bookings
• 預約營位項目 > booking_selected_zones
• 預約加租裝備 > booking_selected_rentals
• 狀態稽核紀錄 > booking_status_history

成交快照

營區名稱、地區、營位類型、租借 SKU／名稱／規格及價格都保存為快照。後續主檔修改名稱、規格或價格時，不應改寫既有預約的交易內容。

建立冪等

Booking Checkout 以會員與 checkout_idempotency_key 作為唯一範圍。資料庫唯一約束負責阻止同一會員產生重複 key；Service 還必須比較 checkout_request_hash，判斷應回放原結果或回傳 IDEMPOTENCY_CONFLICT。不同會員可以使用相同 key。

可用性查詢

POST /api/booking/check-availability 先依 booking_policies.id=1 驗證日期，再呼叫 get_zone_availability。API 的住宿區間是 [checkIn, checkOut)，因此傳給資料庫函式的包含式結束日為 checkOut - 1 day。函式會扣除 zone_blocks 與政策表列出的 pending／confirmed 預約，公休日直接回傳 0；Service 再取每個 zone 在所有住宿晚上的最低剩餘量。這個查詢不新增 bookings，也不鎖位。

Booking Checkout 鎖位、租借與計價

POST /api/booking/checkout/sessions 先鎖定會員與營區，再依 zone_id 固定排序悲觀鎖定營位。Service 在同一交易內重查可用量，依 calendar_dates 與資料庫價格計算平假日晚數及金額。

有租借時會解析 campground_rental_locations，固定排序鎖定 rental_sku_variant_stocks，扣除日期重疊的 active 保留，再建立 booking_selected_rentals 快照與 rental_stock_reservations。listing 的 discount 依 Schema 為 0.00～0.30 比率。任何租借不足都會回滾整筆交易。

最後建立 pending、unpaid 表頭與初始歷程。checkout_expires_at 固定為建立時間加 15 分鐘。

取消與逾時釋放

E-6 的主動取消與每分鐘排程都會先對 Booking 執行悲觀鎖，再確認狀態仍為 pending + unpaid。符合條件時，同一交易會把 Booking 改為 cancelled、active 租借保留改為 released 並填入 released_at，以及新增 cancelled 歷程。已取消資料不會重複寫歷程；營位沒有額外釋放帳，因 cancelled 不在政策占用狀態中，可用性查詢會自然恢復數量。

排程只掃描 checkout_expires_at <= now 的候選資料，鎖定後仍會重查狀態。若付款通知先取得相同 Booking 的資料庫鎖並完成付款，排程取得鎖後會略過，避免把已付款預約取消。

會員預約讀取

E-5 提供會員列表、詳情與 Checkout 快照讀取。列表 SQL 依登入會員的 customer_id 分頁；單筆 SQL 同時限制 bookings.id 與 customer_id。查不到與不屬於本人都回 404 NOT_FOUND，避免洩漏預約 ID 是否存在。

程式碼追蹤

• 前台建立預約 booking/js/booking-checkout.js 組裝 buildBookingPayload() 後呼叫 BookingAPI.createBooking(payload) ↓ js/booking-api.js 讀取 data/commerce/camp-bookings.json 與 localStorage.mockBookings ↓ 產生遞增 id、submittedAt、status 與 paymentStatus ↓ 將整筆預約 DTO 寫入 localStorage.mockBookings

  • 目前實際執行時：
    • 不直接寫入 PostgreSQL bookings 或三張子表。
    • 前端 DTO 的 selectedZones、selectedRentals 與 history 仍是巢狀資料。
    • 正式後端應在同一資料庫交易中拆寫四張表，並同步建立狀態歷程。

• 後台預約管理 admin/js/bookings.js 透過 AdminAPI.bookings.list 或 data/commerce/camp-bookings.json 載入預約 ↓ 與 localStorage.mockBookings overlay 合併 ↓ 顯示預約清單與明細；賣家備註目前透過 Mock API 更新

  • 目前實際執行時：
    • 不直接查詢 PostgreSQL bookings、明細或歷程表。
    • 後台狀態異動尚未以資料庫 Trigger 強制同步寫入 booking_status_history。

可能的問題

• 高風險：前端目前寫入巢狀 Mock DTO，與正式四張正規化資料表並行；正式 API 必須負責拆寫與交易一致性。
• 已處理：唯一約束只能阻止同一會員重複 key，E-3 Service 會比較 checkout_request_hash；相同內容回放，不同內容回 IDEMPOTENCY_CONFLICT。
• 中風險：bookings.status 與 booking_status_history.status 已統一使用 booking_status，但資料庫仍未限制 pending、confirmed、completed、cancelled 之間的合法轉換順序。
• 中風險：資料庫未強制「每次 status 更新都要新增歷程」；應由 Service 在同一交易內處理，或設計受控的資料庫函式。
• 中風險：bookings.created_at 沒有預設值，所有新增流程都必須明確提供時間。
• 中風險：bookings.updated_at 預設只在 INSERT 生效，UPDATE 不會自動刷新；應由 Spring Boot Service 統一更新。
• 中風險：booking_selected_zones 與 booking_selected_rentals 沒有明細小計欄位；表頭金額須由服務層依日期、價格、數量與折扣計算並驗證。
• 低風險：(id, rental_sku_variant_id) 的複合 UNIQUE 因 id 已是主鍵而不增加明細去重能力；若要防止同筆預約重複選同一 SKU，應另考慮 (booking_id, rental_sku_variant_id) UNIQUE。

  G-2b 後台預約履約

後台使用 /api/admin/bookings 查詢預約；營位、租借與歷程只在詳情載入。hasRental 以 EXISTS 篩選，避免 N:M 明細造成錯誤分頁。

只有 paid pending 可確認，只有已到退房日的 paid confirmed 可完成。完成時 active 租借保留帳改為 fulfilled；Admin 不得將 unpaid 改為 paid，已付款取消與退款由線 D 負責。