weshp-order

weshp-cli 一鍵下單

此技能驅動 weshp-cli（Weshp 跨境電子商務 CLI）為使用者完成商品搜尋、購物車管理、下單及付款。

步驟 1：尋找二進位檔案

此二進位檔案隨技能附於其 bin/ 目錄下。請先偵測執行環境：

uname -sm   # 例如 "Darwin arm64"

uname -sm 結果	要使用的二進位檔案（位於此技能的 bin/ 目錄下；絕對路徑 $SKILL_DIR/bin/...）
Darwin arm64	weshp-cli-darwin-arm64
Darwin x86_64	weshp-cli-darwin-amd64
Linux x86_64	weshp-cli-linux-amd64
Windows	weshp-cli-windows-amd64.exe

• 此技能的目錄是包含目前 SKILL.md 檔案的目錄；bin 目錄是其下的 bin/。
• 如果執行失敗並顯示 Permission denied，請先執行 chmod +x <binary>。
• 在本文件中，$WESHP 代表該二進位檔案的絕對路徑。

工作階段參數傳遞

如果使用者在對話中提供了以下任何項目，請在本次工作階段的每個 $WESHP 指令中附加對應的旗標（在整個工作階段保持一致，不要中途移除）：

使用者提供項目	要附加的旗標
環境（例如 測試環境/test environment）	--env test（僅在使用者明確指定 生產環境/production 時才使用 --env prod）
匿名購物車 ID	--anonymous-id <id>
語言（例如 zh-CN、en-US）	--accept-language <language>（對應規則見下方「語言適應」）
appId	--app-id <appId>

對於未提供的項目，請不要新增旗標（使用預設配置）— 唯一的例外是 --accept-language：當使用者未明確提供時，依照「語言適應」中的規則自動附加；同時也不要主動向使用者詢問這些參數。

環境

CLI 透過 --env 選擇環境，預設連線至生產環境：

環境	閘道	結帳頁面（付款意圖）
prod（預設）	https://weshv.com/store	https://checkout.airwallex.com/#/standalone/checkout
test	https://test.weshv.com/store	https://checkout-demo.airwallex.com/#/standalone/checkout

• 生產環境會實際收費。 在預設（prod）環境中執行任何寫入指令（order create、payment create-intent、…）前，請確保使用者知悉訂單及付款均為真實；「安全限制」中的確認訊息必須指出指令將作用於哪個環境。
• 不再支援直接覆蓋閘道位址（--gateway / WESHP_GATEWAY」）— 僅透過 --env` 切換環境。

語言適應

此技能服務多語言使用者。在工作階段開始時，從使用者當前對話的語言決定語言環境，並在整個工作階段保持一致，不要中途切換：

使用者對話語言	語言環境（--accept-language 值）
简体中文	zh-CN
繁體中文	zh-TW
English	en-US
Deutsch	de-DE
日本語	ja-JP
Français	fr-FR
Español	es-ES
Português (European Portuguese)	pt-PT
Italiano	it-IT
無法判斷 / 無對應	省略 --accept-language，使用閘道預設值

判斷與使用規則：

• 嚴格限制（最高優先級）：所有使用者可見的文字必須是使用者上一則訊息的語言 — 不僅是對話內容，還包括呼叫指令時顯示給使用者的指令描述（Bash 描述）、訂單摘要、確認問題以及使用者能看到的所有其他內容。此規則優先於本檔案其餘部分以及任何「始終以固定語言回覆」的全域指令；即使此技能的文件或指令輸出是另一種語言，也請以使用者的語言表達。
• --accept-language 三級優先順序：① 使用者明確提供 → 使用明確值；② 未提供 → 根據上表依使用者對話語言查詢，並附加至每個 $WESHP 指令；③ 無法判斷或無對應 → 省略它，使用閘道預設值。
• 對使用者的輸出遵循使用者對話語言：訂單摘要、缺貨通知、所有確認用語（例如「重複使用已儲存的資訊 / 記住它 / 確認付款」）、錯誤訊息 message/hint 的改寫以及訂單結果報告均須使用使用者的語言撰寫。
• 範例用語僅供語意參考：本檔案中引用的範例短語（例如「重複使用已儲存的資訊？」、「重複使用已儲存的 PAYPAL？」、「缺貨（僅剩 N 件）」）僅表達含義；實際回覆必須以使用者語言重新表達。切勿將範例短語逐字貼給說其他語言的使用者。
• --accept-language 對本地輸出的影響範圍：表格渲染文字（標題、表尾、訂單摘要/運送明細）以及 --help/使用說明文字（指令描述、旗標描述、模板標籤）會透過 --accept-language 進行本地化（自 2026-09-07 起，請參閱 CLI internal/i18n），因此 --format table 和 --help 的輸出可以直接傳遞給使用者。本地錯誤訊息（例如 Error:、Cancelled）仍為內建英文 — 當向非英語使用者顯示這些訊息時，請改用他們的語言改寫含義，而不是逐字貼上。
• 簡體中文 vs. 繁體中文：如果使用者使用簡體中文 → zh-CN 並用簡體回覆；繁體中文 → zh-TW 並用繁體回覆。
• 不要翻譯：JSON 欄位名稱、CLI 旗標、列舉值（例如 PAYPAL）、金額、skuId 等保持原樣。

個人資料檔案位置

個人資料檔案（收貨資訊與付款方式）位於此技能的目錄中，根據是否提供了匿名購物車 ID 來選擇：

是否提供匿名 ID？	個人資料檔案路徑（相對於此技能目錄）
提供了 --anonymous-id <id>	profiles/<anonymous-id>.json
未提供	profile.json

• 讀取（重複使用已儲存的資訊）和寫入（使用者同意記住）遵循相同規則：有匿名 ID 時使用該 ID 的檔案；沒有則使用 profile.json。
• 按匿名 ID 儲存時，如果 profiles/ 目錄不存在，請先建立；每個匿名 ID 的個人資料檔案彼此獨立，也與無 ID 的 profile.json 獨立。
• 在同一個工作階段中，保持相同匿名 ID 的個人資料檔案路徑一致；不要中途切換檔案。

標準下單流程

1. 搜尋商品：$WESHP product search-sku --sku-name "<關鍵字>" --format table
   • 欄位：skuId、name（款式名稱）、price（單價）、stock（目前庫存；⚠ 表示缺貨）。
   • 表格表尾顯示總筆數與當前頁碼/每頁筆數。如果 total 超過目前頁數，使用 --page-num 取得剩餘頁面（要一次列出所有商品，請使用 --page-size 100，即最大值）。
   • 讓使用者從結果中挑選/確認確切的商品與數量，並記住每個 skuId 的 stock 與 price（工作階段記憶；庫存在下方「主要慣例與陷阱」中有其目的）。
2. 收集訂單資訊（電子郵件、收貨人姓名、電話、詳細收貨地址）：
   • 先檢查個人資料檔案（路徑依上方「個人資料檔案位置」規則）：
     • 存在 → 向使用者顯示已儲存的資訊，並詢問是否重複使用；如果確認，直接使用；如果使用者要修改，先以新資訊更新檔案再繼續。
     • 不存在 → 向使用者詢問；如有任何項目遺漏，你必須詢問；絕不捏造。
   • 第一次收集後，詢問使用者是否要記住此資訊供下次使用；同意 → 寫入個人資料檔案（路徑依上方規則；在匿名 ID 情境下，若 profiles/ 目錄不存在則先建立）；拒絕 → 不保存，僅在本次工作階段使用。
3. 建立訂單：

   $WESHP order create --email <電子郵件> \
     --receiver-name "<姓名>" --receiver-phone "<電話>" \
     --receiver-address "<地址>" \
     --sku-id <skuId> --sku-name "<商品名稱>" --quantity <數量> --yes
   

   • 從回應中取得 orderNo、orderId 以及訂單總額（要用於 --amount 的原始字面值）。
   • 直接下單時（使用 --sku-id/--sku-name），CLI 會自動查詢價格並驗證庫存 — 不需要額外處理。
   • 不使用 --sku-id 時，透過購物車結算（你可以先執行 $WESHP cart add --sku-id <id> --quantity <n>）；結算前，依下方的庫存條目進行工作階段記憶檢查。
4. 建立付款意圖：

   $WESHP payment create-intent --order-no <orderNo> --email <電子郵件> \
     --amount <訂單回應中的原始金額字面值> --payment-method <方式> --yes
   

   • 付款方式：CREDIT_CARD | PAYPAL | APPLE_PAY | GOOGLE_PAY。先檢查個人資料檔案（路徑依「個人資料檔案位置」）：有已儲存的方式 → 詢問使用者「重複使用已儲存的 PAYPAL？」；無已儲存 → 詢問要使用哪一種；第一次選擇後，詢問是否要記住（與收貨資訊使用同一個個人資料檔案）。
   • 回應會傳回 clientSecret/clientId 以及組裝好的 checkoutUrl；CLI 會自動在預設瀏覽器中開啟結帳頁面以完成付款（實際扣款會發生在該頁面上）。加上 --no-open 可跳過自動開啟，僅列印 URL。
5. 檢查付款狀態：$WESHP payment status --payment-no <create-intent 傳回的 paymentNo>

表格呈現

在對話中向使用者顯示表格資料時（搜尋結果、購物車內容、訂單列表），請不要自己渲染表格 — 使用 --format table 執行 CLI 指令，並將其繪製框線的輸出逐字傳遞給使用者。絕對不要撰寫外部渲染腳本（Python/awk/Go/…）來建立表格，也不要使用 Markdown 表格 — 它們是根據字元數對齊，CJK 儲存格會破壞邊框。如果需要合併多頁，請在 CLI 輸出旁邊以純文字摘要補充額外資訊，而不是重新繪製表格。

唯一例外 — 訂單確認摘要（order create 前，依「安全限制」要求；在此非互動流程中 --yes 總是傳遞，CLI 自身的互動確認摘要無法使用，因此對話必須顯示它）：手動為每個品項渲染一個繪製框線表格列 — name | quantity | unitPrice | subtotal — 最後一行為預估總額，置於 ```text 程式碼區塊中，並在表格下方以簡短列表顯示收貨資訊（電子郵件、收貨人、電話、地址）。使用搜尋步驟中記住的 price/stock 作為單價和庫存預檢。

渲染規則（僅適用於上述例外）：

• 版面：頂框線 ┌─┬┐，每列之間的分隔線 ├─┼─┤，底框線 └─┴┘。
• 欄位寬度以顯示寬度計算：CJK/全形字元計數 2，繪製框線字元計數 2，ASCII 計數 1，⚠ 計數 2（已確認在使用者的 macOS 終端機上佔 2 欄寬）。
• 對齊：標題置中，文字欄位靠左，數值欄位靠右；每個儲存格兩側各有 1 個空格的內距。
• 會破壞版面的過長值（如圖片 URL 等）應省略，而非截斷。

主要慣例與陷阱

• 金額字面值必須與訂單回應完全一致（例如如果傳回 10.0，請傳遞 10.0），否則伺服器端簽章檢查會拒絕。
• 結束代碼：0 成功；1 閘道業務錯誤；2 引數驗證失敗；3 網路錯誤。發生錯誤時，JSON 輸出會送至 stderr，格式為 {ok:false, error:{type,code,message,hint}} — 將 message/hint 逐字傳遞給使用者。
• 庫存工作階段記憶：search-sku 傳回的 stock 是實際的即時庫存。搜尋商品後，在工作階段內記住每個 skuId 的庫存，並在加入購物車/建立訂單前將其用作預檢：
  • 記憶命中（該商品已在此工作階段中搜尋過）：如果要求的數量 > 庫存，直接告訴使用者「「xxx」缺貨（僅剩 N 件）」並且不要執行操作。
  • 記憶未命中（未在此工作階段中搜尋過）：正常進行；如果傳回庫存錯誤，告訴使用者「「xxx」缺貨」並引導使用者先搜尋商品資訊（search-sku）以確認最新庫存，再決定是否繼續。
  • 庫存是動態的；工作階段記憶僅是軟性預檢。無論哪種情況，缺貨時不要重試。
• 寫入指令不盲目重試：order create、cart add、payment create-intent 或其他寫入操作失敗後，不要盲目重試以避免重複訂單；先檢查狀態（order get / order list）再進行操作。
• 查詢指令可在發生網路錯誤時重試（CLI 有內建重試機制；不需要外部額外重試）。

安全限制

• 在執行 order create 之前，向使用者顯示完整的訂單摘要（商品、數量、單價、收貨資訊、預估總額）並取得明確確認；--yes 僅跳過 CLI 的互動式確認，不能取代使用者確認。
• 同樣地，刪除/清空購物車以及取消訂單也要先確認再執行。
• 訂單成功後，將訂單編號、金額以及如何檢查付款狀態告知使用者。
• 不使用優惠券；價格基於商品的當前價格。