From 5e633709839f42a3f614c8fa13b4c26dbfa7ab58 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Wed, 6 May 2026 14:13:02 +0800 Subject: [PATCH] =?UTF-8?q?[DOCS]=20=E6=9B=B4=E6=96=B0=20B014=20API=20?= =?UTF-8?q?=E6=8A=80=E8=A1=93=E8=A6=8F=E6=A0=BC=E8=AA=AA=E6=98=8E=E8=88=87?= =?UTF-8?q?=E6=96=87=E6=A1=88=E8=AA=BF=E6=95=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. [DOCS] 更新 SKILL.md 中 B014 介面的認證規範，改為透過 machine 參數識別。 2. [DOCS] 移除 SKILL.md 中關於 B014 的冗餘安全性規範說明。 3. [DOCS] 調整 api-docs.php 中 B014 的描述文案並修正行尾空白。 --- .agents/skills/api-technical-specs/SKILL.md | 10 +++------- config/api-docs.php | 13 ++++++------- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/.agents/skills/api-technical-specs/SKILL.md b/.agents/skills/api-technical-specs/SKILL.md index 18c852c..d2059df 100644 --- a/.agents/skills/api-technical-specs/SKILL.md +++ b/.agents/skills/api-technical-specs/SKILL.md @@ -16,7 +16,6 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 ### 2.1 維運人員認證 (User Authentication) - **核發端點**：B000 (登入)。 -- **使用端點**：B014 (參數下載)。 - **方式**：使用 Laravel Sanctum 核發之 **User Token**。 - **Header**：`Authorization: Bearer `。 @@ -50,7 +49,7 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 | 參數 | 類型 | 說明 | 範例 | | :--- | :--- | :--- | :--- | | message | String | 驗證結果 (Success 或 Failed) | Success | -| token | String | **臨時身份認證 Token** (用於 B014) | 1|abcdefg... | +| token | String | **臨時身份認證 Token** (可選，供未來擴充使用) | 1|abcdefg... | --- @@ -154,8 +153,8 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。 - **URL**: GET /api/v1/app/machine/setting/B014 -- **Authentication**: **User Token** (Sanctum Header) -- **Request Body:** 無 (由 Query String 帶入 `machine` 參數) +- **Authentication**: None (由 Query String 帶入 `machine` 參數識別) +- **Request Body:** 無 | 參數 | 類型 | 必填 | 說明 | 範例 | | :--- | :--- | :--- | :--- | :--- | @@ -176,9 +175,6 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與 | **TP_APP_ID** | 趨勢支付 AppID | TrendPay ID | | **TP_APP_KEY** | 趨勢支付 Key | TrendPay Key | -> [!CAUTION] -> **安全性規範**：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。 - --- ### 3.8 B017: 貨道庫存同步 (Slot Synchronization) diff --git a/config/api-docs.php b/config/api-docs.php index 79806bd..ac0a3ef 100644 --- a/config/api-docs.php +++ b/config/api-docs.php @@ -14,7 +14,7 @@ return [ 'slug' => 'b000-tech-login', 'method' => 'POST', 'path' => '/api/v1/app/admin/login/B000', - 'description' => '機台啟動引導的第一步。維運人員輸入個人帳密與機台編號進行認證，成功後核發臨時 Sanctum Token 供後續 B014 下載敏感設定使用。', + 'description' => '機台啟動引導的第一步。維運人員輸入個人帳密與機台編號進行認證，成功後核發臨時 Token 供後續擴充使用。', 'headers' => [ 'Content-Type' => 'application/json', ], @@ -46,7 +46,7 @@ return [ ], 'token' => [ 'type' => 'string', - 'description' => '臨時身份認證 Token (Sanctum)', + 'description' => '臨時身份認證 Token', 'example' => '1|abcdefg...' ], ], @@ -65,9 +65,8 @@ return [ 'slug' => 'b014-config-download', 'method' => 'GET', 'path' => '/api/v1/app/machine/setting/B014', - 'description' => '機台引導階段的第二步。在人員登入後，透過此介面下載金流金鑰、電子發票設定與機台專屬通訊 Token。', + 'description' => '透過此介面下載金流金鑰、電子發票設定與機台專屬通訊 Token。', 'headers' => [ - 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], 'parameters' => [ @@ -114,7 +113,7 @@ return [ ] ] ], - 'notes' => '此 API 受 auth:sanctum 保護，必須在 Header 帶上從 B000 取得的 Token。' + 'notes' => '此 API 為機台初始化引導用，目前不強制驗證 User Token。' ], [ 'name' => 'B005: 廣告清單同步 (Ad Sync)', @@ -551,7 +550,7 @@ return [ 'order.items[].product_id' => ['type' => 'integer', 'description' => '(必填) 商品 ID'], 'order.items[].price' => ['type' => 'numeric', 'description' => '(必填) 商品單價'], 'order.items[].quantity' => ['type' => 'integer', 'description' => '(必填) 數量'], - + 'invoice' => ['type' => 'object', 'description' => '(選填) 發票開立資訊 (若無發票可省略)', 'required' => false], 'invoice.invoice_no' => ['type' => 'string', 'description' => '(必填，若有invoice) 發票號碼', 'required' => false], 'invoice.invoice_date' => ['type' => 'string', 'description' => '(必填，若有invoice) 發票日期 (Y-m-d)', 'required' => false], @@ -564,7 +563,7 @@ return [ 'invoice.business_tax_id' => ['type' => 'string', 'description' => '(選填) 買受人統編', 'required' => false], 'invoice.rtn_code' => ['type' => 'string', 'description' => '(選填) 電子發票回傳代碼', 'required' => false], 'invoice.rtn_msg' => ['type' => 'string', 'description' => '(選填) 電子發票回傳訊息', 'required' => false], - + 'dispense' => ['type' => 'array', 'description' => '(必填) 出貨結果清單'], 'dispense[].slot_no' => ['type' => 'string', 'description' => '(必填) 貨道編號'], 'dispense[].product_id' => ['type' => 'integer', 'description' => '(必填) 商品 ID'],