[FEAT] 優化機台硬體通訊協議與管理介面互動性

1. 修復帳號管理與角色權限頁面搜尋功能，支援 Enter 鍵快捷提交。 2. 完成 B013 (機台故障上報) API 實作，改用非同步隊列 (ProcessMachineError) 處理日誌上報。 3. 精簡 B013 API 參數，移除冗餘的 message 欄位，統一由雲端對照表翻譯。 4. 更新技術規格文件 (SKILL.md) 與系統 API 文件配置 (api-docs.php)。 5. 修正平台管理員帳號在搜尋過濾時的資料隔離邏輯。
2026-04-08 14:52:00 +08:00
parent c343df34ee
commit a599b14df1
21 changed files with 1039 additions and 117 deletions
--- a/app/Http/Controllers/Admin/MachineController.php
+++ b/app/Http/Controllers/Admin/MachineController.php
@@ -71,17 +71,21 @@ class MachineController extends AdminController
     */
    public function logsAjax(Request $request, Machine $machine)
    {
-        $per_page = $request->input('per_page', 10);
+        $per_page = $request->input('per_page', 20);

-        $startDate = $request->get('start_date', now()->format('Y-m-d'));
-        $endDate = $request->get('end_date', now()->format('Y-m-d'));
+        $startDate = $request->get('start_date');
+        $endDate = $request->get('end_date');

        $logs = $machine->logs()
            ->when($request->level, function ($query, $level) {
                return $query->where('level', $level);
            })
-            ->whereDate('created_at', '>=', $startDate)
-            ->whereDate('created_at', '<=', $endDate)
+            ->when($startDate, function ($query, $start) {
+                return $query->where('created_at', '>=', str_replace('T', ' ', $start));
+            })
+            ->when($endDate, function ($query, $end) {
+                return $query->where('created_at', '<=', str_replace('T', ' ', $end));
+            })
            ->when($request->type, function ($query, $type) {
                return $query->where('type', $type);
            })
--- a/app/Http/Controllers/Admin/PermissionController.php
+++ b/app/Http/Controllers/Admin/PermissionController.php
@@ -318,7 +318,11 @@ class PermissionController extends Controller
            }

            if ($user->isSystemAdmin() && $request->filled('company_id')) {
-                $query->where('company_id', $request->company_id);
+                if ($request->company_id === 'system') {
+                    $query->whereNull('company_id');
+                } else {
+                    $query->where('company_id', $request->company_id);
+                }
            }

            $per_page = $request->input('per_page', 10);
--- a/app/Http/Controllers/Api/V1/App/MachineAuthController.php
+++ b/app/Http/Controllers/Api/V1/App/MachineAuthController.php
@@ -9,6 +9,7 @@ use App\Models\System\User;
 use App\Models\Machine\Machine;
 use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Log;
+use App\Jobs\Machine\ProcessStateLog;

 class MachineAuthController extends Controller
 {
@@ -20,30 +21,14 @@ class MachineAuthController extends Controller
    {
        // 1. 驗證欄位 (相容舊版 Java App 發送的 JSON 格式)
        $validated = $request->validate([
-            'machine'     => 'required|string',
-            'Su_Account'  => 'required|string',
+            'machine' => 'required|string',
+            'Su_Account' => 'required|string',
            'Su_Password' => 'required|string',
-            'ip'          => 'nullable|string',
-            'type'        => 'nullable|string',
+            'ip' => 'nullable|string',
+            'type' => 'nullable|string',
        ]);

-        // 2. 透過帳號尋找使用者 (允許使用 username 或 email)
-        $user = User::where('username', $validated['Su_Account'])
-            ->orWhere('email', $validated['Su_Account'])
-            ->first();
-
-        // 若無此帳號或密碼錯誤
-        if (!$user || !Hash::check($validated['Su_Password'], $user->password)) {
-            Log::warning("B000 機台登入失敗: 帳密錯誤", [
-                'account' => $validated['Su_Account'], 
-                'machine' => $validated['machine']
-            ]);
-            // 按現行設定，Java 端只認 Success 字串，其餘視為帳密錯誤
-            return response()->json(['message' => 'Failed']);
-        }
-
-        // 3. 取得機台物件
-        // 因為此 API 無狀態 (沒有登入 session)，為了避免被 global scope 擋住，直接取消所有 scope 來撈取
+        // 2. 取得機台物件 (需優先於帳密驗證，以便記錄日誌到正確機台)
        $machine = Machine::withoutGlobalScopes()->where('serial_no', $validated['machine'])->first();

        if (!$machine) {
@@ -53,38 +38,79 @@ class MachineAuthController extends Controller
            return response()->json(['message' => 'Failed']);
        }

-        // 4. RBAC 權限驗證 (遵循多租戶與機台授權規範)
+        // 3. 透過帳號尋找使用者 (允許使用 username 或 email)
+        $user = User::where('username', $validated['Su_Account'])
+            ->orWhere('email', $validated['Su_Account'])
+            ->first();
+
+        // 4. 驗證密碼
+        if (!$user || !Hash::check($validated['Su_Password'], $user->password)) {
+            Log::warning("B000 機台登入失敗: 帳密錯誤", [
+                'account' => $validated['Su_Account'],
+                'machine' => $validated['machine']
+            ]);
+
+            // 寫入機台日誌
+            ProcessStateLog::dispatch(
+                $machine->id,
+                $machine->company_id,
+                __("Login failed: :account", ['account' => $validated['Su_Account']]),
+                'warning',
+                [],
+                'login'
+            );
+
+            return response()->json(['message' => 'Failed']);
+        }
+
+        // 5. RBAC 權限驗證 (遵循多租戶與機台授權規範)
+        $isAuthorized = false;
        if ($user->isSystemAdmin()) {
-            // [系統管理員] : 擁有最高權限，可登入平台下轄所有機台，直接放行
-            
+            $isAuthorized = true;
        } elseif ($user->is_admin) {
-            // [公司管理員] : 不需要檢查 machine_user 表，但【必須驗證】該機台是否隸屬於他的公司
-            if ($machine->company_id !== $user->company_id) {
-                Log::warning("B000 機台登入失敗: 企圖越權登入其他公司的機台", [
-                    'user_id'         => $user->id,
-                    'user_company'    => $user->company_id,
-                    'machine_company' => $machine->company_id
-                ]);
-                return response()->json(['message' => 'Forbidden']);
+            if ($machine->company_id === $user->company_id) {
+                $isAuthorized = true;
            }
-            
        } else {
-            // [一般租戶帳號] : （包括補貨員等）必須嚴格檢查該帳號有沒有被分配到這台機器的 machine_user 關聯授權
-            if (!$user->machines()->where('machine_id', $machine->id)->exists()) {
-                Log::warning("B000 機台登入失敗: 該帳號沒有此機台的授權", [
-                    'user_id'    => $user->id,
-                    'machine_id' => $machine->id
-                ]);
-                return response()->json(['message' => 'Forbidden']);
+            if ($user->machines()->where('machine_id', $machine->id)->exists()) {
+                $isAuthorized = true;
            }
        }

-        // 5. 驗證完美通過！回傳固定字串 Success 讓 Java 端放行
+        if (!$isAuthorized) {
+            Log::warning("B000 機台登入失敗: 權限不足", [
+                'user_id' => $user->id,
+                'machine_id' => $machine->id
+            ]);
+
+            ProcessStateLog::dispatch(
+                $machine->id,
+                $machine->company_id,
+                __("Unauthorized login attempt: :account", ['account' => $user->username]),
+                'warning',
+                [],
+                'login'
+            );
+
+            return response()->json(['message' => 'Forbidden']);
+        }
+
+        // 6. 驗證完美通過！
        Log::info("B000 機台登入成功", [
-            'account' => $user->username, 
+            'account' => $user->username,
            'machine' => $machine->serial_no
        ]);
-        
+
+        // 寫入成功登入日誌
+        ProcessStateLog::dispatch(
+            $machine->id,
+            $machine->company_id,
+            __("User logged in: :name", ['name' => $user->name ?? $user->username]),
+            'info',
+            [],
+            'login'
+        );
+
        return response()->json([
            'message' => 'Success'
        ]);
--- a/app/Http/Controllers/Api/V1/App/MachineController.php
+++ b/app/Http/Controllers/Api/V1/App/MachineController.php
@@ -9,8 +9,11 @@ use App\Models\System\User;
 use App\Jobs\Machine\ProcessHeartbeat;
 use App\Jobs\Machine\ProcessTimerStatus;
 use App\Jobs\Machine\ProcessCoinInventory;
+use App\Jobs\Machine\ProcessMachineError;
+use App\Jobs\Machine\ProcessStateLog;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Validator;
+use Illuminate\Support\Facades\Cache;

 class MachineController extends Controller
 {
@@ -22,6 +25,69 @@ class MachineController extends Controller
        $machine = $request->get('machine');
        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入的 Model 物件與認證 key

+        // === 狀態異動觸發 (Redis 快取免查 DB) ===
+        $cacheKey = "machine:{$machine->serial_no}:state";
+        $oldState = Cache::get($cacheKey);
+
+        $currentPage = $data['current_page'] ?? null;
+        $doorStatus = $data['door_status'] ?? null;
+        $firmwareVersion = $data['firmware_version'] ?? null;
+        $model = $data['model'] ?? null;
+
+        if ($currentPage !== null || $doorStatus !== null || $firmwareVersion !== null || $model !== null) {
+            // 更新目前狀態到 Redis (保存 1 天)
+            $newState = $oldState ?? [];
+            if ($currentPage !== null) $newState['current_page'] = $currentPage;
+            if ($doorStatus !== null) $newState['door_status'] = $doorStatus;
+            if ($firmwareVersion !== null) $newState['firmware_version'] = $firmwareVersion;
+            if ($model !== null) $newState['model'] = $model;
+
+            Cache::put($cacheKey, $newState, 86400);
+
+            // 若有歷史紀錄才進行比對 (避開 Cache Miss 造成的雪崩)
+            if ($oldState !== null) {
+                // 1. 判斷頁面是否變更
+                if ($currentPage !== null && (string)$currentPage !== (string)($oldState['current_page'] ?? '')) {
+                    // 只記錄「絕對狀態」，配合 lang 中 "Page X" 的翻譯
+                    ProcessStateLog::dispatch($machine->id, $machine->company_id, "Page {$currentPage}", 'info');
+                }
+
+                // 2. 判斷門禁是否變更 (0: 關閉, 1: 開啟)
+                if ($doorStatus !== null && (string)$doorStatus !== (string)($oldState['door_status'] ?? '')) {
+                    $doorMessage = $doorStatus == 1 ? "Door Opened" : "Door Closed";
+                    $doorLevel = 'info'; // 不論開關門皆為 info，避免觸發異常狀態
+                    ProcessStateLog::dispatch($machine->id, $machine->company_id, $doorMessage, $doorLevel);
+                }
+
+                // 3. 判斷韌體版本是否變更
+                if ($firmwareVersion !== null && (string)$firmwareVersion !== (string)($oldState['firmware_version'] ?? '')) {
+                    $oldVersion = $oldState['firmware_version'] ?? 'Unknown';
+                    // 直接在 Controller 進行翻譯並填值，確保儲存到 DB 的是最終正確字串
+                    $versionMessage = __("Firmware updated to :version", ['version' => $firmwareVersion]);
+                    ProcessStateLog::dispatch(
+                        $machine->id, 
+                        $machine->company_id, 
+                        $versionMessage, 
+                        'info',
+                        ['old' => $oldVersion, 'new' => $firmwareVersion]
+                    );
+                }
+
+                // 4. 判斷型號是否變更
+                if ($model !== null && (string)$model !== (string)($oldState['model'] ?? '')) {
+                    $oldModel = $oldState['model'] ?? 'Unknown';
+                    $modelMessage = __("Model changed to :model", ['model' => $model]);
+                    ProcessStateLog::dispatch(
+                        $machine->id, 
+                        $machine->company_id, 
+                        $modelMessage, 
+                        'info',
+                        ['old' => $oldModel, 'new' => $model]
+                    );
+                }
+            }
+        }
+
        // 異步處理狀態更新
        ProcessHeartbeat::dispatch($machine->serial_no, $data);

@@ -372,4 +438,22 @@ class MachineController extends Controller
            'data' => $products
        ]);
    }
+
+    /**
+     * B013: Report Machine Hardware Error/Status (Asynchronous)
+     */
+    public function reportError(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->only(['tid', 'error_code']);
+
+        // 異步分派處理 (Dispatch to queue)
+        ProcessMachineError::dispatch($machine->serial_no, $data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Error report accepted',
+        ], 202); // 202 Accepted
+    }
 }
--- a/app/Jobs/Machine/ProcessMachineError.php
+++ b/app/Jobs/Machine/ProcessMachineError.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\Machine;
+use App\Services\Machine\MachineService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class ProcessMachineError implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $serialNo;
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(string $serialNo, array $data)
+    {
+        $this->serialNo = $serialNo;
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(MachineService $service): void
+    {
+        $machine = Machine::where('serial_no', $this->serialNo)->first();
+
+        if ($machine) {
+            $service->recordErrorLog($machine, $this->data);
+        }
+    }
+}
--- a/app/Jobs/Machine/ProcessStateLog.php
+++ b/app/Jobs/Machine/ProcessStateLog.php
@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\MachineLog;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessStateLog implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $machineId;
+    protected $companyId;
+    protected $message;
+    protected $level;
+    protected $type;
+    protected $context;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(int $machineId, ?int $companyId, string $message, string $level = 'info', array $context = [], string $type = 'status')
+    {
+        $this->machineId = $machineId;
+        $this->companyId = $companyId;
+        $this->message = $message;
+        $this->level = $level;
+        $this->context = $context;
+        $this->type = $type;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        try {
+            MachineLog::create([
+                'machine_id' => $this->machineId,
+                'company_id' => $this->companyId,
+                'type' => $this->type,
+                'level' => $this->level,
+                'message' => $this->message,
+                'context' => $this->context,
+            ]);
+        } catch (\Exception $e) {
+            Log::error("Failed to create state log for machine {$this->machineId}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}
--- a/app/Models/Machine/MachineLog.php
+++ b/app/Models/Machine/MachineLog.php
@@ -24,6 +24,33 @@ class MachineLog extends Model
        'context' => 'array',
    ];

+    protected $appends = [
+        'translated_message',
+    ];
+
+    /**
+     * 動態重組翻譯後的訊息
+     */
+    public function getTranslatedMessageAttribute(): string
+    {
+        $context = $this->context;
+
+        // 若 context 中已有翻譯標籤 (B013 封裝)，則進行動態重組
+        if (isset($context['translated_label'])) {
+            $label = __($context['translated_label']);
+            $tid = $context['tid'] ?? null;
+            $code = $context['raw_code'] ?? '0000';
+
+            if ($tid) {
+                return __('Slot') . " {$tid}: {$label} (Code: {$code})";
+            }
+            return "{$label} (Code: {$code})";
+        }
+
+        // 預設退回原始 message (支援歷史資料的翻譯判定與佔位符替換)
+        return __($this->message, $context ?? []);
+    }
+
    public function machine()
    {
        return $this->belongsTo(Machine::class);
--- a/app/Services/Machine/MachineService.php
+++ b/app/Services/Machine/MachineService.php
@@ -10,6 +10,56 @@ use Carbon\Carbon;

 class MachineService
 {
+    /**
+     * B013: 硬體狀態代碼對照表 (Hardware Status Code Mapping)
+     */
+    public const ERROR_CODE_MAP = [
+        // 出貨狀態類 (Prefix: 04 - BUY_STATUS)
+        '0401' => ['label' => 'Dispensing in progress', 'level' => 'info'],
+        '0402' => ['label' => 'Dispense successful', 'level' => 'info'],
+        '0403' => ['label' => 'Slot jammed', 'level' => 'error'],
+        '0404' => ['label' => 'Motor not stopped', 'level' => 'warning'],
+        '0406' => ['label' => 'Slot not found', 'level' => 'error'],
+        '0407' => ['label' => 'Dispense error (0407)', 'level' => 'error'],
+        '0408' => ['label' => 'Dispense error (0408)', 'level' => 'error'],
+        '0409' => ['label' => 'Dispense error (0409)', 'level' => 'error'],
+        '040A' => ['label' => 'Dispense error (040A)', 'level' => 'error'],
+        '0410' => ['label' => 'Elevator rising', 'level' => 'info'],
+        '0411' => ['label' => 'Elevator descending', 'level' => 'info'],
+        '0412' => ['label' => 'Elevator rise error', 'level' => 'error'],
+        '0413' => ['label' => 'Elevator descent error', 'level' => 'error'],
+        '0414' => ['label' => 'Pickup door closed', 'level' => 'info'],
+        '0415' => ['label' => 'Pickup door error', 'level' => 'error'],
+        '0416' => ['label' => 'Delivery door opened', 'level' => 'info'],
+        '0417' => ['label' => 'Delivery door open error', 'level' => 'error'],
+        '0418' => ['label' => 'Delivering product', 'level' => 'info'],
+        '0419' => ['label' => 'Delivery door closed', 'level' => 'info'],
+        '0420' => ['label' => 'Delivery door close error', 'level' => 'error'],
+        '0421' => ['label' => 'Hopper empty', 'level' => 'warning'],
+        '0422' => ['label' => 'Hopper overheated', 'level' => 'warning'],
+        '0423' => ['label' => 'Hopper heating timeout', 'level' => 'error'],
+        '0424' => ['label' => 'Hopper error (0424)', 'level' => 'error'],
+        '0426' => ['label' => 'Microwave door opened', 'level' => 'info'],
+        '0427' => ['label' => 'Microwave door error', 'level' => 'error'],
+        '04FF' => ['label' => 'Dispense stopped', 'level' => 'info'],
+
+        // 貨道狀態類 (Prefix: 02 - SLOT_STATUS)
+        '0201' => ['label' => 'Slot normal', 'level' => 'info'],
+        '0202' => ['label' => 'Product empty', 'level' => 'warning'],
+        '0203' => ['label' => 'Slot empty', 'level' => 'warning'],
+        '0206' => ['label' => 'Slot not closed', 'level' => 'warning'],
+        '0207' => ['label' => 'Slot motor error (0207)', 'level' => 'error'],
+        '0208' => ['label' => 'Slot motor error (0208)', 'level' => 'error'],
+        '0209' => ['label' => 'Slot motor error (0209)', 'level' => 'error'],
+        '0212' => ['label' => 'Hopper empty (0212)', 'level' => 'warning'],
+
+        // 機台整體狀態類 (Prefix: 54 - MACHINE_STATUS)
+        '5400' => ['label' => 'Machine normal', 'level' => 'info'],
+        '5401' => ['label' => 'Elevator sensor error', 'level' => 'error'],
+        '5402' => ['label' => 'Pickup door not closed', 'level' => 'warning'],
+        '5403' => ['label' => 'Elevator failure', 'level' => 'error'],
+    ];
+
    /**
     * Update machine heartbeat and status.
     * 
@@ -178,6 +228,36 @@ class MachineService
        });
    }

+    /**
+     * B013: Record machine hardware error/status log with auto-translation.
+     * 
+     * @param Machine $machine
+     * @param array $data
+     * @return MachineLog
+     */
+    public function recordErrorLog(Machine $machine, array $data): MachineLog
+    {
+        $errorCode = $data['error_code'] ?? '0000';
+        $mapping = self::ERROR_CODE_MAP[$errorCode] ?? ['label' => 'Unknown Status', 'level' => 'error'];
+        
+        $slotNo = $data['tid'] ?? null;
+        $label = $mapping['label'];
+        
+        // 儲存原始英文格式作為 DB 備用，前端顯示會優先使用 model accessor 的動態翻譯內容
+        $message = $slotNo ? "Slot {$slotNo}: {$label} (Code: {$errorCode})" : "{$label} (Code: {$errorCode})";
+
+        return $machine->logs()->create([
+            'company_id' => $machine->company_id,
+            'type' => 'submachine',
+            'level' => $mapping['level'],
+            'message' => $message,
+            'context' => array_merge($data, [
+                'translated_label' => $label,
+                'raw_code' => $errorCode
+            ]),
+        ]);
+    }
+
    /**
     * Update machine slot stock (single slot).
     * Legacy support for recordLog (Existing code).