From 66f7c1ffb845ad02ccd996d8756389caeb402714 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Tue, 14 Apr 2026 15:06:51 +0800 Subject: [PATCH] =?UTF-8?q?[FEAT]=20=E5=AF=A6=E4=BD=9C=20B017=20=E8=B2=A8?= =?UTF-8?q?=E9=81=93=E5=BA=AB=E5=AD=98=E5=85=A8=E9=87=8F=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=20API=20=E8=88=87=E5=A4=9A=E8=AA=9E=E7=B3=BB=E6=94=AF=E6=8F=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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)。 --- .agents/skills/api-technical-specs/SKILL.md | 36 ++++++++++++ .../Api/V1/App/MachineController.php | 29 +++++++--- config/api-docs.php | 58 +++++++++++++++++++ lang/en.json | 3 +- lang/ja.json | 3 +- lang/zh_TW.json | 3 +- 6 files changed, 120 insertions(+), 12 deletions(-) diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md index a920ef0..a0da026 100644 --- a/.agents/skills/api-technical-specs/SKILL.md +++ b/.agents/skills/api-technical-specs/SKILL.md @@ -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`。 diff --git a/app/Http/Controllers/Api/V1/App/MachineController.php b/app/Http/Controllers/Api/V1/App/MachineController.php index 29ea080..0a39afa 100644 --- a/app/Http/Controllers/Api/V1/App/MachineController.php +++ b/app/Http/Controllers/Api/V1/App/MachineController.php @@ -168,35 +168,46 @@ class MachineController extends Controller /** * B017: Get Slot Info & Stock (Synchronous) */ + /** + * B017: Get Slot Info & Stock (Synchronous - Full Sync) + */ public function getSlots(Request $request) { $machine = $request->get('machine'); - $slots = $machine->slots()->with('product')->get(); + + // 依貨道編號排序 (Sorted by slot_no as requested) + $slots = $machine->slots()->with('product')->orderBy('slot_no')->get(); // 自動轉 Success: 若機台來撈 B017，代表之前的 reload_stock 指令已成功被機台響應 + // 同時處理 sent 與 pending 狀態，確保狀態機正確關閉 \App\Models\Machine\RemoteCommand::where('machine_id', $machine->id) ->where('command_type', 'reload_stock') - ->where('status', 'sent') - ->update(['status' => 'success', 'executed_at' => now()]); + ->whereIn('status', ['pending', 'sent']) + ->update([ + 'status' => 'success', + 'executed_at' => now(), + 'note' => __('Inventory synced with machine') + ]); return response()->json([ 'success' => true, 'code' => 200, 'data' => $slots->map(function ($slot) { return [ - 'slot_no' => $slot->slot_no, - 'product_id' => $slot->product_id, - 'stock' => $slot->stock, - 'capacity' => $slot->capacity, - 'price' => $slot->price, - 'status' => $slot->status, + 'tid' => $slot->slot_no, + 'num' => (int)$slot->stock, 'expiry_date' => $slot->expiry_date, 'batch_no' => $slot->batch_no, + // 保留原始欄位以供除錯或未來擴充 + 'product_id' => $slot->product_id, + 'capacity' => $slot->max_stock, + 'status' => $slot->is_active ? '1' : '0', ]; }) ]); } + /** * B710: Sync Timer status (Asynchronous) */ diff --git a/config/api-docs.php b/config/api-docs.php index 98dae36..fe714ab 100644 --- a/config/api-docs.php +++ b/config/api-docs.php @@ -459,6 +459,64 @@ return [ ], 'notes' => '硬體代碼對照表見後端 MachineService::ERROR_CODE_MAP 定義。 0402: 出貨成功, 0403: 貨道卡貨, 0202: 貨道缺貨, 0415: 取貨門異常...等。' + ], + [ + 'name' => 'B017: 貨道庫存同步 (Slot Synchronization)', + 'slug' => 'b017-slot-sync', + 'method' => 'POST', + 'path' => '/api/v1/app/machine/reload_msg/B017', + 'description' => '用於機台端獲獲取所有貨道的最新庫存、效期與狀態。通常由 B010 回傳 status: 49 時觸發。', + 'headers' => [ + 'Authorization' => 'Bearer ', + 'Content-Type' => 'application/json', + ], + 'parameters' => [ + 'machine' => [ + 'type' => 'string', + 'required' => true, + 'description' => '機台序號', + 'example' => 'SN00001' + ], + ], + 'response_parameters' => [ + 'success' => [ + 'type' => 'boolean', + 'description' => '是否成功', + 'example' => true + ], + 'data' => [ + 'type' => 'array', + 'description' => '貨道數據陣列。', + 'example' => [ + [ + 'tid' => '1', + 'num' => 10, + 'expiry_date' => '2026-12-31', + 'batch_no' => 'B2026', + 'status' => '1' + ] + ] + ], + ], + 'request' => [ + 'machine' => 'SN00001' + ], + 'response' => [ + 'success' => true, + 'code' => 200, + 'data' => [ + [ + 'tid' => '1', + 'num' => 10, + 'expiry_date' => '2026-12-31', + 'batch_no' => 'B2026', + 'product_id' => 1, + 'capacity' => 15, + 'status' => '1' + ] + ] + ], + 'notes' => 'B017 為全量同步。實作上後端會依據 slot_no 進行排序，並將相關指令狀態更新為已完成。' ] ] ] diff --git a/lang/en.json b/lang/en.json index 5df7d7d..b8ff430 100644 --- a/lang/en.json +++ b/lang/en.json @@ -1152,5 +1152,6 @@ "Ongoing": "Ongoing", "Waiting": "Waiting", "Publish Time": "Publish Time", - "Expired Time": "Expired Time" + "Expired Time": "Expired Time", + "Inventory synced with machine": "Inventory synced with machine" } \ No newline at end of file diff --git a/lang/ja.json b/lang/ja.json index ed9855d..b449490 100644 --- a/lang/ja.json +++ b/lang/ja.json @@ -1151,5 +1151,6 @@ "Ongoing": "進行中", "Waiting": "待機中", "Publish Time": "公開時間", - "Expired Time": "終了時間" + "Expired Time": "終了時間", + "Inventory synced with machine": "在庫が機体と同期されました" } \ No newline at end of file diff --git a/lang/zh_TW.json b/lang/zh_TW.json index 29109df..9cb86f4 100644 --- a/lang/zh_TW.json +++ b/lang/zh_TW.json @@ -1152,5 +1152,6 @@ "Ongoing": "進行中", "Waiting": "等待中", "Publish Time": "發布時間", - "Expired Time": "下架時間" + "Expired Time": "下架時間", + "Inventory synced with machine": "庫存已與機台同步" } \ No newline at end of file