sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
58 lines
2.8 KiB
Markdown
58 lines
2.8 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. 數據完整性與異常處理 (Integrity & Exceptions)
|
||
|
||
### 4.1 出貨超時監控 (Dispense Timeout)
|
||
* **閾值建議**：若系統收到 B600 (金流) 超過 **5 分鐘** 仍未收到任何對應之 B602 (出貨回報)，雲端後台應自動將該訂單標記為 **「出貨超時」**。
|
||
* **用途**：此狀態主要用於輔助對帳，標記可能發生網路中斷或機台異常卡死之交易，需由管理員介入核實。
|
||
|
||
### 4.2 出貨失敗處理 (Dispense Failure)
|
||
* **狀態遷移**：當 B602 回報 `dispense_status = 1` (失敗) 時，訂單狀態應更新為 **「出貨失敗」**。
|
||
* **即時通知**：系統應立即產出 **「後台警示通知」** 並推播給營運人員，以便快速處理現場排礙或後續補償。
|
||
* **補償與維護策略 (現階段)**：
|
||
- **點數/優惠券**：目前不採自動退回機制，維持異常狀態由管理員人工處理。
|
||
- **營運維護**：目前暫不自動產出維護工單或推播給補貨員，僅紀錄於異常日誌並顯示於後台通知區。
|
||
|
||
---
|
||
|
||
## 5. 待確認事項 (已結案)
|
||
|
||
所有關於出貨流程與超時判定之技術決策已於 2026-03-12 完成確認。
|