sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# B600 API (消費金流回傳) 技術規範與執行指南
|
||
|
||
本文件定義 B600 API 的技術實作規範，這是系統處理金流交易、訂單生成與跨 API 關聯的核心。
|
||
|
||
---
|
||
|
||
## 1. 交易生命週期與 `flow_id` 串聯
|
||
|
||
為確保一筆交易數據的完整性，系統採用 `flow_id` 串聯三個連續上報的 API：
|
||
|
||
1. **B600 (金流上報)**：
|
||
* 機台於支付成功後即時呼叫。
|
||
* 雲端收到後產出專屬的 `flow_id` 並回傳給機台。
|
||
2. **B601 (發票上報)**：
|
||
* 機台開立發票後，攜帶 B600 取得的 `flow_id` 呼叫。
|
||
* 系統根據 `flow_id` 將發票資訊與 `orders` 表關聯。
|
||
3. **B602 (出貨上報)**：
|
||
* 機台實體出貨後，攜帶 `flow_id` 呼叫。
|
||
* 系統根據 `flow_id` 更新訂單的出貨狀態。
|
||
|
||
---
|
||
|
||
## 2. 金流類型與標準化
|
||
|
||
### 2.1 類型定義
|
||
根據 B600 PDF 文件規範 (Req3)，系統優先採用以下預定義類型進行處理與對帳。
|
||
|
||
### 2.2 防重複上報 (Idempotency)
|
||
為防止網路不穩導致機台重複呼叫 B600，系統必須使用機台產生的 `order_no (tid)` 結合 `machine_id` 作為唯一鍵值校驗。
|
||
|
||
---
|
||
|
||
## 3. 執行面優化：異步隊列 (Async Queue)
|
||
|
||
在高併發環境下，為確保機台端不因等待資料庫寫入而時耗，B600 採以下流程：
|
||
|
||
1. **即時回應**：API 接收請求後，將原始 JSON 派發至 **Redis Queue**。
|
||
2. **背景處理**：由 `ProcessTransaction` 任務異步執行：
|
||
* 建立 `orders` 與 `order_items`。
|
||
* 計算並異動會員點數/優惠券。
|
||
* 同步更新儀表板統計數據。
|
||
3. **異步回傳**：機台呼叫 API 後會收到 `202 Accepted`，`flow_id` 則透過回應檔同步回傳。
|
||
|
||
---
|
||
|
||
## 4. 數據完整性與異常處理 (Integrity & Exceptions)
|
||
|
||
### 4.1 自動對帳機制 (Auto-Reconciliation)
|
||
* **機制**：系統後台需建立定期定時任務（Scheduled Task），比對同一 `flow_id` 下的以下數據：
|
||
- **B600 (收取金額)**：訂單總計金額。
|
||
- **B602 (出貨總價值)**：機台實際出貨商品之總價值。
|
||
* **異常標記**：若兩者金額不符（例如：付了 $50 但僅出貨 $0 或 $30），系統應自動將該訂單標記為 **「金額異常」**，並同步產出警示通知供營運人員手動稽核。
|
||
|
||
### 4.2 出貨失敗處理 (Dispense Failure)
|
||
* **原則**：若 B602 回報「出貨失敗」，系統**不觸發自動退款**程序。
|
||
* **處理流程**：系統僅記錄失敗狀態並維持訂單為「待處理/異常」，後續由客服或管理員介入，根據實際情況進行人工退款、補發指令或現場處理。
|
||
|
||
---
|
||
|
||
## 5. 待確認事項 (已結案)
|
||
|
||
所有關鍵決策已於 2026-03-12 完成確認。
|