[FIX] 修正與標準化 B005 廣告下載 API 以相容既有 Android App

1. 修改 MachineController@getAdvertisements 回傳欄位，將 t070v02 改為播放秒數，t070v03 改為位置代碼 (Flag)。
2. 根據 Android App 原始碼分析結果，調整位置對應：3 為待機廣告 (HomeActivity)，1 為販賣頁廣告 (FontendActivity)。
3. 在 AdvertisementController@getMachineAds 增加 sort_order 排序，確保後台管理介面視圖與 API 輸出順序一致。
4. 更新廣告下載 API 的技術文件 (SKILL.md)，明確標記欄位用途與位置代碼。
5. 在 routes/api.php 補上 B005 與 B009 的路由定義。

app/Http/Controllers/Admin/AdvertisementController.php

@@ -179,6 +179,7 @@ class AdvertisementController extends AdminController
     {
         $assignments = MachineAdvertisement::where('machine_id', $machine->id)
             ->with('advertisement')
+            ->orderBy('sort_order', 'asc')
             ->get()
             ->groupBy('position');
 

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

@@ -194,4 +194,95 @@ class MachineController extends Controller
             ]
         ]);
     }
+
+    /**
+     * B005: Download Machine Advertisements (Synchronous)
+     */
+    public function getAdvertisements(Request $request)
+    {
+        $machine = $request->get('machine');
+
+        $advertisements = \App\Models\Machine\MachineAdvertisement::where('machine_id', $machine->id)
+            ->with(['advertisement' => function ($query) {
+                $query->active();
+            }])
+            ->get()
+            ->filter(fn($ma) => $ma->advertisement !== null)
+            ->map(function ($ma) {
+                // 定義顯示順序權重 (待機 > 購物 > 成功禮)
+                $posWeight = [
+                    'standby' => 1,
+                    'vending' => 2,
+                    'visit_gift' => 3
+                ];
+
+                // 為了相容現有機台 App 邏輯：
+                // App 讀取 t070v03 作為位置標籤 (flag)：
+                // 1. HomeActivity (待機) 讀取 "3"
+                // 2. FontendActivity (販賣頁) 讀取 "1"
+                $posIdMap = [
+                    'standby' => '3',
+                    'vending' => '1',
+                    'visit_gift' => '2'
+                ];
+
+                return [
+                    't070v01' => $ma->advertisement->name,
+                    't070v02' => (string) ($ma->advertisement->duration ?? 15), // 秒數改放這裡
+                    't070v03' => (string) ($posIdMap[$ma->position] ?? '1'),    // 位置數字改放這裡 (App 會讀這欄當 Flag)
+                    't070v04' => $ma->advertisement->url,
+                    't070v05' => (string) $ma->sort_order,
+                    'raw_pos_weight' => $posWeight[$ma->position] ?? 99, 
+                    'raw_sort' => (int) $ma->sort_order
+                ];
+            })
+            ->sortBy([
+                ['raw_pos_weight', 'asc'],
+                ['raw_sort', 'asc']
+            ])
+            ->values()
+            ->map(function($item) {
+                unset($item['raw_pos_weight'], $item['raw_sort']);
+                return $item;
+            });
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => $advertisements->values()
+        ]);
+    }
+
+    /**
+     * B009: Report Machine Slot List / Supplementary (Synchronous)
+     */
+    public function reportSlotList(Request $request, \App\Services\Machine\MachineService $machineService)
+    {
+        $machine = $request->get('machine');
+        $payload = $request->all();
+
+        // 映射舊版機台回傳格式 (Map legacy machine format)
+        // t060v00 -> product_id, num -> stock, tid -> slot_no
+        $legacyData = $payload['data'] ?? [];
+        $mappedSlots = array_map(function ($item) {
+            return [
+                'slot_no' => $item['tid'] ?? null,
+                'product_id' => $item['t060v00'] ?? null,
+                'stock' => $item['num'] ?? 0,
+            ];
+        }, $legacyData);
+
+        // 過濾無效資料 (Filter invalid entries)
+        $mappedSlots = array_filter($mappedSlots, fn($s) => $s['slot_no'] !== null);
+
+        // 同步處理更新庫存 (直接更新不進隊列)
+        $machineService->syncSlots($machine, $mappedSlots);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Slot report synchronized success',
+            'status' => '49'
+        ]);
+    }
 }

app/Services/Machine/MachineService.php

@@ -64,24 +64,36 @@ class MachineService
     public function syncSlots(Machine $machine, array $slotsData): void
     {
         DB::transaction(function () use ($machine, $slotsData) {
+            // 蒐集所有傳入的商品 ID (可能是 SKU 或 實際 ID)
+            $productCodes = collect($slotsData)->pluck('product_id')->filter()->unique()->toArray();
+            
+            // 批次查詢商品 (支援以 SKU 查詢，確保對應至資料庫 ID)
+            $products = \App\Models\Product\Product::whereIn('sku', $productCodes)
+                ->orWhereIn('id', $productCodes)
+                ->get()
+                ->keyBy(fn($p) => $p->sku ?: $p->id);
+
             foreach ($slotsData as $slotData) {
                 $slotNo = $slotData['slot_no'] ?? null;
                 if (!$slotNo) continue;
 
                 $existingSlot = $machine->slots()->where('slot_no', $slotNo)->first();
+                
+                // 查找對應的實體 ID
+                $productCode = $slotData['product_id'] ?? null;
+                $actualProductId = null;
+                if ($productCode) {
+                    $actualProductId = $products->get($productCode)?->id;
+                }
 
                 $updateData = [
-                    'product_id' => $slotData['product_id'] ?? null,
+                    'product_id' => $actualProductId,
                     'stock' => $slotData['stock'] ?? 0,
-                    'capacity' => $slotData['capacity'] ?? ($existingSlot->capacity ?? 10),
-                    'price' => $slotData['price'] ?? ($existingSlot->price ?? 0),
-                    'last_restocked_at' => now(),
+                    'max_stock' => $slotData['capacity'] ?? ($existingSlot->max_stock ?? 10),
+                    'is_active' => true,
                 ];
 
-                // 如果商品變了，或者這是一次明確的補貨回報，清空效期等待管理員更新
-                // 這裡我們暫定只要有 report 進來，就需要重新確認效期
-                $updateData['expiry_date'] = null;
-
+                // 如果這是一次明確的補貨回報，建議更新時間並記錄
                 if ($existingSlot) {
                     $existingSlot->update($updateData);
                 } else {