訂單與金流模型
一張訂單把「賣了什麼」「客人欠多少」「收了多少」「退了多少」拆成獨立明細；訂單上的金額與狀態都是這些明細算出來的結果。
理解這點，你才能正確解讀 GET /orders/{id} 回傳的欄位——外殼上的 *Twd 與狀態都是派生值，不是你直接設定的欄位。
訂單物件
一張訂單（order）是與產品種類無關的外殼（kind 為 tour 或 lodging）。它本身不帶總額——金額來自下面幾組明細，訂單上看到的 *Twd 與狀態欄位都是派生值：
| 欄位（回傳） | 意義 |
|---|---|
orderNumber | 訂單編號 |
kind | tour（梯次團）或 lodging（住宿） |
bookingState / paymentState / refundState | 三軸狀態（見下） |
grossReceivableTwd | 應收總額（chargeLines 加總） |
collectedTwd | 已收現金 |
customerCashAppliedTwd | 已套用到此單的客人現金（已收 − 已退） |
outstandingTwd | 尚欠 = 應收 − 已套用現金 |
chargeLines / schedules / intents / transactions / travelers | 各類明細陣列 |
訂單外殼沒有 total、沒有 paidAt。要知道客人欠多少看 outstandingTwd，收了多少看 collectedTwd——這些都由明細即時算出。
金額怎麼來
金額都是整數台幣（客人一律付台幣）。回傳的金額欄位對應這組白話關係：
應收 grossReceivableTwd = 所有 chargeLines 金額加總（含折扣為負）
已收 collectedTwd = 所有收進來的現金
已套用 customerCashAppliedTwd = 已收 − 退給客人的現金
尚欠 outstandingTwd = 應收 − 已套用
所以折扣、加價、房升補款都是 chargeLines 裡的一筆（折扣是負數），不是訂單上某個彙總欄位。
三軸狀態
訂單沒有單一「狀態」。顯示狀態由三個獨立軸組成：
bookingState : pending_payment → confirmed → completed ;（任一 → cancelled）
paymentState : unpaid | partially_paid | deposit_paid | paid | overpaid
refundState : none | partially_refunded | refunded
paymentState = paid 不代表錢還在手上——它只代表「應收已被現金覆蓋」。一張全額退款的訂單，paymentState 仍是 paid，退款狀態由 refundState 表達（與 Stripe 全退的 PaymentIntent 仍 succeeded 同理）。畫狀態標籤請三軸一起看，不要只看 paymentState。
退款的兩種意義
退款分兩種，務必分清：
| 種類 | 動應收嗎？ | 算進 refundState？ |
|---|---|---|
| 減應收退款（取消 / 降價 / 服務未提供） | 是——同時調降 grossReceivableTwd | 是 |
| 溢收退還（退多收的錢） | 否——只退現金 | 否 |
退款本身有自己的工作流狀態：
draft → submitted → approved → processing → paid
submitted → rejected ; approved → cancelled ; processing → failed
對應 API：POST /orders/{id}/refunds 建立、.../refunds/{refundId}/approve、/mark-paid、/reject。
常見流程
建立 tour 訂單：POST /orders 帶 tripId / departureId / travelers / paymentMethod 等，平台會以保座方式建單（座位不足回 409 conflict），並依付款方案產生收款計畫。
付款後加價（如房型升級）：平台新增一筆 chargeLines → 訂單重新出現 outstandingTwd → 產生補款連結。不會靜默把已付訂單金額改大。
讀取：GET /orders 列表（依角色自動限縮可見範圍），GET /orders/{id} 取完整訂單（含旅客、應收、現金、收款計畫、退款、同意書）。每個欄位的型別見 API 參考的回應欄位表。
下一步
- 付款流程：收款、redirect、webhook、ECPay 設定。
- 總覽：認證、權限、模組。
- orders API · CLI orders。