行程與梯次
一個「行程」是你上架的產品定義；真正被報名、被扣席、被開團號的是它底下的「梯次」。客人買的永遠是某一個梯次。
理解這層關係，你才能正確使用 GET /trips 與梯次相關端點——行程帶目錄與行銷內容，梯次帶日期、名額與售價。
行程與梯次的關係
一個行程（trip）是產品目錄上的一張卡：標題、目的地、天數、起價、上架狀態。它不是可賣的單位——它底下掛梯次（departure），每個梯次有自己的出發日、回程日、名額與售價，才是客人實際報名的對象。
| 概念 | 是什麼 | 在 API 上 |
|---|---|---|
| 行程 trip | 產品定義（目錄 / 行銷內容） | /trips |
| 梯次 departure | 可賣的出團單位（日期 + 名額 + 售價） | /departures |
行程的 status 是 draft（草稿）/ published（上架）/ archived（封存）；梯次的 status 是 selling（銷售中）/ closed / cancelled / completed。列表回傳的 activeDepartureCount、nextDepartureDate 讓你不必逐筆展開就知道一個行程有沒有在賣、下一梯何時出發。
訂房（lodging）不走這個模型。 住宿產品是每晚房型庫存，沒有「梯次」概念。本篇只談梯次團（tour）。
席次與保座
每個梯次有名額（capacity）與已報名數（bookedCount）。報名時平台用保座方式扣席——不是「先讀再寫」，而是條件式扣減，所以多人同時搶最後幾個位子不會超賣。
名額不足時，建立訂單會回 409 conflict。這是預期行為，不是錯誤——代表這個梯次在你送出的當下已經滿了。請以重新整理名額、或改報其他梯次來處理，不要重試同一筆。
取消訂單會把席次釋回該梯次，名額即時反映。
價格通路（直客 / 同業）
同一個梯次對不同客戶可能有不同售價。成交單價由平台依通路解析，順序大致是：梯次優惠價 → 梯次價 → 行程起價，缺價則拒絕結帳。
| 通路 | 意義 |
|---|---|
| 直客（direct） | 一般客人價 |
| 同業（agency） | 旅行同業窗口價 |
| 優惠（promo） | 梯次層的活動覆寫價 |
成交當下，平台會把當時的單價與通路快照寫進訂單明細——之後你改梯次或行程價格，不會回寫已成立的訂單。客戶分類只是結帳時的預設通路，不是訂單事實；訂單的價格事實永遠在那張單的明細上。
團號
團號是梯次的對外識別碼，貫穿報名、開票、估價、出團通知與對帳。它編碼了出團年份、地區（山域）、出發日與同日同地的流水序；海外線多帶一段航空碼：
國內團（無航空）：26 YS 1010 A → 26YS1010A
海外團（有航空）：26 EG TK 1010 A → 26EGTK1010A
YY 地區 [航空] MMDD 序號
- 自動產生：選好地區、（海外才有的）航空與出發日，平台拼出團號並配同地區同日的序號（A / B / C…）。團號在租戶內唯一，併發產生不會撞號。
- 可覆寫：需要沿用舊系統團號或特例時可手填，仍須過唯一與格式檢查。
- 可搜尋：
GET /trips的groupCode參數用團號（前綴亦可）回查含該團號梯次的行程；列表的representativeGroupCode是該行程近期的代表團號。
地區碼與航空碼是每個租戶自行維護的對照表（/group-codes），新增線路不需要改任何程式。停用的碼不再出現在新梯次的選項，但既有團號保留。
抽籤與備案行程
熱門梯次（國家公園山屋床位、permit 配額）的名額不是先到先得，而是抽籤決定。把梯次的分配模式設成抽籤（PATCH /departures/{id}/allocation-mode 的 mode = lottery），它底下的訂單就從「報名」變成「應募」。
抽籤演算法本身不在 cairn 裡——它留在租戶既有的試算表流程。cairn 負責的是抽籤的地基與結果落地：每筆應募訂單有自己的抽籤狀態（已應募 → 中籤 / 未中籤），由線控逐單裁決。應募即扣本梯次的席（代表「誰報了這梯」），抽籤搶的是外部稀缺資源、不是 cairn 的席次。
裁決有三個出口：
旅客報名抽籤梯次時，可從同行程的其他梯次自選一串有序備案（可混先到先得與抽籤梯次）。未中籤時，平台沿這串清單鏈式自動轉單：遇先到先得且有位即當下成立、遇抽籤梯次則重新應募等下一輪、清單走完才退訂金。轉單過程訂金一路結轉、自動催尾款，全程不用人工逐筆搬。備案候選一律與主梯同價，所以跨單結轉不會產生價差。
與訂單的銜接
客人報名某個梯次，就是建立一張 tour 訂單：訂單明細指向該梯次，人數（partySize）掛在訂單上。價格、訂金 / 尾款怎麼拆、收了多少，全部由訂單的金流模型接手——梯次只提供「賣什麼、什麼價、還有沒有位」。
下一步
- 訂單與金流模型：報名之後，應收、現金與三軸狀態的全貌。
- 付款流程：收訂金 / 尾款、redirect、webhook。
- trips API · departures API · group-codes API。