團控分房

一句話：團控分房管理 tour departure 的住宿房間、旅客分配、房型升級補款與對外分房表；它是 per-departure 工作，入口固定從 /admin/control 進。

• 關聯：trips · travelers · orders · order-money-model · control-finance

1. 範圍

本檔擁有：

• departure rooms / room beds；
• traveler room assignment；
• gender、room preference、roommate preference；
• auto-pair suggestion；
• 分房表匯出；
• 房型升級補款與沖正的業務規則。

不擁有：

• 旅宿庫存池：見 lodging-inventory。
• 供應商請款核簽：見 control-finance。
• 退款工作流：見 order-money-model。

2. 資料責任

房費成本可在團控財務彙總，但分房表對外匯出不顯示成本。

3. 下單時需求登記（preference capture）

分房分兩階段：下單登記需求（業務 / 主管在 K 單或訂單頁登記）→ 團控確認排房（per-departure 權威指派）。下單登記的是旅客的分房偏好，寫入 travelers.room_preference 與 travelers.roommate_pref；它不指派實際房間 / 床位（travelers.room_id 一律由團控寫入）。

每位旅客四選一：

「全部自動分房」是一鍵把整張訂單所有旅客設為 auto 的捷徑。

單人房補款時點：下單勾「加價單人房」不立即產生應收。補款一律在團控把旅客排進升級 / 單人房型時，依 §5 規則 append order_charge_lines(type='room_upgrade') 並重算金流；下單階段不動 orders 應收，金流唯一真相維持在團控。

需求登記不改變既有不變式：分房 SSOT 仍在團控，下單需求只作為團控 auto-pair 的起點提示與待辦。

4. 分房規則

分房需符合：

• 每個 traveler 至多一個 active room assignment。
• 每間房不可超過 capacity / bed count。
• gender hard constraint 預設啟用；other 或缺值需人工確認。
• 指定房友優先於自動配對建議。
• 特殊需求不自動保證，只提示線控。

auto-pair 吃 §3 下單登記的 room_preference / roommate_pref 作為起點，只產生建議，不直接覆寫已儲存分房。線控確認後才寫入 room_assignments 並記 audit。

5. 房型升級補款

房升補款是訂單應收的一部分，必須接金流模型：

1. traveler 移入升級房型；
2. 系統依規則計算補款；
3. append order_charge_lines(type='room_upgrade', source_type='room_upgrade')；
4. reconcile payment_schedules，必要時建立 adjustment schedule / intent；
5. 重算 order money state；
6. 寫 audit。

移出升級房型或改回原房型時，不修改原 charge line；append 反向 charge line 或 reversal，再重算 schedule。

已全額付款的訂單若新增補款，UI 應顯示待補款狀態與付款入口；不得把原 paid 狀態靜默維持成「已結清」。

6. 匯出

分房表匯出給：

• 線控內部；
• 旅宿 / 山屋 / 嚮導；
• 保險或入山文件輔助。

匯出欄位只包含作業所需資料：姓名、性別、房號、床位、房友、特殊需求、聯絡資訊摘要。敏感欄位遵守 travelers 與 passport specs 的遮罩規則。

7. UI

實際排房（房間 / 床位 / 升級補款）權威入口：

• 入口：/admin/control/[departureId]/rooms。
• 不新增 sidebar nav。
• 畫面需支援：房間列表、未分配旅客、拖放 / 選單分房、衝突提示、auto-pair preview、匯出、補款狀態提示。
• 所有表單控制使用 admin design system primitives。

下單時需求登記（§3 preference capture）分散三個 surface，皆不開新 sidebar nav：

• 業務 K 單（/admin/orders-new）：旅客名單步驟內每位旅客一個分房需求選擇器 + 「全部自動分房」捷徑。
• 訂單明細（/admin/order-detail）：「分房」tab 檢視 / 修改需求，並顯示團控分房現況（待團控分房 / 已排房號），含前往團控連結。
• 訂單列表（/admin/orders）：分房狀態欄（未登記 / 已登記 / 需單人房 / 已分房）+ 篩選。

Changelog