[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>`。
+- **Bearer Token**：所有 API 必須在 Header 帶入 Authorization: Bearer <api_token>。
-- **身分綁定**：後端透過 Token 自動識別 `machine_id`，禁止在 Body 帶入 `machine` 或 `key` 欄位。
+- **身分綁定**：後端透過 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` |
+| machine | String | 是 | 機台編號 (serial_no) | M-001 |
-| `Su_Account` | String | 是 | 系統管理員或公司管理員帳號 | `admin` |
+| Su_Account | String | 是 | 系統管理員或公司管理員帳號 | admin |
-| `Su_Password` | String | 是 | 密碼 | `password123` |
+| Su_Password | String | 是 | 密碼 | password123 |
-| `ip` | String | 否 | 用戶端 IP (相容舊版) | `192.168.1.100` |
+| ip | String | 否 | 用戶端 IP (相容舊版) | 192.168.1.100 |
-| `type` | String | 否 | 裝置類型代碼 (相容舊版) | `2` |
+| 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` |
+| success | Boolean | 請求是否成功 | true |
-| `code` | Integer | 內部業務狀態碼 | `200` |
+| code | Integer | 內部業務狀態碼 | 200 |
-| `data` | Array | 廣告物件陣列 | `[{"t070v04": "https://..."}]` |
+| data | Array | 廣告物件陣列 | [{"t070v04": "https://..."}] |
 
 **data 陣列內部欄位：**
-- `t070v01`: 廣告名稱 (Name)
+- t070v01: 廣告名稱 (Name)
-- `t070v02`: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
+- t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
-- `t070v03`: 廣告位置 (Position/Flag) — (`3`: 待機廣告, `1`: 販賣頁, `2`: 來店禮)。
+- t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
-- `t070v04`: 廣告 URL。
+- t070v04: 廣告 URL。
-- `t070v05`: 播放順位 (Sort Order)。
+- t070v05: 播放順位 (Sort Order)。
 
 ---
 
@@ -67,82 +67,111 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
 
 #### B009 權限驗證邏輯 (RBAC Compliance)
-系統會依據 `account` 欄位進行三層式權限核查：
+系統會依據 account 欄位進行三層式權限核查：
-1. **系統層 (System Admin)**：當 `company_id` 為 `null` 時，具備全局管理權限，直接放行。
+1. **系統層 (System Admin)**：當 company_id 為 null 時，具備全局管理權限，直接放行。
-2. **公司層 (Company Admin)**：當 `is_admin` 為 `true` 時，檢查機台的 `company_id` 是否與該帳號一致。
+2. **公司層 (Company Admin)**：當 is_admin 為 true 時，檢查機台的 company_id 是否與該帳號一致。
-3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 `machine_user` 授權表，確認該帳號有被分配至此機台。
+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` |
+| account | String | 是 | 操作人員帳號 | 0999123456 |
-| `data` | Array | 是 | 貨道數據陣列 | `[{"tid":"1", "t060v00":"1", "num":"10"}]` |
+| 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` |
+| success | Boolean | 同步是否成功 | true |
-| `code` | Integer | 內部業務狀態碼 | `200` |
+| code | Integer | 內部業務狀態碼 | 200 |
-| `message` | String | 回應訊息 | `Slot report synchronized success` |
+| message | String | 回應訊息 | Slot report synchronized success |
-| `status` | String | 固定回傳 `49` 代表同步完成 | `49` |
+| 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`
+- **URL**: POST /api/v1/app/machine/status/B010
+- **Authentication**: Bearer Token (Header)
 - **Request Body:**
 | 參數 | 類型 | 必填 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- | :--- |
-| `current_page` | Integer | 是 | 當前頁面代碼 (見下表) | `1` |
+| current_page | Integer | 是 | 當前頁面代碼 (見下表) | 1 |
-| `firmware_version` | String | 是 | 韌體版本號 | `1.0.5` |
+| firmware_version | String | 是 | 韌體版本號 | 1.0.5 |
-| `model` | String | 是 | 機台型號 | `STAR-V1` |
+| model | String | 是 | 機台型號 | STAR-V1 |
-| `temperature` | Float | 否 | 環境溫度 | `25.5` |
+| temperature | Float | 否 | 環境溫度 | 25.5 |
-| `door_status` | Integer | 否 | 門狀態 (0:關 / 1:開) | `0` |
+| door_status | Integer | 否 | 門狀態 (0:關 / 1:開) | 0 |
-| `log` | String | 否 | 事件日誌簡述 | `Door opened` |
+| log | String | 否 | 事件日誌簡述 | Door opened |
-| `log_level` | String | 否 | info, warn, error | `info` |
+| log_level | String | 否 | info, warn, error | info |
-| `log_payload` | Object | 否 | 額外日誌 JSON 對象 | `{"code":500}` |
+| log_payload | Object | 否 | 額外日誌 JSON 對象 | {"code":500} |
 
 - **Response Body:**
 | 參數 | 類型 | 說明 | 範例 |
 | :--- | :--- | :--- | :--- |
-| `success` | Boolean | 請求是否處理成功 | `true` |
+| success | Boolean | 請求是否處理成功 | true |
-| `code` | Integer | 內部業務狀態碼 | `200` |
+| code | Integer | 內部業務狀態碼 | 200 |
-| `message` | String | 回應訊息 | `OK` |
+| message | String | 回應訊息 | OK |
-| `status` | String | **雲端指令代碼** (見下表) | `49` |
+| status | String | **雲端指令代碼** (見下表) | 49 |
 
 #### B010 代碼對照表
 
 **頁面代碼 (current_page)：**
-- `0`: 離線 / `1`: 主頁面 / `2`: 販賣頁 / `3`: 管理頁
+- 0: 離線 / 1: 主頁面 / 2: 販賣頁 / 3: 管理頁
-- `4`: 補貨頁 / `5`: 教學頁 / `6`: 購買中 / `7`: 鎖定頁
+- 4: 補貨頁 / 5: 教學頁 / 6: 購買中 / 7: 鎖定頁
-- `60`: 出貨成功 / `61`: 貨道測試 / `62`: 付款選擇
+- 60: 出貨成功 / 61: 貨道測試 / 62: 付款選擇
-- `63`: 等待付款 / `64`: 出貨 / `65`: 收據簽單
+- 63: 等待付款 / 64: 出貨 / 65: 收據簽單
-- `66`: 通行碼 / `67`: 取貨碼 / `68`: 訊息顯示
+- 66: 通行碼 / 67: 取貨碼 / 68: 訊息顯示
-- `69`: 取消購買 / `610`: 購買結束 / `611`: 來店禮
+- 69: 取消購買 / 610: 購買結束 / 611: 來店禮
-- `612`: 出貨失敗
+- 612: 出貨失敗
 
 **雲端指令代碼 (status)：**
-- `49`: reload B017 (貨道同步)
+- 49: reload B017 (貨道同步)
-- `51`: reboot (重啟系統)
+- 51: reboot (重啟系統)
-- `60`: reboot card machine (刷卡機重啟)
+- 60: reboot card machine (刷卡機重啟)
-- `61`: checkout (觸發結帳)
+- 61: checkout (觸發結帳)
-- `70`: unlock (解鎖)
+- 70: unlock (解鎖)
-- `71`: lock (鎖定)
+- 71: lock (鎖定)
-- `85`: reload B0552 (遠端出貨)
+- 85: reload B0552 (遠端出貨)
-- `待定義`: change (遠端找零 - 註：指令中心有此功能，但目前 Java App 尚無對接對應的連動事件)
+
+---
+
+### 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 |

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

@@ -234,7 +234,7 @@ class MachineController extends Controller
                     't070v01' => $ma->advertisement->name,
                     't070v02' => (string) ($ma->advertisement->duration ?? 15), // 秒數改放這裡
                     't070v03' => (string) ($posIdMap[$ma->position] ?? '1'),    // 位置數字改放這裡 (App 會讀這欄當 Flag)
-                    't070v04' => $ma->advertisement->url,
+                    't070v04' => $ma->advertisement->url ? (str_starts_with($ma->advertisement->url, 'http') ? $ma->advertisement->url : asset($ma->advertisement->url)) : '',
                     't070v05' => (string) $ma->sort_order,
                     'raw_pos_weight' => $posWeight[$ma->position] ?? 99,
                     'raw_sort' => (int) $ma->sort_order
@@ -314,6 +314,7 @@ class MachineController extends Controller
                 'slot_no' => $item['tid'] ?? null,
                 'product_id' => $item['t060v00'] ?? null,
                 'stock' => $item['num'] ?? 0,
+                'type' => $item['type'] ?? null,
             ];
         }, $legacyData);
 
@@ -330,4 +331,45 @@ class MachineController extends Controller
             'status' => '49'
         ]);
     }
+
+    /**
+     * B012_new: Download Product Catalog (Synchronous)
+     */
+    public function getProducts(Request $request)
+    {
+        $machine = $request->get('machine');
+
+        $products = \App\Models\Product\Product::where('company_id', $machine->company_id)
+            ->with(['translations'])
+            ->active()
+            ->get()
+            ->map(function ($product) {
+                // 提取多語系名稱 (Extract translations)
+                $nameEn = $product->translations->firstWhere('locale', 'en')?->value ?? '';
+                $nameJp = $product->translations->firstWhere('locale', 'ja')?->value ?? '';
+
+                return [
+                    't060v00' => (string) $product->id, // ID 仍建議維持字串，增加未來編號彈性
+                    't060v01' => $product->name,
+                    't060v01_en' => $nameEn,
+                    't060v01_jp' => $nameJp,
+                    't060v03' => $product->spec ?? '',
+                    't060v06' => $product->image_url ? (str_starts_with($product->image_url, 'http') ? $product->image_url : asset($product->image_url)) : '',
+                    't060v09' => (float) $product->price,
+                    't060v11' => (int) ($product->track_limit ?? 10),
+                    't060v30' => (float) ($product->member_price ?? $product->price),
+                    't060v40' => $product->metadata['marketing_plan'] ?? '', // 行銷計畫
+                    't060v41' => $product->metadata['material_code'] ?? $product->barcode ?? '', // 物料編碼 (優先從 metadata 找，回退至條碼)
+                    'spring_limit' => (int) ($product->spring_limit ?? 10),
+                    'track_limit' => (int) ($product->track_limit ?? 10),
+                    't063v03' => (float) $product->price,
+                ];
+            });
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => $products
+        ]);
+    }
 }

app/Models/Machine/MachineSlot.php

@@ -14,6 +14,7 @@ class MachineSlot extends Model
         'machine_id',
         'product_id',
         'slot_no',
+        'type',
         'max_stock',
         'stock',
         'expiry_date',

app/Models/Product/Product.php

@@ -10,6 +10,14 @@ use App\Traits\TenantScoped;
 class Product extends Model
 {
     use HasFactory, SoftDeletes, TenantScoped;
+    
+    /**
+     * Scope a query to only include active products.
+     */
+    public function scopeActive($query)
+    {
+        return $query->where('is_active', true);
+    }
 
     protected $fillable = [
         'company_id',

app/Services/Machine/MachineService.php

@@ -87,8 +87,21 @@ class MachineService
                     })?->id;
                 }
 
+                // 根據貨道類型自動決定上限 (Auto-calculate max_stock based on slot type)
+                // 若未提供 type，預設為 '1' (履帶/Track)
+                $slotType = $slotData['type'] ?? $existingSlot->type ?? '1';
+                if ($actualProductId) {
+                    $product = $products->find($actualProductId);
+                    if ($product) {
+                        // 1: 履帶, 2: 彈簧
+                        $calculatedMaxStock = ($slotType == '1') ? $product->track_limit : $product->spring_limit;
+                        $slotData['capacity'] = $calculatedMaxStock ?? $slotData['capacity'] ?? null;
+                    }
+                }
+
                 $updateData = [
                     'product_id' => $actualProductId,
+                    'type' => $slotType,
                     'stock' => $slotData['stock'] ?? 0,
                     'max_stock' => $slotData['capacity'] ?? ($existingSlot->max_stock ?? 10),
                     'is_active' => true,

config/api-docs.php

@@ -231,6 +231,77 @@ return [
                         'status' => '49'
                     ],
                     'notes' => '機台收到 B010 回應中的特定 `status` 代碼後，應根據對照表執行對應的指令動作或 API 呼叫 (如 B017)。若為空則代表無指令。'
+                ],
+                [
+                    'name' => 'B012: 商品配置與商品主檔同步 (Unified Sync)',
+                    'slug' => 'b012-unified-sync',
+                    'method' => 'GET/PATCH',
+                    'path' => '/api/v1/app/machine/products/B012',
+                    'description' => '用於機台端獲取目前所有可販售商品的詳細配置。GET 為全量同步，PATCH 為增量更新。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '請求是否處理成功',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'description' => '商品明細物件陣列',
+                            'example' => [
+                                [
+                                    't060v00' => '1',
+                                    't060v01' => '可口可樂 330ml',
+                                    't060v01_en' => 'Coca Cola',
+                                    't060v01_jp' => 'コカコーラ',
+                                    't060v03' => 'Cold Drink',
+                                    't060v06' => 'https://.../coke.png',
+                                    't060v09' => 25.0,
+                                    't060v11' => 10,
+                                    't060v30' => 20.0,
+                                    't063v03' => 25.0,
+                                    't060v40' => 'Buy 1 Get 1',
+                                    't060v41' => 'SKU-001',
+                                    'spring_limit' => 10,
+                                    'track_limit' => 15
+                                ]
+                            ]
+                        ]
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'OK',
+                        'data' => [
+                            [
+                                't060v00' => '1',
+                                't060v01' => '可口可樂 330ml',
+                                't060v01_en' => 'Coca Cola',
+                                't060v01_jp' => 'コカコーラ',
+                                't060v03' => 'Cold Drink',
+                                't060v06' => 'https://.../coke.png',
+                                't060v09' => 25.0,
+                                't060v11' => 10,
+                                't060v30' => 20.0,
+                                't063v03' => 25.0,
+                                't060v40' => 'Buy 1 Get 1',
+                                't060v41' => 'SKU-001',
+                                'spring_limit' => 10,
+                                'track_limit' => 15
+                            ]
+                        ]
+                    ],
+                    'notes' => '運作邏輯 (Client-side Logic): GET 執行全量同步，App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll()。PATCH 執行增量更新，App 僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。'
                 ]
             ]
         ]

database/migrations/2026_04_07_000001_add_type_to_machine_slots.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('machine_slots', function (Blueprint $group) {
+            $group->string('type')->nullable()->after('slot_no')->comment('1: spring, 2: track');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('machine_slots', function (Blueprint $group) {
+            $group->dropColumn('type');
+        });
+    }
+};

database/migrations/2026_04_07_000002_update_type_comment_in_machine_slots.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('machine_slots', function (Blueprint $group) {
+            $group->string('type')->nullable()->comment('1: track, 2: spring')->change();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('machine_slots', function (Blueprint $group) {
+            $group->string('type')->nullable()->comment('1: spring, 2: track')->change();
+        });
+    }
+};

routes/api.php

@@ -61,9 +61,12 @@ Route::prefix('v1')->middleware(['throttle:api'])->group(function () {
         Route::post('machine/coins/B220', [App\Http\Controllers\Api\V1\App\MachineController::class, 'syncCoinInventory']);
         Route::post('machine/member/verify/B650', [App\Http\Controllers\Api\V1\App\MachineController::class, 'verifyMember']);
 
-        // 廣告與貨道清單 (B005, B009)
+        // 廣告與貨道清單 (B005, B009, B012)
         Route::get('machine/ad/B005', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getAdvertisements']);
         Route::put('products/supplementary/B009', [App\Http\Controllers\Api\V1\App\MachineController::class, 'reportSlotList']);
+        
+        // 統一商品主檔 API (B012 整合版)
+        Route::match(['get', 'patch'], 'machine/products/B012', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getProducts']);
 
         // 交易、發票與出貨 (B600, B601, B602)
         Route::post('machine/restock/B018', [App\Http\Controllers\Api\V1\App\MachineController::class, 'recordRestock']);