[FIX] 規格對齊與 B009 庫存同步邏輯優化

1. 更新 B009 (貨道庫存回報) API 規格文件與 config/api-docs.php，對齊參數型別 (tid: String, num: Integer) 並移除 legacy status 欄位。
2. 修正 MachineController 接收參數時的強製型別轉型，防止因 APP 傳入字串格式導致的庫存異動判斷錯誤。
3. 優化 MachineService@syncSlots 邏輯，確保庫存變動比對準確，並補齊新建立貨道時的初始庫存流水帳紀錄。
4. 移除 B009 回應中的 status 欄位，統一使用 success 進行成功判定。

.agents/skills/api-technical-specs/SKILL.md

@@ -88,13 +88,13 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 | 參數 | 類型 | 必填 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- | :--- |
 | account | String | 是 | 執行補貨的人員帳號 (Username 或 Email)，用於權限驗證 | admin |
-| data | Array/Object | 是 | 貨道數據陣列 (若傳單一物件會自動相容為陣列) | [{"tid":"1", "t060v00":"1", "num":"10"}] |
+| data | Array/Object | 是 | 貨道數據陣列 (若傳單一物件會自動相容為陣列) | [{"tid": "1", "t060v00": "1", "num": 10, "type": 1}] |
 
 - **data 陣列內部欄位：**
 
 | 欄位 | 類型 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- |
-| tid | Integer | 貨道編號 (Slot No) | 1 |
+| tid | String | 貨道編號 (Slot No) | "1" |
 | t060v00 | String | 商品資料庫 ID (或是 Barcode) | "1" |
 | num | Integer | 實體剩餘庫存數量 | 10 |
 | type | Integer | 貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。 | 1 |
@@ -110,7 +110,6 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 | success | Boolean | 同步是否成功 | true |
 | code | Integer | 內部業務狀態碼 | 200 |
 | message | String | 回應訊息 | Slot report synchronized success |
-| status | String | 固定回傳 49 代表同步完成 | "49" |
 
 - **Response Body (Failed 403 - 權限不足):**
 
@@ -119,7 +118,6 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 | success | Boolean | 請求是否成功 | false |
 | code | Integer | HTTP 狀態碼 | 403 |
 | message | String | 失敗原因 | Unauthorized: Account not found |
-| status | String | 固定回傳空字串 | "" |
 
 ---
 

app/Http/Controllers/Api/V1/App/MachineController.php

@@ -377,10 +377,10 @@ class MachineController extends Controller
 
         $mappedSlots = array_map(function ($item) {
             return [
-                'slot_no' => $item['tid'] ?? null,
+                'slot_no' => isset($item['tid']) ? (string)$item['tid'] : null,
                 'product_id' => $item['t060v00'] ?? null,
-                'stock' => $item['num'] ?? 0,
-                'type' => $item['type'] ?? null,
+                'stock' => isset($item['num']) ? (int)$item['num'] : 0,
+                'type' => isset($item['type']) ? (int)$item['type'] : null,
             ];
         }, $legacyData);
 
@@ -394,7 +394,6 @@ class MachineController extends Controller
             'success' => true,
             'code' => 200,
             'message' => __('Slot report synchronized success'),
-            'status' => '49'
         ]);
     }
 

app/Services/Machine/MachineService.php

@@ -215,7 +215,7 @@ class MachineService
                     }
                 }
 
-                $newStock = $slotData['stock'] ?? 0;
+                $newStock = (int) ($slotData['stock'] ?? 0);
 
                 $updateData = [
                     'product_id' => $actualProductId,
@@ -243,7 +243,19 @@ class MachineService
                         );
                     }
                 } else {
-                    $machine->slots()->create(array_merge($updateData, ['slot_no' => $slotNo]));
+                    $newSlot = $machine->slots()->create(array_merge($updateData, ['slot_no' => $slotNo]));
+                    
+                    // 新建貨道若有初始庫存，也紀錄流水帳
+                    if ($newStock > 0) {
+                        $this->recordStockMovement(
+                            $newSlot,
+                            $newStock,
+                            MachineStockMovement::TYPE_ADJUSTMENT,
+                            null,
+                            "movement.note.initial_sync_report",
+                            ['old' => 0, 'new' => $newStock]
+                        );
+                    }
                 }
             }
         });

config/api-docs.php

@@ -196,9 +196,9 @@ return [
                         'data' => [
                             'type' => 'array',
                             'required' => true,
-                            'description' => '貨道數據陣列。tid: 貨道號, t060v00: 商品 ID, num: 庫存量',
+                            'description' => '貨道數據陣列。tid: 貨道號, t060v00: 商品 ID, num: 庫存量, type: 貨道類型(1:履帶, 2:彈簧)',
                             'example' => [
-                                ['tid' => '1', 't060v00' => '1', 'num' => '10']
+                                ['tid' => '1', 't060v00' => '1', 'num' => 10, 'type' => 1]
                             ]
                         ],
                     ],
@@ -218,23 +218,17 @@ return [
                             'description' => '回應訊息',
                             'example' => 'Slot report synchronized success'
                         ],
-                        'status' => [
-                            'type' => 'string',
-                            'description' => '固定回傳 49 代表同步完成',
-                            'example' => '49'
-                        ],
                     ],
                     'request' => [
                         'account' => '0999123456',
                         'data' => [
-                            ['tid' => '1', 't060v00' => '1', 'num' => '10']
+                            ['tid' => '1', 't060v00' => '1', 'num' => 10, 'type' => 1]
                         ]
                     ],
                     'response' => [
                         'success' => true,
                         'code' => 200,
                         'message' => 'Slot report synchronized success',
-                        'status' => '49'
                     ],
                 ],
                 [