toko

訂單與金流模型

訂單不存一個「總額」。客人欠多少、付了多少、退了多少,都由一筆一筆的明細算出來。

訂單列表與 GET /api/v1/orders 同時包含行程訂單與訂房單。回應的 kind 為 tour 或 lodging。訂房單的 tripTitle 是旅宿名稱,departureDate 與 returnDate 是入住日與退房日,tripId 與 departureId 為空字串。後台列表的行程、出發日、同意書、分房、抽籤與派發欄對訂房單留空:同意書與審單派發只用在行程訂單。使用行程、梯次、同意書、分房、抽籤或派發篩選時,只列行程訂單。

一張訂單的錢怎麼算

一張訂單有四種明細。後台訂單頁的「款項」分頁逐一列出:

明細記什麼例
應收明細客人為什麼欠錢。折扣與少收是負數。團費 2 人、折扣碼、房型升級
收款計畫應收分幾期收、每期何時到期。訂金 3,000、尾款 7,000
收款每一次「打算收」的錢,例如一條付款連結。尾款刷卡連結
現金紀錄真正收到或退出的錢。報表只認這一層。綠界入帳 3,000

訂單上的金額都從明細算出:

  • 應收 = 全部應收明細加總。
  • 已收 = 全部收進來的現金。
  • 已收淨額 = 已收 − 已退還給客人的現金。
  • 尚欠 = 應收 − 已收淨額。

所以折扣、加價、房升補款都是應收明細裡的一列,不是改訂單上的某個數字。付款後加價時,系統新增一列應收,訂單重新出現尚欠,再產生補款連結。系統不會把已付訂單的金額直接改大。

金額都是整數台幣。客人一律付台幣。

›訂單回傳的金額欄位

GET /orders/{id} 回傳的金額都是派生值,不能直接設定。訂單沒有 total 與 paidAt 欄位。

欄位意義
orderNumber訂單編號
kindtour(梯次團)或 lodging(住宿)
grossReceivableTwd應收(chargeLines 加總,含負數)
collectedTwd已收現金,含保留款轉入。已取消訂單對帳讀 accounting.cancelledCash
customerCashAppliedTwd已收淨額(已收 − 已退)
outstandingTwd尚欠(應收 − 已收淨額)
refundableCashTwd可退現金(已收淨額 − 已執行退款的手續費)。實際可退款額度另見取消與退款指南。
actions呼叫者現在可做的動作,與不可做的原因
chargeLines / schedules / intents / transactions / travelers應收明細、收款計畫、收款、現金紀錄、旅客

讀取用 GET /orders(依角色自動限縮可見範圍)與 GET /orders/{id}。判斷能不能補尾款、開付款連結,請讀 actions,不要只看 paymentState。

怎麼看訂單狀態

訂單沒有單一的「狀態」欄。系統分三個面向記錄,後台再合成一個標籤顯示:

面向問的是可能的值
訂位這張單成立了沒有待付款 → 已確認 → 已完成;任一階段都可能已取消
付款應收被現金蓋住多少未付、部分付款、已付訂金、已付款、多付
退款退過減應收的退款嗎無、部分退款、已退款

後台列表與訂單頁的標籤依這個順序取第一個符合的:已取消 → 已退款 → 部分退款 → 已完成 → 付款面向(待付款、部分付款、已付訂金、多付、已付款)。

›三軸狀態值
txt
bookingState : pending_payment → confirmed → completed ;(任一 → cancelled)
paymentState : unpaid | partially_paid | deposit_paid | paid | overpaid
refundState  : none | partially_refunded | refunded

後台標籤的對應:cancelled 已取消、refunded 已退款、partially_refunded 部分退款、completed 已完成、unpaid 待付款、partially_paid 部分付款、deposit_paid 已付訂金、overpaid 多付、paid 已付款。

只有減應收的退款計入 refundState。退還多付的錢、取消後退回現金都不計入,詳見取消與退款。

建立訂單(K 單)

承辦代客人建單,叫做 K 單。從頂列「新增」選單或 ⌘K 選「K 單」。

K 單需要行程模組。未開通時隱藏入口,POST /orders 回 403 module_disabled。獨立訂房建單不受影響。既有行程訂單仍可收款與退款。

  1. 選行程與梯次。訂購人須為會員:從會員資料搜尋帶入,或輸入會員註冊的 Email。
  2. 填旅客。第 1 位是主要聯絡人。證件等資料可以先建單、之後補。
  3. 選訂購人分類,決定套直客價或同業價。
  4. 需要時填「少收申請與尾款到期日」。少收要由管理員核准才生效。
  5. 選付款方式,勾選條款,建立訂單。

規則:

  • 可以先存草稿。 草稿不佔名額,也不產生應收。只有建立者看得到、改得到。送出時重新檢查名額與資料,同一份草稿重送不會建出兩張單。
  • 建單就保座。 名額不夠時建單失敗。
  • 尾款到期日可以指定。 留空時照行程規則。期限是台北時間當日結束。抽籤梯次不能指定,期限在中籤當天加上公司設定的天數。
  • 登山行程可以先預覽資格。 預覽只用這次填的登山經歷,不查證件或過去紀錄。建單時重新計算,預覽不能代替審核。
›建單 API
  • POST /orders 帶 tripId、departureId、travelers、paymentMethod 等。名額不足回 409 conflict。旅客的 birthDate 須是存在的 YYYY-MM-DD 日期,否則回 422 validation。一般訂單的 idNumber/passportNo 可後補;受管制抽籤須擇一,受限名額須 idNumber。缺件時回 422 validation 並指出第幾位旅客(見旅客與個資)。
  • 建單前試算金額用 POST /orders/quote,見折扣碼與分潤。
  • 登山資格預覽用 POST /orders/screening-preview,帶 departureId 與 travelers[].climbingRecords。每筆經歷只給 label 與選填的 hasAlpineExperience,分數由公司的路線分級表算。需要 order.create 與登山模組。
  • K 單草稿只有後台入口。

調整應收:掛帳與少收

訂單金額要改時,在訂單頁「款項」分頁按「掛帳 / 少收」:

  • 掛帳:加收一筆,例如加購保險。
  • 少收:減收一筆,例如議價。

兩者都新增一列應收明細,必填原因。登記後不能刪除;填錯時用沖正,把那一列抵銷。

少收要不要經管理員核准

在「後台 → 公司設定 → 付款設定 → 少收核准」開啟「少收必須經核准」後:

  • 管理員以外的人只能掛帳,不能直接少收。
  • 沖正只限自己開的掛帳列。
  • 跨行程換梯時,不能填負數的人工調整。

要少收時,在訂單頁送「手動少收申請」。規則:

  • 待核准的金額不影響應收、試算與收款。
  • 送出時,鈴鐺通知可核准的管理員。管理員的工作台另有「少收待核」清單。已取消或已完成的訂單不列入。
  • 管理員在訂單頁核准或拒絕,結果通知申請人。拒絕可填原因。撤回不通知。
  • 送出後訂單金流有變動時,原申請不能核准。請撤回後重新申請。
  • 核准只減應收,不會自動退款。
›調整 API 與錯誤碼
  • 掛帳與少收:POST /orders/{id}/adjust,kind 為 surcharge(掛帳)或 allowance(少收)。需要 order.adjust。
  • 沖正:POST /orders/{id}/reverse。
  • 開啟「少收必須經核准」時,非管理員送 kind: "allowance" 回 409 conflict;沖正別人開的列、團費、折扣、少收或匯入列也回 409 conflict。
  • 手動少收申請與核准只有後台入口。

派發與搶單

客人在前台自己下的訂單,要指派給一位業務,才計入那位業務的業績。派發模式、手動派發與通知規則見訂單派發。

公司開啟「開放業務自派搶單」後,業務可在訂單列表選「可搶單」篩選,自己接下待派發的訂單。搶到之前只看得到非個資欄位。

›搶單 API

POST /orders/{id}/claim:需要 order.claim,且公司開啟搶單。

登山資格審核

登山行程的訂單建立時,系統依旅客的登山經歷算出能力分。能力不足的旅客標成「待人工審核」,不擋下單也不擋收款。判定方式見旅客與個資。

待審訂單在「後台 → 訂單 → 派發 / 資格審核」處理:

  • 核可:旅客通過。
  • 駁回:必須選一種處置,系統只記錄,不會自動取消、換團或退款。
處置後續
補件重審等客人補經歷。訂單標成待回覆。
換團請客人選別的梯次。訂單標成待回覆。
退款轉退款作業,不標待回覆。

可以一次裁決整張單,也可以只裁決一位旅客。可附通知範本寄信給客人;寄信失敗不撤回裁決。客人回覆並處理完成後,按「標記已解決」解除待回覆。

›審核 API
  • POST /orders/{id}/review-screening:decision 為 approve 或 reject。駁回必帶 disposition(resupplement、switch_trip、refund),未帶回 422。核可不接受 disposition。
  • 選填 travelerId 只裁決該旅客。重新裁決過期的人工結果時帶 redecide: true 與 travelerId。
  • 選填 templateId 寄通知,核可與駁回都可帶。note 會填入範本的 {{補充說明}}。回應 emailSent 表示已排入寄送佇列。不要因 emailSent: false 重送裁決。
  • 結束待回覆:POST /orders/{id}/resolve-screening-follow-up。沒有待回覆時回 409。
  • 需要 screening.review 與登山模組。未知欄位回 422。
  • CLI:orders review-screening <id> --decision reject --disposition resupplement --traveler-id <id> --template-id <id> --confirm;核可寄通知用 --decision approve --template-id <id>;重新裁決加 --redecide;orders resolve-screening-follow-up <id> --confirm。

訂單對話

每張訂單都有一條與訂購人的留言串,客人不用先開口。最後一則是客人留言時,對話變成待回覆;承辦回覆或按「標記已解決」後解除。

所有待回覆的對話集中在「後台 → 訂單 → 訂單對話」。要讓外部機器人讀取待回覆清單,見待回覆留言機器人。

舊轉單鏈的訂單

從舊系統搬入的部分訂單是一條「轉單鏈」:客人先報 A 團,再轉到 B 團,錢留在 A。這類訂單今天仍會遇到,規則如下:

  • 舊單收到的錢留在舊單。轉過來的金額叫「結轉款」,用來抵減目前這張單的應收,不算進這張單的已收。
  • 所以結轉款已付清訂金時,這張單仍可能顯示待付款或部分付款。補尾款、開付款連結、寄尾款繳款單照常可用。
  • 訂單頁「訂單細項」列出全鏈累計入款、有效結轉款與全鏈已退現金。

例:舊單已收 8,000,新團費 10,000。這張單還沒收錢時,尚欠 2,000。再收 500 後,尚欠 1,500。

舊鏈訂單換梯與取消的規則見換梯與拆單與取消與退款。

相關指南

Command Palette

Search for a command to run...