訂房散客直訂

一句話：訂房散客直訂是 lodging 模組的成交 flow，前台或後台選旅宿 / 房型 / 日期區間，扣每晚庫存，建立 lodging order line，並接同一套金流分類帳。

• 關聯：lodging-inventory · orders · order-money-model · member-ownership · control-finance

1. 成交 Flow

1.1 前台自助

1. 使用者進 /booking，只看 lodging 模組啟用且可直訂的旅宿。
2. 選日期、房型、間數與入住人數。
3. 系統查 room_night_inventory，計算逐晚價格與可售數。
4. checkout 建單：
   • 建 orders(kind='lodging')；
   • 建 order_lines(line_kind='lodging')；
   • 建 lodging_booking_lines；
   • 建 lodging_nightly_snapshots；
   • 每晚寫 order_charge_lines(type='lodging_night')；
   • 若有折扣碼，寫負的 discount charge line；
   • 建 payment_schedules 與首個 payment_intents。
5. redirect 到付款 provider；付款成功後金流 helper 重算狀態。

1.2 後台代訂

後台 /admin/lodging/book 可替客戶建 lodging order。代訂可選立即手動入帳、ATM / credit card redirect，或先建立待付款單；無論入口如何，資料模型與前台自助一致。

2. 庫存與 race-safe

訂房不走 trips/departures 席次模型；庫存以 property + room_type + date 為單位。

• reserveNightsInTx 在同一交易中 conditional update 每晚 booked_count；
• 任一晚不足即整筆失敗，不建立訂單；
• 取消 lodging order 時釋回所有 nights，但不自動退款；
• direct booking 與 lodging-tour-package 共用同一份 room_night_inventory。

3. 訂單 Line 模型

Lodging order 不在 orders 外殼保存房型或金額。資料責任：

會員中心與訂單詳情必須 kind-aware 呈現 lodging 訂單；tour-only 管理頁面不得靜默把 lodging order 當 tour 處理。

4. 付款

• lodging 自助預設全額收款；若未來支援訂金，也應透過 payment_schedules 表達。
• ECPay / test provider 都是 adapter；付款事實只在 payment_transactions。
• 已付款後更改住宿內容，應 append charge line 並產生 adjustment schedule / intent，不直接改原始 nightly snapshot。

5. 取消與退款

取消 lodging order：

1. 鎖訂單；
2. 釋回 nightly inventory；
3. 將 booking_state 轉為 cancelled；
4. 重算金流狀態；
5. 寫 audit。

退款需另走 refunds 工作流；取消本身不代表自動退款。

6. 權限與 Gate

• lodging 模組未啟用時，前台 /booking 與後台 lodging routes fail closed。
• 後台代訂需 staff 權限；前台自助需 customer session。
• 所有 DB 仍是 tenant DB；不得在 lodging flow 引入 tenant id column。

Changelog