訂房產品線

訂房賣的是「某房型的某一晚」，不是梯次席次。它有自己的庫存脊椎（物件 → 房型 → 每晚房況），但成交後一樣是一張訂單，接同一套金流模型。

如果你已經熟悉訂單與金流模型，訂房只多了「住宿物件與每晚庫存」這層；訂單與收款的部分完全沿用。所有端點見 lodging API。

注意

訂房受「訂房模組」閘控。 讀取端點（GET）只要 lodging.read 權限；建立 / 修改類端點（建物件、改房型、覆寫房況、建訂房單）額外要求租戶已啟用訂房模組，否則回 403 module_disabled。

訂房不是行程

cairn 的行程產品走 trips → departures，訂單訂的是固定出發日的「席次」。訂房不套這個模型：

	行程（tour）	訂房（lodging）
庫存單位	梯次席次	某房型的「每一晚」
客人選什麼	出發梯次	入住 / 退房日期區間
資源主檔	trips / departures	properties / room-types
訂單 `kind`	`tour`	`lodging`

兩者最終都收斂成一張訂單，差別只在「賣的是什麼」。

住宿物件與房型

訂房的資源是兩層：

物件（property）— 一處自家住宿。kind（如 camp 露營 / hotel 旅館）、isOverseas、地點與內容。用 GET /lodging/properties 列出、POST 建立。
房型（room-type）— 物件底下的可售單位。關鍵欄位 inventoryUnit（room 賣整間 / bed 賣床位）、unitsTotal（共幾間或幾床）、capacityPerUnit（每單元可住幾人）、basePriceTwd（基準晚價）。用 GET /lodging/properties/{id}/room-types 取得。

物件與房型都帶相簿（images）與設施等內容欄位，供前台呈現。

每晚庫存與房況

每個房型每一晚有一筆房況，記「容量 / 已訂 / 當晚價」，是訂房庫存的單一真相。平日 / 假日 / 旺季靠逐晚覆寫價，封房則把該晚關閉。

查可訂量與報價走房況查詢：

GET /lodging/room-types/{id}/availability?checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD
→ available      區間可訂單元數（跨晚取最小；0 表不可訂）
  nights         晚數（不含退房日）
  totalPriceTwd  區間總價（逐晚價加總）
  perNight[]     每一晚的剩餘量與當晚價

說明

日期區間是左閉右開 [checkIn, checkOut)——退房日不算一晚。報價是逐晚累加，不是「晚數 × 單一價」，所以跨平假日 / 旺季的區間會自動反映各晚的覆寫價。

庫存扣減是 race-safe 的：訂一段區間時，每一晚都要夠才成立，任一晚不足則整筆失敗（不超賣、不部分成立）。

散客直訂

散客直訂是訂房最直接的成交路徑：選物件 / 房型 / 日期，扣每晚庫存，開一張 kind='lodging' 的訂單。

POST /lodging/bookings 帶 propertyId / roomTypeId / checkIn / checkOut / units（間數或床數）/ guestCount（入住人數）/ bookerEmail / paymentMethod（cash 現金 / atm 虛擬帳號 / manual 其他人工）。庫存不足會被擋下、不建單。

其餘端點：GET /lodging/bookings 列表（可帶 status / q 篩選）、.../{orderId} 取單筆詳情、.../{orderId}/cancel 取消。取消會釋回每晚庫存，但不自動退款——退款另走訂單的退款流程。

行程配套

第二條通路是把住宿綁進滑雪等行程：行程設計時固定指定一間物件 + 房型 + 入住幾晚，出團時對那幾晚整塊預留團體床位。

客人報的是行程訂單（kind='tour'），住宿由團體 block 涵蓋，報名時不再各自扣房況。
配套的 block 與散客直訂扣同一份每晚庫存——所以同一物件不會被兩條通路超賣。
前台行程頁顯示所指定物件的細節（設施 / 房型 / 照片），純資訊、不在行程頁單獨下訂住宿。

說明

散客直訂與行程配套是訂房的兩條通路，共用同一份每晚房況。這是訂房模型的核心不變量：任何一晚的「已訂」是兩條通路相加，CHECK 守住不超賣。

訂房訂單如何接金流

訂房單成交後就是一張普通訂單，套用訂單與金流模型的全部規則，差別只在「賣的是住宿、逐晚計價」：

訂單外殼是 kind='lodging'，一樣帶三軸狀態（bookingState / paymentState / refundState）。
每一晚的應收是一筆獨立的應收明細；折扣、加價、退款都是明細，外殼不存彙總額。
收款走付款流程同一套機制——現金即時入帳、ATM 取號後等繳費、線上刷卡走 redirect + webhook。
已付款後變更住宿內容，新增一筆應收明細產生補款，不會靜默改大原訂單。

所以你不需要為訂房學一套新的金流語意：拿到 orderId 後，讀訂單、收款、退款都跟 tour 訂單一致。

下一步

訂單與金流模型：應收、現金、三軸狀態與退款的全貌。
付款流程：收款生命週期、redirect、webhook。
lodging API · orders API。