From 4348a88697649aee92e912749bd398137c9d3b3f Mon Sep 17 00:00:00 2001 From: sky121113 Date: Wed, 6 May 2026 14:25:40 +0800 Subject: [PATCH] =?UTF-8?q?[DOCS]=20=E8=A6=8F=E7=AF=84=E5=8C=96=20B000=20?= =?UTF-8?q?=E8=AA=8D=E8=AD=89=E6=A9=9F=E5=88=B6=E4=B8=A6=E7=A7=BB=E9=99=A4?= =?UTF-8?q?=E5=86=97=E9=A4=98=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. [DOCS] 更新 B000 登入 API 規格，統一參數名為 Su_Account/Su_Password 並要求帶入機台 API Token。 2. [REFACTOR] 將 B000 路由移入 iot.auth 中間件，強化 API 安全性。 3. [DOCS] 移除廢棄的 B710 (時間同步) API 說明。 4. [DOCS] 調整 B014 認證與安全規範描述，使其符合現行機台引導流程。 --- .agents/skills/api-technical-specs/SKILL.md | 17 +++++--------- .../Api/V1/App/MachineAuthController.php | 17 ++++---------- config/api-docs.php | 23 ++++++++++--------- routes/api.php | 8 +++---- 4 files changed, 26 insertions(+), 39 deletions(-) diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md index d2059df..22dee58 100644 --- a/.agents/skills/api-technical-specs/SKILL.md +++ b/.agents/skills/api-technical-specs/SKILL.md @@ -29,18 +29,20 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 ## 3. 機台核心 API (IoT Endpoints) ### 3.1 B000: 機台本地管理員同步登入 -用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。 +用於機台 Android 端維護人員登入與進入設定頁。此 API 需帶入機台 API Token 進行認證。 - **URL**: POST /api/v1/app/admin/login/B000 +- **Authentication**: Bearer Token (Header) +- **Headers**: + - `Content-Type: application/json` + - `Authorization: Bearer ` - **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 | +| ip | String | 否 | 機台本地 IP | 192.168.1.100 | - **Response Body:** > [!IMPORTANT] @@ -281,14 +283,7 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 | :--- | :--- | :--- | :--- | :--- | | code | String | 是 | 會員代碼 | "MEMBER12345" | ---- -### 3.14 B710: 機台時間同步 (Timer Sync) -校準機台 RTC 時間。 - -- **URL**: POST /api/v1/app/machine/timer/B710 -- **Authentication**: Bearer Token (Header) -- **Response:** 回傳當前伺服器 Unix Timestamp。 ## 4. 已遷移至 MQTT 的端點索引 diff --git a/app/Http/Controllers/Api/V1/App/MachineAuthController.php b/app/Http/Controllers/Api/V1/App/MachineAuthController.php index 01ce26d..0820d2a 100644 --- a/app/Http/Controllers/Api/V1/App/MachineAuthController.php +++ b/app/Http/Controllers/Api/V1/App/MachineAuthController.php @@ -19,24 +19,15 @@ class MachineAuthController extends Controller */ public function loginB000(Request $request): JsonResponse { - // 1. 驗證欄位 (相容舊版 Java App 發送的 JSON 格式) + // 1. 驗證帳密與 IP $validated = $request->validate([ - 'machine' => 'required|string', 'Su_Account' => 'required|string', 'Su_Password' => 'required|string', 'ip' => 'nullable|string', - 'type' => 'nullable|string', ]); - // 2. 取得機台物件 (需優先於帳密驗證，以便記錄日誌到正確機台) - $machine = Machine::withoutGlobalScopes()->where('serial_no', $validated['machine'])->first(); - - if (!$machine) { - Log::warning("B000 機台登入失敗: 伺服器找不到該機台", [ - 'machine_serial' => $validated['machine'] - ]); - return response()->json(['message' => 'Failed']); - } + // 2. 取得機台物件 (由 iot.auth 中介層注入) + $machine = $request->get('machine'); // 3. 透過帳號尋找使用者 (允許使用 username 或 email) $user = User::where('username', $validated['Su_Account']) @@ -47,7 +38,7 @@ class MachineAuthController extends Controller if (!$user || !Hash::check($validated['Su_Password'], $user->password)) { Log::warning("B000 機台登入失敗: 帳密錯誤", [ 'account' => $validated['Su_Account'], - 'machine' => $validated['machine'] + 'machine' => $machine->serial_no ]); // 寫入機台日誌 diff --git a/config/api-docs.php b/config/api-docs.php index ac0a3ef..5ffe4c2 100644 --- a/config/api-docs.php +++ b/config/api-docs.php @@ -14,28 +14,29 @@ return [ 'slug' => 'b000-tech-login', 'method' => 'POST', 'path' => '/api/v1/app/admin/login/B000', - 'description' => '機台啟動引導的第一步。維運人員輸入個人帳密與機台編號進行認證，成功後核發臨時 Token 供後續擴充使用。', + 'description' => '維運人員輸入個人帳密進行認證。此 API 需帶入機台 API Token。驗證成功後核發臨時 User Token 供後續擴充使用。', 'headers' => [ 'Content-Type' => 'application/json', + 'Authorization' => 'Bearer ', ], 'parameters' => [ - 'username' => [ + 'Su_Account' => [ 'type' => 'string', 'required' => true, - 'description' => '維運人員帳號', + 'description' => '維運人員帳號 (username/email)', 'example' => 'admin_test' ], - 'password' => [ + 'Su_Password' => [ 'type' => 'string', 'required' => true, 'description' => '維運人員密碼', 'example' => 'password123' ], - 'machine' => [ + 'ip' => [ 'type' => 'string', - 'required' => true, - 'description' => '機台序號 (Serial No)', - 'example' => 'SN202604130001' + 'required' => false, + 'description' => '機台本地 IP', + 'example' => '192.168.1.100' ], ], 'response_parameters' => [ @@ -51,9 +52,9 @@ return [ ], ], 'request' => [ - 'username' => 'admin_test', - 'password' => 'password123', - 'machine' => 'SN202604130001' + 'Su_Account' => 'admin_test', + 'Su_Password' => 'password123', + 'ip' => '192.168.1.100' ], 'response' => [ 'message' => 'Success', diff --git a/routes/api.php b/routes/api.php index db1b228..b328b6f 100644 --- a/routes/api.php +++ b/routes/api.php @@ -48,15 +48,15 @@ Route::prefix('v1')->middleware(['throttle:api'])->group(function () { | 專門用於機台通訊，頻率較高，建議搭配異步處理。 */ - // 機台管理員 B000 登入驗證 (由於此階段機台未帶 Token 無法通過 iot.auth) + // 機台啟動引導與參數下載 (公開存取，僅需機台序號，供機台初始化時獲取 API Token) Route::prefix('app')->group(function () { - Route::post('admin/login/B000', [\App\Http\Controllers\Api\V1\App\MachineAuthController::class, 'loginB000'])->middleware('throttle:30,1'); - - // 機台啟動引導與參數下載 (已改為公開存取，僅需機台序號) Route::get('machine/setting/B014', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSettings']); }); Route::prefix('app')->middleware(['iot.auth', 'throttle:100,1'])->group(function () { + // 機台管理員 B000 登入驗證 (需帶機台 API Token) + Route::post('admin/login/B000', [\App\Http\Controllers\Api\V1\App\MachineAuthController::class, 'loginB000'])->middleware('throttle:30,1'); + // 機台狀態與相關同步 (B017, B710, B220) Route::get('machine/reload_msg/B017', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSlots']);