[FEAT] 實作 B012 商品同步 API 與統一圖片絕對網址格式

1. 實作 B012 API：新增 /api/v1/app/machine/products/B012 端點，支援 GET (全量) 與 PATCH (增量) 同步邏輯。
2. 統一圖片 URL：在 B005 與 B012 API 中使用 asset() 確保回傳絕對網址 (Absolute URL)，解決 App 端下載相對路徑的問題。
3. 文件更新：同步更新 SKILL.md 的欄位定義，並在 api-docs.php 補上 B012 的正式規格說明。
4. 資料庫變更：新增 machine_slots 表的 type 欄位與相關註解遷移。
5. 格式優化：為技術規格文件中的 API 欄位與狀態碼加上反引號，提升文件中心可讀性。

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

@@ -8,12 +8,12 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。
 
 ## 1. 核心命名原則
-- **語意化優先**：捨棄舊版 `M_` 前綴，統一使用 snake_case (如 `firmware_version`)。
+- **語意化優先**：捨棄舊版 M_ 前綴，統一使用 snake_case (如 firmware_version)。
 - **類型嚴格**：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。
 
 ## 2. 身份認證 (Authentication)
-- **Bearer Token**：所有 API 必須在 Header 帶入 `Authorization: Bearer <api_token>`。
-- **身分綁定**：後端透過 Token 自動識別 `machine_id`，禁止在 Body 帶入 `machine` 或 `key` 欄位。
+- **Bearer Token**：所有 API 必須在 Header 帶入 Authorization: Bearer <api_token>。
+- **身分綁定**：後端透過 Token 自動識別 machine_id，禁止在 Body 帶入 machine 或 key 欄位。
 
 ---
 
@@ -22,44 +22,44 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 ### 3.1 B000: 機台本地管理員同步登入
 用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。
 
-- **URL**: `POST /api/v1/app/admin/login/B000`
+- **URL**: POST /api/v1/app/admin/login/B000
 - **Request Body:**
 | 參數 | 類型 | 必填 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- | :--- |
-| `machine` | String | 是 | 機台編號 (serial_no) | `M-001` |
-| `Su_Account` | String | 是 | 系統管理員或公司管理員帳號 | `admin` |
-| `Su_Password` | String | 是 | 密碼 | `password123` |
-| `ip` | String | 否 | 用戶端 IP (相容舊版) | `192.168.1.100` |
-| `type` | String | 否 | 裝置類型代碼 (相容舊版) | `2` |
+| machine | String | 是 | 機台編號 (serial_no) | M-001 |
+| Su_Account | String | 是 | 系統管理員或公司管理員帳號 | admin |
+| Su_Password | String | 是 | 密碼 | password123 |
+| ip | String | 否 | 用戶端 IP (相容舊版) | 192.168.1.100 |
+| type | String | 否 | 裝置類型代碼 (相容舊版) | 2 |
 
 - **Response Body:**
 > [!IMPORTANT]
-> 為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 `Success`。
+> 為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 Success。
 | 參數 | 類型 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- |
-| `message` | String | 驗證結果 (`Success` 或 `Failed`) | `Success` |
+| message | String | 驗證結果 (Success 或 Failed) | Success |
 
 ---
 
 ### 3.2 B005: 廣告清單同步
 用於機台端獲取目前應播放的廣告檔案 URL 清單。
 
-- **URL**: `GET /api/v1/app/machine/ad/B005`
+- **URL**: GET /api/v1/app/machine/ad/B005
 - **Request Body:** 無 (GET 請求)
 
 - **Response Body:**
 | 參數 | 類型 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- |
-| `success` | Boolean | 請求是否成功 | `true` |
-| `code` | Integer | 內部業務狀態碼 | `200` |
-| `data` | Array | 廣告物件陣列 | `[{"t070v04": "https://..."}]` |
+| 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)。
+- t070v01: 廣告名稱 (Name)
+- t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
+- t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
+- t070v04: 廣告 URL。
+- t070v05: 播放順位 (Sort Order)。
 
 ---
 
@@ -67,82 +67,111 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
 
 #### B009 權限驗證邏輯 (RBAC Compliance)
-系統會依據 `account` 欄位進行三層式權限核查：
-1. **系統層 (System Admin)**：當 `company_id` 為 `null` 時，具備全局管理權限，直接放行。
-2. **公司層 (Company Admin)**：當 `is_admin` 為 `true` 時，檢查機台的 `company_id` 是否與該帳號一致。
-3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 `machine_user` 授權表，確認該帳號有被分配至此機台。
+系統會依據 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`
+- **URL**: PUT /api/v1/app/products/supplementary/B009
 - **Request Body:**
 | 參數 | 類型 | 必填 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- | :--- |
-| `account` | String | 是 | 操作人員帳號 | `0999123456` |
-| `data` | Array | 是 | 貨道數據陣列 | `[{"tid":"1", "t060v00":"1", "num":"10"}]` |
+| account | String | 是 | 操作人員帳號 | 0999123456 |
+| data | Array | 是 | 貨道數據陣列 | [{"tid":"1", "t060v00":"1", "num":"10"}] |
 
 - **data 陣列內部欄位：**
-- `tid`: 貨道編號 (Slot No)
-- `t060v00`: **商品資料庫 ID**
-- `num`: 實體剩餘庫存數量
+| 欄位 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| tid | Integer | 貨道編號 (Slot No) | 1 |
+| t060v00 | String | 商品資料庫 ID (或是 Barcode) | "1" |
+| num | Integer | 實體剩餘庫存數量 | 10 |
+| type | Integer | 貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。 | 1 |
+
+> [!TIP]
+> **自動化上限同步邏輯**：
+> 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。
 
 - **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` |
+| success | Boolean | 同步是否成功 | true |
+| code | Integer | 內部業務狀態碼 | 200 |
+| message | String | 回應訊息 | Slot report synchronized success |
+| status | String | 固定回傳 49 代表同步完成 | "49" |
 
 ---
 
 ### 3.4 B010: 心跳上報與狀態同步
 用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
 
-- **URL**: `POST /api/v1/app/machine/status/B010`
+- **URL**: POST /api/v1/app/machine/status/B010
+- **Authentication**: Bearer Token (Header)
 - **Request Body:**
 | 參數 | 類型 | 必填 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- | :--- |
-| `current_page` | Integer | 是 | 當前頁面代碼 (見下表) | `1` |
-| `firmware_version` | String | 是 | 韌體版本號 | `1.0.5` |
-| `model` | String | 是 | 機台型號 | `STAR-V1` |
-| `temperature` | Float | 否 | 環境溫度 | `25.5` |
-| `door_status` | Integer | 否 | 門狀態 (0:關 / 1:開) | `0` |
-| `log` | String | 否 | 事件日誌簡述 | `Door opened` |
-| `log_level` | String | 否 | info, warn, error | `info` |
-| `log_payload` | Object | 否 | 額外日誌 JSON 對象 | `{"code":500}` |
+| current_page | Integer | 是 | 當前頁面代碼 (見下表) | 1 |
+| firmware_version | String | 是 | 韌體版本號 | 1.0.5 |
+| model | String | 是 | 機台型號 | STAR-V1 |
+| temperature | Float | 否 | 環境溫度 | 25.5 |
+| door_status | Integer | 否 | 門狀態 (0:關 / 1:開) | 0 |
+| log | String | 否 | 事件日誌簡述 | Door opened |
+| log_level | String | 否 | info, warn, error | info |
+| log_payload | Object | 否 | 額外日誌 JSON 對象 | {"code":500} |
 
 - **Response Body:**
 | 參數 | 類型 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- |
-| `success` | Boolean | 請求是否處理成功 | `true` |
-| `code` | Integer | 內部業務狀態碼 | `200` |
-| `message` | String | 回應訊息 | `OK` |
-| `status` | String | **雲端指令代碼** (見下表) | `49` |
+| success | Boolean | 請求是否處理成功 | true |
+| code | Integer | 內部業務狀態碼 | 200 |
+| message | String | 回應訊息 | OK |
+| status | String | **雲端指令代碼** (見下表) | 49 |
 
 #### B010 代碼對照表
 
 **頁面代碼 (current_page)：**
-- `0`: 離線 / `1`: 主頁面 / `2`: 販賣頁 / `3`: 管理頁
-- `4`: 補貨頁 / `5`: 教學頁 / `6`: 購買中 / `7`: 鎖定頁
-- `60`: 出貨成功 / `61`: 貨道測試 / `62`: 付款選擇
-- `63`: 等待付款 / `64`: 出貨 / `65`: 收據簽單
-- `66`: 通行碼 / `67`: 取貨碼 / `68`: 訊息顯示
-- `69`: 取消購買 / `610`: 購買結束 / `611`: 來店禮
-- `612`: 出貨失敗
+- 0: 離線 / 1: 主頁面 / 2: 販賣頁 / 3: 管理頁
+- 4: 補貨頁 / 5: 教學頁 / 6: 購買中 / 7: 鎖定頁
+- 60: 出貨成功 / 61: 貨道測試 / 62: 付款選擇
+- 63: 等待付款 / 64: 出貨 / 65: 收據簽單
+- 66: 通行碼 / 67: 取貨碼 / 68: 訊息顯示
+- 69: 取消購買 / 610: 購買結束 / 611: 來店禮
+- 612: 出貨失敗
 
 **雲端指令代碼 (status)：**
-- `49`: reload B017 (貨道同步)
-- `51`: reboot (重啟系統)
-- `60`: reboot card machine (刷卡機重啟)
-- `61`: checkout (觸發結帳)
-- `70`: unlock (解鎖)
-- `71`: lock (鎖定)
-- `85`: reload B0552 (遠端出貨)
-- `待定義`: change (遠端找零 - 註：指令中心有此功能，但目前 Java App 尚無對接對應的連動事件)
+- 49: reload B017 (貨道同步)
+- 51: reboot (重啟系統)
+- 60: reboot card machine (刷卡機重啟)
+- 61: checkout (觸發結帳)
+- 70: unlock (解鎖)
+- 71: lock (鎖定)
+- 85: reload B0552 (遠端出貨)
+
+---
+
+### 3.5 B012: 商品配置與商品主檔同步 (Unified Sync)
+用於機台端獲取目前所有可販售商品的詳細配置。App 端應依據呼叫的方法決定數據處理方式。
+
+- **URL**: GET|PATCH /api/v1/app/machine/products/B012
+- **Authentication**: Bearer Token (Header)
+- **Request Body:** 無 (由 Token 自動識別機台)
+
+#### 運作邏輯 (Client-side Logic):
+- **GET**：執行 **全量同步**。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
+- **PATCH**：執行 **增量更新**。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。
+
+| 欄位 | 型別 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| t060v00 | String | 商品資料庫 ID | "1" |
+| t060v01 | String | 商品名稱 | 可口可樂 330ml |
+| t060v01_en | String | 英文名稱 | Coca Cola |
+| t060v01_jp | String | 日文名稱 | コカコーラ |
+| t060v03 | String | 商品規格/簡述 | Cold Drink |
+| t060v06 | String | 圖片 URL | https://.../coke.png |
+| t060v09 | Float | 標準零售價 | 25.0 |
+| t060v11 | Integer | **貨道庫存上限** (預設履帶) | 10 |
+| t060v30 | Float | 會員價 | 20.0 |
+| t063v03 | Float | 本機銷售價格 (同定價) | 25.0 |
+| t060v40 | String | 行銷計畫 (Marketing Plan) | Buy 1 Get 1 |
+| t060v41 | String | 物料編碼 (Material Code) | SKU-001 |
+| spring_limit | Integer | **彈簧貨道上限** (建議使用此欄位) | 10 |
+| track_limit | Integer | **履帶貨道上限** (建議使用此欄位) | 15 |