sky121113
8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# B602 API (出貨回傳) 技術規範與執行指南
|
||
|
||
本文件定義 B602 API 的技術實作規範，用於紀錄機台實體出貨結果，並作為訂單完結與庫存校準的依據。
|
||
|
||
---
|
||
|
||
## 1. 業務邏輯與交易完結
|
||
|
||
### 1.1 串聯機制
|
||
* **關聯 ID**：必須攜帶 B600 取得的 `flow_id`，以確保出貨紀錄正確鏈結至對應的 `orders`。
|
||
|
||
### 1.2 多品項交易處理 (Multi-item Orders)
|
||
* **一對多關係**：系統支持一筆訂單（同一個 `flow_id`）對應多筆 `dispense_records`。
|
||
* **上報方式**：機台每完成一個貨道之出貨即呼叫一次 B602。雲端後端將自動彙整所有關聯之出貨紀錄以計算該訂單之總體狀態。
|
||
|
||
---
|
||
|
||
## 2. 庫存一致性機制 (Stock Consistency)
|
||
|
||
為確保雲端與機台端的物理庫存同步，系統採以下策略：
|
||
|
||
1. **強制信任機制**：系統將「強制信任」機台在 B602 中回報的 `remaining_stock` (絕對值)，並直接更新資料庫中的貨道庫存。
|
||
2. **異常監控**：若機台回報的庫存與系統計算的預期值（原值 - 1）不符時，系統應於後台標記該次出貨為「庫存異動異常」，供管理員檢查是否發生卡貨或漏貨。
|
||
|
||
---
|
||
|
||
## 3. 資料庫結構：`dispense_records`
|
||
|
||
| 欄位 | 說明 | 備註 |
|
||
|------|------|------|
|
||
| `order_id` | 訂單 ID | 透過 `flow_id` 關聯 |
|
||
| `product_id` | 商品 ID | 出貨之商品 |
|
||
| `slot_no` | 貨道編號 | 出貨之貨道 |
|
||
| `dispense_status` | 出貨狀態 | 0: 成功, 1: 失敗 |
|
||
| `remaining_stock` | 剩餘庫存 | 機台回報之絕對值 |
|
||
| `source` | 來源標記 | `local` (B602), `remote` (B055) |
|
||
|
||
---
|
||
|
||
## 4. 待確認事項 (To-be-confirmed)
|
||
|
||
### 4.1 訂單完結判斷
|
||
1. **超時標記**：若雲端收到 B600 但遲遲未收到 B602，預設在多久後應將訂單標記為「出貨超時」？
|
||
2. **狀態遷移**：出貨失敗 (`status=1`) 時，訂單的最終顯示文字與處理流程。
|
||
|
||
### 4.2 營收與點數處理
|
||
3. **出貨失敗補償**：若 B602 回報失敗：
|
||
* 行動支付是否自動觸發退款？
|
||
* 是否自動退回該次交易所扣除之會員點數與優惠券？
|
||
4. **現金交易失敗**：出貨失敗且為現金交易時，是否應產出待維護工單或通知補貨員。
|