sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# B055 API (遠端出貨) 技術規範與執行指南
|
||
|
||
本文件定義 B055 API 的技術實作規範，用於處理從雲端發起的機台遠端出貨指令及其結果回饋。
|
||
|
||
---
|
||
|
||
## 1. 業務流程與通訊機制
|
||
|
||
### 1.1 指令下發流程
|
||
1. **指令生成**：Cloud 後端（管理者）在 `remote_commands` 表中建立一筆類型為 `dispense`、狀態為 `pending` 的指令。
|
||
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_commands`
|
||
|
||
遠端出貨指令統一存放在 `remote_commands` 表中，B055 的特定參數將存放於 `payload` (JSON) 欄位。
|
||
|
||
| 欄位 | B055 對應說明 | 備註 |
|
||
|------|--------------|------|
|
||
| `id` | 執行命令 ID | 用於追蹤單次指令 (POST 回傳) |
|
||
| `payload->slot_no` | 貨道 ID | 指派機台出貨的通道 |
|
||
| `status` | 執行狀態 | pending/sent/success/failed |
|
||
| `ttl` | 指令效期 | 預設 60 秒 |
|
||
|
||
---
|
||
|
||
## 3. 執行面優化 (Execution Strategy)
|
||
|
||
* **Redis 隊列**：由於遠端出貨屬於高優先權操作，待執行指令應快取於 Redis 中，以確保機台呼叫 POST 時能即時回應。
|
||
* **異步處理**：機台 PUT 回報結果後，系統透過隊列更新 DB 狀態，並根據結果觸發後續邏輯（如扣除庫存、異動日誌）。
|
||
|
||
---
|
||
|
||
## 4. 欄位定義與對照
|
||
|
||
| B055 欄位 | 資料庫對應 | 說明 |
|
||
|----------|------------|------|
|
||
| `command_id` | `remote_dispense_commands.id` | 指令唯一識別碼 |
|
||
| `slot_no` | `machine_slots.slot_no` | 目標貨道編號 |
|
||
|
||
---
|
||
|
||
## 5. 業務邏輯細節建議
|
||
|
||
### 5.1 指令效期 (TTL)
|
||
* **建議設定**：**60 秒 (1 分鐘)**。
|
||
* **理由**：由於遠端出貨指令由管理員手動發起（通常用於現場故障排除或客訴處理），若機台因網路問題超過一分鐘未拉取指令，該次操作的情境通常已失效，應自動失效以防止後續無預警出貨。
|
||
|
||
### 5.2 失敗處理
|
||
* **機制**：機台回報出貨失敗時，系統僅需記錄結果並在後台顯示異常狀態。
|
||
* **處理原則**：考量目前僅供管理員手動發起，**不需執行自動退款**，由管理員依據日誌進行後續手動處理即可。
|
||
|
||
### 5.3 安全與權限
|
||
* **驗證機制**：維持 `api_token` 驗證，不需額外的加密簽名。
|
||
* **權限控制**：建議在 RBAC 權限系統中，限制僅「高級管理員」或「維修主管」具備發起遠端出貨的權限。
|
||
|
||
---
|
||
|
||
## 6. 待確認事項 (已結案)
|
||
|
||
所有關鍵決策已於 2026-03-12 完成確認。
|