sky121113
8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# B055 API (遠端出貨) 技術規範與執行指南
|
||
|
||
本文件定義 B055 API 的技術實作規範，用於處理從雲端發起的機台遠端出貨指令及其結果回饋。
|
||
|
||
---
|
||
|
||
## 1. 業務流程與通訊機制
|
||
|
||
### 1.1 指令下發流程
|
||
1. **指令生成**：Cloud 後端（管理者或系統觸發）在 `remote_dispense_commands` 表中建立一筆狀態為 `0` (待執行) 的指令。
|
||
2. **心跳通知**：在該機台的 B010 回應中，將 `status` 設為 `85` (reload B055)。
|
||
3. **機台撈取 (POST)**：機台呼叫 B055 POST API (`/api/app/machine/dispense/{workid}`) 取得詳細出貨參數（貨道 ID、指令 ID）。
|
||
4. **執行與回報 (PUT)**：機台嘗試出貨後，呼叫 B055 PUT API 回報出貨結果及剩餘庫存。
|
||
|
||
### 1.2 數據關聯 (Data Linking)
|
||
* **出貨紀錄整合**：遠端出貨成功後，系統必須在 `dispense_records` 表中同步存入一筆紀錄，並將 `source` 標記為 `remote`（或對應識別），確保後台報表包含所有實體出貨數據。
|
||
|
||
---
|
||
|
||
## 2. 資料庫結構：`remote_dispense_commands`
|
||
|
||
| 欄位 | 說明 | 備註 |
|
||
|------|------|------|
|
||
| `command_id` | 執行命令 ID | 用於追蹤單次指令 |
|
||
| `slot_no` | 貨道 ID | 指派機台出貨的通道 |
|
||
| `status` | 執行狀態 | 0:待執行, 1:成功, 2:失敗 |
|
||
| `remaining_stock` | 剩餘庫存 | 由機台回報 |
|
||
|
||
---
|
||
|
||
## 3. 執行面優化 (Execution Strategy)
|
||
|
||
* **Redis 隊列**：由於遠端出貨屬於高優先權操作，待執行指令應快取於 Redis 中，以確保機台呼叫 POST 時能即時回應。
|
||
* **異步處理**：機台 PUT 回報結果後，系統透過隊列更新 DB 狀態，並根據結果觸發後續邏輯（如扣除庫存、異動日誌）。
|
||
|
||
---
|
||
|
||
## 4. 待確認事項 (To-be-confirmed)
|
||
|
||
### 4.1 業務情境 (Scenario)
|
||
1. **指令發起來源**：確認指令是由後台管理員手動測試發起，還是串接外部線上購買系統產出的取貨指令？
|
||
|
||
### 4.2 失敗處理機制 (Failure Handling)
|
||
2. **自動退款/告警**：若機台 PUT 回報出貨失敗，雲端是否需要自動發起退款（針對線上訂單）或發送維修告警通知？
|
||
|
||
### 4.3 指令效期與防重 (TTL & Idempotency)
|
||
3. **指令效期**：如果指令發出後機台失聯，該指令應在多久後失效 (TTL)？
|
||
4. **防重複機制**：如何嚴格確保同一個 `command_id` 不會被重複執行兩次？
|
||
|
||
### 4.4 安全性與權限 (Security)
|
||
5. **指令簽名**：除了 `api_token`，發送出貨指令是否需要額外的加密簽名驗證以防偽造？
|
||
6. **權限限制**：是否限制僅特定高級管理員可發起此類高風險指令？
|
||
|
||
### 4.5 欄位定義
|
||
7. **URL {workid}**：確認是否對標 `serial_no`。
|