CLI 參考
進階套組cairn <resource> <verb> 全 259 命令，依領域分類。每條標出對應的 /api/v1 端點與回應欄位；寫入命令對 production target 需 --confirm。按 ⌘K 搜尋。
開始使用
cairn CLI 是 API 的命令列封裝——你（或你的 agent）在終端機操作租戶後台，走跟後台網頁完全相同的業務規則、 權限與稽核。整個 CLI 自我描述：cairn help 列出所有資源、cairn <resource> help 列出該資源的命令，不必背。
認證走 OAuth 2.0 device flow：先 cairn target add 設定要操作的租戶網域，cairn login 取得驗證碼、到瀏覽器（已登入、含 2FA）核准後 CLI 拿到 bearer token——終端機從不輸入密碼。token 按 target 各存一份、隨租戶網域天然隔離；權限沿用你帳號的角色，CLI 不會給你後台沒有的能力。
輸出預設是給人看的精簡表格；加 --json 就回 API 的原始 JSON，方便管線與 agent 解析。
bun run cairn help cairn target add demo https://your-tenant.example.com cairn login # 開瀏覽器核准 device code cairn whoami cairn orders list --status pending_payment cairn orders list --status pending_payment --json
命令結構
絕大多數命令都是同一個形狀：cairn <resource> <verb> [positional] [--flags]。positional 通常是主鍵 id，flags 是篩選／欄位／選項。
全域旗標所有命令通用：--target <name> 單次指定要打的 target、--json 機器可讀輸出、--confirm 對 production 寫入時必帶（見下）。
CLI 不是另一條捷徑——每個命令對應一個 /api/v1 端點，走相同的權限檢查與稽核。下方參考每條命令都標出對應端點（可點擊跳到 API 參考），回應欄位即該端點的回應。
cairn target list cairn target use demo cairn orders list --target staging # 單次覆寫
Production 安全
把正式環境的 target 標成 production，CLI 就會在任何寫入命令上要求 --confirm，避免手滑打到正式資料。讀取命令不受影響。
--confirm 只是 client 端的減速丘，不是授權：每個寫入端點都會在 server 重跑權限檢查，權限不足一律回 403 forbidden；owner-scope 也由 server 依你的 token 重算——業務經 CLI 一樣只看得到自己經手的訂單。
cairn target add prod https://your-tenant.example.com --production cairn orders mark-paid <id> # ✗ 需 --confirm cairn orders mark-paid <id> --confirm # ✓
cairn discount-codes
折扣碼：列表、明細、預覽試算、兌換報表
cairn discount-codes list列出所有折扣碼
參數
--json回應欄位 · data[]
id折扣碼 id（disc_ 前綴）。
code折扣碼字串（客戶結帳輸入用，租戶內唯一）。
label折扣碼顯示名稱（後台辨識用）。
discountType折扣型別：fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值：fixed 為 TWD 整數，percentage 為百分比數字。
profitShareType分潤型別：fixed 定額 / percentage 比例；null = 無分潤。
profitShareValue分潤值：fixed 為 TWD 整數，percentage 為百分比；null = 無分潤。
profitSharePayee分潤受款對象（如合作夥伴名稱）；null = 無。
isActive是否啟用（停用後不可再兌換）。
validFrom生效起始時間；null = 無下限。
validUntil生效截止時間；null = 無上限。
maxRedemptions總兌換次數上限；null = 不限。
redemptionCount已兌換次數（不含已取消訂單）。
minOrderTwd最低訂單金額門檻（TWD 整數）；null = 無門檻。
appliesToAll是否適用所有行程（true = 全站，false = 僅限 tripIds 名單）。
maxRedemptionsPerCustomer每位客戶兌換次數上限；null = 不限。
allowedPriceChannels限用的價格通路清單（如 direct / agency）；null = 不限。
allowedCustomerTypes限用的客戶類型清單；null = 不限。
stackable是否可與其他折扣疊加使用。
notes內部備註；null = 無。
createdAt建立時間。
cairn discount-codes list
{
"ok": true,
"data": [
{
"id": "…",
"code": "…",
"label": "…",
"discountType": "…",
"discountValue": 0,
"profitShareType": null,
"profitShareValue": 0,
"profitSharePayee": "…",
"isActive": true,
"validFrom": null,
"validUntil": null,
"maxRedemptions": 0,
"redemptionCount": 0,
"minOrderTwd": 0,
"appliesToAll": true,
"maxRedemptionsPerCustomer": 0,
"allowedPriceChannels": "…",
"allowedCustomerTypes": "…",
"stackable": true,
"notes": "…",
"createdAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn discount-codes get單一折扣碼完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id折扣碼 id（disc_ 前綴）。
code折扣碼字串（客戶結帳輸入用，租戶內唯一）。
label折扣碼顯示名稱（後台辨識用）。
discountType折扣型別：fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值：fixed 為 TWD 整數，percentage 為百分比數字。
profitShareType分潤型別：fixed 定額 / percentage 比例；null = 無分潤。
profitShareValue分潤值：fixed 為 TWD 整數，percentage 為百分比；null = 無分潤。
profitSharePayee分潤受款對象（如合作夥伴名稱）；null = 無。
isActive是否啟用（停用後不可再兌換）。
validFrom生效起始時間；null = 無下限。
validUntil生效截止時間；null = 無上限。
maxRedemptions總兌換次數上限；null = 不限。
redemptionCount已兌換次數（不含已取消訂單）。
minOrderTwd最低訂單金額門檻（TWD 整數）；null = 無門檻。
appliesToAll是否適用所有行程（true = 全站，false = 僅限 tripIds 名單）。
maxRedemptionsPerCustomer每位客戶兌換次數上限；null = 不限。
allowedPriceChannels限用的價格通路清單（如 direct / agency）；null = 不限。
allowedCustomerTypes限用的客戶類型清單；null = 不限。
stackable是否可與其他折扣疊加使用。
notes內部備註；null = 無。
createdAt建立時間。
tripIds限定適用的行程 id 清單（appliesToAll=false 時生效）。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id（ord_ 前綴）。
orderNumber訂單編號（人類可讀流水號）。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額（TWD 整數）。
discountTwd本次折抵金額（TWD 整數）。
profitShareTwd本次分潤金額（TWD 整數）。
orderStatus訂單當前狀態。
createdAt兌換（下單）時間。
totalDiscountTwd累計折抵金額合計（TWD 整數）。
totalProfitShareTwd累計分潤金額合計（TWD 整數）。
totalPaidTwd兌換訂單累計已收金額合計（TWD 整數）。
cairn discount-codes get <id>
{
"ok": true,
"data": {
"id": "…",
"code": "…",
"label": "…",
"discountType": "…",
"discountValue": 0,
"profitShareType": null,
"profitShareValue": 0,
"profitSharePayee": "…",
"isActive": true,
"validFrom": null,
"validUntil": null,
"maxRedemptions": 0,
"redemptionCount": 0,
"minOrderTwd": 0,
"appliesToAll": true,
"maxRedemptionsPerCustomer": 0,
"allowedPriceChannels": "…",
"allowedCustomerTypes": "…",
"stackable": true,
"notes": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"tripIds": [
"…"
],
"redemptions": [
{
"orderId": "…",
"orderNumber": "…",
"codeSnapshot": "…",
"originalTotalTwd": 0,
"discountTwd": 0,
"profitShareTwd": 0,
"orderStatus": "…",
"createdAt": "2026-06-30T08:00:00.000Z"
}
],
"totalDiscountTwd": 0,
"totalProfitShareTwd": 0,
"totalPaidTwd": 0
}
}cairn discount-codes preview預覽試算折抵（唯讀，不消耗名額）
參數
--code <CODE>欲試算的折扣碼字串
--kind產品種類：tour 行程或 lodging 住宿
--trip-id行程 id（kind=tour 時必填）
--total <twd>試算用原始金額（TWD，未折扣前）
--price-channel價格渠道（direct / agency / promo），用於折扣碼資格判定
--customer-type客戶類型（direct / agency_contact），用於折扣碼資格判定
--user-id客戶 user id，用於每客戶使用次數限制判定
--jsoncairn discount-codes preview --code <CODE> --kind --total <twd>
{
"ok": true,
"data": "…"
}cairn discount-codes redemptions折扣碼兌換 / 分潤報表
參數
<id>位置參數 · 必填--json回應欄位 · data
id折扣碼 id（disc_ 前綴）。
code折扣碼字串。
label折扣碼顯示名稱。
redemptionCount已兌換次數（不含已取消訂單）。
totalDiscountTwd累計折抵金額合計（TWD 整數）。
totalProfitShareTwd累計分潤金額合計（TWD 整數）。
totalPaidTwd兌換訂單累計已收金額合計（TWD 整數）。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id（ord_ 前綴）。
orderNumber訂單編號（人類可讀流水號）。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額（TWD 整數）。
discountTwd本次折抵金額（TWD 整數）。
profitShareTwd本次分潤金額（TWD 整數）。
orderStatus訂單當前狀態。
createdAt兌換（下單）時間。
cairn discount-codes redemptions <id>
{
"ok": true,
"data": {
"id": "…",
"code": "…",
"label": "…",
"redemptionCount": 0,
"totalDiscountTwd": 0,
"totalProfitShareTwd": 0,
"totalPaidTwd": 0,
"redemptions": [
{
"orderId": "…",
"orderNumber": "…",
"codeSnapshot": "…",
"originalTotalTwd": 0,
"discountTwd": 0,
"profitShareTwd": 0,
"orderStatus": "…",
"createdAt": "2026-06-30T08:00:00.000Z"
}
]
}
}cairn discount-codes create建立折扣碼
參數
--code <C>折扣碼字串（前台結帳輸入，不分大小寫須唯一）
--label <t>折扣碼顯示名稱（後台與報表辨識用）
--discount-type折抵方式：fixed 固定金額（TWD）或 percentage 百分比
--discount-value <n>折抵數值；fixed 為折抵金額（TWD），percentage 為百分比（1–100）
--profit-share-type分潤方式：fixed 固定金額或 percentage 百分比；null 為不分潤
--profit-share-value分潤數值；搭配 profitShareType，percentage 須 1–100，null 為不分潤
--profit-share-payee分潤對象名稱（如合作推廣者），供出款對帳辨識
--active--valid-from生效起日（YYYY-MM-DD）；留空為不限起日
--valid-until生效迄日（YYYY-MM-DD）；留空為不限迄日
--max-redemptions全碼可使用總次數上限；null 為不限
--min-order--applies-to-all是否適用全部行程；true 時忽略 tripIds
--trip-ids指定可套用的行程 id 清單（appliesToAll=false 時生效）
--max-per-customer--price-channels--customer-types--stackable是否可與其他折扣碼疊加使用
--notes內部備註（不對外顯示）
--confirm回應欄位 · data
id新建立折扣碼的 id（disc_ 前綴）。
cairn discount-codes create --code <C> --label <t> --discount-type --discount-value <n>
{
"ok": true,
"data": {
"id": "…"
}
}cairn discount-codes update更新折扣碼（送出完整欄位，未帶旗標的欄位沿用表單預設）
參數
<id>位置參數 · 必填--code <C>折扣碼字串（前台結帳輸入，不分大小寫須唯一）
--label <t>折扣碼顯示名稱（後台與報表辨識用）
--discount-type折抵方式：fixed 固定金額（TWD）或 percentage 百分比
--discount-value <n>折抵數值；fixed 為折抵金額（TWD），percentage 為百分比（1–100）
--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn discount-codes update <id> --code <C> --label <t> --discount-type --discount-value <n>
{
"ok": true,
"data": {
"ok": true
}
}cairn discount-codes set-active啟用 / 停用折扣碼
參數
<id>位置參數 · 必填--active--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn discount-codes set-active <id> --active
{
"ok": true,
"data": {
"ok": true
}
}cairn group-codes
團號：碼表（地區/航空）與團號反查
cairn group-codes regions地區碼對照表
參數
--active-only--jsoncairn group-codes regions
cairn group-codes airlines航空碼對照表
參數
--active-only--jsoncairn group-codes airlines
cairn group-codes lookup精確團號反查單一梯次
參數
<groupCode>位置參數 · 必填--json回應欄位 · data
id梯次 id（dep_ 前綴）。
tripId所屬行程 id（trip_ 前綴）。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日（ISO 'YYYY-MM-DD'）。
groupCode完整團號。
regionCode地區代碼；null = 未設。
airlineCode航空公司代碼；null = 國內團或未設。
cairn group-codes lookup <groupCode>
{
"ok": true,
"data": {
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureDate": "…",
"groupCode": "…",
"regionCode": "…",
"airlineCode": "…"
}
}cairn group-codes search前綴團號反查多梯次
參數
<prefix>位置參數 · 必填--json回應欄位 · data[]
id梯次 id（dep_ 前綴）。
tripId所屬行程 id（trip_ 前綴）。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日（ISO 'YYYY-MM-DD'）。
groupCode完整團號。
regionCode地區代碼；null = 未設。
airlineCode航空公司代碼；null = 國內團或未設。
cairn group-codes search <prefix>
{
"ok": true,
"data": [
{
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureDate": "…",
"groupCode": "…",
"regionCode": "…",
"airlineCode": "…"
}
]
}cairn group-codes region-create新增地區碼
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱（如地區或航空公司全名）
--order--inactive回應欄位 · data
ok操作成功旗標，恆為 true。
code新增或更新的地區代碼。
cairn group-codes region-create <code> --name <名>
{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}cairn group-codes region-update更新地區碼（name / 啟用 / 排序，不改碼）
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱（如地區或航空公司全名）
--order--inactive回應欄位 · data
ok操作成功旗標，恆為 true。
code新增或更新的地區代碼。
cairn group-codes region-update <code> --name <名>
{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}cairn group-codes airline-create新增航空碼
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱（如地區或航空公司全名）
--order--inactive回應欄位 · data
ok操作成功旗標，恆為 true。
code新增或更新的航空公司代碼。
cairn group-codes airline-create <code> --name <名>
{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}cairn group-codes airline-update更新航空碼（name / 啟用 / 排序，不改碼）
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱（如地區或航空公司全名）
--order--inactive回應欄位 · data
ok操作成功旗標，恆為 true。
code新增或更新的航空公司代碼。
cairn group-codes airline-update <code> --name <名>
{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}cairn holidays
國定假日 / 補班表：查詢、年度統計
cairn holidays list列出假日 / 補班（可依年度篩選）
參數
--year--jsoncairn holidays list
cairn holidays stats某年度假日 / 補班計數
參數
--year要統計的西元年份（1000..9999，必填）
--json回應欄位 · data
holidayCount該年度放假日數。
makeupCount該年度補班日數。
cairn holidays stats --year
{
"ok": true,
"data": {
"holidayCount": 0,
"makeupCount": 0
}
}cairn holidays upsert新增 / 覆寫一筆假日或補班（date 為自然鍵）
參數
--date假日 / 補班日的日期（YYYY-MM-DD，路徑參數），作為該筆紀錄的自然鍵
--name假日 / 補班日名稱（如「春節」「補行上班」）
--makeup--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn holidays upsert --date --name
{
"ok": true,
"data": {
"ok": true
}
}cairn holidays delete刪除一筆假日 / 補班
參數
--date假日 / 補班日的日期（YYYY-MM-DD，路徑參數），作為該筆紀錄的自然鍵
--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn holidays delete --date
{
"ok": true,
"data": {
"ok": true
}
}cairn images
圖片庫：查詢圖片、行程選單
cairn images list列出/搜尋行程圖片
參數
--trip-id行程 ID 篩選，僅回傳掛在該行程的圖片
--q關鍵字，模糊比對行程標題、slug、圖說或網址
--page分頁頁碼，從 1 起算，預設第 1 頁
--page-size每頁筆數，上限 200，預設由後端決定
--json回應欄位 · data
rows當頁圖片列。
id圖片資源 id（timg_ 前綴）。
tripId所屬行程 id（trip_ 前綴）。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
url圖片公開 URL。
caption圖說文字；null = 無。
displayOrder在行程相簿中的排序（由小到大）。
createdAt上傳建立時間。
total符合條件的總筆數（跨頁）。
page目前頁碼（1 起算）。
pageSize每頁筆數。
cairn images list
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"url": "…",
"caption": "…",
"displayOrder": 0,
"createdAt": "2026-06-30T08:00:00.000Z"
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn images trips可掛圖的行程選單（draft + published）
參數
--json回應欄位 · data[]
id行程 id（trip_ 前綴）。
title行程標題。
cairn images trips
{
"ok": true,
"data": [
{
"id": "…",
"title": "…"
}
]
}cairn images create掛圖到行程（以網址）
參數
--trip-id <id>行程 ID 篩選，僅回傳掛在該行程的圖片
--url <https://…>圖片網址（http 或 https），以引用方式掛載，非檔案上傳
--caption圖片說明文字，選填
--display-order排序權重，數字越小越前面，預設 0
--confirm回應欄位 · data
id新建立圖片的 id（timg_ 前綴）。
cairn images create --trip-id <id> --url <https://…>
{
"ok": true,
"data": {
"id": "…"
}
}cairn images delete刪除行程圖片
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn images delete <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging
旅宿：物件、房型、可用量、訂房、統計
cairn lodging properties列出旅宿物件
參數
--json回應欄位 · data[]
id住宿館 id（prop_ 前綴）。
lengthReturns the length of a String object.
slug網址 slug（公開站路徑，租戶內唯一）。
name住宿館名稱。
kind類型：hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述；null = 未設。
description簡介文字；null = 未設。
contentMdx內文（MDX 原始碼）；null = 未設。
facilities設施清單（JSON）；null = 未設。
coverImageUrl封面圖 URL；null = 未設。
usageHint用途：direct 散客直訂 / package 梯次配套 / both 兩者皆可。
checkInTime入住時間文字（如「15:00」）；null = 未設。
checkOutTime退房時間文字（如「11:00」）；null = 未設。
checkInInfo入住須知；null = 未設。
houseRules館內規範；null = 未設。
cancellationPolicy取消政策；null = 未設。
addressRegion地址：縣市／區域；null = 未設。
addressLocality地址：鄉鎮／地區；null = 未設。
streetAddress街道地址；null = 未設。
postalCode郵遞區號；null = 未設。
latitude緯度；null = 未設。
longitude經度；null = 未設。
phone聯絡電話；null = 未設。
petsAllowed是否允許攜帶寵物；null = 未設。
smokingAllowed是否允許吸菸；null = 未設。
status狀態：active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫；null = 沿用內容欄。
seoDescriptionSEO 描述；null = 未設。
ogImageUrlOpen Graph 分享圖 URL；null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
cairn lodging properties
{
"ok": true,
"data": [
{
"id": {
"length": 0
},
"slug": "…",
"name": "…",
"kind": "…",
"isOverseas": true,
"location": "…",
"description": "…",
"contentMdx": "…",
"facilities": "…",
"coverImageUrl": "…",
"usageHint": "…",
"checkInTime": "…",
"checkOutTime": "…",
"checkInInfo": "…",
"houseRules": "…",
"cancellationPolicy": "…",
"addressRegion": "…",
"addressLocality": "…",
"streetAddress": "…",
"postalCode": "…",
"latitude": 0,
"longitude": 0,
"phone": "…",
"petsAllowed": true,
"smokingAllowed": true,
"status": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn lodging property單一旅宿物件
參數
<id>位置參數 · 必填--json回應欄位 · data
id住宿館 id（prop_ 前綴）。
lengthReturns the length of a String object.
slug網址 slug（公開站路徑，租戶內唯一）。
name住宿館名稱。
kind類型：hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述；null = 未設。
description簡介文字；null = 未設。
contentMdx內文（MDX 原始碼）；null = 未設。
facilities設施清單（JSON）；null = 未設。
coverImageUrl封面圖 URL；null = 未設。
usageHint用途：direct 散客直訂 / package 梯次配套 / both 兩者皆可。
checkInTime入住時間文字（如「15:00」）；null = 未設。
checkOutTime退房時間文字（如「11:00」）；null = 未設。
checkInInfo入住須知；null = 未設。
houseRules館內規範；null = 未設。
cancellationPolicy取消政策；null = 未設。
addressRegion地址：縣市／區域；null = 未設。
addressLocality地址：鄉鎮／地區；null = 未設。
streetAddress街道地址；null = 未設。
postalCode郵遞區號；null = 未設。
latitude緯度；null = 未設。
longitude經度；null = 未設。
phone聯絡電話；null = 未設。
petsAllowed是否允許攜帶寵物；null = 未設。
smokingAllowed是否允許吸菸；null = 未設。
status狀態：active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫；null = 沿用內容欄。
seoDescriptionSEO 描述；null = 未設。
ogImageUrlOpen Graph 分享圖 URL；null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
cairn lodging property <id>
{
"ok": true,
"data": {
"id": {
"length": 0
},
"slug": "…",
"name": "…",
"kind": "…",
"isOverseas": true,
"location": "…",
"description": "…",
"contentMdx": "…",
"facilities": "…",
"coverImageUrl": "…",
"usageHint": "…",
"checkInTime": "…",
"checkOutTime": "…",
"checkInInfo": "…",
"houseRules": "…",
"cancellationPolicy": "…",
"addressRegion": "…",
"addressLocality": "…",
"streetAddress": "…",
"postalCode": "…",
"latitude": 0,
"longitude": 0,
"phone": "…",
"petsAllowed": true,
"smokingAllowed": true,
"status": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn lodging room-types列出某物件的房型
參數
--property <propertyId>--json回應欄位 · data[]
id房型 id（rt_ 前綴）。
lengthReturns the length of a String object.
propertyId所屬住宿館 id（prop_ 前綴）。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位：room 以房計 / bed 以床位計。
unitsTotal總庫存量（房間數或床位數）。
capacityPerUnit每單位可住人數。
basePriceTwd底價（TWD 整數，每晚每單位；可被逐晚覆寫）。
description房型描述；null = 未設。
facilities設施清單（JSON）；null = 未設。
bedConfig床型配置（JSON）；null = 未設。
floorSizeSqm房間坪數（平方公尺）；null = 未設。
status狀態：active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
cairn lodging room-types --property <propertyId>
{
"ok": true,
"data": [
{
"id": {
"length": 0
},
"propertyId": {
"length": 0
},
"name": "…",
"inventoryUnit": "…",
"unitsTotal": 0,
"capacityPerUnit": 0,
"basePriceTwd": 0,
"description": "…",
"facilities": "…",
"bedConfig": "…",
"floorSizeSqm": 0,
"status": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn lodging room-type單一房型
參數
<id>位置參數 · 必填--json回應欄位 · data
id房型 id（rt_ 前綴）。
lengthReturns the length of a String object.
propertyId所屬住宿館 id（prop_ 前綴）。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位：room 以房計 / bed 以床位計。
unitsTotal總庫存量（房間數或床位數）。
capacityPerUnit每單位可住人數。
basePriceTwd底價（TWD 整數，每晚每單位；可被逐晚覆寫）。
description房型描述；null = 未設。
facilities設施清單（JSON）；null = 未設。
bedConfig床型配置（JSON）；null = 未設。
floorSizeSqm房間坪數（平方公尺）；null = 未設。
status狀態：active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
cairn lodging room-type <id>
{
"ok": true,
"data": {
"id": {
"length": 0
},
"propertyId": {
"length": 0
},
"name": "…",
"inventoryUnit": "…",
"unitsTotal": 0,
"capacityPerUnit": 0,
"basePriceTwd": 0,
"description": "…",
"facilities": "…",
"bedConfig": "…",
"floorSizeSqm": 0,
"status": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn lodging availability房型逐夜可用量＋價格 [check-in, check-out)
參數
--room-type <id>--check-in <date>入住日（YYYY-MM-DD，含此晚）
--check-out <date>退房日（YYYY-MM-DD，不含此晚）
--json回應欄位 · data
available整段住宿期間可訂房間數（各晚剩餘取最小；任一晚關閉則為 0）。
nights住宿晚數。
totalPriceTwd整段期間房價合計（TWD 整數，逐晚牌價加總）。
perNight逐晚可售明細。
night該晚日期（ISO 'YYYY-MM-DD'）。
capacity該晚可售容量（房間數；有覆寫則用覆寫值，否則房型總數）。
booked該晚已訂數。
remaining該晚剩餘可訂數（capacity − booked，不小於 0）。
priceTwd該晚房價（TWD 整數；有逐晚覆寫則用覆寫值，否則房型底價）。
status該晚販售狀態：open 開放 / closed 關閉。
cairn lodging availability --room-type <id> --check-in <date> --check-out <date>
{
"ok": true,
"data": {
"available": 0,
"nights": 0,
"totalPriceTwd": 0,
"perNight": [
{
"night": "…",
"capacity": 0,
"booked": 0,
"remaining": 0,
"priceTwd": 0,
"status": "…"
}
]
}
}cairn lodging breakdown逐夜已訂量（直訂 vs 套裝）[from, to)
參數
--room-type <id>--from <date>起始日（YYYY-MM-DD，含此晚）
--to <date>結束日（YYYY-MM-DD，不含此晚）
--json回應欄位 · data[]
night該晚日期（ISO 'YYYY-MM-DD'）。
directBooked該晚散客直訂的已訂數。
packageBooked該晚梯次配套佔用的已訂數。
cairn lodging breakdown --room-type <id> --from <date> --to <date>
{
"ok": true,
"data": [
{
"night": "…",
"directBooked": 0,
"packageBooked": 0
}
]
}cairn lodging images列出物件或房型的圖片
參數
<id>位置參數 · 必填--room-type <id>--jsoncairn lodging images <id> --room-type <id>
cairn lodging bookings列出旅宿訂房（代訂）
參數
--q自由文字關鍵字（訂房人、旅宿等）
--status依訂單狀態篩選（省略則回全部）
--json回應欄位 · data[]
orderId訂單 id（ord_ 前綴）。
orderNumber訂單編號（人類可讀流水號）。
status顯示狀態（派生自三軸，沿用舊欄名供 UI badge / canCancel 相容）。
bookingState訂位軸狀態（如 confirmed / cancelled）。
paymentState付款軸狀態（如 unpaid / partial / paid）。
refundState退款軸狀態。
totalTwd應收總額（TWD 整數，訂單各應收明細加總）。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id（prop_ 前綴）。
propertyName住宿館名稱。
roomTypeId房型 id（rt_ 前綴）。
roomTypeName房型名稱。
checkIn入住日（ISO 'YYYY-MM-DD'）。
checkOut退房日（ISO 'YYYY-MM-DD'）。
units訂購房間數。
guestCount入住總人數。
cairn lodging bookings
{
"ok": true,
"data": [
{
"orderId": "…",
"orderNumber": "…",
"status": "…",
"bookingState": "…",
"paymentState": "…",
"refundState": "…",
"totalTwd": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"bookerName": "…",
"bookerEmail": "…",
"propertyId": "…",
"propertyName": "…",
"roomTypeId": "…",
"roomTypeName": "…",
"checkIn": "…",
"checkOut": "…",
"units": 0,
"guestCount": 0
}
]
}cairn lodging booking單一旅宿訂房明細
參數
<orderId>位置參數 · 必填--json回應欄位 · data
orderId訂單 id（ord_ 前綴）。
orderNumber訂單編號（人類可讀流水號）。
status顯示狀態（派生自三軸，沿用舊欄名供 UI badge / canCancel 相容）。
bookingState訂位軸狀態（如 confirmed / cancelled）。
paymentState付款軸狀態（如 unpaid / partial / paid）。
refundState退款軸狀態。
totalTwd應收總額（TWD 整數，訂單各應收明細加總）。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id（prop_ 前綴）。
propertyName住宿館名稱。
roomTypeId房型 id（rt_ 前綴）。
roomTypeName房型名稱。
checkIn入住日（ISO 'YYYY-MM-DD'）。
checkOut退房日（ISO 'YYYY-MM-DD'）。
units訂購房間數。
guestCount入住總人數。
cairn lodging booking <orderId>
{
"ok": true,
"data": {
"orderId": "…",
"orderNumber": "…",
"status": "…",
"bookingState": "…",
"paymentState": "…",
"refundState": "…",
"totalTwd": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"bookerName": "…",
"bookerEmail": "…",
"propertyId": "…",
"propertyName": "…",
"roomTypeId": "…",
"roomTypeName": "…",
"checkIn": "…",
"checkOut": "…",
"units": 0,
"guestCount": 0
}
}cairn lodging stats旅宿 KPI 統計
參數
--json回應欄位 · data
tonightCheckInUnits今晚入住房間數（Asia/Taipei）。
tonightCheckInGuests今晚入住總人數（Asia/Taipei）。
weekOccupancyPct未來 7 晚住房率（已訂 / 可售，0–100）。
next7AvailableUnits未來 7 晚仍可售的房晚數。
pendingPaymentCount待收款訂單筆數。
pendingPaymentTwd待收款金額合計（TWD 整數）。
cairn lodging stats
{
"ok": true,
"data": {
"tonightCheckInUnits": 0,
"tonightCheckInGuests": 0,
"weekOccupancyPct": 0,
"next7AvailableUnits": 0,
"pendingPaymentCount": 0,
"pendingPaymentTwd": 0
}
}cairn lodging property-create新增旅宿物件
參數
--slug <s>旅宿代稱（小寫英數與連字號，2-63 字，租戶內唯一，用於網址）
--name <n>旅宿名稱（對外顯示）
--kind旅宿類型：camp 營地／hotel 旅館，預設 hotel
--overseas--location所在地點概述（如縣市、區域）
--description旅宿介紹文字
--usage-hint銷售用途：direct 僅直接訂房／package 僅併入套裝行程／both 兩者皆可，預設 both
--confirm--json回應欄位 · data
id新建立住宿館的 id（prop_ 前綴）。
cairn lodging property-create --slug <s> --name <n>
{
"ok": true,
"data": {
"id": "…"
}
}cairn lodging property-update更新旅宿物件（patch 語意；只送有帶的欄位）
參數
<id>位置參數 · 必填--name旅宿名稱（對外顯示）
--location所在地點概述（如縣市、區域）
--description旅宿介紹文字
--usage-hint銷售用途：direct 僅直接訂房／package 僅併入套裝行程／both 兩者皆可
--facilities設施代碼陣列（須為合法 amenity key；送空陣列代表清空）
--pets--smoking--seo-titleSEO 標題（送空字串代表清空，退回預設）
--seo-descriptionSEO 描述（送空字串代表清空，退回預設）
--og-image-url社群分享圖 URL（須為 http/https，送空字串代表清空）
--phone聯絡電話
--confirm--json回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging property-update <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging property-archive封存旅宿物件（status→inactive）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging property-archive <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging room-type-create新增房型
參數
--property <id>--name <n>房型名稱（如標準雙人房）
--units-total <n>此房型可售總單元數（房數或床位數）
--base-price <twd>--inventory-unit庫存單位：room 以房計／bed 以床位計，預設 room
--capacity-per-unit <n>每單元可容納人數，預設 1
--bed-type床型代碼（須為合法 bed type，搭配 bedCount 才生效）
--floor-size <sqm>--facilities房型設施代碼陣列（須為合法 amenity key）
--description房型介紹文字
--confirm--json回應欄位 · data
id新建立房型的 id（rt_ 前綴）。
cairn lodging room-type-create --property <id> --name <n> --units-total <n> --base-price <twd>
{
"ok": true,
"data": {
"id": "…"
}
}cairn lodging room-type-update更新房型（patch；送 --facilities= 空字串可清空）
參數
<id>位置參數 · 必填--name房型名稱（如標準雙人房）
--units-total此房型可售總單元數（房數或床位數）
--base-price--inventory-unit庫存單位：room 以房計／bed 以床位計
--capacity-per-unit每單元可容納人數
--bed-type床型代碼（須為合法 bed type，搭配 bedCount 才生效）
--floor-size--facilities房型設施代碼陣列（須為合法 amenity key；送空陣列代表清空）
--description房型介紹文字
--confirm--json回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging room-type-update <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging room-type-archive封存房型（status→inactive）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging room-type-archive <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging nights-override批次覆寫房型一段區間每晚的價/容量/封房 [from, to]（inclusive）
參數
--room-type <id>--from <date>套用起始日（YYYY-MM-DD，含此日）
--to <date>套用結束日（YYYY-MM-DD，含此日；須不早於起始日）
--price <twd>--capacity <n>覆寫的每晚可售單元數，若低於已訂數量會回 409 衝突
--status每晚開關房狀態：open 開放／closed 封房
--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging nights-override --room-type <id> --from <date> --to <date>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging booking-cancel取消旅宿訂房（釋回保留夜；owner-scope）
參數
<orderId>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging booking-cancel <orderId>
{
"ok": true,
"data": {
"ok": true
}
}cairn lodging book代客建立旅宿訂房（訂房人須為既有會員）
參數
--property <id>--room-type <id>--check-in <date>入住日（YYYY-MM-DD，含此晚）
--check-out <date>退房日（YYYY-MM-DD，不含此晚，須晚於入住日）
--units <n>預訂單元數（房數或床位數，1-50）
--guests <n>--email <e>--payment-method <cash|atm|manual>付款方式：cash 現金／atm 轉帳／manual 其他人工
--receiving-account--notes代訂備註
--confirm--json回應欄位 · data
orderId新建立住宿訂單的 id（ord_ 前綴）。
cairn lodging book --property <id> --room-type <id> --check-in <date> --check-out <date> --units <n> --guests <n> --email <e> --payment-method <cash|atm|manual>
{
"ok": true,
"data": {
"orderId": "…"
}
}cairn lodging image-add新增物件或房型圖片
參數
<id>位置參數 · 必填--room-type <id>--url <u>圖片網址
--caption圖片說明文字（可省略）
--order--confirm--jsoncairn lodging image-add <id> --room-type <id> --url <u>
cairn lodging image-delete刪除物件或房型圖片
參數
<imageId>位置參數 · 必填--room-type--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn lodging image-delete <imageId> --room-type
{
"ok": true,
"data": {
"ok": true
}
}cairn trips
行程：查詢、明細、團號梯次、成本範本
cairn trips list列出/搜尋行程
參數
--status依行程狀態篩選（draft 草稿／published 上架／archived 封存）
--q自由文字搜尋（行程標題／代稱／目的地）
--group-code依團號篩選，列出含該團號梯次的行程
--json回應欄位 · data[]
id行程 id（trip_ 前綴）。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
priceFromTwd「NT$ X 起」起價（TWD 整數）。
status上架狀態：draft 草稿 / published 已上架 / archived 封存。
updatedAt最後更新時間。
isClimbing是否登山團（行程層模組旗標）。
isOverseas是否海外團（行程層模組旗標）。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號（group-code §8.2）：最新一筆有團號的梯次；無則 null（UI 顯示 —）。
cairn trips list
{
"ok": true,
"data": [
{
"id": "…",
"slug": "…",
"title": "…",
"destination": "…",
"durationDays": 0,
"priceFromTwd": 0,
"status": "…",
"updatedAt": "2026-06-30T08:00:00.000Z",
"isClimbing": true,
"isOverseas": true,
"activeDepartureCount": 0,
"nextDepartureDate": "…",
"representativeGroupCode": "…"
}
]
}cairn trips get單一行程完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id行程 id（trip_ 前綴）。
lengthReturns the length of a String object.
slug行程網址 slug（公開站路徑）。
title行程標題。
summary一句話摘要；null = 未設。
contentMdx行程內文（MDX 原始碼）；null = 未設。
destination目的地名稱。
durationDays天數。
priceFromTwd「NT$ X 起」起價（TWD 整數）。
coverImageUrl封面圖 URL；null = 未設。
status上架狀態：draft 草稿 / published 已上架 / archived 封存。
createdAt建立時間。
updatedAt最後更新時間。
isClimbing是否登山團（行程層模組旗標）。
isOverseas是否海外團（行程層模組旗標）。
gradeScore難度評鑑分數（climbing-screening §3.1）；null = 未評級。
requiresAlpineExperience是否要求具備高山經驗（報名審核用）。
gradeLabel難度標籤（如「B＋」）；null = 未設。
feeInclusions團費包含/不包含（前台費用區唯一來源）；null = 未設。
seoTitleSEO 標題覆寫；null = 沿用 title。
seoDescriptionSEO 描述；null = 未設。
ogImageUrlOpen Graph 分享圖 URL；null = 未設。
images行程相簿圖片（依 displayOrder 排序）。
id圖片資源 id（timg_ 前綴）。
url圖片公開 URL。
caption圖說文字；null = 無。
displayOrder在行程相簿中的排序（由小到大）。
departuresActive (selling, future) departures only on the public side; all on admin.
id梯次 id（dep_ 前綴）。
tripId所屬行程 id（trip_ 前綴）。
departureDate出發日（ISO 'YYYY-MM-DD'）。
returnDate回程日（ISO 'YYYY-MM-DD'）。
priceTwd售價（TWD 整數，未稅牌價）。
capacity名額上限（人數）。
bookedCount已成團佔用名額（人數）。
status梯次狀態：selling 販售中 / closed 關閉 / cancelled 取消 / completed 已結團。
notes內部備註；null = 無。
allocationMode抽籤分配模式（lottery-integration §2.1）：fcfs=先到先得 / lottery=抽籤制。
agencyPriceTwd選填同業價（TWD 整數）；admin-only，公開站不映射。
depositMode選填訂金規則模式：none 免訂金 / fixed 定額 / percent 比例；admin-only。
depositAmountTwd選填訂金定額（TWD 整數，depositMode=fixed 時適用）；admin-only。
depositPercent選填訂金比例（百分比，depositMode=percent 時適用）；admin-only。
groupCode選填團號（group-code §3.3）；admin-only，公開站不映射。
regionCode選填地區代碼（團號組成）；admin-only。
airlineCode選填航空公司代碼（團號組成）；admin-only。
promoActive選填梯次促銷是否啟用（trip-pricing）；admin-only。
promoPriceTwd選填促銷覆寫售價（TWD 整數）；admin-only。
promoAgencyPriceTwd選填促銷覆寫同業價（TWD 整數）；admin-only。
cairn trips get <id>
{
"ok": true,
"data": {
"id": {
"length": 0
},
"slug": "…",
"title": "…",
"summary": "…",
"contentMdx": "…",
"destination": "…",
"durationDays": 0,
"priceFromTwd": 0,
"coverImageUrl": "…",
"status": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z",
"isClimbing": true,
"isOverseas": true,
"gradeScore": 0,
"requiresAlpineExperience": true,
"gradeLabel": "…",
"feeInclusions": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"images": [
{
"id": "…",
"url": "…",
"caption": "…",
"displayOrder": 0
}
],
"departures": [
{
"id": "…",
"tripId": "…",
"departureDate": "…",
"returnDate": "…",
"priceTwd": 0,
"capacity": 0,
"bookedCount": 0,
"status": "…",
"notes": "…",
"allocationMode": "fcfs",
"agencyPriceTwd": 0,
"depositMode": null,
"depositAmountTwd": 0,
"depositPercent": 0,
"groupCode": "…",
"regionCode": "…",
"airlineCode": "…",
"promoActive": true,
"promoPriceTwd": 0,
"promoAgencyPriceTwd": 0
}
]
}
}cairn trips departures梯次：查詢（find/search）、建立、編輯、狀態、團號
參數
<tripId>位置參數 · 必填<departureId>位置參數 · 必填--group-code <code>完整團號，格式為 YY+地區+航空+MMDD+序號（如 26EGTK1010A，自動轉大寫）
--group-code-prefix <prefix>團號前綴，前綴比對列出多個梯次
--status <s>梯次狀態（selling 銷售中／closed 關閉／cancelled 取消／completed 完成）
--region <c>--airline <c>--departure-date <d>出發日期（YYYY-MM-DD）
回應欄位 · data
id新建立梯次的 id（dep_ 前綴）。
cairn trips departures <tripId> <departureId> --group-code <code> --group-code-prefix <prefix> --status <s> --region <c> --airline <c> --departure-date <d>
{
"ok": true,
"data": {
"id": "…"
}
}cairn trips create建立行程
參數
--slug <s>行程網址代稱（slug），用於前台路徑與後台識別，只能小寫英數與連字號
--title <t>行程標題，顯示於前台與訂單
--destination <d>目的地名稱
--duration-days <n>行程天數
--price-from-twd <n>起價（新台幣），前台「OOO 元起」顯示用
--summary行程摘要，前台列表卡片用的一句話簡介
--status依行程狀態篩選（draft 草稿／published 上架／archived 封存）
--confirm回應欄位 · data
id新建立行程的 id（trip_ 前綴）。
cairn trips create --slug <s> --title <t> --destination <d> --duration-days <n> --price-from-twd <n>
{
"ok": true,
"data": {
"id": "…"
}
}cairn trips update更新行程（null = 清空、未帶 = 不動）
參數
<id>位置參數 · 必填--title行程標題，顯示於前台與訂單
--slug行程網址代稱（slug），用於前台路徑與後台識別，只能小寫英數與連字號
--status行程狀態（draft 草稿／published 上架／archived 封存）
--price-from-twd起價（新台幣），前台「OOO 元起」顯示用
--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn trips update <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn trips set-cost-template綁定 / 解綁行程的成本範本（可多範本疊加）
參數
<tripId>位置參數 · 必填--template-ids <id1,id2,…>要綁定的成本範本 ID 陣列（依序疊加）；[] 或省略表示解除全部綁定
--confirm回應欄位 · data
ok操作成功旗標，恆為 true。
cairn trips set-cost-template <tripId>
{
"ok": true,
"data": {
"ok": true
}
}cairn trips cost-templates列出可綁定的 active 成本範本
參數
--json回應欄位 · data[]
id成本範本 id（ct_ 前綴）。
name成本範本名稱。
cairn trips cost-templates
{
"ok": true,
"data": [
{
"id": "…",
"name": "…"
}
]
}cairn trips import批次匯入行程（.xlsx/.csv；預設 dry-run，--commit 才建檔）
參數
--file <path.xlsx>--commit--confirm--json回應欄位 · data
filename已匯入的檔名。
result匯入結果（建檔筆數與逐列結果）。
importBatchId本次匯入批次 id（imp_ 前綴），供稽核追溯。
createdTripCount新建行程數。
createdDepartureCount新建梯次數。
skippedCount略過列數（重複／無需匯入）。
errorCount失敗列數。
results逐列匯入結果。
cairn trips import --file <path.xlsx>
{
"ok": true,
"data": {
"filename": "…",
"result": {
"importBatchId": "…",
"createdTripCount": 0,
"createdDepartureCount": 0,
"skippedCount": 0,
"errorCount": 0,
"results": []
}
}
}cairn trips export匯出行程為 CSV/JSON（同 list 篩選）
參數
--status依行程狀態篩選（draft 草稿／published 上架／archived 封存）
--q自由文字搜尋（行程標題／代稱／目的地）
--group-code依團號篩選，匯出含該團號梯次的行程
--format--json回應欄位 · data
rows匯出的行程列（套用相同 filter，無分頁）。
id行程 id（trip_ 前綴）。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
priceFromTwd「NT$ X 起」起價（TWD 整數）。
status上架狀態：draft 草稿 / published 已上架 / archived 封存。
updatedAt最後更新時間。
isClimbing是否登山團（行程層模組旗標）。
isOverseas是否海外團（行程層模組旗標）。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號（group-code §8.2）：最新一筆有團號的梯次；無則 null（UI 顯示 —）。
total匯出總筆數。
truncated是否因上限被截斷（此端點回全列，恆為 false）。
cairn trips export
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"slug": "…",
"title": "…",
"destination": "…",
"durationDays": 0,
"priceFromTwd": 0,
"status": "…",
"updatedAt": "2026-06-30T08:00:00.000Z",
"isClimbing": true,
"isOverseas": true,
"activeDepartureCount": 0,
"nextDepartureDate": "…",
"representativeGroupCode": "…"
}
],
"total": 0,
"truncated": true
}
}cairn agencies
同業：查詢、明細、指派候選、匯出
cairn agencies list列出/篩選同業
參數
--status同業狀態篩選（active 啟用中／archived 已封存；省略為全部）
--owner <userId>負責業務篩選（傳明確使用者 ID；none＝只列尚未指派負責業務者；all 或省略＝全部）
--has-tax-id是否有統一編號篩選（yes 僅列有統編者／no 僅列無統編者）
--json回應欄位 · data[]
id同業 id（前綴 `agc_`）。
name同業公司名 / 個人團主名稱。
taxId統一編號（個人團主可留空）。
contactName主要聯絡人姓名（未填 → null）。
phone聯絡電話（未填 → null）。
email聯絡 Email（未填 → null）。
address公司地址（未填 → null）。
paymentTerm帳期 / 結算方式（自由文字，例：'月結 30 天'）。
ownerUserId負責業務 user id（NULL = 未指派）。
ownerName負責業務顯示名；未指派為 null。
status同業狀態：active 啟用中 / archived 已封存。
note內部備註（未填 → null）。
orderCount累計訂單數（COUNT orders WHERE agency_id = id）。
createdAt建立時間。
updatedAt最後更新時間。
cairn agencies list
{
"ok": true,
"data": [
{
"id": "…",
"name": "…",
"taxId": "…",
"contactName": "…",
"phone": "…",
"email": "…",
"address": "…",
"paymentTerm": "…",
"ownerUserId": "…",
"ownerName": "…",
"status": "active",
"note": "…",
"orderCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn agencies get單一同業完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id同業 id（前綴 `agc_`）。
name同業公司名 / 個人團主名稱。
taxId統一編號（個人團主可留空）。
contactName主要聯絡人姓名（未填 → null）。
phone聯絡電話（未填 → null）。
email聯絡 Email（未填 → null）。
address公司地址（未填 → null）。
paymentTerm帳期 / 結算方式（自由文字，例：'月結 30 天'）。
ownerUserId負責業務 user id（NULL = 未指派）。
ownerName負責業務顯示名；未指派為 null。
status同業狀態：active 啟用中 / archived 已封存。
note內部備註（未填 → null）。
orderCount累計訂單數（COUNT orders WHERE agency_id = id）。
createdAt建立時間。
updatedAt最後更新時間。
cairn agencies get <id>
{
"ok": true,
"data": {
"id": "…",
"name": "…",
"taxId": "…",
"contactName": "…",
"phone": "…",
"email": "…",
"address": "…",
"paymentTerm": "…",
"ownerUserId": "…",
"ownerName": "…",
"status": "active",
"note": "…",
"orderCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn agencies assignable-staff負責業務指派候選清單
參數
--json回應欄位 · data[]
userId員工使用者 id（可作為負責業務指派的 ownerUserId）。
name員工顯示名。
role角色代碼（admin / sales / op / accountant）。
cairn agencies assignable-staff
{
"ok": true,
"data": [
{
"userId": "…",
"name": "…",
"role": "…"
}
]
}cairn agencies export匯出同業名單（當前篩選視圖）
參數
--status同業狀態篩選（active 啟用中／archived 已封存；省略為全部）
--owner <userId>負責業務篩選（傳明確使用者 ID；none＝只列尚未指派負責業務者；all 或省略＝全部）
--has-tax-id是否有統一編號篩選（yes 僅列有統編者／no 僅列無統編者）
--json回應欄位 · data
rows同業匯出資料列（依 owner 篩選後的全表快照，供試算表匯出）。
id同業 id（前綴 `agc_`）。
name同業公司名 / 個人團主名稱。
taxId統一編號（個人團主可留空）。
contactName主要聯絡人姓名（未填 → null）。
phone聯絡電話（未填 → null）。
email聯絡 Email（未填 → null）。
address公司地址（未填 → null）。
paymentTerm帳期 / 結算方式（自由文字，例：'月結 30 天'）。
ownerUserId負責業務 user id（NULL = 未指派）。
ownerName負責業務顯示名；未指派為 null。
status同業狀態：active 啟用中 / archived 已封存。
note內部備註（未填 → null）。
orderCount累計訂單數（COUNT orders WHERE agency_id = id）。
createdAt建立時間。
updatedAt最後更新時間。
cairn agencies export
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"name": "…",
"taxId": "…",
"contactName": "…",
"phone": "…",
"email": "…",
"address": "…",
"paymentTerm": "…",
"ownerUserId": "…",
"ownerName": "…",
"status": "active",
"note": "…",
"orderCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}
}cairn agencies create新增同業（鏡射 createAgency；agency.manage）
參數
--name <name>同業公司名稱（B2B 旅行社或個人團主名稱）
--tax-id統一編號（選填）
--contact-name主要聯絡人姓名（選填）
--phone聯絡電話（選填）
--email聯絡 Email（選填；留空字串視為未填）
--address公司地址（選填）
--payment-term付款條件／帳期約定（選填，如月結 30 天）
--owner <userId>負責業務篩選（傳明確使用者 ID；none＝只列尚未指派負責業務者；all 或省略＝全部）
--status同業狀態篩選（active 啟用中／archived 已封存；省略為全部）
--note內部備註（選填）
--confirm回應欄位 · data
id新建立同業的 ID（agc_ 前綴）。
cairn agencies create --name <name>
{
"ok": true,
"data": {
"id": "…"
}
}cairn agencies update更新同業（真 partial；鏡射 updateAgency；agency.manage）
參數
<id>位置參數 · 必填--name同業公司名稱（省略則不更動）
--tax-id統一編號（省略則不更動）
--contact-name主要聯絡人姓名（省略則不更動）
--phone聯絡電話（省略則不更動）
--email聯絡 Email（省略則不更動；空字串視為清空）
--address公司地址（省略則不更動）
--payment-term付款條件／帳期約定（省略則不更動）
--owner <userId>--status同業狀態（active 啟用中／archived 已封存；省略則不更動）
--note內部備註（省略則不更動）
--confirm回應欄位 · data
ok固定為 true：同業資料已更新。
cairn agencies update <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn agencies archive下架同業（鏡射 setAgencyStatus archived；agency.manage）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true：同業啟用／停用狀態已更新。
cairn agencies archive <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn agencies restore上架同業（鏡射 setAgencyStatus active；agency.manage）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true：同業啟用／停用狀態已更新。
cairn agencies restore <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn consent
同意書範本：查詢、明細
cairn consent list列出同意書範本（各版本）
參數
--kind同意書類別代碼，指定時僅列出該類別的範本版本
--json回應欄位 · data[]
id同意書範本 id（前綴 `ct_`）。同一 kind 每個版本各有一個 id。
kind同意書類型：pdpa（個資）/ tour_agreement（旅遊契約）/ cancellation_policy / refund_policy。
version版本號，同一 kind 從 1 遞增；範本 append-only，編輯即新增下一版。
contentMdx範本內容（MDX 原始碼），可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數（COUNT consent_signatures）。
cairn consent list
{
"ok": true,
"data": [
{
"id": "…",
"kind": "…",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "2026-06-30T08:00:00.000Z",
"createdAt": "2026-06-30T08:00:00.000Z",
"signatureCount": 0
}
]
}cairn consent get單一同意書範本明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id同意書範本 id（前綴 `ct_`）。同一 kind 每個版本各有一個 id。
kind同意書類型：pdpa（個資）/ tour_agreement（旅遊契約）/ cancellation_policy / refund_policy。
version版本號，同一 kind 從 1 遞增；範本 append-only，編輯即新增下一版。
contentMdx範本內容（MDX 原始碼），可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數（COUNT consent_signatures）。
cairn consent get <id>
{
"ok": true,
"data": {
"id": "…",
"kind": "…",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "2026-06-30T08:00:00.000Z",
"createdAt": "2026-06-30T08:00:00.000Z",
"signatureCount": 0
}
}cairn consent create新增同意書範本版本（append-only，版號自動遞增）
參數
--kind <pdpa|tour_agreement|cancellation_policy|refund_policy>同意書類別代碼，指定時僅列出該類別的範本版本
--content-mdx <text|@file>同意書內文（MDX 格式），即此版本的條款全文
--confirm回應欄位 · data
id新建立同意書範本的 ID。
version範本版本號（每次發布遞增，簽署時綁定當下版本）。
cairn consent create --kind <pdpa|tour_agreement|cancellation_policy|refund_policy> --content-mdx <text|@file>
{
"ok": true,
"data": {
"id": "…",
"version": 0
}
}cairn members
會員（客戶）：查詢、明細、統計
cairn members list列出/搜尋會員
參數
--q關鍵字，模糊比對會員姓名、Email 或電話
--county縣市篩選，僅回傳通訊地址在該縣市的會員
--year加入年份（西元四位數），僅回傳該年註冊的會員
--page分頁頁碼，從 1 起算，預設第 1 頁
--page-size每頁筆數，上限 200，預設由後端決定
--json回應欄位 · data
rows當前頁的會員列。
userId會員（顧客）的 user id。
email會員 Email（登入帳號）。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話（未填 → null）。
address通訊地址（未填 → null）。
birthDate生日 YYYY-MM-DD（未填 → null）。
orderCount累計訂單數（含所有狀態與 kind）。
paidOrderCount已付清 / 已完成的訂單數（payment_state in paid/overpaid 或 booking_state=completed）。
totalSpent累計消費（上述已付清訂單的應收總額，TWD 整數）。
lastOrderAt最後一筆訂單建立時間（無訂單 → null）。
pdpaSignedAt最新版 PDPA 同意書簽署時間（未簽 → null）。
anonymizedAtPDPA 匿名化時間；非空 = 已匿名化。
total符合篩選的會員總數。
page當前頁碼（從 1 起算）。
pageSize每頁筆數。
cairn members list
{
"ok": true,
"data": {
"rows": [
{
"userId": "…",
"email": "…",
"name": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"phone": "…",
"address": "…",
"birthDate": "…",
"orderCount": 0,
"paidOrderCount": 0,
"totalSpent": 0,
"lastOrderAt": null,
"pdpaSignedAt": null,
"anonymizedAt": null
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn members get單一會員完整明細（含訂單/同意紀錄）
參數
<userId>位置參數 · 必填--json回應欄位 · data
profile會員基本資料 + 訂單彙整。
userId會員（顧客）的 user id。
email會員 Email（登入帳號）。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話（未填 → null）。
address通訊地址（未填 → null）。
birthDate生日 YYYY-MM-DD（未填 → null）。
orderCount累計訂單數（含所有狀態與 kind）。
paidOrderCount已付清 / 已完成的訂單數（payment_state in paid/overpaid 或 booking_state=completed）。
totalSpent累計消費（上述已付清訂單的應收總額，TWD 整數）。
lastOrderAt最後一筆訂單建立時間（無訂單 → null）。
pdpaSignedAt最新版 PDPA 同意書簽署時間（未簽 → null）。
anonymizedAtPDPA 匿名化時間；非空 = 已匿名化。
orders近期訂單列表（上限 50 筆，含 lodging）。
id訂單 id。
orderNumber人類可讀訂單編號。
status金流模型 v2：deriveOrderDisplayStatus(booking/payment/refund) 派生的單一顯示狀態。
total該會員所有訂單的應收總額（TWD 整數）。
createdAt訂單建立時間。
tripTitle行程 / 產品標題。
consents已簽署的同意書紀錄（上限 50 筆）。
id簽署紀錄 id。
kind同意書類型（pdpa / tour_agreement / cancellation_policy / refund_policy）。
version簽署當下的範本版本號。
signedAt簽署時間。
ipAddress簽署時來源 IP（未記錄 → null）。
cairn members get <userId>
{
"ok": true,
"data": {
"profile": {
"userId": "…",
"email": "…",
"name": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"phone": "…",
"address": "…",
"birthDate": "…",
"orderCount": 0,
"paidOrderCount": 0,
"totalSpent": 0,
"lastOrderAt": null,
"pdpaSignedAt": null,
"anonymizedAt": null
},
"orders": [
{
"id": "…",
"orderNumber": "…",
"status": "…",
"total": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"tripTitle": "…"
}
],
"consents": [
{
"id": "…",
"kind": "…",
"version": 0,
"signedAt": "2026-06-30T08:00:00.000Z",
"ipAddress": "…"
}
]
}
}cairn members stats會員 KPI 統計
參數
--json回應欄位 · data
totalMembers會員（顧客）總數（排除員工帳號）。
newThisMonth本月新註冊會員數。
withOrders有下過訂單的會員數。
averageOrders平均訂單數（只計有訂單者，避免零訂單稀釋）。
cairn members stats
{
"ok": true,
"data": {
"totalMembers": 0,
"newThisMonth": 0,
"withOrders": 0,
"averageOrders": 0
}
}cairn members expiry-flags標記護照即將到期的會員（給定 userId 批次）
參數
--ids以逗號分隔的會員使用者 ID 批次，上限 200 個，回傳其中護照即將到期者
--json回應欄位 · data
userIds證件即將到期（或已過期）需提醒的會員 user id 清單。
cairn members expiry-flags --ids
{
"ok": true,
"data": {
"userIds": [
"…"
]
}
}cairn members anonymizePDPA 匿名化會員（不可逆：抹除 PII + 封鎖登入 + 撤銷憑證）
參數
<userId>位置參數 · 必填--reason匿名化原因，記入稽核紀錄備查
--confirm回應欄位 · data
ok固定為 true：會員個資已匿名化（PDPA 刪除權）。
cairn members anonymize <userId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders
訂單：查詢、明細、統計
cairn orders list列出/搜尋訂單
參數
--status依訂單顯示狀態篩選（如 pending、paid、cancelled）
--q關鍵字搜尋（訂單編號、訂購人姓名或 Email 等）
--date-from出發日期區間起（格式 YYYY-MM-DD，含當日）
--date-to出發日期區間迄（格式 YYYY-MM-DD，含當日）
--page頁碼，從 1 起算，預設第 1 頁
--json回應欄位 · data
rows當前頁的訂單列（tour-centric，每筆 tour line 一列）。
id訂單 id（前綴 `ord_`）。
orderNumber人類可讀訂單編號（每租戶 sequence 產生，如 `20260707-0001`）。
bookingState預訂狀態（真相軸）：pending_payment → confirmed → completed；cancelled 為終態。
paymentState付款狀態（派生自分類帳、快取於此供過濾）：unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」，不代表錢未退。
refundState退款狀態（派生快取，只算會影響應收的已付退款）：none / partially_refunded / refunded。
grossReceivableTwd應收（TWD 整數，派生自應收分類帳）。
collectedTwd收到現金（TWD 整數，派生）。
customerCashAppliedTwd客戶現金淨套用（收款減已退現金，TWD 整數，派生）。
outstandingTwd未收（應收減客戶現金淨套用，TWD 整數，派生）。
partySize參團人數（tour 訂單）。
createdAt訂單建立時間。
notes訂單備註（未填 → null）。
userId下單客戶的 user id（同庫 user 表）。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名（is_primary，未登記 → null）。
primaryTravelerPhone主要旅客電話（未登記 → null）。
tripId行程 id（tour 訂單經梯次反查；lodging 為空字串）。
tripTitle行程 / 產品標題。
tripSlug行程 slug。
departureId梯次 id（tour 訂單；lodging 為空字串）。
departureDate出發日 YYYY-MM-DD（lodging 為入住日）。
returnDate回程日 YYYY-MM-DD（lodging 為退房日）。
assignedToUserId派發給哪位業務的 user id（未派發 → null）。
assigneeName承辦業務顯示名（未派發 / 查無 → null）。
assignmentStatus派發狀態：unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間（未派發 → null）。
assignedByUserId執行派發者的 user id（未派發 → null）。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署（true = 待客戶重簽）。
roomingStatus分房狀態：由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態（null = FCFS 非抽籤）。'applied'|'won'|'lost'。
failoverFromOrderId備案單反查主單用：備案單的 failover_from_order_id 指向主單 id。
isOverdue逾期旗標：存在 status='open' 且 due_at 已過的收款計畫（未收齊的到期款）。 供列表列以 `bg-destructive/5` 標紅提示。由 OVERDUE_SUBSELECT 一次算回。
total符合篩選的訂單總數（DISTINCT 訂單，非列數）。
page當前頁碼（從 1 起算）。
pageSize每頁筆數。
cairn orders list
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"orderNumber": "…",
"bookingState": "…",
"paymentState": "…",
"refundState": "…",
"grossReceivableTwd": 0,
"collectedTwd": 0,
"customerCashAppliedTwd": 0,
"outstandingTwd": 0,
"partySize": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"notes": "…",
"userId": "…",
"userName": "…",
"userEmail": "…",
"primaryTravelerName": "…",
"primaryTravelerPhone": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureId": "…",
"departureDate": "…",
"returnDate": "…",
"assignedToUserId": "…",
"assigneeName": "…",
"assignmentStatus": "…",
"assignedAt": null,
"assignedByUserId": "…",
"createdByUserId": "…",
"pendingConsent": true,
"roomingStatus": "…",
"lotteryState": "…",
"failoverFromOrderId": "…",
"isOverdue": true
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn orders get單一訂單完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id訂單 id（前綴 `ord_`）。
orderNumber人類可讀訂單編號（每租戶 sequence 產生，如 `20260707-0001`）。
bookingState預訂狀態（真相軸）：pending_payment → confirmed → completed；cancelled 為終態。
paymentState付款狀態（派生自分類帳、快取於此供過濾）：unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」，不代表錢未退。
refundState退款狀態（派生快取，只算會影響應收的已付退款）：none / partially_refunded / refunded。
grossReceivableTwd應收（TWD 整數，派生自應收分類帳）。
collectedTwd收到現金（TWD 整數，派生）。
customerCashAppliedTwd客戶現金淨套用（收款減已退現金，TWD 整數，派生）。
outstandingTwd未收（應收減客戶現金淨套用，TWD 整數，派生）。
partySize參團人數（tour 訂單）。
createdAt訂單建立時間。
notes訂單備註（未填 → null）。
userId下單客戶的 user id（同庫 user 表）。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名（is_primary，未登記 → null）。
primaryTravelerPhone主要旅客電話（未登記 → null）。
tripId行程 id（tour 訂單經梯次反查；lodging 為空字串）。
tripTitle行程 / 產品標題。
tripSlug行程 slug。
departureId梯次 id（tour 訂單；lodging 為空字串）。
departureDate出發日 YYYY-MM-DD（lodging 為入住日）。
returnDate回程日 YYYY-MM-DD（lodging 為退房日）。
assignedToUserId派發給哪位業務的 user id（未派發 → null）。
assigneeName承辦業務顯示名（未派發 / 查無 → null）。
assignmentStatus派發狀態：unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間（未派發 → null）。
assignedByUserId執行派發者的 user id（未派發 → null）。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署（true = 待客戶重簽）。
roomingStatus分房狀態：由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態（null = FCFS 非抽籤）。'applied'|'won'|'lost'。
failoverFromOrderId備案單反查主單用：備案單的 failover_from_order_id 指向主單 id。
isOverdue逾期旗標：存在 status='open' 且 due_at 已過的收款計畫（未收齊的到期款）。 供列表列以 `bg-destructive/5` 標紅提示。由 OVERDUE_SUBSELECT 一次算回。
kind訂單種類（kind-agnostic 外殼）。'tour' 用既有 tour 區塊（梯次/分房/登山審核）； 'lodging' 隱藏 tour-only 區、改顯示住宿 header（見 `lodging`）。共用的金流/旅客/ 派發/同意書區塊兩者皆 order-scoped 通用。
lodginglodging 住宿 header（房型/住期/房數/人數）；tour 為 null。
travelers旅客名單（含 PII 遮罩欄；主要旅客排前）。
id旅客 id（前綴 `trv_`）。
fullName旅客姓名。
idNumberMask遮罩碼（jsonb→mask，零解密）；NULL = 未填。全碼走 reveal action（Task 7）。
passportNoMask護照號碼遮罩碼（零解密）；NULL = 未填。全碼走 order-scoped reveal。
birthDate生日 YYYY-MM-DD（未填 → null）。
phone聯絡電話（未填 → null）。
email聯絡 Email（未填 → null）。
emergencyContactName緊急聯絡人姓名（未填 → null）。
emergencyContactPhone緊急聯絡人電話（未填 → null）。
isPrimary是否為主要旅客（訂單聯絡人）。
gender性別（分房硬約束 + 顯示）：'male'|'female'|'other'|null。明文。
roomPreference分房房型偏好（下單登記）。
roommatePref指定房友 / 特殊需求自由文字。
diet飲食需求（葷素）明文；null = 未填。非 PII，不走 reveal。
medicalNotes醫療 / 過敏 / 病史備註明文；null = 未填。非 PII，不走 reveal。
address通訊地址（未填 → null）。
roomLabel團控已排房號的房間 label（null = 待團控分房）。
chargeLines應收分類帳（itemized）。
id應收明細列 id。
type應收類型：base（原始價）/ room_upgrade（房升補款）/ adjustment / failover_deposit_credit 等。
amountTwd金額（TWD 整數，signed；credit / 沖銷為負）。
description明細說明文字。
sourceType來源：system（系統派生）/ manual（人工登錄）等。
reversesChargeLineId若為沖銷列，指向被沖銷的應收明細列 id（否則 null）。
createdAt建立時間。
transactions現金分類帳。
id現金交易列 id。
direction金流方向：in（收款）/ out（退款、扣款、沖銷）。
type交易類型：payment / refund / chargeback / reversal。
amountTwd交易金額（TWD 整數，正值）。
feeTwd金流商手續費（TWD 整數）。
netTwd淨額 = amount − fee（TWD 整數）。
provider金流商：manual / ecpay / test 等。
providerTradeNo金流商交易序號（manual 入帳可能為 null）。
refundId若屬退款，指向 refunds 列 id（否則 null）。
occurredAt交易發生時間。
schedules收款計畫（current + historical）。
id收款計畫列 id。
purpose用途：full（全額）/ deposit（訂金）/ balance（尾款）/ adjustment（補款）。
targetAmountTwd應收目標金額（TWD 整數）。
status計畫狀態：open（未收齊）/ satisfied（已收齊）。
dueAt到期日（null = 未設）。
sequence排序序號（deposit → balance → adjustment）。
cairn orders get <id>
{
"ok": true,
"data": {
"id": "…",
"orderNumber": "…",
"bookingState": "…",
"paymentState": "…",
"refundState": "…",
"grossReceivableTwd": 0,
"collectedTwd": 0,
"customerCashAppliedTwd": 0,
"outstandingTwd": 0,
"partySize": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"notes": "…",
"userId": "…",
"userName": "…",
"userEmail": "…",
"primaryTravelerName": "…",
"primaryTravelerPhone": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureId": "…",
"departureDate": "…",
"returnDate": "…",
"assignedToUserId": "…",
"assigneeName": "…",
"assignmentStatus": "…",
"assignedAt": null,
"assignedByUserId": "…",
"createdByUserId": "…",
"pendingConsent": true,
"roomingStatus": "…",
"lotteryState": "…",
"failoverFromOrderId": "…",
"isOverdue": true,
"kind": "lodging",
"lodging": null,
"travelers": [
{
"id": "…",
"fullName": "…",
"idNumberMask": "…",
"passportNoMask": "…",
"birthDate": "…",
"phone": "…",
"email": "…",
"emergencyContactName": "…",
"emergencyContactPhone": "…",
"isPrimary": true,
"gender": "…",
"roomPreference": "…",
"roommatePref": "…",
"diet": "…",
"medicalNotes": "…",
"address": "…",
"roomLabel": "…"
}
],
"chargeLines": [
{
"id": "…",
"type": "…",
"amountTwd": 0,
"description": "…",
"sourceType": "…",
"reversesChargeLineId": "…",
"createdAt": "2026-06-30T08:00:00.000Z"
}
],
"transactions": [
{
"id": "…",
"direction": "…",
"type": "…",
"amountTwd": 0,
"feeTwd": 0,
"netTwd": 0,
"provider": "…",
"providerTradeNo": "…",
"refundId": "…",
"occurredAt": "2026-06-30T08:00:00.000Z"
}
],
"schedules": [
{
"id": "…",
"purpose": "…",
"targetAmountTwd": 0,
"status": "…",
"dueAt": null,
"sequence": 0
}
]
}
}cairn orders reveal顯示旅客證號/護照全碼（owner-scope；寫 traveler.decrypt 稽核）
參數
<orderId>位置參數 · 必填<travelerId>位置參數 · 必填--field <idNumber|passportNo>欲顯示全碼的個資欄位：idNumber 身分證字號、passportNo 護照號碼
--json回應欄位 · data
field本次解密的欄位：idNumber 身分證字號 / passportNo 護照號碼。
value解密後的證件明碼；null = 該欄未填。每次呼叫都會寫入解密稽核紀錄。
cairn orders reveal <orderId> <travelerId> --field <idNumber|passportNo>
{
"ok": true,
"data": {
"field": "idNumber",
"value": "…"
}
}cairn orders create代客 K 單（手動建立 tour 訂單；訂購人須為既有會員）
參數
--trip <id>--departure <id>--email <e>--party-size <n>報名人數，決定佔位數，須為 1 至 20 之間整數
--payment-method <cash|atm|manual>收款方式：cash 現金、atm 轉帳、manual 人工
--travelers <json>旅客名單，筆數須與報名人數一致
--customer-type客戶類型：direct 直客、agency 同業，預設直客
--payment-plan付款方案：full 全額、deposit 訂金，預設全額
--receiving-account--assignee--notes訂單備註
--confirm回應欄位 · data
orderId新建立訂單的 ID（ord_ 前綴）。
orderNumber訂單編號（租戶內流水序號，對外顯示用）。
cairn orders create --trip <id> --departure <id> --email <e> --party-size <n> --payment-method <cash|atm|manual> --travelers <json>
{
"ok": true,
"data": {
"orderId": "…",
"orderNumber": "…"
}
}cairn orders mark-paid手動入帳標記訂單已付（idempotent）
參數
<id>位置參數 · 必填--note對帳備註，記錄人工核款說明
--receiving-account--confirm回應欄位 · data
idempotenttrue = 訂單原已為已付狀態，本次為冪等無變更。
cairn orders mark-paid <id>
{
"ok": true,
"data": {
"idempotent": true
}
}cairn orders cancel取消訂單（釋回席次，不自動退款）
參數
<id>位置參數 · 必填--reason取消事由說明
--confirm回應欄位 · data
ok固定為 true：訂單已取消（座位釋出、booking_state 轉 cancelled）。
cairn orders cancel <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders adjust掛帳：加收 / 折讓（append charge line + 重算金流）
參數
<id>位置參數 · 必填--kind <surcharge|allowance>調整類型：surcharge 加收、allowance 減免
--amount <twd>--description <t>調整事由說明
--confirm回應欄位 · data
ok固定為 true：訂單金額調整已套用。
cairn orders adjust <id> --kind <surcharge|allowance> --amount <twd> --description <t>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders reverse沖正既有應收項目（append reversal line）
參數
<id>位置參數 · 必填--charge-line <id>--description <t>沖正事由說明
--confirm回應欄位 · data
ok固定為 true：訂單已沖銷（沖回應收與已認列項）。
cairn orders reverse <id> --charge-line <id> --description <t>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders refund-create建立並送審客戶退款（draft→submitted）
參數
<orderId>位置參數 · 必填--amount <twd>--reason <t>退款事由說明
--kind <receivable_reduction|overpayment_return>--execution-method退款執行方式：chargeback 原路退刷、remit 銀行匯款
--origin-account--admin-fee--remit-fee--payee-name--payee-bank--payee-account--confirm回應欄位 · data
id退款單 id（前綴 `rfnd_`）。
refundNumber人類可讀退款單號。
status退款工作流狀態：draft → submitted → approved → processing → paid。
cairn orders refund-create <orderId> --amount <twd> --reason <t> --kind <receivable_reduction|overpayment_return>
{
"ok": true,
"data": {
"id": "…",
"refundNumber": "…",
"status": "…"
}
}cairn orders refund-approve核准退款（責任分離：非建單人）
參數
<orderId>位置參數 · 必填--refund <refundId>--confirm回應欄位 · data
ok固定為 true：退款申請已核准。
cairn orders refund-approve <orderId> --refund <refundId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders refund-reject退件退款（submitted→cancelled）
參數
<orderId>位置參數 · 必填--refund <refundId>--reason退件事由說明
--confirm回應欄位 · data
ok固定為 true：退款申請已駁回。
cairn orders refund-reject <orderId> --refund <refundId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders refund-paid標記退款已付（approved→paid，現金整合點）
參數
<orderId>位置參數 · 必填--refund <refundId>--bank-ref--receiving-account--confirm回應欄位 · data
ok固定為 true：退款已標記為完成出款。
cairn orders refund-paid <orderId> --refund <refundId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders assign指派訂單給承辦業務（首派；pending_review→assigned）
參數
<id>位置參數 · 必填--assignee <userId>--reason派發事由說明（上限 500 字）
--confirm回應欄位 · data
ok固定為 true：訂單已指派承辦。
idempotenttrue = 該訂單原已指派給同一承辦，本次為冪等無變更。
cairn orders assign <id> --assignee <userId>
{
"ok": true,
"data": {
"ok": true,
"idempotent": true
}
}cairn orders reassign重新指派已派發訂單（admin-only；→reassigned）
參數
<id>位置參數 · 必填--assignee <userId>--reason重派事由說明（上限 500 字）
--confirm回應欄位 · data
ok固定為 true：訂單已改派承辦。
idempotenttrue = 目標承辦與原承辦相同，本次為冪等無變更。
cairn orders reassign <id> --assignee <userId>
{
"ok": true,
"data": {
"ok": true,
"idempotent": true
}
}cairn orders bulk-assign批次把多張訂單派給同一位業務（all-or-nothing）
參數
--assignee <userId>--orders <id,id,...>--reason派發事由說明（上限 500 字）
--confirm回應欄位 · data
ok固定為 true：批次指派已執行。
assignedCount成功指派的訂單筆數。
skippedCount略過的訂單筆數（如已指派或不在可指派範圍）。
cairn orders bulk-assign --assignee <userId> --orders <id,id,...>
{
"ok": true,
"data": {
"ok": true,
"assignedCount": 0,
"skippedCount": 0
}
}cairn orders review-screening人工核可/駁回登山資格審核（駁回不自動退單）
參數
<id>位置參數 · 必填--decision <approve|reject>登山資格審核裁決：approve 核可、reject 駁回
--note審核註記說明（上限 500 字）
--confirm回應欄位 · data
ok固定為 true：名單複核結果已登錄。
cairn orders review-screening <id> --decision <approve|reject>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders balance-link產生/重用尾款付款連結（回待補金額；owner-scope）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true：尾款付款連結已產生。
amountTwd本次尾款金額（TWD 整數）。
scheduleId對應的收款計畫 ID。
cairn orders balance-link <id>
{
"ok": true,
"data": {
"ok": true,
"amountTwd": 0,
"scheduleId": "…"
}
}cairn orders traveler-add新增旅客到訂單（owner-scope；出發前 7 天凍結）
參數
<orderId>位置參數 · 必填--full-name <n>旅客全名，須與證件一致；新增旅客時必填，更新時可省略
--phone旅客聯絡電話
--email旅客電子郵件
--birth-date旅客出生日期（格式 YYYY-MM-DD）
--gender旅客性別：male 男、female 女、other 其他
--id-number身分證字號，屬個資將加密保存
--passport--room-pref--roommate-pref指定同住室友（用於分房作業）
--emergency-name--emergency-phone--address旅客通訊地址
--confirm回應欄位 · data
ok固定為 true：旅客已新增至訂單。
travelerId新建立旅客的 ID（trv_ 前綴）。
cairn orders traveler-add <orderId> --full-name <n>
{
"ok": true,
"data": {
"ok": true,
"travelerId": "…"
}
}cairn orders traveler-update更新旅客資料（owner-scope；出發前 7 天凍結）
參數
<orderId>位置參數 · 必填<travelerId>位置參數 · 必填--full-name旅客全名，須與證件一致；新增旅客時必填，更新時可省略
--phone旅客聯絡電話
--email旅客電子郵件
--birth-date旅客出生日期（格式 YYYY-MM-DD）
--gender旅客性別：male 男、female 女、other 其他
--id-number身分證字號，屬個資將加密保存
--passport--room-pref--roommate-pref指定同住室友（用於分房作業）
--emergency-name--emergency-phone--address旅客通訊地址
--confirm回應欄位 · data
ok固定為 true：旅客資料已更新。
cairn orders traveler-update <orderId> <travelerId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders traveler-remove移除旅客（owner-scope；至少保留一位、不可移主要聯絡人）
參數
<orderId>位置參數 · 必填<travelerId>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true：旅客已自訂單移除。
cairn orders traveler-remove <orderId> <travelerId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders rooming-pref更新旅客分房需求（房型偏好/指定室友；owner-scope）
參數
<orderId>位置參數 · 必填<travelerId>位置參數 · 必填--room-pref--roommate-pref指定同住室友（用於分房作業）
--confirm回應欄位 · data
ok固定為 true：旅客分房設定已更新。
cairn orders rooming-pref <orderId> <travelerId>
{
"ok": true,
"data": {
"ok": true
}
}cairn orders stats訂單 KPI 統計
參數
--json回應欄位 · data
pendingPayment待付款訂單數（未取消 / 未完成 / 未退款且 payment_state=unpaid）。
depositPaid已付訂金訂單數（payment_state=deposit_paid）。
paid已收齊訂單數（payment_state in paid/overpaid）。
cancelled已取消訂單數（booking_state=cancelled）。
refunded有退款的訂單數（refund_state in refunded/partially_refunded）。
completed已完成訂單數（booking_state=completed）。
thisMonthPaidTwd本月實收現金（payment_transactions direction=in 加總，TWD 整數）。
thisMonthNewOrders本月新建訂單數。
thisMonthCancelled本月取消訂單數。
cairn orders stats
{
"ok": true,
"data": {
"pendingPayment": 0,
"depositPaid": 0,
"paid": 0,
"cancelled": 0,
"refunded": 0,
"completed": 0,
"thisMonthPaidTwd": 0,
"thisMonthNewOrders": 0,
"thisMonthCancelled": 0
}
}cairn orders export匯出訂單為 CSV/JSON（同 list 篩選 + owner-scope；取全頁）
參數
--status依訂單顯示狀態篩選（如 pending、paid、cancelled）
--date-from出發日期區間起（格式 YYYY-MM-DD，含當日）
--date-to出發日期區間迄（格式 YYYY-MM-DD，含當日）
--q關鍵字搜尋（訂單編號、訂購人姓名或 Email 等）
--assignment依派發狀態篩選（如 unassigned、assigned）
--rooming依分房狀態篩選
--agency-id依合作旅行社 ID 篩選（同業單）
--format--json回應欄位 · data
rows符合篩選條件的所有列（逐頁累積；達安全上限時截斷）。
id訂單 id（前綴 `ord_`）。
orderNumber人類可讀訂單編號（每租戶 sequence 產生，如 `20260707-0001`）。
bookingState預訂狀態（真相軸）：pending_payment → confirmed → completed；cancelled 為終態。
paymentState付款狀態（派生自分類帳、快取於此供過濾）：unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」，不代表錢未退。
refundState退款狀態（派生快取，只算會影響應收的已付退款）：none / partially_refunded / refunded。
grossReceivableTwd應收（TWD 整數，派生自應收分類帳）。
collectedTwd收到現金（TWD 整數，派生）。
customerCashAppliedTwd客戶現金淨套用（收款減已退現金，TWD 整數，派生）。
outstandingTwd未收（應收減客戶現金淨套用，TWD 整數，派生）。
partySize參團人數（tour 訂單）。
createdAt訂單建立時間。
notes訂單備註（未填 → null）。
userId下單客戶的 user id（同庫 user 表）。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名（is_primary，未登記 → null）。
primaryTravelerPhone主要旅客電話（未登記 → null）。
tripId行程 id（tour 訂單經梯次反查；lodging 為空字串）。
tripTitle行程 / 產品標題。
tripSlug行程 slug。
departureId梯次 id（tour 訂單；lodging 為空字串）。
departureDate出發日 YYYY-MM-DD（lodging 為入住日）。
returnDate回程日 YYYY-MM-DD（lodging 為退房日）。
assignedToUserId派發給哪位業務的 user id（未派發 → null）。
assigneeName承辦業務顯示名（未派發 / 查無 → null）。
assignmentStatus派發狀態：unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間（未派發 → null）。
assignedByUserId執行派發者的 user id（未派發 → null）。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署（true = 待客戶重簽）。
roomingStatus分房狀態：由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態（null = FCFS 非抽籤）。'applied'|'won'|'lost'。
failoverFromOrderId備案單反查主單用：備案單的 failover_from_order_id 指向主單 id。
isOverdue逾期旗標：存在 status='open' 且 due_at 已過的收款計畫（未收齊的到期款）。 供列表列以 `bg-destructive/5` 標紅提示。由 OVERDUE_SUBSELECT 一次算回。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷（true 表未回傳完整結果，呼叫端應提示）。
cairn orders export
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"orderNumber": "…",
"bookingState": "…",
"paymentState": "…",
"refundState": "…",
"grossReceivableTwd": 0,
"collectedTwd": 0,
"customerCashAppliedTwd": 0,
"outstandingTwd": 0,
"partySize": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"notes": "…",
"userId": "…",
"userName": "…",
"userEmail": "…",
"primaryTravelerName": "…",
"primaryTravelerPhone": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureId": "…",
"departureDate": "…",
"returnDate": "…",
"assignedToUserId": "…",
"assigneeName": "…",
"assignmentStatus": "…",
"assignedAt": null,
"assignedByUserId": "…",
"createdByUserId": "…",
"pendingConsent": true,
"roomingStatus": "…",
"lotteryState": "…",
"failoverFromOrderId": "…",
"isOverdue": true
}
],
"total": 0,
"truncated": true
}
}cairn control
團控：梯次列表、名單、驗證、分房、財務、報表
cairn control departures近期梯次主列表（團控面板）
參數
--range時間視窗：future_60（未來 60 天）/ this_month（本月）/ next_month（下個月），預設不限
--trip行程 ID，只看該行程的梯次
--status梯次狀態篩選（如 open / closed）
--attention設為 true 時只回傳付款或同意書有異常、需要關注的梯次
--json回應欄位 · data[]
id梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
tripSlug行程公開頁網址代稱（slug）。
groupCode團號（可空）。
departureDate出發日（YYYY-MM-DD）。
returnDate回程日（YYYY-MM-DD）。
capacity團位容量（總名額）。
bookedCount已佔位人數。
status梯次狀態（如 open 開放／closed 關閉）。
allocationMode佔位模式：fcfs 先到先得／lottery 抽籤。
leaderNames已排領隊姓名（confirmed + tentative 皆列；空 = 未指派）。
assistantNames已排協作 / 助教姓名（空 = 未指派協作）。
priceTwd定價（TWD）。
agencyPriceTwd同業／旅行社報價（TWD；未設為 null）。
promoActive是否有進行中的促銷價。
promoPriceTwd促銷價（TWD；無促銷為 null）。
promoAgencyPriceTwd同業促銷價（TWD；無促銷為 null）。
daysUntilDeparture距出發天數（負值表示已出發）。
travelerCount旅客總人數（未取消訂單的 party_size 加總）。
paidCount已付款人數（party_size 加總）。
pendingCount未結清人數（未付／部分付／已付訂金；不含取消）。
cancelledCount已取消人數（僅供參考，不計入總數）。
ordersWithoutConsent尚未簽署同意書（PDPA）的訂單數。
codedRevenueTwd有折扣訂單的應收營收合計（TWD；排除取消／退款）。
discountTotalTwd折扣金額合計（TWD）。
profitShareTotalTwd利潤分潤金額合計（TWD）。
cairn control departures
{
"ok": true,
"data": [
{
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"groupCode": "…",
"departureDate": "…",
"returnDate": "…",
"capacity": 0,
"bookedCount": 0,
"status": "…",
"allocationMode": "fcfs",
"leaderNames": [
"…"
],
"assistantNames": [
"…"
],
"priceTwd": 0,
"agencyPriceTwd": 0,
"promoActive": true,
"promoPriceTwd": 0,
"promoAgencyPriceTwd": 0,
"daysUntilDeparture": 0,
"travelerCount": 0,
"paidCount": 0,
"pendingCount": 0,
"cancelledCount": 0,
"ordersWithoutConsent": 0,
"codedRevenueTwd": 0,
"discountTotalTwd": 0,
"profitShareTotalTwd": 0
}
]
}cairn control manifest梯次旅客名單
參數
<depId>位置參數 · 必填--json回應欄位 · data[]
orderId所屬訂單 id。
orderNumber所屬訂單編號。
travelerName旅客姓名。
phone聯絡電話。
email聯絡 Email。
isPrimary是否為該訂單的主要聯絡人（訂購人）。
gender性別（明文 enum-like）：'male'|'female'|'other'|null（未填）。
birthDate生日 ISO `YYYY-MM-DD`；null = 未填。
diet飲食需求（葷素）明文；null = 未填。
medicalNotes醫療 / 過敏 / 病史備註明文；null = 未填。
specialNeeds「飲食 · 特殊需求」欄的合併顯示字串（diet + medical_notes，以 ` · ` 併接）。 結構化欄落地後改吃 diet / medical_notes（不再湊 roommate_pref —— 分房需求回歸分房面板）。 兩者皆空 → null。
emergencyContactName緊急聯絡人姓名；null = 未填。
emergencyContactPhone緊急聯絡人電話；null = 未填。
consentPending該訂單是否仍缺最新版 PDPA 同意書（per-order，同訂單所有旅客共享此旗標）。 true = 未簽 / 只簽過舊版；與 dashboard KPI、催簽 badge 同一述詞。
orderStatusSingle display status (派生自三軸，與 deriveOrderDisplayStatus 同 precedence)。
amount該訂單應收金額（TWD；自 order_charge_lines 派生）。
cairn control manifest <depId>
{
"ok": true,
"data": [
{
"orderId": "…",
"orderNumber": "…",
"travelerName": "…",
"phone": "…",
"email": "…",
"isPrimary": true,
"gender": "male",
"birthDate": "…",
"diet": "…",
"medicalNotes": "…",
"specialNeeds": "…",
"emergencyContactName": "…",
"emergencyContactPhone": "…",
"consentPending": true,
"orderStatus": "…",
"amount": 0
}
]
}cairn control validation梯次旅客資料驗證摘要
參數
<depId>位置參數 · 必填--json回應欄位 · data[]
orderId訂單 id。
orderNumber訂單編號。
errorCount該訂單的 error（必補缺漏）項目數。
warningCount該訂單的 warning（建議補齊）項目數。
incompleteTravelerCount至少有一項 error 或 warning 的旅客數（資料待補人數）。
errorTravelerCount含 error 的旅客數（出團前置紅標用）。
cairn control validation <depId>
{
"ok": true,
"data": [
{
"orderId": "…",
"orderNumber": "…",
"errorCount": 0,
"warningCount": 0,
"incompleteTravelerCount": 0,
"errorTravelerCount": 0
}
]
}cairn control lottery-orders梯次抽籤訂單清單
參數
<depId>位置參數 · 必填--json回應欄位 · data[]
orderId訂單 id。
orderNumber訂單編號。
customerName訂購人姓名。
partySize佔位人數。
lotteryState抽籤狀態：applied 已應募／won 中籤／lost 未中籤。
backupChoiceCount客人自選的有序備案筆數（order_backup_choices；0 = 無備案）。
collectedTwd已收現金（payment_transactions direction='in'）；抽籤未中安置時的訂金結轉基準。
failoverFromOrderId落腳譜系：本單若是由某主單 force-place / cascade 落腳而成立的備案單，指向原主單 id。 null = 本單即主單（非備案落腳單）。供線控從備案列回溯主單。
awaitingPlacementtrue when lottery_state='lost' and still active (not cancelled). Means backup cascade exhausted — awaiting manual placement or explicit cancel.
cairn control lottery-orders <depId>
{
"ok": true,
"data": [
{
"orderId": "…",
"orderNumber": "…",
"customerName": "…",
"partySize": 0,
"lotteryState": "applied",
"backupChoiceCount": 0,
"collectedTwd": 0,
"failoverFromOrderId": "…",
"awaitingPlacement": true
}
]
}cairn control rooms梯次分房檢視
參數
<depId>位置參數 · 必填--json回應欄位 · data
departure梯次表頭（id／起訖日／行程名／容量等）。
id梯次 id（dep_ 前綴）。
departureDate出發日（ISO 'YYYY-MM-DD'）。
returnDate回程日（ISO 'YYYY-MM-DD'）。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
capacity名額上限（人數）。
bookedCount已成團佔用名額（人數）。
rooms此梯次的所有房間（含入住旅客）。
id房間 id。
roomLabel房號／房間標籤。
roomType房型（如 single 單人／double 雙人／dorm 通舖）。
bedCount床位數。
bedConfig床位配置說明（可空）。
accommodationName住宿名稱（梯次配套派生房才有；可空）。
accommodationDate住宿日期（YYYY-MM-DD；可空）。
baseCostTwd房間底價成本（TWD）。
upgradeFeeTwd房型升等補款（TWD）。
notes備註（可空）。
departureLodgingIdnull = 手動建立的房；non-null = 梯次配套自動派生房的來源 ID。
assignedTravelers已入住此房的旅客。
unassignedTravelers尚未分房的旅客清單。
id旅客 id。
fullName旅客姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
isPrimary是否為該訂單的主要聯絡人（訂購人）。
gender性別：'male'|'female'|'other'|null。
birthDate選填出生日期（YYYY-MM-DD；可空）。
roomPreference下單登記的房型偏好（auto-pair 起點提示）。
roommatePref指定房友 id / 特殊需求自由文字。
stats分房統計彙總（總人數／已分房數／房間數／升等補款合計）。
totalTravelers此梯次旅客總人數。
assignedCount已分配房間的旅客數。
roomCount房間數。
totalUpgradeFee升等補款合計（TWD 整數）。
cairn control rooms <depId>
{
"ok": true,
"data": {
"departure": {
"id": "…",
"departureDate": "…",
"returnDate": "…",
"tripTitle": "…",
"tripSlug": "…",
"capacity": 0,
"bookedCount": 0
},
"rooms": [
{
"id": "…",
"roomLabel": "…",
"roomType": "…",
"bedCount": 0,
"bedConfig": "…",
"accommodationName": "…",
"accommodationDate": "…",
"baseCostTwd": 0,
"upgradeFeeTwd": 0,
"notes": "…",
"departureLodgingId": "…",
"assignedTravelers": []
}
],
"unassignedTravelers": [
{
"id": "…",
"fullName": "…",
"orderId": "…",
"orderNumber": "…",
"isPrimary": true,
"gender": "…",
"birthDate": "…",
"roomPreference": "…",
"roommatePref": "…"
}
],
"stats": {
"totalTravelers": 0,
"assignedCount": 0,
"roomCount": 0,
"totalUpgradeFee": 0
}
}
}cairn control room-stats多梯次分房進度統計
參數
<depId>位置參數 · 必填--jsoncairn control room-stats <depId>
{
"ok": true,
"data": {}
}cairn control finance梯次財務摘要（唯讀）
參數
<depId>位置參數 · 必填--json回應欄位 · data
header梯次表頭（團號／行程名／出發日等基本資訊）。
id梯次 id（dep_ 前綴）。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日（ISO 'YYYY-MM-DD'）。
returnDate回程日（ISO 'YYYY-MM-DD'）。
finance應收／已收金額彙整（TWD）。
receivableTwd梯次應收：tour 訂單 order_charge_lines 聚合（排除已取消單）。
collectedTwd實收：tour 訂單 payment_transactions(direction='in')。
cashReturnedTwd客戶現金退回（refund/chargeback/reversal）。
outstandingTwd待收 = 應收 − (實收 − 退回)，floor 0。
costTwd成本：departure_costs 真實額（房費另計，見成本登記簿）。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本。
anomalyOrderCount異常單數：overpaid / partially_refunded / refund pending 的 tour 訂單。
cost成本彙整（各類直接成本合計，TWD）。
totalTwd內帳真實成本合計（TWD 整數，各成本列金額加總）。
billedTwd已轉請款的成本合計（TWD 整數）。
unbilledTwd尚未轉請款的成本合計（TWD 整數）。
declarableTwd外帳可申報金額合計（TWD 整數，各列憑證金額加總）。
nonDeclarableTwd無憑證的不可申報成本合計（TWD 整數，逐列取 金額−憑證 的正值，不可跨列抵減）。
count成本列筆數。
cairn control finance <depId>
{
"ok": true,
"data": {
"header": {
"id": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureDate": "…",
"returnDate": "…"
},
"finance": {
"receivableTwd": 0,
"collectedTwd": 0,
"cashReturnedTwd": 0,
"outstandingTwd": 0,
"costTwd": 0,
"costBilledTwd": 0,
"costUnbilledTwd": 0,
"anomalyOrderCount": 0
},
"cost": {
"totalTwd": 0,
"billedTwd": 0,
"unbilledTwd": 0,
"declarableTwd": 0,
"nonDeclarableTwd": 0,
"count": 0
}
}
}cairn control template-costs梯次成本範本列
參數
<depId>位置參數 · 必填--json回應欄位 · data[]
id梯次成本列 ID。
category成本分類（如 交通 / 餐費 / 保險）。
vendorName供應商 / 廠商名（可空）。
description摘要說明（可空）。
amountTwd內帳成本金額（TWD；數量 × 單價派生）。
invoiceAmountTwd報帳／發票金額（TWD；is_declarable=true 時同步 amount，否則 0）。
isDeclarable是否有合法憑證可報帳（開發票）。
quantityMode數量模式：fixed 固定值 / headcount 依人頭公式（ceil(Σ人頭 / 組距)）。
headcountComponentsheadcount 模式選定的人頭 component（passenger / leader / assistant / driver）；fixed 為 null。
groupDivisorheadcount 模式的組距（每 N 人一組，ceil 進位）；null = 直接加總。
quantity實際套用的數量（依 quantityMode 派生）。
unitPriceTwd內帳單價（TWD；外幣列可為 null）。
currency幣別（'TWD' = 台幣列）。
unitPriceForeign外幣單價；TWD 列 null。
foreignAmount外幣金額快照 = unit_price_foreign × quantity；TWD 列 null。
internalRate內帳匯率快照（numeric 字串）；TWD 列 null。
externalRate外帳匯率快照（numeric 字串）；TWD 列 null。
isManualOverride是否為線控手動改寫（true 時重算會跳過此列，不覆蓋手改值）。
payableId已轉請款 → 鎖定（不可手改 / 重算）。
cairn control template-costs <depId>
{
"ok": true,
"data": [
{
"id": "…",
"category": "…",
"vendorName": "…",
"description": "…",
"amountTwd": 0,
"invoiceAmountTwd": 0,
"isDeclarable": true,
"quantityMode": null,
"headcountComponents": null,
"groupDivisor": 0,
"quantity": 0,
"unitPriceTwd": 0,
"currency": "…",
"unitPriceForeign": 0,
"foreignAmount": 0,
"internalRate": "…",
"externalRate": "…",
"isManualOverride": true,
"payableId": "…"
}
]
}cairn control manifest-export梯次旅客名單匯出（csv|json）
參數
<depId>位置參數 · 必填--format--json回應欄位 · data[]
orderId所屬訂單 id。
orderNumber所屬訂單編號。
travelerName旅客姓名。
phone聯絡電話。
email聯絡 Email。
isPrimary是否為該訂單的主要聯絡人（訂購人）。
gender性別（明文 enum-like）：'male'|'female'|'other'|null（未填）。
birthDate生日 ISO `YYYY-MM-DD`；null = 未填。
diet飲食需求（葷素）明文；null = 未填。
medicalNotes醫療 / 過敏 / 病史備註明文；null = 未填。
specialNeeds「飲食 · 特殊需求」欄的合併顯示字串（diet + medical_notes，以 ` · ` 併接）。 結構化欄落地後改吃 diet / medical_notes（不再湊 roommate_pref —— 分房需求回歸分房面板）。 兩者皆空 → null。
emergencyContactName緊急聯絡人姓名；null = 未填。
emergencyContactPhone緊急聯絡人電話；null = 未填。
consentPending該訂單是否仍缺最新版 PDPA 同意書（per-order，同訂單所有旅客共享此旗標）。 true = 未簽 / 只簽過舊版；與 dashboard KPI、催簽 badge 同一述詞。
orderStatusSingle display status (派生自三軸，與 deriveOrderDisplayStatus 同 precedence)。
amount該訂單應收金額（TWD；自 order_charge_lines 派生）。
cairn control manifest-export <depId>
{
"ok": true,
"data": [
{
"orderId": "…",
"orderNumber": "…",
"travelerName": "…",
"phone": "…",
"email": "…",
"isPrimary": true,
"gender": "male",
"birthDate": "…",
"diet": "…",
"medicalNotes": "…",
"specialNeeds": "…",
"emergencyContactName": "…",
"emergencyContactPhone": "…",
"consentPending": true,
"orderStatus": "…",
"amount": 0
}
]
}cairn control rooming-export分房表匯出（csv|json）
參數
<depId>位置參數 · 必填--format--json回應欄位 · data[]
fullName旅客姓名。
gender性別（中文標籤：男／女／其他）。
roomLabel房號／房間標籤（未排房為「未分房」）。
bedInfo床位資訊（房型中文標籤 + 床位）。
roommates同房其他旅客姓名（依房號分組派生）。
specialRequest特殊需求（房友偏好等自由文字）。
contactSummary聯絡摘要（電話已遮罩，只露末 3 碼）。
cairn control rooming-export <depId>
{
"ok": true,
"data": [
{
"fullName": "…",
"gender": "…",
"roomLabel": "…",
"bedInfo": "…",
"roommates": "…",
"specialRequest": "…",
"contactSummary": "…"
}
]
}cairn control cost-add登記梯次成本（現場作業）
參數
<depId>位置參數 · 必填--category <c>成本科目類別，決定歸入哪個分類帳
--amount <twd>--vendor--desc--confirm回應欄位 · data
ok建立成功旗標，恆為 true。
id新建立的梯次成本列 id。
cairn control cost-add <depId> --category <c> --amount <twd>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control cost-update編輯梯次成本（會計）
參數
<depId>位置參數 · 必填--cost <costId>--category <c>成本科目類別，決定歸入哪個分類帳
--amount <twd>--vendor--desc--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn control cost-update <depId> --cost <costId> --category <c> --amount <twd>
{
"ok": true,
"data": {
"ok": true
}
}cairn control cost-rm刪除梯次成本（會計）
參數
<depId>位置參數 · 必填--cost <costId>--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control cost-rm <depId> --cost <costId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control template-apply套用行程綁定範本到本梯次（冪等）
參數
<depId>位置參數 · 必填--confirm回應欄位 · data
ok套用成功旗標，恆為 true。
inserted本次新補插入的範本成本行數（冪等，已存在的不重複插）。
cairn control template-apply <depId>
{
"ok": true,
"data": {
"ok": true,
"inserted": 0
}
}cairn control template-override手改某範本成本列金額（停自動重算）
參數
<depId>位置參數 · 必填--id <costId>範本成本列 ID
--amount <twd>--confirm回應欄位 · data
ok手改金額成功旗標，恆為 true。
cairn control template-override <depId> --id <costId> --amount <twd>
{
"ok": true,
"data": {
"ok": true
}
}cairn control template-clear-override重設範本成本列為範本算法（清手改鎖）
參數
<depId>位置參數 · 必填--id <costId>範本成本列 ID
--confirm回應欄位 · data
ok清除手改鎖並重算成功旗標，恆為 true。
cairn control template-clear-override <depId> --id <costId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control cost-to-payable成本轉請款（建立 payable）
參數
<depId>位置參數 · 必填--cost-ids <a,b>要轉成請款單的成本列 ID 清單，至少一筆
--payee-type <supplier|guide|staff_commission|other>受款人類型：supplier（供應商）/ guide（領隊）/ staff_commission（員工佣金）/ other（其他）
--payee-name <n>受款人姓名／戶名（必填）
--bank-account--bank-name--tax-id--submit--confirm回應欄位 · data
ok轉請款成功旗標，恆為 true。
payableId新建立的出款單（payable）id。
payableNumber出款單編號。
cairn control cost-to-payable <depId> --cost-ids <a,b> --payee-type <supplier|guide|staff_commission|other> --payee-name <n>
{
"ok": true,
"data": {
"ok": true,
"payableId": "…",
"payableNumber": "…"
}
}cairn control room-add建立梯次房間
參數
<depId>位置參數 · 必填--label <l>--type <t>--beds <n>--base-cost--upgrade-fee--notes房間備註
--confirm回應欄位 · data
ok建立成功旗標，恆為 true。
id新建立的房間 id。
cairn control room-add <depId> --label <l> --type <t> --beds <n>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control room-update編輯房間
參數
<depId>位置參數 · 必填--room <roomId>--label--type--beds--notes房間備註；給 null 清空、未給則不變
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn control room-update <depId> --room <roomId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control room-rm刪除房間
參數
<depId>位置參數 · 必填--room <roomId>--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control room-rm <depId> --room <roomId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control room-assign指派旅客進房
參數
--room <roomId>--traveler <travelerId>--confirm回應欄位 · data
ok指派入房成功旗標，恆為 true。
cairn control room-assign --room <roomId> --traveler <travelerId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control room-unassign把旅客移出房間
參數
--traveler <travelerId>--confirm回應欄位 · data
ok移出房間成功旗標，恆為 true。
cairn control room-unassign --traveler <travelerId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control room-auto-pair-previewauto-pair 建議分組預覽（純讀取；供 apply 取 travelerIds）
參數
<depId>位置參數 · 必填--json回應欄位 · data
suggestionauto-pair 引擎產出的分房建議（未寫入，供線控確認）。
groups建議的分房組合（每組一間房，含旅客與需確認註記）。
unmatched無法安全自動配對、待人工處理的旅客。
namestravelerId → 顯示名（建議分組渲染用）。
cairn control room-auto-pair-preview <depId>
{
"ok": true,
"data": {
"suggestion": {
"groups": [],
"unmatched": []
},
"names": "…"
}
}cairn control room-auto-pair-apply套用 auto-pair 建議分組（單一交易建房+整組指派）
參數
<depId>位置參數 · 必填--travelers <a,b,c>--type--confirm回應欄位 · data
ok套用成功旗標，恆為 true。
roomId建議分組寫入後所在的房間 id。
travelerIds被排入該房的旅客 id 清單。
cairn control room-auto-pair-apply <depId> --travelers <a,b,c>
{
"ok": true,
"data": {
"ok": true,
"roomId": "…",
"travelerIds": [
"…"
]
}
}cairn control lottery-resolve抽籤手動裁決（won|lost）
參數
<orderId>位置參數 · 必填--outcome <won|lost>抽籤裁決結果：won 中籤確認、lost 未中籤（啟動備案或取消）
--confirm回應欄位 · data
ok固定為 true：抽籤結果已登錄。
outcome抽籤結果：won 中籤 / lost 未中籤。
cairn control lottery-resolve <orderId> --outcome <won|lost>
{
"ok": true,
"data": {
"ok": true,
"outcome": "won"
}
}cairn control lottery-set-mode設定梯次分配模式（fcfs|lottery）
參數
<depId>位置參數 · 必填--mode <fcfs|lottery>分配模式：fcfs（先到先得）或 lottery（抽籤）
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
departureId被更新的梯次 id。
mode更新後的佔位模式：fcfs 先到先得／lottery 抽籤。
cairn control lottery-set-mode <depId> --mode <fcfs|lottery>
{
"ok": true,
"data": {
"ok": true,
"departureId": "…",
"mode": "fcfs"
}
}cairn control prep-checklist設定行前總檢查項勾選
參數
<depId>位置參數 · 必填--item <key>--checked <true|false>該檢查項目是否已完成勾選
--confirm回應欄位 · data
ok設定成功旗標，恆為 true。
id行前檢查項紀錄 id。
cairn control prep-checklist <depId> --item <key> --checked <true|false>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-documentupsert 證件追蹤狀態
參數
<depId>位置參數 · 必填--type <docType>--apply-status申辦狀態：todo（待辦）/ applying（申請中）/ approved（已核准）
--file-ready文件檔案是否已備妥
--note備註；給 null 清空
--confirm回應欄位 · data
okupsert 成功旗標，恆為 true。
id證件追蹤紀錄 id。
cairn control prep-document <depId> --type <docType>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-deadlines設定梯次期限警戒（登山專屬；全量取代，空值=清除）
參數
<depId>位置參數 · 必填--permit-apply入山申請截止日（ISO 日期）；傳空字串或省略則清除此期限
--permit-download入山證下載截止日（ISO 日期）；傳空字串或省略則清除此期限
--climbing-insurance登山險送保截止日（ISO 日期）；傳空字串或省略則清除此期限
--liability-insurance旅責險送保截止日（ISO 日期）；傳空字串或省略則清除此期限
--confirm回應欄位 · data
permitApply入山申請截止日（ISO 日期；null = 未設 / 已清除）。
permitDownload入山證下載截止日（ISO 日期；null = 未設 / 已清除）。
climbingInsurance登山險送保截止日（ISO 日期；null = 未設 / 已清除）。
liabilityInsurance旅責險送保截止日（ISO 日期；null = 未設 / 已清除）。
ok設定成功旗標，恆為 true。
departureId被設定期限的梯次 id。
cairn control prep-deadlines <depId>
{
"ok": true,
"data": {
"permitApply": "…",
"permitDownload": "…",
"climbingInsurance": "…",
"liabilityInsurance": "…",
"ok": true,
"departureId": "…"
}
}cairn control prep-equipment-needupsert 裝備需求數
參數
<depId>位置參數 · 必填--item <equipmentItemId>--qty <n>--note需求備註；給 null 清空
--confirm回應欄位 · data
okupsert 成功旗標，恆為 true。
id裝備需求紀錄 id。
cairn control prep-equipment-need <depId> --item <equipmentItemId> --qty <n>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-equipment-need-rm刪除裝備需求列
參數
<depId>位置參數 · 必填--id <needId>裝備需求列 ID
--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control prep-equipment-need-rm <depId> --id <needId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-guide-assign指派領隊到梯次
參數
<depId>位置參數 · 必填--guide <guideId>--role <leader|assistant>指派角色：leader（領隊）或 assistant（隨隊／助理）
--status指派狀態：tentative（暫定）或 confirmed（已確認）
--confirm回應欄位 · data
ok指派成功旗標，恆為 true。
id領隊指派紀錄 id。
cairn control prep-guide-assign <depId> --guide <guideId> --role <leader|assistant>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-rental從裝備需求開租借單（含金流接入）
參數
<depId>位置參數 · 必填--order <orderId>--lines <itemId:qty,itemId:qty>租借品項明細（品項 + 數量），數量需大於 0 才計入
--renter--confirm回應欄位 · data
ok開單成功旗標，恆為 true。
rentalId新開立的裝備租借單 id。
cairn control prep-rental <depId> --order <orderId> --lines <itemId:qty,itemId:qty>
{
"ok": true,
"data": {
"ok": true,
"rentalId": "…"
}
}cairn control prep-insurance-add新增投保紀錄
參數
<depId>位置參數 · 必填--kind <k>保險種類（如登山險、旅責險）
--insurer保險公司名稱
--policy-no保單號碼
--status投保狀態，預設 pending
--note備註；給 null 清空
--confirm回應欄位 · data
ok建立成功旗標，恆為 true。
id新建立的投保紀錄 id。
cairn control prep-insurance-add <depId> --kind <k>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-insurance-update更新投保紀錄
參數
<depId>位置參數 · 必填--id <insId>投保紀錄 ID
--insurer保險公司名稱
--policy-no保單號碼
--status投保狀態
--note備註；給 null 清空
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn control prep-insurance-update <depId> --id <insId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-insurance-rm刪除投保紀錄
參數
<depId>位置參數 · 必填--id <insId>投保紀錄 ID
--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control prep-insurance-rm <depId> --id <insId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-transport-add新增派車紀錄
參數
<depId>位置參數 · 必填--desc--driver--vehicle--fare-note車資備註
--status派車狀態，預設 pending
--confirm回應欄位 · data
ok建立成功旗標，恆為 true。
id新建立的派車紀錄 id。
cairn control prep-transport-add <depId>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-transport-update更新派車紀錄
參數
<depId>位置參數 · 必填--id <tId>派車紀錄 ID
--desc--driver--vehicle--fare-note車資備註
--status派車狀態
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn control prep-transport-update <depId> --id <tId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-transport-rm刪除派車紀錄
參數
<depId>位置參數 · 必填--id <tId>派車紀錄 ID
--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control prep-transport-rm <depId> --id <tId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-catering-add新增餐食紀錄
參數
<depId>位置參數 · 必填--supplier餐食供應商名稱
--meal-plan餐食安排說明（如餐數、菜色）
--headcount-note人數備註（如素食、特殊餐需求）
--status餐食安排狀態，預設 pending
--confirm回應欄位 · data
ok建立成功旗標，恆為 true。
id新建立的餐食紀錄 id。
cairn control prep-catering-add <depId>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn control prep-catering-update更新餐食紀錄
參數
<depId>位置參數 · 必填--id <cId>餐食紀錄 ID
--supplier餐食供應商名稱
--meal-plan餐食安排說明（如餐數、菜色）
--headcount-note人數備註（如素食、特殊餐需求）
--status餐食安排狀態
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn control prep-catering-update <depId> --id <cId>
{
"ok": true,
"data": {
"ok": true
}
}cairn control prep-catering-rm刪除餐食紀錄
參數
<depId>位置參數 · 必填--id <cId>餐食紀錄 ID
--confirm回應欄位 · data
ok刪除成功旗標，恆為 true。
cairn control prep-catering-rm <depId> --id <cId>
{
"ok": true,
"data": {
"ok": true
}
}cairn equipment
裝備租借：品項主檔、租借單查詢
cairn equipment items裝備品項主檔：list / get / create / update
參數
<id>位置參數 · 必填--active-only--name <n>--total--rent-price--activecairn equipment items <id>
cairn equipment rentals租借單：list / get / order-options / create / return / mark-overdue
參數
<id>位置參數 · 必填<rentalId>位置參數 · 必填--return-state--recon-state--order-id <id>--limit--line <itemId>--damage-costcairn equipment rentals <id> <rentalId> --line <itemId>
cairn guide-roster
帶團排班：名冊載量、月梯次、檔期衝突
cairn guide-roster guides名冊 + 該月帶團載量
參數
--month <YYYY-MM>查詢月份（YYYY-MM 格式）
--include-inactive是否一併列出已停用的嚮導（預設不列出）
--json回應欄位 · data[]
id嚮導 id。
name嚮導姓名。
rosterRole名冊職能：leader 領隊／assistant 隨隊助理／both 皆可。
specialties可帶路線 / 專長；未設為空陣列。
status嚮導狀態：active 啟用／inactive 停用。
maxDaysPerMonth單月可帶上限（天）；NULL = 不限。
monthDays本月 confirmed 指派的帶團天數彙總。
monthTrips本月 confirmed 帶團梯次數。
hasTentative本月是否含 tentative（預塞）指派。
availability派生載量狀態。
cairn guide-roster guides --month <YYYY-MM>
{
"ok": true,
"data": [
{
"id": "…",
"name": "…",
"rosterRole": "leader",
"specialties": [
"…"
],
"status": "…",
"maxDaysPerMonth": 0,
"monthDays": 0,
"monthTrips": 0,
"hasTentative": true,
"availability": "…"
}
]
}cairn guide-roster departures該月梯次 + 已排指派
參數
--month <YYYY-MM>查詢月份（YYYY-MM 格式）
--include-cancelled是否一併納入已取消的梯次（預設不納入）
--json回應欄位 · data[]
id梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
departureDate出發日（YYYY-MM-DD）。
returnDate回程日（YYYY-MM-DD）。
days帶團天數（含頭尾）。
capacity團位容量（總名額）。
bookedCount已成團報名人數。
status梯次狀態（如 open 開放／full 已滿／cancelled 已取消）。
assignments該梯次所有指派（領隊在前）。
id指派紀錄 id。
guideId被指派的嚮導 id。
guideName被指派的嚮導姓名。
role指派角色：leader 領隊／assistant 隨隊助理。
status指派狀態：tentative 預塞暫定／confirmed 正式確認。
cairn guide-roster departures --month <YYYY-MM>
{
"ok": true,
"data": [
{
"id": "…",
"tripId": "…",
"tripTitle": "…",
"departureDate": "…",
"returnDate": "…",
"days": 0,
"capacity": 0,
"bookedCount": 0,
"status": "…",
"assignments": [
{
"id": "…",
"guideId": "…",
"guideName": "…",
"role": "leader",
"status": "tentative"
}
]
}
]
}cairn guide-roster conflicts該月檔期衝突偵測
參數
--month <YYYY-MM>查詢月份（YYYY-MM 格式）
--json回應欄位 · data[]
guideId發生衝突的嚮導 id。
guideName發生衝突的嚮導姓名。
a衝突梯次之一（含梯次 id／行程名／起訖日）。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日（YYYY-MM-DD）。
returnDate回程日（YYYY-MM-DD）。
b與 a 日期重疊的另一梯次（含梯次 id／行程名／起訖日）。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日（YYYY-MM-DD）。
returnDate回程日（YYYY-MM-DD）。
cairn guide-roster conflicts --month <YYYY-MM>
{
"ok": true,
"data": [
{
"guideId": "…",
"guideName": "…",
"a": {
"departureId": "…",
"tripTitle": "…",
"departureDate": "…",
"returnDate": "…"
},
"b": {
"departureId": "…",
"tripTitle": "…",
"departureDate": "…",
"returnDate": "…"
}
}
]
}cairn guide-roster check-conflict撞期預檢（指定梯次×領隊）
參數
--departure <id>--guide <id>--jsoncairn guide-roster check-conflict --departure <id> --guide <id>
{
"ok": true,
"data": null
}cairn guide-roster assign指派 / 重派領隊到梯次（upsert）
參數
--departure <id>--guide <id>--role <leader|assistant>指派角色（leader 領隊／assistant 隨隊助理）
--status <tentative|confirmed>指派狀態（tentative 預塞暫定／confirmed 正式確認）
--confirm回應欄位 · data
id新建立（或重派後）的指派紀錄 id。
cairn guide-roster assign --departure <id> --guide <id> --role <leader|assistant> --status <tentative|confirmed>
{
"ok": true,
"data": {
"id": "…"
}
}cairn guide-roster confirm正式確認某筆指派
參數
<assignmentId>位置參數 · 必填--confirm回應欄位 · data
ok確認成功旗標，恆為 true。
cairn guide-roster confirm <assignmentId>
{
"ok": true,
"data": {
"ok": true
}
}cairn guide-roster remove移除某筆指派
參數
<assignmentId>位置參數 · 必填--confirm回應欄位 · data
ok移除成功旗標，恆為 true。
cairn guide-roster remove <assignmentId>
{
"ok": true,
"data": {
"ok": true
}
}cairn guide-roster change-leader換領隊（升任新領隊為 confirmed leader）
參數
--departure <id>--to <guideId>--reason <t>換領隊的原因（必填，記入稽核）
--from <guideId>--confirm回應欄位 · data
id新任領隊的指派紀錄 id。
removedGuideIds被移除的舊領隊嚮導 id 清單（DB 權威）。
cairn guide-roster change-leader --departure <id> --to <guideId> --reason <t>
{
"ok": true,
"data": {
"id": "…",
"removedGuideIds": [
"…"
]
}
}cairn guides
嚮導：查詢、明細
cairn guides list列出/搜尋嚮導
參數
--status嚮導狀態篩選（all 全部／active 啟用／inactive 停用）
--q關鍵字搜尋（比對嚮導姓名等欄位）
--page頁碼（從 1 起算）
--page-size每頁筆數（上限 200）
--jsoncairn guides list
{
"ok": true,
"data": "…"
}cairn guides get單一嚮導明細（依 id 或 --slug）
參數
<id>位置參數 · 必填--slug <slug>公開頁網址代稱（小寫英數與連字號；省略則不更動）
--jsoncairn guides get <id> --slug <slug>
cairn guides create建立嚮導（建檔）
參數
--name <name>嚮導／領隊姓名
--slug依嚮導公開頁網址代稱（slug）精確查單筆（選填）
--bio嚮導簡介／經歷（選填）
--avatar-url大頭照圖片網址（選填，http/https）
--specialties專長領域（選填，以逗號分隔多項）
--years-experience帶團年資（年數，0～80；選填）
--contact-phone聯絡電話（選填）
--contact-email聯絡 Email（選填）
--status嚮導狀態篩選（all 全部／active 啟用／inactive 停用）
--confirm回應欄位 · data
id新建立的嚮導 id。
slug嚮導公開頁網址代稱（未帶則系統自動產生）。
cairn guides create --name <name>
{
"ok": true,
"data": {
"id": "…",
"slug": "…"
}
}cairn guides update更新嚮導（建檔編輯；只送有帶的欄位）
參數
<id>位置參數 · 必填--name嚮導／領隊姓名（省略則不更動）
--slug公開頁網址代稱（小寫英數與連字號；省略則不更動）
--bio嚮導簡介／經歷（省略則不更動）
--avatar-url大頭照圖片網址（http/https；省略則不更動）
--specialties專長領域（以逗號分隔多項；省略則不更動）
--years-experience帶團年資（年數，0～80；省略則不更動）
--contact-phone聯絡電話（省略則不更動）
--contact-email聯絡 Email（省略則不更動）
--status嚮導狀態（active 啟用／inactive 停用；省略則不更動）
--confirm回應欄位 · data
ok更新成功旗標，恆為 true。
cairn guides update <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn guides archive封存嚮導（status→inactive；重啟用請用 guides update --status active）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok封存成功旗標，恆為 true。
cairn guides archive <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn guides invite-account開通嚮導 portal 登入帳號（回傳一次性暫時密碼，僅此一次）
參數
<id>位置參數 · 必填--email <e>嚮導 portal 登入帳號的 Email
--name <n>嚮導帳號的顯示姓名
--confirm--json回應欄位 · data
tempPassword一次性明文暫時密碼（僅此次回傳，請立即轉交嚮導並要求首次登入改密）。
email已開通登入帳號的 Email。
cairn guides invite-account <id> --email <e> --name <n>
{
"ok": true,
"data": {
"tempPassword": "…",
"email": "…"
}
}cairn journal
嚮導手記：查詢、明細、作者選項
cairn journal list列出/搜尋手記
參數
--status依狀態篩選：all 全部、draft 草稿、published 已發佈、archived 已封存
--q關鍵字搜尋（標題／內容）
--page頁碼（從 1 起）
--page-size每頁筆數（上限 200）
--json回應欄位 · data
rows本頁的手記文章列表。
id手記文章 id（journalPost_ 前綴）。
slug文章公開頁網址代稱（slug）。
title文章標題。
excerpt摘要（列表／SEO 用；可空）。
coverImageUrl封面圖網址（可空）。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id（未指定作者時 null）。
seoTitleSEO 標題（覆寫 <title>；可空）。
seoDescriptionSEO 描述（meta description；可空）。
ogImageUrlOpen Graph 分享圖網址（可空）。
status文章狀態：draft 草稿／published 已發佈／archived 已封存。
publishedAt首次發佈時間（尚未發佈為 null）。
createdAt建檔時間。
updatedAt最後更新時間。
total符合條件的文章總數（跨頁）。
page目前頁碼（從 1 起）。
pageSize每頁筆數。
cairn journal list
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"slug": "…",
"title": "…",
"excerpt": "…",
"coverImageUrl": "…",
"contentMdx": "…",
"authorGuideId": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"status": "…",
"publishedAt": null,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn journal get單一手記完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id手記文章 id（journalPost_ 前綴）。
slug文章公開頁網址代稱（slug）。
title文章標題。
excerpt摘要（列表／SEO 用；可空）。
coverImageUrl封面圖網址（可空）。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id（未指定作者時 null）。
seoTitleSEO 標題（覆寫 <title>；可空）。
seoDescriptionSEO 描述（meta description；可空）。
ogImageUrlOpen Graph 分享圖網址（可空）。
status文章狀態：draft 草稿／published 已發佈／archived 已封存。
publishedAt首次發佈時間（尚未發佈為 null）。
createdAt建檔時間。
updatedAt最後更新時間。
cairn journal get <id>
{
"ok": true,
"data": {
"id": "…",
"slug": "…",
"title": "…",
"excerpt": "…",
"coverImageUrl": "…",
"contentMdx": "…",
"authorGuideId": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"status": "…",
"publishedAt": null,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn journal create建立手記
參數
--title <t>手記標題，顯示於前台與後台列表
--content-mdx <md>內文（MDX 格式）
--slug <s>網址代稱（slug）；僅小寫英數與連字號，省略時由系統依標題產生
--excerpt <e>摘要，列表與分享預覽用；null 清除
--cover-image-url <url>封面圖網址（http/https）；null 清除
--author-guide-id <id>作者嚮導 ID；null 表示無指定作者
--seo-title <t>SEO 標題，省略時用 title；null 清除
--seo-description <d>SEO 描述（meta description）；null 清除
--og-image-url <url>Open Graph 分享圖網址（http/https）；null 清除
--status依狀態篩選：all 全部、draft 草稿、published 已發佈、archived 已封存
--json回應欄位 · data
id新建立的手記文章 id。
slug文章公開頁網址代稱（slug）。
cairn journal create --title <t> --content-mdx <md>
{
"ok": true,
"data": {
"id": "…",
"slug": "…"
}
}cairn journal update更新手記（整體取代，欄位比照建立）
參數
<id>位置參數 · 必填--title <t>手記標題，顯示於前台與後台列表
--content-mdx <md>內文（MDX 格式）
--slug <s>網址代稱（slug）；僅小寫英數與連字號，省略時由系統依標題產生
--excerpt <e>摘要，列表與分享預覽用；null 清除
--cover-image-url <url>封面圖網址（http/https）；null 清除
--author-guide-id <id>作者嚮導 ID；null 表示無指定作者
--seo-title <t>SEO 標題，省略時用 title；null 清除
--seo-description <d>SEO 描述（meta description）；null 清除
--og-image-url <url>Open Graph 分享圖網址（http/https）；null 清除
--status發佈狀態：draft 草稿、published 已發佈、archived 已封存
--json回應欄位 · data
ok更新成功旗標，恆為 true。
cairn journal update <id> --title <t> --content-mdx <md>
{
"ok": true,
"data": {
"ok": true
}
}cairn journal archive封存手記
參數
<id>位置參數 · 必填--json回應欄位 · data
ok封存成功旗標，恆為 true。
cairn journal archive <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn exchange-rates
牌告匯率：列出、解析
cairn exchange-rates list列出牌告匯率（台銀 bot + manual 覆蓋）
參數
--currency幣別篩選（ISO 4217 三碼，如 JPY / USD）；省略則回傳所有幣別
--month-from起始月份（YYYY-MM，含當月）；省略則不設下界
--month-to結束月份（YYYY-MM，含當月）；省略則不設上界
--json回應欄位 · data[]
id匯率牌價列 ID。
rateDate掛牌日期（'YYYY-MM-DD'，Asia/Taipei）。
currencyISO 4217（'JPY' / 'IDR' / 'USD'…）。
cashBuy各報價 canonical「1 外幣 = ? 台幣」（numeric → 字串原值保精度；NULL = 該幣別無此報價）。
cashSell現金賣出匯率「1 外幣 = ? 台幣」（字串保精度；null = 無此報價）。
spotBuy即期買入匯率「1 外幣 = ? 台幣」（字串保精度；null = 無此報價）。
spotSell即期賣出匯率「1 外幣 = ? 台幣」（字串保精度；null = 無此報價）。
source牌價來源：bot 台銀自動抓取 / manual 租戶手動覆蓋。
createdAt建立時間。
updatedAt最後更新時間。
cairn exchange-rates list
{
"ok": true,
"data": [
{
"id": "…",
"rateDate": "…",
"currency": "…",
"cashBuy": "…",
"cashSell": "…",
"spotBuy": "…",
"spotSell": "…",
"source": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn exchange-rates resolve解析某幣別某日報價（manual 優先 + carry-forward）
參數
--currency要換算的外幣幣別（ISO 4217 三碼，如 JPY / USD）
--date換算基準日期（YYYY-MM-DD），套用手動優先 + 往前承接的解析規則
--quote報價類型：cash_buy 現金買入、cash_sell 現金賣出、spot_buy 即期買入、spot_sell 即期賣出；省略預設 spot_sell
--json回應欄位 · data
currency換算的外幣幣別（ISO 4217 三碼）。
date換算基準日期（YYYY-MM-DD）。
quote使用的報價類型（cash_buy / cash_sell / spot_buy / spot_sell）。
rate解析出的匯率「1 外幣 = ? 台幣」（字串保精度）；查無適用牌價為 null。
cairn exchange-rates resolve --currency --date
{
"ok": true,
"data": {
"currency": "…",
"date": "…",
"quote": "cash_buy",
"rate": "…"
}
}cairn exchange-rates set-manual手動覆蓋某日某幣別匯率（source=manual，可重存覆蓋）
參數
--date--currency幣別（ISO 4217 三碼大寫，如 JPY / USD）
--cash-buy現金買入匯率（正數最多 6 位小數，以字串表達）；四種報價至少填一個，留空傳 null
--cash-sell現金賣出匯率（正數最多 6 位小數，以字串表達）；四種報價至少填一個，留空傳 null
--spot-buy即期買入匯率（正數最多 6 位小數，以字串表達）；四種報價至少填一個，留空傳 null
--spot-sell即期賣出匯率（正數最多 6 位小數，以字串表達）；四種報價至少填一個，留空傳 null
--confirm回應欄位 · data
ok是否覆蓋寫入成功。
id寫入 / 更新的 manual 匯率牌價列 ID。
cairn exchange-rates set-manual --date --currency
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn payment-requests
對外應付請款單：查詢、明細、統計、廠商建議
cairn payment-requests list列出/搜尋對外應付請款單
參數
--status依狀態篩選（draft 草稿 / submitted 已送審 / approved 已核准 / paid 已付款 / rejected 已退件 / cancelled 已取消 / all 全部）
--payee-type依收款對象類型篩選（supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他 / all 全部）
--departure--created-by--q關鍵字搜尋（請款單號、收款對象名稱等）
--page頁碼（從 1 起算）
--page-size每頁筆數（上限 200）
--json回應欄位 · data
rows本頁請款單列。
id請款單 ID。
requestNumber請款單號（人可讀，每租戶流水號）。
status核簽工作流狀態：draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型：supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額（TWD 整數；= 細項小計合計，代扣稅前）。
netAmountTwd實付淨額（TWD 整數；= 請款總額 − 代扣稅額，即實際匯款金額）。
taxAmountTwd代扣稅額（TWD 整數）。
departureId關聯梯次 ID；未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤（行程名稱＋出發日）；無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名；查無為 null。
paidAt標記付款完成時間；未付為 null。
submittedAt送審時間；未送審為 null。
approvedAt核准時間；未核准為 null。
total符合篩選條件的總筆數（跨全部分頁）。
page目前頁碼（從 1 起算）。
pageSize每頁筆數。
cairn payment-requests list
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"requestNumber": "…",
"status": "…",
"payeeType": "…",
"payeeName": "…",
"amountTwd": 0,
"netAmountTwd": 0,
"taxAmountTwd": 0,
"departureId": "…",
"departureLabel": "…",
"description": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z",
"createdByUserId": "…",
"createdByName": "…",
"paidAt": null,
"submittedAt": null,
"approvedAt": null
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn payment-requests get單一請款單完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
payeeBankAccount收款銀行帳號。
payeeBankName收款銀行名稱。
payeeBankBranch收款銀行分行。
payeeTaxId收款對象統一編號 / 稅籍編號。
submittedByUserId送審人 user ID；未送審為 null。
submittedByName送審人姓名；無則為 null。
approvedByUserId核准人 user ID；未核准為 null。
approvedByName核准人姓名；無則為 null。
paidByUserId標記付款人 user ID；未付為 null。
paidByName標記付款人姓名；無則為 null。
rejectedAt退件時間；未退件為 null。
rejectedByName退件人姓名；無則為 null。
rejectionReason退件原因；無則為 null。
cancelledAt取消時間；未取消為 null。
cancelledByName取消人姓名；無則為 null。
cancellationReason取消原因；無則為 null。
pdfGeneratedAt請款單 PDF 產生時間；未產生為 null。
paperPrintedAt紙本列印時間；未列印為 null。
paperSignedBy紙本簽核人；未簽為 null。
bankReference銀行匯款交易參考號（付款後回填）；無則為 null。
items請款細項清單。
id請款細項 ID。
category細項類別（如住宿、交通、餐食）。
description細項說明。
quantity數量。
unitPriceTwd單價（TWD 整數；負值表折讓）。
totalTwd細項小計（TWD 整數；= 數量 × 單價）。
notes細項備註；無則為 null。
sortOrder顯示排序（由小到大）。
audit稽核軌跡（狀態機每次轉移一筆，時間新到舊或建立序）。
id稽核記錄 ID。
action動作代號（如 payable.create、payable.submit、payable.approve）。
createdAt動作發生時間。
actorUserId操作者 user ID；系統動作為 null。
actorName操作者姓名；無則為 null。
metadata動作附帶的結構化資料（欄位隨 action 而定）。
ipAddress操作來源 IP；無則為 null。
id請款單 ID。
requestNumber請款單號（人可讀，每租戶流水號）。
status核簽工作流狀態：draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型：supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額（TWD 整數；= 細項小計合計，代扣稅前）。
netAmountTwd實付淨額（TWD 整數；= 請款總額 − 代扣稅額，即實際匯款金額）。
taxAmountTwd代扣稅額（TWD 整數）。
departureId關聯梯次 ID；未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤（行程名稱＋出發日）；無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名；查無為 null。
paidAt標記付款完成時間；未付為 null。
submittedAt送審時間；未送審為 null。
approvedAt核准時間；未核准為 null。
cairn payment-requests get <id>
{
"ok": true,
"data": {
"payeeBankAccount": "…",
"payeeBankName": "…",
"payeeBankBranch": "…",
"payeeTaxId": "…",
"submittedByUserId": "…",
"submittedByName": "…",
"approvedByUserId": "…",
"approvedByName": "…",
"paidByUserId": "…",
"paidByName": "…",
"rejectedAt": null,
"rejectedByName": "…",
"rejectionReason": "…",
"cancelledAt": null,
"cancelledByName": "…",
"cancellationReason": "…",
"pdfGeneratedAt": null,
"paperPrintedAt": null,
"paperSignedBy": "…",
"bankReference": "…",
"items": [
{
"id": "…",
"category": "…",
"description": "…",
"quantity": 0,
"unitPriceTwd": 0,
"totalTwd": 0,
"notes": "…",
"sortOrder": 0
}
],
"audit": [
{
"id": "…",
"action": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"actorUserId": "…",
"actorName": "…",
"metadata": "…",
"ipAddress": "…"
}
],
"id": "…",
"requestNumber": "…",
"status": "…",
"payeeType": "…",
"payeeName": "…",
"amountTwd": 0,
"netAmountTwd": 0,
"taxAmountTwd": 0,
"departureId": "…",
"departureLabel": "…",
"description": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z",
"createdByUserId": "…",
"createdByName": "…",
"paidAt": null,
"submittedAt": null,
"approvedAt": null
}
}cairn payment-requests stats對外應付請款單 KPI 統計
參數
--json回應欄位 · data
draftCount草稿狀態的請款單數。
submittedCount已送審待核准的請款單數。
approvedCount已核准待付款的請款單數。
paidCount已付款的請款單數。
thisMonthPaidCount本月已付款的請款單數。
thisMonthAmount本月已付款的實付淨額合計（TWD 整數；台北月起算）。
totalApprovedAmount已核准未付的實付淨額合計（TWD 整數；待出款金額）。
cairn payment-requests stats
{
"ok": true,
"data": {
"draftCount": 0,
"submittedCount": 0,
"approvedCount": 0,
"paidCount": 0,
"thisMonthPaidCount": 0,
"thisMonthAmount": 0,
"totalApprovedAmount": 0
}
}cairn payment-requests suggest-items由梯次住宿成本推導供應商請款細項建議
參數
--departure <id>--json回應欄位 · data[]
category建議的請款細項類別（如住宿）。
description建議的細項說明（住宿廠商 × 房型 × 晚數）。
quantity建議數量（間數 × 晚數）。
unitPriceTwd建議單價（TWD 整數；每間每晚成本）。
totalTwd建議小計（TWD 整數；= 數量 × 單價）。
suggestedPayee建議的收款對象（住宿供應商名稱）；查無為 null。
cairn payment-requests suggest-items --departure <id>
{
"ok": true,
"data": [
{
"category": "…",
"description": "…",
"quantity": 0,
"unitPriceTwd": 0,
"totalTwd": 0,
"suggestedPayee": "…"
}
]
}cairn payment-requests create建立對外應付請款單（draft，或 --submit 同步送審）
參數
<cat:desc:qty:price[:notes]>位置參數 · 必填--payee-type <supplier|guide|staff_commission|other>依收款對象類型篩選（supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他 / all 全部）
--payee-name <n>收款對象名稱
--description <d>請款單摘要說明
--tax--departure--bank-account--bank-name--bank-branch--tax-id--submit--confirm回應欄位 · data
id新建立請款單的 id。
requestNumber新建立請款單的單號（人可讀）。
status建立後狀態（draft，或 submitImmediately 時為 submitted）。
cairn payment-requests create <cat:desc:qty:price[:notes]> --payee-type <supplier|guide|staff_commission|other> --payee-name <n> --description <d>
{
"ok": true,
"data": {
"id": "…",
"requestNumber": "…",
"status": "…"
}
}cairn payment-requests approve核可請款單（submitted→approved；責任分離，需 payable.approve）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否核可成功（submitted→approved）。
cairn payment-requests approve <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests submit送審請款單（draft→submitted）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否送審成功（draft→submitted）。
cairn payment-requests submit <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests reject退件請款單（submitted→draft）
參數
<id>位置參數 · 必填--reason <text>退件原因（必填，回饋給建單人）
--confirm回應欄位 · data
ok是否退件成功（submitted→draft）。
cairn payment-requests reject <id> --reason <text>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests mark-paid標記請款單已付（approved→paid）
參數
<id>位置參數 · 必填--bank-reference <ref>網銀交易序號 / 轉帳憑證號（必填）
--receiving-account--paper-signed-by紙本簽核人姓名
--confirm回應欄位 · data
ok是否標記付款成功（approved→paid）。
cairn payment-requests mark-paid <id> --bank-reference <ref>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests cancel取消請款單（非 paid；僅建單人或 admin）
參數
<id>位置參數 · 必填--reason取消原因；留空預設為「使用者取消」（上限 200 字）
--confirm回應欄位 · data
ok是否取消成功（idempotent，已取消再呼叫仍為 true）。
cairn payment-requests cancel <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests mark-signed記錄紙本簽核人
參數
<id>位置參數 · 必填--signed-by <name>紙本簽核人姓名（必填）
--confirm回應欄位 · data
ok是否記錄紙本簽核人成功。
cairn payment-requests mark-signed <id> --signed-by <name>
{
"ok": true,
"data": {
"ok": true
}
}cairn payment-requests mark-printed標記 PDF/紙本已產生（idempotent）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否標記 PDF / 紙本已產生成功（idempotent）。
cairn payment-requests mark-printed <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn payments
收款流水帳：查詢、統計
cairn payments list列出/搜尋收款流水
參數
--status依金流狀態篩選（如 paid 已收款 / pending 待付 / failed 失敗 / refunded 已退款）
--method依付款方式篩選（如信用卡、ATM 轉帳）
--q關鍵字搜尋（訂單編號、客戶名稱等）
--date-from收款日期區間起日（YYYY-MM-DD）
--date-to收款日期區間迄日（YYYY-MM-DD）
--page頁碼（從 1 起算）
--json回應欄位 · data
rows本頁付款嘗試列。
id付款嘗試（payment attempt）ID，此列的唯一識別。
orderId所屬訂單 ID。
orderNumber所屬訂單編號（人可讀）。
merchantTradeNoprovider_order_ref（= 我們產的 MerchantTradeNo）。
providerTradeNo金流商回傳的交易序號（未成交或手動入帳為 null）。
provider金流商代號（如 ecpay、test；手動入帳為 manual）。
paymentMethod付款方式（如信用卡、ATM 虛擬帳號）。
amountTwd此筆嘗試的金額（TWD 整數）。
statusattempt 狀態：pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易（out 方向）。
paidAt實際入帳（現金結算）時間；未結算為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數（跨全部分頁）。
page目前頁碼（從 1 起算）。
pageSize每頁筆數。
cairn payments list
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"orderId": "…",
"orderNumber": "…",
"merchantTradeNo": "…",
"providerTradeNo": "…",
"provider": "…",
"paymentMethod": "…",
"amountTwd": 0,
"status": "…",
"refunded": true,
"paidAt": null,
"createdAt": "2026-06-30T08:00:00.000Z",
"customerName": "…",
"customerEmail": "…",
"tripTitle": "…"
}
],
"total": 0,
"page": 0,
"pageSize": 0
}
}cairn payments stats收款 KPI 統計
參數
--json回應欄位 · data
totalAmount累計實收現金（payment_transactions in）。
paidCount已成功收款的付款嘗試數。
pendingCount待付 / 處理中的付款嘗試數（pending、submitted）。
failedCount失敗或逾期的付款嘗試數（failed、expired）。
refundedCount有關聯退款 / 退單的付款嘗試數。
thisMonthAmount本月累計實收現金（TWD 整數）。
cairn payments stats
{
"ok": true,
"data": {
"totalAmount": 0,
"paidCount": 0,
"pendingCount": 0,
"failedCount": 0,
"refundedCount": 0,
"thisMonthAmount": 0
}
}cairn payments export匯出金流分類帳為 CSV/JSON（同 list 篩選；取全頁）
參數
--status依金流狀態篩選（如 paid 已收款 / pending 待付 / failed 失敗 / refunded 已退款）
--method依付款方式篩選（如信用卡、ATM 轉帳）
--date-from收款日期區間起日（YYYY-MM-DD）
--date-to收款日期區間迄日（YYYY-MM-DD）
--q關鍵字搜尋（訂單編號、客戶名稱等）
--format--json回應欄位 · data
rows符合篩選條件的所有列（逐頁累積；達安全上限時截斷）。
id付款嘗試（payment attempt）ID，此列的唯一識別。
orderId所屬訂單 ID。
orderNumber所屬訂單編號（人可讀）。
merchantTradeNoprovider_order_ref（= 我們產的 MerchantTradeNo）。
providerTradeNo金流商回傳的交易序號（未成交或手動入帳為 null）。
provider金流商代號（如 ecpay、test；手動入帳為 manual）。
paymentMethod付款方式（如信用卡、ATM 虛擬帳號）。
amountTwd此筆嘗試的金額（TWD 整數）。
statusattempt 狀態：pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易（out 方向）。
paidAt實際入帳（現金結算）時間；未結算為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷（true 表未回傳完整結果，呼叫端應提示）。
cairn payments export
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"orderId": "…",
"orderNumber": "…",
"merchantTradeNo": "…",
"providerTradeNo": "…",
"provider": "…",
"paymentMethod": "…",
"amountTwd": 0,
"status": "…",
"refunded": true,
"paidAt": null,
"createdAt": "2026-06-30T08:00:00.000Z",
"customerName": "…",
"customerEmail": "…",
"tripTitle": "…"
}
],
"total": 0,
"truncated": true
}
}cairn reconciliation
收款帳戶對帳 + 帳戶結算（讀取 / 報表）
cairn reconciliation accounts逐收款帳戶現金進出對帳
參數
--date-from對帳期間起日（YYYY-MM-DD，含當日），以 Asia/Taipei 牆鐘日界計；省略則不設下界
--date-to對帳期間迄日（YYYY-MM-DD，含整日），以 Asia/Taipei 牆鐘日界計；省略則不設上界
--json回應欄位 · data[]
accountId收款帳戶 id；null = 未歸戶桶。
code帳戶代碼；未歸戶桶為 null。
displayName帳戶顯示名；未歸戶桶為 null。
kind帳戶類型（bank / cash / gateway）；未歸戶桶為 null。
inTwd期間內 direction='in' 的金額合計。
outTwd期間內 payment_transactions direction='out' 的金額合計（客戶退款 / gateway 出）。
payableOutTwd期間內供應商出款合計（payables paid 的 net_amount_twd；非 order-scoped，獨立來源 §3.1）。
netTwd淨額 = in − out − payableOut（不扣手續費，純現金流向；對帳找銀行入帳用毛額）。
txCount期間內這帳戶的活動筆數（payment_transactions + payables paid）。
cairn reconciliation accounts
{
"ok": true,
"data": [
{
"accountId": "…",
"code": "…",
"displayName": "…",
"kind": null,
"inTwd": 0,
"outTwd": 0,
"payableOutTwd": 0,
"netTwd": 0,
"txCount": 0
}
]
}cairn reconciliation list-accounts收款帳戶目錄
參數
--active-only是否只回傳啟用中的收款帳戶（true/false）；省略則含停用
--json回應欄位 · data[]
id收款帳戶 ID。
code帳戶代碼（租戶內唯一穩定識別）。
displayName帳戶顯示名。
kind帳戶類型：bank 銀行 / cash 現金 / gateway 金流閘道。
bankName銀行名稱；現金／閘道帳戶為 null。
accountNo銀行帳號；現金／閘道帳戶為 null。
canReceive可收款（幾乎都 true）。
canRemit可對外匯款（ATM / 匯出退款 / 補款匯出）。荒野只有永豐。
canChargeback可刷退（退回原信用卡）。荒野只有綠界（gateway）。
isDeprecated廢帳戶：仍可零星收款，但其收款需由他帳戶代墊歸集。荒野＝RU 台銀 / 登山社。
isSettlementMaster主結算帳戶：所有資金最終向它彙整。每租戶恰一個（partial unique index）。荒野＝永豐。
currency帳戶幣別（ISO 4217；既有帳戶皆 'TWD'，外幣帳戶如 IDR / USD）。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位（小者在前）。
usedCount被多少 payment_transactions 引用（UI 鎖頭 / 「使用中 N」）。
createdAt建立時間。
updatedAt最後更新時間。
cairn reconciliation list-accounts
{
"ok": true,
"data": [
{
"id": "…",
"code": "…",
"displayName": "…",
"kind": "…",
"bankName": "…",
"accountNo": "…",
"canReceive": true,
"canRemit": true,
"canChargeback": true,
"isDeprecated": true,
"isSettlementMaster": true,
"currency": "…",
"isActive": true,
"displayOrder": 0,
"usedCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn reconciliation settlement-overview月結互抵派生總覽
參數
--period要查詢月結互抵總覽的結算期（YYYY-MM）
--json回應欄位 · data
period結算月份（YYYY-MM，Asia/Taipei）。
matrix兩層互抵矩陣（各帳戶對主結算帳戶的有向淨額 + 未分類彙總）。
lines各帳戶對主結算帳戶（或其類別 final）的有向淨額；恆正、方向由 debtor/creditor。
unclassified未分類（未標費用類型）收款彙總，不進互抵，供 UI 提示補 tag。
obligations本期相關掛帳（period_settlement，含結清進度）。
id帳戶間掛帳 ID。
debtorAccountId欠款方（債務人）收款帳戶 ID。
creditorAccountId收款方（債權人）收款帳戶 ID。
amountTwd應補目標總額（TWD 整數，恆正）。
settledAmountTwd已結清金額（TWD 整數，0 ≤ settled ≤ amount）。
outstandingTwd待結餘額（派生 = amount − settled，>= 0）。
reason掛帳成因：period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份（YYYY-MM，Asia/Taipei）。
status結清狀態：outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註；無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
carriedForward跨期掛帳結轉基數（上期未結 period_settlement 殘額，已種入 matrix 淨額；此處供顯示明細 + 小計）。
lines上期未結 period_settlement 殘額逐筆明細（已種入本期互抵基數）。
totalTwd結轉殘額小計（TWD 整數）。
cairn reconciliation settlement-overview --period
{
"ok": true,
"data": {
"period": "…",
"matrix": {
"lines": [],
"unclassified": "…"
},
"obligations": [
{
"id": "…",
"debtorAccountId": "…",
"creditorAccountId": "…",
"amountTwd": 0,
"settledAmountTwd": 0,
"outstandingTwd": 0,
"reason": "…",
"originPeriod": "…",
"status": "…",
"note": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
],
"carriedForward": {
"lines": [],
"totalTwd": 0
}
}
}cairn reconciliation transfers帳戶間移轉統一分類帳
參數
--kind移轉類型篩選（fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / reversal 沖正）；省略則含全部
--account帳戶 ID 篩選，回傳該帳戶為出帳或進帳方的移轉；省略則不限帳戶
--date-from移轉日期起日（YYYY-MM-DD，含當日）；省略則不設下界
--date-to移轉日期迄日（YYYY-MM-DD，含當日）；省略則不設上界
--settlement-period對應月結期間（YYYY-MM）篩選；省略則不限月結
--obligation掛帳 ID 篩選，回傳沖減該筆掛帳的移轉；省略則不限掛帳
--json回應欄位 · data[]
id帳戶間移轉 ID。
kind移轉類型：fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 期初 / reversal 沖正。
fromAccountId出帳帳戶 ID；期初等單邊移轉為 null。
toAccountId進帳帳戶 ID；單邊移轉為 null。
amountTwd移轉金額（TWD 整數）。
feeTwd手續費（TWD 整數）。
currency外幣幣別（ISO 4217；純台幣移轉為 null）。
foreignAmount外幣金額（整數；非外幣移轉為 null）。
feeForeign外幣手續費（整數；無則為 null）。
grossRate換匯牌價（numeric → 字串原值保精度；顯示/溯源用）。
settlementPeriod對應月結期間（YYYY-MM）；未歸屬月結為 null。
obligationId沖減的帳戶間掛帳 ID；未沖減掛帳為 null。
reversesTransferId被本筆沖正的原移轉 ID（kind='reversal' 時非 null）。
occurredAt移轉日期（'YYYY-MM-DD'，date 欄）。
note備註；無則為 null。
createdByUserId登錄人 user ID。
createdAt建立時間。
updatedAt最後更新時間。
cairn reconciliation transfers
{
"ok": true,
"data": [
{
"id": "…",
"kind": "…",
"fromAccountId": "…",
"toAccountId": "…",
"amountTwd": 0,
"feeTwd": 0,
"currency": "…",
"foreignAmount": 0,
"feeForeign": 0,
"grossRate": "…",
"settlementPeriod": "…",
"obligationId": "…",
"reversesTransferId": "…",
"occurredAt": "…",
"note": "…",
"createdByUserId": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn reconciliation obligations未結掛帳追蹤
參數
--period月結來源期間（YYYY-MM），篩選由該期月結互抵推導出的掛帳；省略則不限期間
--reason掛帳原因代碼，篩選特定成因的掛帳；省略則不限原因
--status掛帳狀態（如未結清 / 已結清），篩選特定結清狀態；省略則含全部
--json回應欄位 · data[]
id帳戶間掛帳 ID。
debtorAccountId欠款方（債務人）收款帳戶 ID。
creditorAccountId收款方（債權人）收款帳戶 ID。
amountTwd應補目標總額（TWD 整數，恆正）。
settledAmountTwd已結清金額（TWD 整數，0 ≤ settled ≤ amount）。
outstandingTwd待結餘額（派生 = amount − settled，>= 0）。
reason掛帳成因：period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份（YYYY-MM，Asia/Taipei）。
status結清狀態：outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註；無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
cairn reconciliation obligations
{
"ok": true,
"data": [
{
"id": "…",
"debtorAccountId": "…",
"creditorAccountId": "…",
"amountTwd": 0,
"settledAmountTwd": 0,
"outstandingTwd": 0,
"reason": "…",
"originPeriod": "…",
"status": "…",
"note": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn reconciliation refund-execs退款執行清單（approved + paid）
參數
--status退款狀態篩選：approved 待執行（已核准）、paid 已執行（已出款）；省略則合併回傳兩者
--json回應欄位 · data
rows退款執行列（合併 approved 待執行 + paid 已執行，或收斂為指定段）。
id退款單 ID。
refundNumber退款單號（人可讀，每租戶流水號）。
orderId所屬訂單 ID。
orderNumber所屬訂單編號（人可讀）；無則為 null。
status退款工作流狀態：draft / submitted / approved / processing / paid / failed / cancelled。
refundKind退款種類：receivable_reduction 減應收退款（取消 / 降價 / 服務失敗）/ overpayment_return 溢收退還（不動應收，只退多收現金）。
affectsReceivable是否減少應收（receivable_reduction 為 true、overpayment_return 為 false；溢收退還不列入 refund_state）。
amountTwd退款金額（TWD 整數，正值）。
method退款方式：original_gateway 原路退刷 / bank_transfer 銀行匯款 / cash 現金 / manual 手動。
reason退款原因說明。
createdAt退款單建立時間。
paidAt實際退款出款（現金結算）時間；未執行為 null。
createdByName建單人姓名；無則為 null。
executionMethod退款執行方法：chargeback 原信用卡刷退 / remit 匯出；未指定為 null。
originAccountId出款來源帳戶 ID（從哪個收款帳戶退出）；未指定為 null。
adminFeeTwd內扣手續費（TWD 整數；自退款金額中扣除的行政費）。
remitFeeTwd匯款手續費（TWD 整數；銀行匯出的轉帳費）。
payeeAccountName收款人戶名（匯款退款用）；無則為 null。
payeeBankCode收款銀行代碼（匯款退款用）；無則為 null。
payeeAccountNumber收款帳號（匯款退款用）；無則為 null。
total回傳的退款執行筆數。
cairn reconciliation refund-execs
{
"ok": true,
"data": {
"rows": [
{
"id": "…",
"refundNumber": "…",
"orderId": "…",
"orderNumber": "…",
"status": "…",
"refundKind": "…",
"affectsReceivable": true,
"amountTwd": 0,
"method": "…",
"reason": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"paidAt": null,
"createdByName": "…",
"executionMethod": null,
"originAccountId": "…",
"adminFeeTwd": 0,
"remitFeeTwd": 0,
"payeeAccountName": "…",
"payeeBankCode": "…",
"payeeAccountNumber": "…"
}
],
"total": 0
}
}cairn reconciliation settlement-report月結互抵矩陣報表（同 settlement-overview 資料源）
參數
--period要查詢月結互抵總覽的結算期（YYYY-MM）
--json回應欄位 · data
period結算月份（YYYY-MM，Asia/Taipei）。
matrix兩層互抵矩陣（各帳戶對主結算帳戶的有向淨額 + 未分類彙總）。
lines各帳戶對主結算帳戶（或其類別 final）的有向淨額；恆正、方向由 debtor/creditor。
unclassified未分類（未標費用類型）收款彙總，不進互抵，供 UI 提示補 tag。
obligations本期相關掛帳（period_settlement，含結清進度）。
id帳戶間掛帳 ID。
debtorAccountId欠款方（債務人）收款帳戶 ID。
creditorAccountId收款方（債權人）收款帳戶 ID。
amountTwd應補目標總額（TWD 整數，恆正）。
settledAmountTwd已結清金額（TWD 整數，0 ≤ settled ≤ amount）。
outstandingTwd待結餘額（派生 = amount − settled，>= 0）。
reason掛帳成因：period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份（YYYY-MM，Asia/Taipei）。
status結清狀態：outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註；無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
carriedForward跨期掛帳結轉基數（上期未結 period_settlement 殘額，已種入 matrix 淨額；此處供顯示明細 + 小計）。
lines上期未結 period_settlement 殘額逐筆明細（已種入本期互抵基數）。
totalTwd結轉殘額小計（TWD 整數）。
cairn reconciliation settlement-report --period
{
"ok": true,
"data": {
"period": "…",
"matrix": {
"lines": [],
"unclassified": "…"
},
"obligations": [
{
"id": "…",
"debtorAccountId": "…",
"creditorAccountId": "…",
"amountTwd": 0,
"settledAmountTwd": 0,
"outstandingTwd": 0,
"reason": "…",
"originPeriod": "…",
"status": "…",
"note": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
],
"carriedForward": {
"lines": [],
"totalTwd": 0
}
}
}cairn reconciliation compute-settlement重跑當期月結互抵派生 + upsert 掛帳（冪等）
參數
--period要計算月結互抵的結算期（YYYY-MM），可重跑且冪等（不回退已結額）
--json回應欄位 · data
period結算月份（YYYY-MM，Asia/Taipei）。
matrix兩層互抵矩陣（各帳戶對主結算帳戶的有向淨額 + 未分類彙總）。
lines各帳戶對主結算帳戶（或其類別 final）的有向淨額；恆正、方向由 debtor/creditor。
unclassified未分類（未標費用類型）收款彙總，不進互抵，供 UI 提示補 tag。
upserts本次 run 對每條互抵列 upsert 的結果（含冪等護欄調整）。
debtorAccountId欠款方（債務人）收款帳戶 ID。
creditorAccountId收款方（債權人）收款帳戶 ID。
derivedAmountTwd本次派生的目標淨額。
appliedAmountTwd實際落地的掛帳 amount_twd（受冪等護欄約束，不低於已 settled）。
obligationId對應的帳戶間掛帳 ID（本次 upsert 的目標列）。
action本次動作：created 新建 / updated 更新 / floored_to_settled 派生低於已結被護欄下限鎖住。
adjustmentTwd派生目標低於已結額、被 floor 時的差額（保留為 adjustment 線索；> 0 表示有缺口）。
adjustmentObligationIdfloor 缺口另記的 adjustment 掛帳 id（action='floored_to_settled' 時非 null）。
deletedObligationIds本次 run 刪除的失效派生掛帳 id（settled=0 且不在新派生）。
cairn reconciliation compute-settlement --period
{
"ok": true,
"data": {
"period": "…",
"matrix": {
"lines": [],
"unclassified": "…"
},
"upserts": [
{
"debtorAccountId": "…",
"creditorAccountId": "…",
"derivedAmountTwd": 0,
"appliedAmountTwd": 0,
"obligationId": "…",
"action": "created",
"adjustmentTwd": 0,
"adjustmentObligationId": "…"
}
],
"deletedObligationIds": [
"…"
]
}
}cairn reconciliation create-transfer登錄帳戶間移轉（補款/代墊/回填/退款匯出/換匯/沖正；可選沖減掛帳）
參數
--kind <fx_conversion|replenishment|advance|backfill|refund_payout|reversal>移轉類型篩選（fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / reversal 沖正）；省略則含全部
--amount <twd>--occurred-at <YYYY-MM-DD>移轉發生日期（YYYY-MM-DD）
--from--to--fee--settlement-period對應月結期間（YYYY-MM）篩選；省略則不限月結
--currency換匯外幣幣別（ISO 4217 三碼）；非換匯傳 null
--foreign-amount換匯外幣金額（整數最小單位，須大於 0）；非換匯傳 null
--gross-rate換匯牌價（正數，最多 6 位小數，以字串表達避免精度遺失）；非換匯傳 null
--obligation掛帳 ID 篩選，回傳沖減該筆掛帳的移轉；省略則不限掛帳
--confirm回應欄位 · data
ok是否登錄成功（移轉 + 沖減掛帳的原子交易皆完成）。
cairn reconciliation create-transfer --kind <fx_conversion|replenishment|advance|backfill|refund_payout|reversal> --amount <twd> --occurred-at <YYYY-MM-DD>
{
"ok": true,
"data": {
"ok": true
}
}cairn reconciliation statement銀行對帳單匯入 + 配對（範本 / 匯入 / 自動配對 / 人工配對 / 略過 / 刪批）
參數
<importId>位置參數 · 必填<lineId>位置參數 · 必填--account <id>收款帳戶 ID，回傳該帳戶的對帳單批次 / 行 / 進度彙總
--out <path>--period-start <d>對帳單期間起日（含當日）
--period-end <d>對帳單期間迄日（含當日）
--file <path.xlsx>--commit--confirm--source-type <payment_transaction|payable|account_transfer>配對來源種類：payment_transaction / payable / account_transfer
--source-id <id>配對來源 ID（該帳戶內未被配對的 ERP 候選）
--reason <r>略過原因（必填；如「手續費」「利息」）
回應欄位 · data
imports該帳戶的對帳單批次清單（新到舊）。
id對帳單批次 ID。
periodStart批次期間起日（'YYYY-MM-DD'，含當日）。
periodEnd批次期間迄日（'YYYY-MM-DD'，含當日）。
filename匯入的檔名。
createdAt匯入時間。
lineCount批內總行數。
autoCount自動配對的行數。
manualCount人工配對的行數。
unmatchedCount尚未配對的行數。
ignoredCount已略過（ignored）的行數。
excludedCount已解除配對（excluded）的行數。
lines該帳戶所有對帳單行（跨批次）。
id對帳單行 ID。
importId所屬對帳單批次 ID。
lineNo檔案內行號（1 起算）。
txnDate交易日期（'YYYY-MM-DD'）。
direction現金流向：in 存入 / out 支出。
amountTwd金額（TWD 整數）。
memo摘要 / 備註文字。
status配對狀態：unmatched 未配 / auto 自動 / manual 人工 / ignored 略過 / excluded 已解除。
matchedSourceType已配對來源種類（payment_transaction / payable / account_transfer）；未配為 null。
matchedSourceId已配對來源 ID；未配為 null。
ignoredReason略過原因；非 ignored 為 null。
progress配對進度彙總。
total總行數。
matched已配對行數（auto + manual）。
unmatched未配對行數。
ignored已略過行數。
excluded已解除配對行數。
cairn reconciliation statement <importId> <lineId> --account <id> --out <path> --period-start <d> --period-end <d> --file <path.xlsx> --source-type <payment_transaction|payable|account_transfer> --source-id <id> --reason <r>
{
"ok": true,
"data": {
"imports": [
{
"id": "…",
"periodStart": "…",
"periodEnd": "…",
"filename": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"lineCount": 0,
"autoCount": 0,
"manualCount": 0,
"unmatchedCount": 0,
"ignoredCount": 0,
"excludedCount": 0
}
],
"lines": [
{
"id": "…",
"importId": "…",
"lineNo": 0,
"txnDate": "…",
"direction": "out",
"amountTwd": 0,
"memo": "…",
"status": "…",
"matchedSourceType": "…",
"matchedSourceId": "…",
"ignoredReason": "…"
}
],
"progress": {
"total": 0,
"matched": 0,
"unmatched": 0,
"ignored": 0,
"excluded": 0
}
}
}cairn accrual-ledger
掛帳台帳：四區塊派生、梯次彙總（純讀）
cairn accrual-ledger get單一期間掛帳台帳四區塊
參數
--period出團月（格式 YYYY-MM，Asia/Taipei 時區）
--json回應欄位 · data
period結算期間（YYYY-MM，Asia/Taipei 出團月）。
departureSummary梯次彙總（區塊 1）：出團月落於 period 的各梯次收入 / 成本 / 毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期（YYYY-MM-DD）。
pax出團人數（該梯次確認人數）。
revenueTwd總收入（梯次成交應收，排除已取消訂單，TWD 整數）。
realCostTwd真實成本合計（TWD 整數）= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 （房費由分房資料另計），故逐筆成本加總會小於此值，差額即房費（設計如此）。
grossProfitTwd毛利毛估 = revenue − realCost（含房費）。
costLines成本掛帳逐筆（區塊 2）：該期梯次上所有 departure_costs 成本列。
id成本列 ID。
tripTitle團名。
departureDate所屬梯次出團日期（YYYY-MM-DD）。
category成本分類（如 交通 / 餐費 / 保險 / 嚮導）。
vendor廠商：已建檔廠商名優先，否則用成本列上填寫的廠商名；null = 未填。
amountTwd代墊額（真實成本，TWD 整數）。
invoiceAmountTwd憑證額（外帳可申報金額，TWD 整數）。
isDeclarable有無發票憑證。
reviewStatus覆核狀態：掛了支出證明單則用其 status（pending/approved），否則由有無憑證派生。
payables應付清單（區塊 3）：該期歸屬的請款單（payables）。
payableNumber請款單號（人類可讀）。
tripTitle團名（未綁定梯次的手動請款顯示「未綁定梯次」）。
payeeName受款對象（供應商 / 嚮導 / 派車人等）。
amountTwd請款金額（整數 TWD）。
statusdraft | submitted | approved | paid | cancelled | rejected。
receivables應收清單（區塊 4）：該期梯次上的 tour 訂單應收 / 實收 / 待收。
orderNumber訂單編號。
tripTitle團名（該訂單在期間內任一梯次的團名）。
receivableTwd應收金額（TWD 整數）。
receivedTwd實收金額（收款減退款，TWD 整數）。
outstandingTwd待收 = receivable − received。
cairn accrual-ledger get --period
{
"ok": true,
"data": {
"period": "…",
"departureSummary": [
{
"departureId": "…",
"tripTitle": "…",
"departureDate": "…",
"pax": 0,
"revenueTwd": 0,
"realCostTwd": 0,
"grossProfitTwd": 0
}
],
"costLines": [
{
"id": "…",
"tripTitle": "…",
"departureDate": "…",
"category": "…",
"vendor": "…",
"amountTwd": 0,
"invoiceAmountTwd": 0,
"isDeclarable": true,
"reviewStatus": "…"
}
],
"payables": [
{
"payableNumber": "…",
"tripTitle": "…",
"payeeName": "…",
"amountTwd": 0,
"status": "…"
}
],
"receivables": [
{
"orderNumber": "…",
"tripTitle": "…",
"receivableTwd": 0,
"receivedTwd": 0,
"outstandingTwd": 0
}
]
}
}cairn accrual-ledger departure-summary梯次彙總區塊（收入/成本/毛利）
參數
--period出團月（格式 YYYY-MM，Asia/Taipei 時區）
--json回應欄位 · data
period結算期間（YYYY-MM，Asia/Taipei 出團月），回聲請求參數。
departureSummary梯次彙總：出團月落於 period 的各梯次收入 / 真實成本 / 毛估毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期（YYYY-MM-DD）。
pax出團人數（該梯次確認人數）。
revenueTwd總收入（梯次成交應收，排除已取消訂單，TWD 整數）。
realCostTwd真實成本合計（TWD 整數）= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 （房費由分房資料另計），故逐筆成本加總會小於此值，差額即房費（設計如此）。
grossProfitTwd毛利毛估 = revenue − realCost（含房費）。
cairn accrual-ledger departure-summary --period
{
"ok": true,
"data": {
"period": "…",
"departureSummary": [
{
"departureId": "…",
"tripTitle": "…",
"departureDate": "…",
"pax": 0,
"revenueTwd": 0,
"realCostTwd": 0,
"grossProfitTwd": 0
}
]
}
}cairn cost-templates
成本範本：查詢、明細
cairn cost-templates list列出成本範本（--active 只回啟用中精簡清單）
參數
--status依狀態篩選：active 啟用、archived 已封存
--active啟用時只回傳輕量的 { id, name } 綁定挑選清單（行程設定的成本範本下拉用）
--json回應欄位 · data[]
id成本範本 id（ct_ 前綴）。
name成本範本名稱。
cairn cost-templates list
{
"ok": true,
"data": [
{
"id": "…",
"name": "…"
}
]
}cairn cost-templates get單一成本範本完整明細（含成本行）
參數
<id>位置參數 · 必填--json回應欄位 · data
lines成本行明細（品項 × 單價 × 數量模型）。
id成本行 ID。
templateId所屬成本範本 ID。
category成本分類（如 交通 / 餐費 / 保險）。
vendorName供應商 / 廠商名（選填）。
description摘要說明（選填）。
unitPriceTwdTWD 行的單價；外幣行 null。
currency幣別（'TWD' = 台幣行）。
unitPriceForeign外幣行的外幣單價；TWD 行 null。
internalRateSource外幣行的內帳匯率來源；TWD 行 null。
fxAccountIdinternalRateSource='fx_account' 時的外幣帳戶 id。
quantityMode數量模式：fixed 固定值 / headcount 依人頭公式（ceil(Σ人頭 / 組距)）。
quantityFixedfixed 模式的固定數量；headcount 模式為 null。
headcountComponentsheadcount 模式選定的人頭 component（passenger / leader / assistant / driver）；fixed 為 null。
groupDivisorheadcount 模式的組距（每 N 人一組，ceil 進位）；null = 直接加總。
isDeclarable是否預設有合法憑證（帶入成本列的 is_declarable 初值）。
sortOrder顯示排序。
id成本範本 ID。
name範本名稱。
description範本說明（選填）。
status狀態：active 啟用 / archived 已封存。
lineCount成本行數（派生）。
boundTripCount綁定行程數（派生）。
createdAt建立時間。
updatedAt最後更新時間。
cairn cost-templates get <id>
{
"ok": true,
"data": {
"lines": [
{
"id": "…",
"templateId": "…",
"category": "…",
"vendorName": "…",
"description": "…",
"unitPriceTwd": 0,
"currency": "…",
"unitPriceForeign": 0,
"internalRateSource": null,
"fxAccountId": "…",
"quantityMode": "…",
"quantityFixed": 0,
"headcountComponents": null,
"groupDivisor": 0,
"isDeclarable": true,
"sortOrder": 0
}
],
"id": "…",
"name": "…",
"description": "…",
"status": "active",
"lineCount": 0,
"boundTripCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn cost-templates create建立成本範本
參數
--name <名稱>成本範本名稱
--description <說明>成本範本說明
--json回應欄位 · data
id新建成本範本 ID（ct_ 前綴）。
cairn cost-templates create --name <名稱>
{
"ok": true,
"data": {
"id": "…"
}
}cairn cost-templates update更新成本範本（名稱／說明／狀態）
參數
<id>位置參數 · 必填--name <名稱>成本範本名稱
--status範本狀態：active 啟用、archived 已封存
--description <說明>成本範本說明
--json回應欄位 · data
ok是否更新成功。
cairn cost-templates update <id> --name <名稱> --status
{
"ok": true,
"data": {
"ok": true
}
}cairn cost-templates add-line新增成本行（--line 為 JSON：{category,unitPriceTwd,quantityMode,...}）
參數
<templateId>位置參數 · 必填--line成本明細列：含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式（fixed 固定／headcount 人數）與對應數量／人數組成、isDeclarable 是否可報帳等欄位
--json回應欄位 · data
id新建成本明細行 ID。
cairn cost-templates add-line <templateId> --line
{
"ok": true,
"data": {
"id": "…"
}
}cairn cost-templates update-line更新成本行（--line 為 JSON）
參數
<lineId>位置參數 · 必填--line成本明細列更新內容：含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式（fixed 固定／headcount 人數）與對應數量／人數組成、isDeclarable 是否可報帳等欄位
--json回應欄位 · data
ok是否更新成功。
cairn cost-templates update-line <lineId> --line
{
"ok": true,
"data": {
"ok": true
}
}cairn cost-templates delete-line刪除成本行
參數
<lineId>位置參數 · 必填--json回應欄位 · data
ok是否刪除成功。
cairn cost-templates delete-line <lineId>
{
"ok": true,
"data": {
"ok": true
}
}cairn ledger
內外帳：梯次毛利、逐筆成本、支出證明單、待覆核申報
cairn ledger list列出各梯次內外帳摘要（毛利 / 可申報 / pending 證明單）
參數
--period--trip <id>--window-days--jsoncairn ledger list
cairn ledger get單一梯次內外帳派生明細
參數
<departureId>位置參數 · 必填--jsoncairn ledger get <departureId>
cairn ledger costs列出某梯次逐筆成本登記
參數
<departureId>位置參數 · 必填--created-by <userId>--jsoncairn ledger costs <departureId>
cairn ledger proofs列出某梯次支出證明單
參數
<departureId>位置參數 · 必填--jsoncairn ledger proofs <departureId>
cairn ledger declarations列出跨梯次待覆核的嚮導申報成本
參數
--jsoncairn ledger declarations
cairn ledger cancelled-departures列出取消梯次待結轉（殘餘成本 / 是否已結轉特殊損益）
參數
--jsoncairn ledger cancelled-departures
cairn ledger cost-create登記一筆成本（departure_cost.manage）
參數
<departureId>位置參數 · 必填--category <類別>--amount <twd>--vendor--description--no-receipt--invoice-amount--quantity-mode <fixed|headcount>--unit-price-twd <twd>--headcount-components <passenger,leader,assistant,driver>--group-divisor <n>--quantity-fixed <n>--currency <fx_account|published|manual>--confirmcairn ledger cost-create <departureId> --category <類別> --amount <twd>
cairn ledger cost-update更新一筆成本（departure_cost.manage）
參數
<costId>位置參數 · 必填--category <類別>--amount--vendor--description--no-receipt--invoice-amount--quantity-mode <fixed|headcount>--unit-price-twd <twd>--headcount-components <passenger,leader,assistant,driver>--group-divisor <n>--quantity-fixed <n>--currency--confirmcairn ledger cost-update <costId> --category <類別>
cairn ledger cost-delete刪除一筆未轉請款的成本（departure_cost.manage）
參數
<costId>位置參數 · 必填--confirmcairn ledger cost-delete <costId>
cairn ledger approve-proof核准支出證明單（ledger.approve；責任分離）
參數
<proofId>位置參數 · 必填--confirmcairn ledger approve-proof <proofId>
cairn ledger approve-declaration覆核嚮導自報待覆核成本（ledger.approve；責任分離）
參數
<costId>位置參數 · 必填--confirmcairn ledger approve-declaration <costId>
cairn ledger convert-to-payable成本轉請款核簽（departure_cost.manage 且 payable.create）
參數
<departureId>位置參數 · 必填--costs <id1,id2,...>--payee-name--payee-type <supplier|guide|staff_commission|other>--bank-account--bank-name--bank-branch--tax-id--tax-amount--submit--confirmcairn ledger convert-to-payable <departureId> --costs <id1,id2,...> --payee-name
cairn ledger convert-cancelled結轉取消梯次殘餘成本為公司特殊損益（operating_expense.manage）
參數
--departure <id>--category <expenseCategoryId>--amount <twd>--period--description--note--confirmcairn ledger convert-cancelled --departure <id> --category <expenseCategoryId> --amount <twd> --period --description
cairn ledger revert-cancelled撤銷取消梯次的結轉（operating_expense.manage）
參數
--departure <id>--confirmcairn ledger revert-cancelled --departure <id>
cairn payouts
出款批次：彙整 preview、出帳帳戶、批次轉帳檔
cairn payouts aggregate建批前彙整 preview（當月已核准未付 payable 依收款對象 group）
參數
--period <YYYY-MM>出款月份（YYYY-MM），彙整該月已核准未付的應付
--scope <guide|supplier|staff>收款對象範圍（guide 領隊嚮導 / supplier 供應商 / staff 員工）
--json回應欄位 · data[]
payeeType收款對象類型：guide 領隊嚮導 / supplier 供應商 / staff 員工。
payeeRefId收款對象識別 key：供應商為其 ID，領隊 / 員工為收款人姓名。
payeeName收款對象名稱。
payeeAccountName收款人戶名（supplier 取 suppliers / guide 取 guides；staff 暫無主檔 → null）。
payeeBankCode收款銀行代號（同上來源；無主檔為 null）。
payeeAccountNumber收款帳號（同上來源；無主檔為 null，遮罩回傳）。
grossTwd當月已核准未付的請款單淨額合計（TWD 整數）。
items彙整明細（日期 + 團名 + 金額，唯讀派生，不另存）。
payableId請款單 ID。
payableNumber請款單人類可讀單號。
date梯次出發日（'YYYY-MM-DD'）；無連梯次時 null。
tripLabel團名；無連梯次時 null。
amountTwd該請款單的應付淨額（TWD 整數）。
cairn payouts aggregate --period <YYYY-MM> --scope <guide|supplier|staff>
{
"ok": true,
"data": [
{
"payeeType": "…",
"payeeRefId": "…",
"payeeName": "…",
"payeeAccountName": "…",
"payeeBankCode": "…",
"payeeAccountNumber": "…",
"grossTwd": 0,
"items": [
{
"payableId": "…",
"payableNumber": "…",
"date": "…",
"tripLabel": "…",
"amountTwd": 0
}
]
}
]
}cairn payouts remit-accounts出帳帳戶選項（收款帳戶目錄）
參數
--json回應欄位 · data[]
id收款帳戶 ID。
code帳戶代碼（租戶內唯一穩定識別）。
displayName帳戶顯示名。
kind帳戶類型：bank 銀行 / cash 現金 / gateway 金流閘道。
bankName銀行名稱；現金／閘道帳戶為 null。
accountNo銀行帳號；現金／閘道帳戶為 null。
canReceive可收款（幾乎都 true）。
canRemit可對外匯款（ATM / 匯出退款 / 補款匯出）。荒野只有永豐。
canChargeback可刷退（退回原信用卡）。荒野只有綠界（gateway）。
isDeprecated廢帳戶：仍可零星收款，但其收款需由他帳戶代墊歸集。荒野＝RU 台銀 / 登山社。
isSettlementMaster主結算帳戶：所有資金最終向它彙整。每租戶恰一個（partial unique index）。荒野＝永豐。
currency帳戶幣別（ISO 4217；既有帳戶皆 'TWD'，外幣帳戶如 IDR / USD）。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位（小者在前）。
usedCount被多少 payment_transactions 引用（UI 鎖頭 / 「使用中 N」）。
createdAt建立時間。
updatedAt最後更新時間。
cairn payouts remit-accounts
{
"ok": true,
"data": [
{
"id": "…",
"code": "…",
"displayName": "…",
"kind": "…",
"bankName": "…",
"accountNo": "…",
"canReceive": true,
"canRemit": true,
"canChargeback": true,
"isDeprecated": true,
"isSettlementMaster": true,
"currency": "…",
"isActive": true,
"displayOrder": 0,
"usedCount": 0,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn payouts transfer-file出款批次標準四欄批次轉帳檔
參數
<pob_id>位置參數 · 必填--format輸出格式：json 完整匯出（預設）或 csv 僅回傳轉帳檔字串
--jsoncairn payouts transfer-file <pob_id>
{
"ok": true,
"data": "…"
}cairn payouts create-batch建立出款批次草稿（gross + 通用扣款項 → draft，不 mark paid）
參數
--period <YYYY-MM>出款月份（YYYY-MM）
--scope <guide|supplier|staff>--account <acct_id>--lines <json|@file>納入批次的出款列（至少一列）
--confirm回應欄位 · data
id新建立出款批次的 ID（pob_ 前綴）。
cairn payouts create-batch --period <YYYY-MM> --scope <guide|supplier|staff> --lines <json|@file>
{
"ok": true,
"data": {
"id": "…"
}
}cairn payouts confirm-batch確認出款批次（draft → confirmed：mark paid + 記出帳）
參數
<pob_id>位置參數 · 必填--bank-ref <ref>--confirm回應欄位 · data
ok固定為 true：出款批次已確認送出。
cairn payouts confirm-batch <pob_id>
{
"ok": true,
"data": {
"ok": true
}
}cairn payouts issue-confirm-token為供應商批次列簽發廠商自助確認 token（idempotent，回 token）
參數
<pobl_id>位置參數 · 必填--confirm回應欄位 · data
token廠商自助確認 token（拼成對外確認頁網址；idempotent，重複簽發回原 token）。
cairn payouts issue-confirm-token <pobl_id>
{
"ok": true,
"data": {
"token": "…"
}
}cairn pnl
公司損益：營業費用台帳、費用科目、月損益表
cairn pnl expenses列出公司營業費用（list）
參數
--period歸屬月（格式 YYYY-MM）；只列出該月的費用
--kind費用大類：opex 營業費用、tax 稅、platform_fee 平台手續費、special 特殊損益
--category費用類別 ID；只列出該類別的費用
--json回應欄位 · data[]
id費用列 ID。
categoryId費用科目 ID。
categoryCode費用科目代碼（如 rent / salary_admin）。
categoryDisplayName費用科目顯示名。
categoryKind費用科目大類（opex / tax / platform_fee / special）。
period歸屬月（YYYY-MM，損益表據此彙整；可與支付日不同月）。
incurredOn發生 / 支付日期（YYYY-MM-DD）；金流商內扣 / 攤提無單一發生日者為 null。
amountTwd金額（整數 TWD）。
description摘要（廠商 / 品名，如 台中房租 / 委外廣告投放）。
paidFromAccountId出帳帳戶 ID；金流商內扣者為 null。
paidFromAccountName出帳帳戶顯示名。
frontedByUserId代墊者 user ID；非空代表由此人代墊待回補（走請款回補代墊者）。
frontedByName代墊者姓名。
payableId若走出款核簽，連結的請款單 ID；否則 null。
payableNumber連結請款單的人類可讀單號。
recurring月固定標記（人工登記時備註「月固定」；自動生成走範本表，非此欄）。
status'draft'（月固定範本自動生成、待確認，不入損益）| 'confirmed'（計入損益）。
origin'manual'（手動登記）| 'recurring'（月固定範本自動生成）| 'departure_conversion'（取消梯次結轉，§3.4）。
sourceTemplateId生成來源範本（origin='recurring'）；手動登記為 null。
note備註。
createdByUserId經手人 user ID（建立此費用列者）。
createdAt建立時間。
updatedAt最後更新時間。
cairn pnl expenses
{
"ok": true,
"data": [
{
"id": "…",
"categoryId": "…",
"categoryCode": "…",
"categoryDisplayName": "…",
"categoryKind": "…",
"period": "…",
"incurredOn": "…",
"amountTwd": 0,
"description": "…",
"paidFromAccountId": "…",
"paidFromAccountName": "…",
"frontedByUserId": "…",
"frontedByName": "…",
"payableId": "…",
"payableNumber": "…",
"recurring": true,
"status": "confirmed",
"origin": "manual",
"sourceTemplateId": "…",
"note": "…",
"createdByUserId": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn pnl expense-categories列出費用科目目錄（list）
參數
--active-only是否只回傳啟用中的費用類別；預設含停用列
--json回應欄位 · data[]
id費用類別 ID。
code科目代碼（租戶內唯一穩定識別，如 rent / salary_admin / tax_vat）。
displayName顯示名（如 房租 / 行政薪資 / 營業稅）。
kind費用大類：opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益（損益表據此 roll-up）。
isActive是否啟用（停用不刪，既有費用列仍引用得到）。
createdAt建立時間。
updatedAt最後更新時間。
cairn pnl expense-categories
{
"ok": true,
"data": [
{
"id": "…",
"code": "…",
"displayName": "…",
"kind": "opex",
"isActive": true,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn pnl expense-create登錄一筆公司營業費用（與梯次無關；歸屬月供月損益彙整）
參數
--category <id>費用類別 ID；只列出該類別的費用
--period <YYYY-MM>歸屬月（格式 YYYY-MM）；只列出該月的費用
--description <t>費用摘要
--amount <twd>--paid-from--fronted-by--incurred-on費用發生日期（格式 YYYY-MM-DD）
--note備註
--recurring是否為週期性費用
--confirm回應欄位 · data
ok固定為 true：營業費用列已新增。
id新建立營業費用列的 ID（opx_ 前綴）。
cairn pnl expense-create --category <id> --period <YYYY-MM> --description <t> --amount <twd>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn pnl expense-update更正一筆公司營業費用（整列覆寫；payable 連結須帶回）
參數
<id>位置參數 · 必填--category <id>--period <YYYY-MM>歸屬月（格式 YYYY-MM），供月損益表彙整
--description <t>費用摘要
--amount <twd>--paid-from--fronted-by--incurred-on費用發生日期（格式 YYYY-MM-DD）
--note備註
--payable-id關聯的請款核簽 ID；整列覆寫時須原樣帶回，省略則清為 null
--recurring是否為週期性費用
--confirm回應欄位 · data
ok固定為 true：營業費用列已更新。
cairn pnl expense-update <id> --category <id> --period <YYYY-MM> --description <t> --amount <twd>
{
"ok": true,
"data": {
"ok": true
}
}cairn pnl statement公司月損益表（各區毛利→公司淨利）
參數
--period損益表結算月（格式 YYYY-MM）
--extra-income額外收入（台幣非負整數），併入公司淨利計算；預設 0
--json回應欄位 · data
period結算期間（YYYY-MM）。
regions各區毛利明細（出團月落 period 的梯次按區 roll-up）。
region派生 region key（穩定，由 trip 屬性派生）。
label顯示標籤（destination 原文 / 衍生）。
revenueTwd本區成交應收（出團月落 period 的梯次合計，TWD 整數）。
directCostTwd本區真實直接成本（TWD 整數）= 房費底價成本 + 已核准的逐筆成本合計。
marginTwd本區毛利 = revenue − directCost。
departures本區梯次數（出團月落 period）。
grossMarginTwd各區毛利加總（整數 TWD）。
revenueTotalTwd各區營收加總（整數 TWD）。
extraIncomeTwd額外收入（GS 二、額外收入總計；本批無 schema 載體 → 0，見 §5）。
adminFeeIncomeTwd行政手續費收入（退款收取的行政手續費，只計未出團 / 取消單，TWD 整數）。
otherIncomeTwd其他收入合計 = extraIncome + adminFeeIncome（整數 TWD）。
expensesByKind公司營業費用按 kind roll-up（opex / tax / platform_fee，只計已確認）。
kind'opex' / 'tax' / 'platform_fee'。
amountTwd該 kind 本期費用合計（整數 TWD）。
count該 kind 本期費用筆數。
operatingExpenseTotalTwd公司營業費用合計 = Σ opex / tax / platform_fee（整數 TWD）。
special特殊損益逐筆（kind='special'，一次性、獨立列，只計已確認）。
id費用列 ID。
categoryId費用科目 ID（特殊損益科目）。
categoryDisplayName費用科目顯示名。
description摘要（如 取消神山床位沒收訂金）。
amountTwd金額（整數 TWD ≥ 0，DB CHECK operating_expenses_amount_nonneg）。**第一版 special 一律視為「損」**（扣減淨利，與營業費用同向）——對齊 GS 五月事件「取消神山床位沒收」= 損。schema 無 sign 欄，無法表達一次性「益」；一次性收益（§3.4）落地 sign 欄後再分流， 屆時 specialTotal 改帶號。當前 specialTotalTwd 一律從淨利扣減。
specialTotalTwd特殊損益加總（整數 TWD，第一版一律視為損）。
netProfitTwd公司淨利 = grossMargin + otherIncome − operatingExpenseTotal − specialTotal。
netMarginPct淨利率（netProfit / revenueTotal），revenue=0 時 null。
cairn pnl statement --period
{
"ok": true,
"data": {
"period": "…",
"regions": [
{
"region": "…",
"label": "…",
"revenueTwd": 0,
"directCostTwd": 0,
"marginTwd": 0,
"departures": 0
}
],
"grossMarginTwd": 0,
"revenueTotalTwd": 0,
"extraIncomeTwd": 0,
"adminFeeIncomeTwd": 0,
"otherIncomeTwd": 0,
"expensesByKind": [
{
"kind": "…",
"amountTwd": 0,
"count": 0
}
],
"operatingExpenseTotalTwd": 0,
"special": [
{
"id": "…",
"categoryId": "…",
"categoryDisplayName": "…",
"description": "…",
"amountTwd": 0
}
],
"specialTotalTwd": 0,
"netProfitTwd": 0,
"netMarginPct": 0
}
}cairn reports
財務報表：月結摘要（實收現金口徑，tour-scoped）
cairn reports monthly月結財務摘要（KPI + 行程排行 + 金流商分布）
參數
--year <YYYY>報表年份（西元四位數），月界以台北時區計
--month <1-12>報表月份，1 至 12
--json回應欄位 · data
year報表年份（西元四位數）。
month報表月份（1-12，月界以 Asia/Taipei 計）。
totalOrders本月建立的 tour 訂單數（依 created_at 計）。
paidOrders本月有實收現金的 tour 訂單數（月內有 inbound 交易）。
cancelledOrders本月取消的 tour 訂單數（依 updated_at 計）。
totalRevenuecollected_cash：本月實收現金 = SUM(payment_transactions in) within month。
refundedAmountrefunded_cash：本月退還現金 = SUM(payment_transactions out, refund/chargeback) within month。
netCashnet_cash：本月淨現金 = SUM(in:+amount, out:-amount) - SUM(fee) within month。
newCustomers本月新註冊會員數（排除 staff 角色）。
byTrip依行程銷售排行（前 10 名，按本月實收現金）。
tripId行程 ID。
tripTitle團名。
orderCount該行程本月有實收現金的訂單數。
revenuecollected_cash by trip：本月實收現金（tour-scoped）。
byProvider依金流商分組的本月實收現金。
provider金流商代碼（如 ecpay / test）。
orderCount該金流商本月有實收現金的訂單數。
amountcollected_cash by provider：本月實收現金（tour-scoped）。
dailyRevenuecollected_cash by day：本月逐日實收現金（tour-scoped，Asia/Taipei 日界）， 整月零填滿（無入帳的日子 amount=0）。Σ amount === totalRevenue，與 KPI 對帳。
day日期（YYYY-MM-DD，Asia/Taipei 日界）。
amount當日實收現金（tour-scoped，整數 TWD）。
cairn reports monthly --year <YYYY> --month <1-12>
{
"ok": true,
"data": {
"year": 0,
"month": 0,
"totalOrders": 0,
"paidOrders": 0,
"cancelledOrders": 0,
"totalRevenue": 0,
"refundedAmount": 0,
"netCash": 0,
"newCustomers": 0,
"byTrip": [
{
"tripId": "…",
"tripTitle": "…",
"orderCount": 0,
"revenue": 0
}
],
"byProvider": [
{
"provider": "…",
"orderCount": 0,
"amount": 0
}
],
"dailyRevenue": [
{
"day": "…",
"amount": 0
}
]
}
}cairn suppliers
廠商目錄：查詢、明細
cairn suppliers list列出/搜尋廠商目錄
參數
--status依狀態篩選（active 啟用 / inactive 停用 / all 全部，預設 active）
--q關鍵字搜尋（廠商名稱或類別）
--json回應欄位 · data[]
id廠商 ID。
name廠商名稱。
categoryHint慣用類別提示（租戶自定，非硬枚舉）。
payeeAccountName收款人戶名（批次轉帳檔欄 (1)）。
payeeBankCode收款銀行代號（批次轉帳檔欄 (3)）。
payeeAccountNumber收款帳號（批次轉帳檔欄 (2)，遮罩回傳）。
status狀態：active 啟用 / inactive 停用（停用不刪）。
createdAt建立時間。
updatedAt最後更新時間。
cairn suppliers list
{
"ok": true,
"data": [
{
"id": "…",
"name": "…",
"categoryHint": "…",
"payeeAccountName": "…",
"payeeBankCode": "…",
"payeeAccountNumber": "…",
"status": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn suppliers get單一廠商明細（含遮罩收款資料）
參數
<sup_id>位置參數 · 必填--json回應欄位 · data
id廠商 ID。
name廠商名稱。
categoryHint慣用類別提示（租戶自定，非硬枚舉）。
payeeAccountName收款人戶名（批次轉帳檔欄 (1)）。
payeeBankCode收款銀行代號（批次轉帳檔欄 (3)）。
payeeAccountNumber收款帳號（批次轉帳檔欄 (2)，遮罩回傳）。
status狀態：active 啟用 / inactive 停用（停用不刪）。
createdAt建立時間。
updatedAt最後更新時間。
cairn suppliers get <sup_id>
{
"ok": true,
"data": {
"id": "…",
"name": "…",
"categoryHint": "…",
"payeeAccountName": "…",
"payeeBankCode": "…",
"payeeAccountNumber": "…",
"status": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn suppliers create新增廠商（出款對象主檔；進階會計模組）
參數
--name <n>廠商名稱（出款對象顯示名）
--category--payee-name--bank-code--account-number--confirm回應欄位 · data
ok固定為 true：廠商已新增。
id新建立廠商的 ID（sup_ 前綴）。
cairn suppliers create --name <n>
{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}cairn suppliers update編輯廠商（partial：省略=保留；帳號 write-only，留空不變更）
參數
<sup_id>位置參數 · 必填--name廠商名稱（出款對象顯示名）
--category--payee-name--bank-code--account-number--confirm回應欄位 · data
ok固定為 true：廠商資料已更新。
cairn suppliers update <sup_id>
{
"ok": true,
"data": {
"ok": true
}
}cairn audit
稽核日誌：查詢、統計（唯讀）
cairn audit list列出/篩選稽核紀錄
參數
--action動作代碼篩選，例如 order.update（比對稽核事件的動作）
--actor操作者篩選，比對執行該動作的使用者 ID
--entity目標實體篩選，比對被操作對象的類型或 ID
--from起始時間（ISO 8601），僅回傳此時間之後的事件
--to結束時間（ISO 8601），僅回傳此時間之前的事件
--limit回傳筆數上限，最多 1000 筆
--json回應欄位 · data[]
id稽核事件 ID。
actorUserId操作者的使用者 ID；系統事件（webhook／排程等非人為列）為 null。
actorEmail操作者 Email；系統事件或帳號已刪時為 null。
actorName操作者顯示名；系統事件或帳號已刪時為 null。
action動作代碼，例如 order.create、traveler.decrypt。
targetType被操作對象的類型，例如 order、member。
targetId被操作對象的 ID。
metadata該事件的附帶內容（欄位隨動作而異的自由結構 JSON）。
ipAddress發起請求的來源 IP；無法取得時為 null。
createdAt事件發生時間。
cairn audit list
{
"ok": true,
"data": [
{
"id": "…",
"actorUserId": "…",
"actorEmail": "…",
"actorName": "…",
"action": "…",
"targetType": "…",
"targetId": "…",
"metadata": "…",
"ipAddress": "…",
"createdAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn audit stats稽核 KPI 統計
參數
--actor操作者使用者 ID，指定時將統計數據限縮至該操作者
--json回應欄位 · data
eventsThisMonth本月（Asia/Taipei）稽核事件總數。
eventsToday今日（Asia/Taipei）稽核事件總數。
writesThisMonth本月寫入類事件數（排除 *.read 讀取事件）。
distinctActorsThisMonth本月有動作紀錄的不重複操作者人數。
cairn audit stats
{
"ok": true,
"data": {
"eventsThisMonth": 0,
"eventsToday": 0,
"writesThisMonth": 0,
"distinctActorsThisMonth": 0
}
}cairn leaderboard
業績排行：每位業務成交應收業績、待派發 KPI（admin-only）
cairn leaderboard list全公司業務業績排行
參數
--period業績統計區間：當月、當季、當年或全部，預設 month
--json回應欄位 · data[]
userId業務的使用者 ID。
name業務顯示姓名。
email業務登入 Email。
role業務角色代碼（admin／sales／op／accountant）。
orderCount承作訂單總數（歸屬此業務、含各狀態的旅遊團訂單）。
paidCount已成交訂單數（已付款或履約完成）。
cancelledCount已取消訂單數。
revenue業績額（TWD 整數）：歸屬於該業務、未取消訂單的應收合計。
commissionTwd估算佣金 = round(revenue × sales_commission_bps / 10000)（tenant_settings 費率）。
bonusTwd月度第一名加碼 = round(revenue × monthly_top_bonus_bps / 10000)，僅當期 rank 1 且 revenue > 0；其餘為 0。與 isMonthlyTop 同步。
isMonthlyTop當期 rank 1（revenue > 0）＝月度第一，享 bonus。
avgOrderTwd客單均價 = round(revenue / orderCount)；0 單為 0。
cairn leaderboard list
{
"ok": true,
"data": [
{
"userId": "…",
"name": "…",
"email": "…",
"role": "…",
"orderCount": 0,
"paidCount": 0,
"cancelledCount": 0,
"revenue": 0,
"commissionTwd": 0,
"bonusTwd": 0,
"isMonthlyTop": true,
"avgOrderTwd": 0
}
]
}cairn leaderboard review-stats待派發訂單 KPI
參數
--json回應欄位 · data
pendingCount待派發（pending_review）訂單筆數。
pendingTotalTwd待派發訂單的應收金額合計（新台幣）。
longestWaitHours目前待派發訂單中，最長已等待的時數。
thisMonthAssigned本月（Asia/Taipei）已完成派發的訂單數。
cairn leaderboard review-stats
{
"ok": true,
"data": {
"pendingCount": 0,
"pendingTotalTwd": 0,
"longestWaitHours": 0,
"thisMonthAssigned": 0
}
}cairn message-templates
罐頭訊息範本：查詢、明細
cairn message-templates list列出訊息範本（可依通道過濾）
參數
--channel--jsoncairn message-templates list
cairn message-templates get單一訊息範本完整明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id範本 ID。
key穩定識別碼（NULL = 未指定）。
stageSOP 階段（受理 → 出團完成）。
channel發送管道：line 或 email。
title範本標題。
bodySingle單人版內文（含 {{...}} 合併變數）。
bodyMulti多人版變體；NULL = 只有單人版。
isActive是否為該階段目前啟用的範本。
createdAt建立時間。
updatedAt最後更新時間。
updatedBy最後更新者姓名（LEFT JOIN 同庫 user；未知 / 帳號已刪為 null）。
cairn message-templates get <id>
{
"ok": true,
"data": {
"id": "…",
"key": "…",
"stage": "受理",
"channel": "email",
"title": "…",
"bodySingle": "…",
"bodyMulti": "…",
"isActive": true,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z",
"updatedBy": "…"
}
}cairn message-templates create新增訊息範本
參數
--stage <stage>訊息對應的 SOP 階段
--channel <line|email>依發送管道篩選範本（line 或 email）
--title <t>範本標題（供後台辨識）
--body-single <b>單人版訊息內文
--key <K>範本識別碼，2–64 碼大寫英數 / _ / -（用於程式化引用，選填，自動轉大寫）
--body-multi <b>多人版訊息內文（留空表示沿用單人版；選填）
--inactive--confirm回應欄位 · data
id新建立的訊息範本 ID。
cairn message-templates create --stage <stage> --channel <line|email> --title <t> --body-single <b>
{
"ok": true,
"data": {
"id": "…"
}
}cairn message-templates update更新訊息範本（全量覆寫）
參數
<id>位置參數 · 必填--stage <stage>訊息對應的 SOP 階段
--channel <line|email>發送管道（line 或 email）
--title <t>範本標題（供後台辨識）
--body-single <b>單人版訊息內文
--key <K>範本識別碼，2–64 碼大寫英數 / _ / -（用於程式化引用，選填，自動轉大寫）
--body-multi <b>多人版訊息內文（留空表示沿用單人版；選填）
--inactive--confirm回應欄位 · data
ok是否成功更新訊息範本。
cairn message-templates update <id> --stage <stage> --channel <line|email> --title <t> --body-single <b>
{
"ok": true,
"data": {
"ok": true
}
}cairn message-templates set-active啟用 / 停用訊息範本
參數
<id>位置參數 · 必填--active--confirm回應欄位 · data
ok是否成功切換訊息範本的啟用狀態。
cairn message-templates set-active <id> --active
{
"ok": true,
"data": {
"ok": true
}
}cairn message-templates delete刪除訊息範本（硬刪，清除草稿）
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否成功刪除訊息範本。
cairn message-templates delete <id>
{
"ok": true,
"data": {
"ok": true
}
}cairn roles
RBAC 角色：列表、明細、權限目錄
cairn roles list列出所有角色（內建 + 自訂）
參數
--system--custom--jsoncairn roles list
cairn roles get單一角色 + 完整權限矩陣
參數
<roleId>位置參數 · 必填--json回應欄位 · data
id角色 ID（內建角色為其代碼）。
name角色代碼（小寫英數與底線，建立後不可改；即帳號綁定的角色值）。
label角色顯示名稱。
isSystem是否為系統內建角色（內建角色不可修改或刪除）。
permissions此角色授予的完整 (resource, action) 權限清單。
resource權限資源代碼，例如 order、member。
action權限動作代碼，例如 read、update。
cairn roles get <roleId>
{
"ok": true,
"data": {
"id": "…",
"name": "…",
"label": "…",
"isSystem": true,
"permissions": [
{
"resource": "…",
"action": "…"
}
]
}
}cairn roles catalog列出權限目錄（每個 resource 的可授權 action）
參數
--json回應欄位 · data[]
resource權限資源代碼，例如 order、member。
actions此資源可授予的動作代碼清單，例如 read、update。
cairn roles catalog
{
"ok": true,
"data": [
{
"resource": "…",
"actions": [
"…"
]
}
]
}cairn roles create新增自訂角色（name + label + 權限）
參數
--name <code>角色代碼，小寫英數與底線、2–32 字且須以字母開頭，建立後不可改
--label <顯示名>角色顯示名稱，呈現於後台角色清單
--permissions此角色授予的權限清單，每筆為一組資源與動作
--confirm回應欄位 · data
id新建立的角色 ID。
cairn roles create --name <code> --label <顯示名>
{
"ok": true,
"data": {
"id": "…"
}
}cairn roles update更新自訂角色顯示名與權限（整組覆寫）
參數
<roleId>位置參數 · 必填--label <顯示名>角色顯示名稱，呈現於後台角色清單
--permissions完整取代後的權限清單，會整批覆寫此角色現有權限
--confirm回應欄位 · data
ok是否成功更新角色。
cairn roles update <roleId> --label <顯示名>
{
"ok": true,
"data": {
"ok": true
}
}cairn roles delete刪除自訂角色（仍有成員使用時拒絕）
參數
<roleId>位置參數 · 必填--confirm回應欄位 · data
ok是否成功刪除角色。
cairn roles delete <roleId>
{
"ok": true,
"data": {
"ok": true
}
}cairn settings
租戶設定：公司檔 / 收款帳戶 / 費用類別 / 模組 / 寄件網域
cairn settings get租戶設定單例（公司檔 / 指派模式 / SEO / 寄件網域；ECPay 憑證一律遮罩）
參數
--json回應欄位 · data
id設定列 ID（單例，恆為 'singleton'）。
companyName公司全名，顯示於發票、合約與對外信件抬頭；null = 未設定。
companyPhone公司聯絡電話，顯示於對外文件；null = 未設定。
taxId公司統一編號（8 位數字），用於開立發票；null = 未設定。
companyAddress公司登記地址，顯示於對外文件；null = 未設定。
logoUrl公司 Logo 圖片網址，用於後台與對外頁面品牌呈現；null = 未設定。
siteTagline公開站標語（SEO／首頁）；null = 未設定。
seoDefaultDescription公開站預設 SEO meta description；null = 未設定。
ogImageUrl社群分享預設 Open Graph 圖片網址；null = 未設定。
emailReplyTo系統寄信時的回覆收件信箱；null = 未設定。
assignmentModeS5: 'auto_round_robin' | 'auto_customer_choice' | 'manual_review'
defaultAssigneeUserIdS5: fallback assignee when round-robin finds no active sales, etc.
allowSalesClaimorder-assignment §6：業務自派搶單開關（per-tenant opt-in，預設 false）。
passportExpiryWarningDays護照效期提醒天數（document-expiry §4.1；NOT NULL DEFAULT 180）。
groupCodePattern團號 token 樣板（如 '{YY}{region}{airline?}{MMDD}{seq}'）。NULL = 內建預設。
groupCodeSeqStyle序號樣式：'alpha' | 'alpha_no_io' | 'numeric'（NOT NULL DEFAULT 'alpha'）。
groupCodeSeqWidthnumeric 序號補零寬度（NOT NULL DEFAULT 2；alpha 樣式忽略）。
ecpayFeeBps預估綠界手續費率（270 = 2.70%）。NOT NULL DEFAULT 270。
fongshouFeeBps預估豐收款手續費率（50 = 0.50%）。NOT NULL DEFAULT 50。
profitTaxBps預估發票 / 營所稅率（500 = 5.00%）。NOT NULL DEFAULT 500。
salesCommissionBps業務抽成率（1000 = 10.00%）。NOT NULL DEFAULT 1000。
monthlyTopBonusBps月度第一名加碼率（500 = 5.00%）。NOT NULL DEFAULT 500。
ecpayMerchantIdECPay 特店 ID（明文，顯示用）。null = 未綁定租戶憑證（走 env 過渡）。
ecpaySecretsMaskECPay HashKey/HashIV 的遮罩碼（`****` + 末 4）。DTO **只暴露 mask**， 整包 EncryptedField（含密文）永不出 repo —— 顯示用零 KMS 呼叫。
travelinvoiceMerchantId代收轉付 travelinvoice 特店 ID（明文，顯示用）。null = 未綁定租戶憑證（fail-closed）。
travelinvoiceSecretsMasktravelinvoice HashKey/HashIV 的遮罩碼（`****` + 末 4）。DTO **只暴露 mask**， 整包 EncryptedField（含密文）永不出 repo —— 顯示用零 KMS 呼叫。
sendingDomain自有寄件 domain 快照；server 派生（enableSendingDomain），非自由輸入。
resendDomainId寄件服務商（Resend）的 domain 識別碼；null = 未設定自有寄件網域。
sendingDomainStatus自有寄件網域的驗證狀態（如 pending／verified）；null = 未設定。
senderLocalPart寄件人 local-part，未填視為 'info'。
updatedAt設定最後更新時間。
cairn settings get
{
"ok": true,
"data": {
"id": "…",
"companyName": "…",
"companyPhone": "…",
"taxId": "…",
"companyAddress": "…",
"logoUrl": "…",
"siteTagline": "…",
"seoDefaultDescription": "…",
"ogImageUrl": "…",
"emailReplyTo": "…",
"assignmentMode": "…",
"defaultAssigneeUserId": "…",
"allowSalesClaim": true,
"passportExpiryWarningDays": 0,
"groupCodePattern": "…",
"groupCodeSeqStyle": "…",
"groupCodeSeqWidth": 0,
"ecpayFeeBps": 0,
"fongshouFeeBps": 0,
"profitTaxBps": 0,
"salesCommissionBps": 0,
"monthlyTopBonusBps": 0,
"ecpayMerchantId": "…",
"ecpaySecretsMask": "…",
"travelinvoiceMerchantId": "…",
"travelinvoiceSecretsMask": "…",
"sendingDomain": "…",
"resendDomainId": "…",
"sendingDomainStatus": "…",
"senderLocalPart": "…",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
}cairn settings accounts收款帳戶目錄
參數
--active-only--jsoncairn settings accounts
cairn settings fee-routes費用類別 → 收款帳戶路由表
參數
--json回應欄位 · data[]
id路由設定 ID。
feeCategory費用類型代碼（租戶自定唯一鍵，如 tour_fee／lodging／equipment）。
displayName費用類型顯示名。
finalAccountId此費用類型最終結算進的收款帳戶 ID。
finalAccountNamefinal 帳戶顯示名（JOIN receiving_accounts；帳戶被刪則 null，但 FK restrict 一般不會）。
finalAccountCodefinal 帳戶代號。
isActive此路由是否啟用。
createdAt建立時間。
updatedAt最後更新時間。
cairn settings fee-routes
{
"ok": true,
"data": [
{
"id": "…",
"feeCategory": "…",
"displayName": "…",
"finalAccountId": "…",
"finalAccountName": "…",
"finalAccountCode": "…",
"isActive": true,
"createdAt": "2026-06-30T08:00:00.000Z",
"updatedAt": "2026-06-30T08:00:00.000Z"
}
]
}cairn settings expense-categories公司營業費用類別目錄
參數
--active-only--jsoncairn settings expense-categories
cairn settings modules租戶啟用的方案模組（唯讀；供應由平台 CLI 管）
參數
--json回應欄位 · data
climbing是否啟用登山團功能模組。
overseas是否啟用海外／出國團功能模組。
lodging是否啟用訂房子系統模組。
accounting是否啟用進階會計子系統模組。
lottery是否啟用抽籤子系統模組。
cairn settings modules
{
"ok": true,
"data": {
"climbing": true,
"overseas": true,
"lodging": true,
"accounting": true,
"lottery": true
}
}cairn settings assignable-staff可被指派訂單的員工名單
參數
--json回應欄位 · data[]
userId員工的使用者 ID（作為指派對象）。
name員工顯示姓名。
email員工登入 Email。
role員工角色代碼（sales／admin 等可指派角色）。
thisMonthAssigned本月（Asia/Taipei）已指派給此員工的訂單數（供輪派負載參考）。
cairn settings assignable-staff
{
"ok": true,
"data": [
{
"userId": "…",
"name": "…",
"email": "…",
"role": "…",
"thisMonthAssigned": 0
}
]
}cairn settings sending-domain寄件網域狀態（含 DNS record；網域未設定時 records 為空）
參數
--json回應欄位 · data
sendingDomain自有寄件網域；未設定時為 null。
resendDomainId寄件服務商（Resend）的網域識別碼；未設定時為 null。
sendingDomainStatus網域驗證狀態（如 pending／verified）；未設定時為 null。
senderLocalPart寄件人信箱的帳號部分（@ 前段）；未填視為 info。
records待設定的 DNS 記錄清單（SPF／DKIM 等）；Resend 不可達或未設定時為空陣列。
recordDNS 記錄用途分類（如 DKIM／SPF 等，來自 Resend）。
name記錄主機名（需在網域 DNS 新增的 host）。
type記錄類型（如 TXT／MX／CNAME）。
value記錄值（需填入 DNS 的內容）。
ttl選填存活時間（TTL）；未指定時省略。
status選填此筆記錄的驗證狀態（如 pending／verified）；未指定時省略。
priority選填MX 記錄優先權；非 MX 記錄省略。
cairn settings sending-domain
{
"ok": true,
"data": {
"sendingDomain": "…",
"resendDomainId": "…",
"sendingDomainStatus": "…",
"senderLocalPart": "…",
"records": [
{
"record": "…",
"name": "…",
"type": "…",
"value": "…",
"ttl": "…",
"status": "…",
"priority": 0
}
]
}
}cairn settings update更新公司檔 / 寄件身分（只送有帶的欄；空字串＝清空）
參數
--company-name公司全名，顯示於發票、合約與對外信件抬頭；傳 null 或空字串清除
--tax-id公司統一編號（8 位數字），用於開立發票；傳 null 或空字串清除
--company-phone公司聯絡電話，顯示於對外文件；傳 null 或空字串清除
--company-address公司登記地址，顯示於對外文件；傳 null 或空字串清除
--logo-url公司 Logo 圖片網址（http/https），用於後台與對外頁面品牌呈現；傳 null 或空字串清除
--email-reply-to系統寄信時的回覆收件信箱，客戶回信會寄到此處；傳 null 或空字串清除
--sender-local-part寄件人信箱的帳號部分（@ 前段），與寄件網域組成完整寄件地址；傳 null 或空字串清除
--passport-expiry-warning-days護照到期前提早幾天提醒（1 至 3650 天），用於行前護照效期預警
--confirm回應欄位 · data
ok是否成功更新租戶設定。
cairn settings update
{
"ok": true,
"data": {
"ok": true
}
}cairn settings seo更新 SEO 預設（tagline / description / og 圖；空字串＝清空）
參數
--tagline--description--og-image-url社群分享預設縮圖（Open Graph image）網址（http/https）；空字串清除
--confirm回應欄位 · data
ok是否成功更新公開站 SEO 設定。
cairn settings seo
{
"ok": true,
"data": {
"ok": true
}
}cairn settings ledger-fees更新內外帳試算費率（bps 0..10000；空＝不變）
參數
--ecpay-bps--fongshou-bps--profit-tax-bps淨利稅率，單位 basis points（0..10000，10000＝100%），用於內外帳淨利試算；留空不變更
--confirm回應欄位 · data
ok是否成功更新內外帳淨利試算的預估費率。
cairn settings ledger-fees
{
"ok": true,
"data": {
"ok": true
}
}cairn settings assignment設定訂單指派模式 + 預設指派人
參數
--mode <auto_round_robin|auto_customer_choice|manual_review>--default-assignee--confirm回應欄位 · data
ok是否成功更新訂單指派模式設定。
cairn settings assignment --mode <auto_round_robin|auto_customer_choice|manual_review>
{
"ok": true,
"data": {
"ok": true
}
}cairn settings ecpayECPay 憑證（set 三欄一起寫 / clear 解除綁定；write-only）
參數
--merchant-id綠界 ECPay 特店編號（MerchantID），用於金流請款與簽章
--hash-key綠界 ECPay HashKey，CheckMacValue 簽章用密鑰；寫入後即 KMS 加密儲存且永不回傳
--hash-iv綠界 ECPay HashIV，CheckMacValue 簽章用初始向量；寫入後即 KMS 加密儲存且永不回傳
--confirm回應欄位 · data
ok是否成功清除 ECPay 憑證。
cairn settings ecpay --merchant-id --hash-key --hash-iv
{
"ok": true,
"data": {
"ok": true
}
}cairn settings sending-domain-manage寄件網域：啟用 / 驗證 / 停用
參數
<enable|verify|disable>位置參數 · 必填--confirmcairn settings sending-domain-manage <enable|verify|disable>
cairn settings accounts-write收款帳戶寫入：create / update
參數
<id>位置參數 · 必填--code收款帳戶代號，建立後不可變更，作為帳戶的穩定識別
--name--kind <bank|cash|gateway>帳戶種類：bank 銀行帳戶、cash 現金、gateway 金流閘道
--currency帳戶幣別，ISO 4217 三碼（如 TWD / JPY / IDR）；空字串預設 TWD，非 TWD 即為外幣池
--confirm回應欄位 · data
id新建立的收款帳戶 ID。
cairn settings accounts-write <id> --code --kind <bank|cash|gateway>
{
"ok": true,
"data": {
"id": "…"
}
}cairn settings fee-routes-write費用類型路由：upsert / set-active
參數
<id>位置參數 · 必填--category--name--final-account--active <true|false>--confirm回應欄位 · data
id新建立或更新的費用類型路由 ID。
cairn settings fee-routes-write <id> --category --name --final-account
{
"ok": true,
"data": {
"id": "…"
}
}cairn settings expense-categories-write費用類別：create / update / set-active
參數
<id>位置參數 · 必填--code費用類別代碼（小寫英數與底線），建立後不可變更，作為類別的穩定識別
--name--kind <opex|tax|platform_fee|special>費用類別種類：opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊，影響損益表歸類
--confirm--active <true|false>回應欄位 · data
id新建立的費用類別 ID。
cairn settings expense-categories-write <id> --code --name --kind <opex|tax|platform_fee|special> --active <true|false>
{
"ok": true,
"data": {
"id": "…"
}
}cairn staff
員工：查詢租戶內部員工名單
cairn staff list列出租戶所有員工
參數
--json回應欄位 · data[]
userId員工的使用者 ID。
email員工登入 Email（帳號識別）。
name員工顯示姓名。
role員工角色代碼（admin／sales／op／accountant）。
createdAt帳號建立時間。
bannedAccount frozen via ban (離職 / 停權).
twoFactorEnabled是否已完成 TOTP 兩步驟驗證註冊。
emailVerifiedEmail 是否已驗證（可視為「受邀者至少完成過一次登入」）。
pending派生的「邀請待完成」狀態：帳號已建立，但受邀者尚未驗證 Email 也未註冊 2FA（未完成首次登入）。
cairn staff list
{
"ok": true,
"data": [
{
"userId": "…",
"email": "…",
"name": "…",
"role": "…",
"createdAt": "2026-06-30T08:00:00.000Z",
"banned": true,
"twoFactorEnabled": true,
"emailVerified": true,
"pending": true
}
]
}cairn staff invite建立新員工帳號（指定角色）；回一次性暫時密碼
參數
--email <e>受邀員工的登入 Email，作為帳號識別
--name <n>員工顯示姓名
--role <admin|sales|op|accountant>指派的員工角色（admin／sales／op／accountant），決定權限範圍
--confirm回應欄位 · data
userId新建立員工的使用者 ID。
tempPassword一次性明文暫時密碼，僅此次回傳（請立即轉交並要求員工首次登入改密）。
email新員工的登入 Email。
role指派的員工角色（admin／sales／op／accountant）。
cairn staff invite --email <e> --name <n> --role <admin|sales|op|accountant>
{
"ok": true,
"data": {
"userId": "…",
"tempPassword": "…",
"email": "…",
"role": "…"
}
}cairn staff set-role變更員工角色（admin|sales|op|accountant）
參數
<userId>位置參數 · 必填--role <admin|sales|op|accountant>變更後的員工角色（admin／sales／op／accountant），決定權限範圍
--confirm回應欄位 · data
ok是否成功變更員工角色。
cairn staff set-role <userId> --role <admin|sales|op|accountant>
{
"ok": true,
"data": {
"ok": true
}
}cairn staff remove移除員工（降為 customer，保留 user 紀錄）
參數
<userId>位置參數 · 必填--confirm回應欄位 · data
ok是否成功移除員工身分（降為一般顧客）。
cairn staff remove <userId>
{
"ok": true,
"data": {
"ok": true
}
}