[FEAT] 完善 IoT API 規范化、機台管理介面優化與 B005 改為 GET

1. 將 B005 (廣告同步) 從 POST 改為 GET，符合 RESTful 規範。
2. 完善 B009 (庫存回報) 回應規格，加入業務代碼 (200 OK)。
3. API 文件 UI 優化：新增 Method Badge (方法標籤)，並修正 JSON 中文/斜線轉義問題。
4. 機台管理介面優化：實作「唯讀庫存與效期」面板，並將日誌圖示改為「👁️」。
5. 標準化 ID 識別邏輯：資料表全面移除對 sku 的依賴，改以 id 為主、barcode 為輔。
6. 新增 Migration：正式移除 sku 欄位並同步 barcode 指向。
7. 更新多語系支援 (zh_TW, en, ja)。

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

@@ -41,7 +41,68 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 
 ---
 
-### 3.2 B010: 心跳上報與狀態同步
+### 3.2 B005: 廣告清單同步
+用於機台端獲取目前應播放的廣告檔案 URL 清單。
+
+- **URL**: `GET /api/v1/app/machine/ad/B005`
+- **Request Body:** 無 (GET 請求)
+
+- **Response Body:**
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| `success` | Boolean | 請求是否成功 | `true` |
+| `code` | Integer | 內部業務狀態碼 | `200` |
+| `data` | Array | 廣告物件陣列 | `[{"t070v04": "https://..."}]` |
+
+**data 陣列內部欄位：**
+- `t070v01`: 廣告名稱 (Name)
+- `t070v02`: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
+- `t070v03`: 廣告位置 (Position/Flag) — (`3`: 待機廣告, `1`: 販賣頁, `2`: 來店禮)。
+- `t070v04`: 廣告 URL。
+- `t070v05`: 播放順位 (Sort Order)。
+
+---
+
+### 3.3 B009: 貨道庫存即時回報 (Supplementary Report)
+當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
+
+#### B009 權限驗證邏輯 (RBAC Compliance)
+系統會依據 `account` 欄位進行三層式權限核查：
+1. **系統層 (System Admin)**：當 `company_id` 為 `null` 時，具備全局管理權限，直接放行。
+2. **公司層 (Company Admin)**：當 `is_admin` 為 `true` 時，檢查機台的 `company_id` 是否與該帳號一致。
+3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 `machine_user` 授權表，確認該帳號有被分配至此機台。
+
+- **URL**: `PUT /api/v1/app/products/supplementary/B009`
+- **Request Body:**
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| `account` | String | 是 | 操作人員帳號 | `0999123456` |
+| `data` | Array | 是 | 貨道數據陣列 | `[{"tid":"1", "t060v00":"1", "num":"10"}]` |
+
+- **data 陣列內部欄位：**
+- `tid`: 貨道編號 (Slot No)
+- `t060v00`: **商品資料庫 ID**
+- `num`: 實體剩餘庫存數量
+
+- **Response Body (Success 200):**
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| `success` | Boolean | 同步是否成功 | `true` |
+| `code` | Integer | 內部業務狀態碼 | `200` |
+| `message` | String | 回應訊息 | `Slot report synchronized success` |
+| `status` | String | 固定回傳 `49` 代表同步完成 | `49` |
+
+- **Response Body (Forbidden 403):**
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| `success` | Boolean | 同步失敗 | `false` |
+| `status` | String | 回傳空字串 `""` 防止觸發指令 | `""` |
+| `code` | Integer | HTTP 狀態碼 | `403` |
+| `message` | String | 錯誤訊息 | `Unauthorized` |
+
+---
+
+### 3.4 B010: 心跳上報與狀態同步
 用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
 
 - **URL**: `POST /api/v1/app/machine/status/B010`
@@ -85,60 +146,3 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 - `71`: lock (鎖定)
 - `85`: reload B0552 (遠端出貨)
 - `待定義`: change (遠端找零 - 註：指令中心有此功能，但目前 Java App 尚無對接對應的連動事件)
-
----
-
-### 3.3 B017: 貨道與庫存同步
-- **URL**: `POST /api/v1/app/machine/reload_msg/B017`
-- **說明**：當機台收到 B010 回應 `status: 49` 時，呼叫此此 API 獲取雲端最新的貨道佈局與庫存設定。
-
----
-
-### 3.4 B005: 廣告清單同步
-用於機台端獲取目前應播放的廣告檔案 URL 清單。
-
-- **URL**: `POST /api/v1/app/machine/ad/B005`
-- **Request Body:** (無須額外 Body 參數，僅需傳送空 JSON `{}`)
-
-- **Response Body:**
-| 參數 | 類型 | 說明 | 範例 |
-| :--- | :--- | :--- | :--- |
-| `success` | Boolean | 請求是否成功 | `true` |
-| `data` | Array | 廣告物件陣列 | `[{"t070v04": "https://..."}]` |
-
-**data 陣列內部欄位：**
-- `t070v01`: 廣告名稱 (Name)
-- `t070v02`: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
-- `t070v03`: 廣告位置 (Position/Flag) — (`3`: 待機廣告, `1`: 販賣頁, `2`: 來店禮)。
-- `t070v04`: 廣告 URL。
-- `t070v05`: 播放順位 (Sort Order)。
-
----
-
-### 3.5 B009: 貨道庫存即時回報 (Supplementary Report)
-當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
-
-- **URL**: `PUT /api/v1/app/products/supplementary/B009`
-- **Request Body:**
-| 參數 | 類型 | 必填 | 說明 | 範例 |
-| :--- | :--- | :--- | :--- | :--- |
-| `account` | String | 是 | 操作人員帳號 | `technician_01` |
-| `vmcType` | String | 否 | VMC 韌體/機型類別 | `XinYuan` |
-| `data` | Array | 貨道數據陣列 | `[{"tid":"1", "t060v00":"SKU001", "num":"10"}]` |
-
-- **data 陣列內部欄位：**
-- `tid`: 貨道編號 (Slot No)
-- `t060v00`: 商品編碼 (SKU / Product Code)
-- `num`: 實體剩餘庫存數量
-
-- **Response Body:**
-| 參數 | 類型 | 說明 | 範例 |
-| :--- | :--- | :--- | :--- |
-| `success` | Boolean | 同步是否成功 | `true` |
-| `status` | String | 固定回傳 `49` 代表已處理 | `49` |
-
----
-
-### 3.6 B600: 交易數據回傳 (規劃中)
-- **URL**: `POST /api/v1/app/B600`
-- 說明：交易完成後提交支付方式、金額、商品與出貨結果。