From 2702e5a6558b5ea1c1bab6b3ee449bcf1f890922 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Tue, 14 Apr 2026 16:46:35 +0800 Subject: [PATCH] =?UTF-8?q?[REFACTOR]=20=E6=A8=99=E6=BA=96=E5=8C=96=20IoT?= =?UTF-8?q?=20API=20=E6=96=B9=E6=B3=95=E4=B8=A6=E4=BF=AE=E6=AD=A3=E6=97=A5?= =?UTF-8?q?=E6=9C=9F=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 將 B014 (參數下載) 與 B017 (貨道同步) 路由從 POST 改為 GET。 2. 移除 B017 冗餘的 machine 參數，改由 Bearer Token 自動識別。 3. 修正 B017 回傳資料中 expiry_date 的 ISO 8601 格式問題，統一為 Y-m-d。 4. 同步更新所有技術規格文件 (.agents/ 規範) 與 API 說明配置 (config/api-docs.php)。 --- .agents/rules/api-rules.md | 6 +++--- .agents/skills/api-technical-specs/SKILL.md | 11 +++++----- .agents/skills/iot-communication/SKILL.md | 2 +- .../Api/V1/App/MachineController.php | 2 +- config/api-docs.php | 21 +++++-------------- routes/api.php | 4 ++-- 6 files changed, 17 insertions(+), 29 deletions(-) diff --git a/.agents/rules/api-rules.md b/.agents/rules/api-rules.md index 794c293..c3d9ffe 100644 --- a/.agents/rules/api-rules.md +++ b/.agents/rules/api-rules.md @@ -56,12 +56,12 @@ trigger: always_on ### 4.2 終端類 (IoT / Machine) — 須嚴格遵守 PDF 規格 * **API 識別碼 (workid)**: URL 中的 `{workid}` 參數固定為該 API 的功能代碼 (如 `B010`, `B017`, `B600`)，不隨機台改變。 * **機台識別方式**: - 1. **Header**: 透過 `Authorization: Bearer ` 識別。 - 2. **Request Body**: 透過 `machine` 或 `serial_no` 等欄位識別具體機台。 + 1. **Header (推薦)**: 透過 `Authorization: Bearer ` 識別。針對 B017 等端點，雲端將自動關聯對應機台，**不需**額外帶入機台識別參數。 + 2. **Request Body (相容/特定模式)**: 透過 `machine` 或 `serial_no` 等欄位識別。主要用於 B000 登入或尚未取得 Token 的引導階段 (如 B014)。 * **主要 Endpoint 範例**: * **心跳上報 (B010)**: `POST /api/app/machine/status/B010` * **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號) - * **貨道庫存 (B017)**: `POST /api/app/machine/reload_msg/B017` + * **貨道庫存 (B017)**: `GET /api/app/machine/reload_msg/B017` * **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055` --- diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md index a0da026..2961a4d 100644 --- a/.agents/skills/api-technical-specs/SKILL.md +++ b/.agents/skills/api-technical-specs/SKILL.md @@ -233,9 +233,9 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 ### 3.7 B014: 機台參數與金鑰下載 (Config Download) 用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。 -- **URL**: POST /api/v1/app/machine/setting/B014 +- **URL**: GET /api/v1/app/machine/setting/B014 - **Authentication**: **User Token** (Sanctum Header) -- **Request Body:** +- **Request Body:** 無 (由 Query String 帶入 `machine` 參數) | 參數 | 類型 | 必填 | 說明 | 範例 | | :--- | :--- | :--- | :--- | :--- | @@ -264,13 +264,12 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 ### 3.8 B017: 貨道庫存同步 (Slot Synchronization) 用於機台端獲取目前所有貨道的最新庫存、效期與狀態。通常由 B010 回應 `status: 49` 觸發。 -- **URL**: POST /api/v1/app/machine/reload_msg/B017 -- **Authentication**: Bearer Token (Header) 或 API Key (Body) -- **Request Body:** +- **URL**: GET /api/v1/app/machine/reload_msg/B017 +- **Authentication**: Bearer Token (Header) 或 API Key (Body/Query) +- **Request Body:** 無 (由 Token 自動識別機台) | 參數 | 類型 | 必填 | 說明 | 範例 | | :--- | :--- | :--- | :--- | :--- | -| machine | String | 是 | 機台編號 | SN00001 | - **Response Body:** diff --git a/.agents/skills/iot-communication/SKILL.md b/.agents/skills/iot-communication/SKILL.md index fda90ab..4996396 100644 --- a/.agents/skills/iot-communication/SKILL.md +++ b/.agents/skills/iot-communication/SKILL.md @@ -12,7 +12,7 @@ description: 規範智能販賣機與 Cloud 平台間的高頻通訊處理流程 所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline。依據通訊協議不同，進入點有兩條路徑： ### 1.1 HTTP 管線 (低頻/大檔操作) -適用於 B000, B009, B012, B014 等低頻或大資料量的端點： +適用於 B000, B009, B012, B014, B017 等低頻、同步需求或大資料量的端點： 1. **API Controller (接收層)**：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 `202 Accepted`。 2. **Job (異步層)**：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。 3. **Service (邏輯層)**：封裝商業邏輯，更新資料庫。 diff --git a/app/Http/Controllers/Api/V1/App/MachineController.php b/app/Http/Controllers/Api/V1/App/MachineController.php index 0a39afa..aacaa03 100644 --- a/app/Http/Controllers/Api/V1/App/MachineController.php +++ b/app/Http/Controllers/Api/V1/App/MachineController.php @@ -196,7 +196,7 @@ class MachineController extends Controller return [ 'tid' => $slot->slot_no, 'num' => (int)$slot->stock, - 'expiry_date' => $slot->expiry_date, + 'expiry_date' => $slot->expiry_date ? $slot->expiry_date->format('Y-m-d') : null, 'batch_no' => $slot->batch_no, // 保留原始欄位以供除錯或未來擴充 'product_id' => $slot->product_id, diff --git a/config/api-docs.php b/config/api-docs.php index fe714ab..a86ecf5 100644 --- a/config/api-docs.php +++ b/config/api-docs.php @@ -62,7 +62,7 @@ return [ [ 'name' => 'B014: 機台參數與金鑰下載 (Config Download)', 'slug' => 'b014-config-download', - 'method' => 'POST', + 'method' => 'GET', 'path' => '/api/v1/app/machine/setting/B014', 'description' => '機台引導階段的第二步。在人員登入後，透過此介面下載金流金鑰、電子發票設定與機台專屬通訊 Token。', 'headers' => [ @@ -97,9 +97,7 @@ return [ ] ], ], - 'request' => [ - 'machine' => 'SN202604130001' - ], + 'request' => [], 'response' => [ 'success' => true, 'code' => 200, @@ -463,21 +461,14 @@ return [ [ 'name' => 'B017: 貨道庫存同步 (Slot Synchronization)', 'slug' => 'b017-slot-sync', - 'method' => 'POST', + 'method' => 'GET', 'path' => '/api/v1/app/machine/reload_msg/B017', 'description' => '用於機台端獲獲取所有貨道的最新庫存、效期與狀態。通常由 B010 回傳 status: 49 時觸發。', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], - 'parameters' => [ - 'machine' => [ - 'type' => 'string', - 'required' => true, - 'description' => '機台序號', - 'example' => 'SN00001' - ], - ], + 'parameters' => [], 'response_parameters' => [ 'success' => [ 'type' => 'boolean', @@ -498,9 +489,7 @@ return [ ] ], ], - 'request' => [ - 'machine' => 'SN00001' - ], + 'request' => [], 'response' => [ 'success' => true, 'code' => 200, diff --git a/routes/api.php b/routes/api.php index 757a846..65d465a 100644 --- a/routes/api.php +++ b/routes/api.php @@ -53,13 +53,13 @@ Route::prefix('v1')->middleware(['throttle:api'])->group(function () { Route::post('admin/login/B000', [\App\Http\Controllers\Api\V1\App\MachineAuthController::class, 'loginB000'])->middleware('throttle:30,1'); // 機台啟動引導與參數下載 (需人員登入 Token) - Route::middleware('auth:sanctum')->post('machine/setting/B014', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSettings']); + Route::middleware('auth:sanctum')->get('machine/setting/B014', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSettings']); }); Route::prefix('app')->middleware(['iot.auth', 'throttle:100,1'])->group(function () { // 心跳與狀態 (B010, B017, B710, B220) Route::post('machine/status/B010', [App\Http\Controllers\Api\V1\App\MachineController::class, 'heartbeat']); - Route::post('machine/reload_msg/B017', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSlots']); + Route::get('machine/reload_msg/B017', [App\Http\Controllers\Api\V1\App\MachineController::class, 'getSlots']); Route::post('machine/timer/B710', [App\Http\Controllers\Api\V1\App\MachineController::class, 'syncTimer']); 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']);