[FEAT] 實作 B017 貨道庫存全量同步 API 與多語系支援

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

@@ -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`。

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)
      */

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 <api_token>',
+                        '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 進行排序，並將相關指令狀態更新為已完成。'
                 ]
             ]
         ]

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"
 }

lang/ja.json

@@ -1151,5 +1151,6 @@
     "Ongoing": "進行中",
     "Waiting": "待機中",
     "Publish Time": "公開時間",
-    "Expired Time": "終了時間"
+    "Expired Time": "終了時間",
+    "Inventory synced with machine": "在庫が機体と同期されました"
 }

lang/zh_TW.json

@@ -1152,5 +1152,6 @@
     "Ongoing": "進行中",
     "Waiting": "等待中",
     "Publish Time": "發布時間",
-    "Expired Time": "下架時間"
+    "Expired Time": "下架時間",
+    "Inventory synced with machine": "庫存已與機台同步"
 }