star-cloud/docs/b055_technical_spec.md

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 完成確認。