[FEAT] 實作 B017 貨道庫存全量同步 API 與多語系支援
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 56s

1. 實作 B017 (reload_msg) 端點,支援貨道庫存、效期與批號的全量同步。
2. 將 B017 回傳欄位映射至 App 需求:slot_no -> tid, stock -> num。
3. 新增 expiry_date (效期) 與 batch_no (批號) 欄位支援。
4. 實作指令狀態閉環邏輯,成功同步後自動將相關 reload_stock 指令標記為成功。
5. 將指令備註欄位多語系化,新增「庫存已與機台同步」繁中、英文、日文翻譯。
6. 更新 API 技術規格文件 (.agents/skills) 與系統 API 文件配置 (config/api-docs.php)。
This commit is contained in:
2026-04-14 15:06:51 +08:00
parent 32fa28dc0f
commit 66f7c1ffb8
6 changed files with 120 additions and 12 deletions

View File

@@ -258,3 +258,39 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
> [!CAUTION]
> **安全性規範**B014 會回傳敏感金鑰與正式 Token背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時,後端才允許發放資料。
---
### 3.8 B017: 貨道庫存同步 (Slot Synchronization)
用於機台端獲取目前所有貨道的最新庫存、效期與狀態。通常由 B010 回應 `status: 49` 觸發。
- **URL**: POST /api/v1/app/machine/reload_msg/B017
- **Authentication**: Bearer Token (Header) 或 API Key (Body)
- **Request Body:**
| 參數 | 類型 | 必填 | 說明 | 範例 |
| :--- | :--- | :--- | :--- | :--- |
| machine | String | 是 | 機台編號 | SN00001 |
- **Response Body:**
| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| success | Boolean | 請求是否成功 | true |
| code | Integer | 200 | 200 |
| data | Array | 貨道數據陣列 (依 slot_no 排序) | 見下表 |
**data 陣列內部欄位:**
| 欄位 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| tid | String | 貨道編號 | "1" |
| num | Integer | 當前庫存數量 | 10 |
| expiry_date | String | 商品效期 | "2026-12-31" |
| batch_no | String | 批號 | "B202604" |
| product_id | Integer | 商品 ID | 1 |
| capacity | Integer | 貨道容量上限 | 15 |
| status | String | 貨道狀態 ("1": 啟用, "0": 停用) | "1" |
> [!IMPORTANT]
> **同步機制**B017 為全量同步。App 收到回應後應更新本地資料庫對應貨道的數值。成功請求後,雲端會自動將相關的 `reload_stock` 指令標記為 `success`