star-cloud/docs/b055_technical_spec.md

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。