[DOCS] 更新 B014 API 技術規格說明與文案調整

1. [DOCS] 更新 SKILL.md 中 B014 介面的認證規範,改為透過 machine 參數識別。
2. [DOCS] 移除 SKILL.md 中關於 B014 的冗餘安全性規範說明。
3. [DOCS] 調整 api-docs.php 中 B014 的描述文案並修正行尾空白。
This commit is contained in:
sky121113 2026-05-06 14:13:02 +08:00
parent cab30b1683
commit 5e63370983
2 changed files with 9 additions and 14 deletions

View File

@ -16,7 +16,6 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
### 2.1 維運人員認證 (User Authentication)
- **核發端點**B000 (登入)。
- **使用端點**B014 (參數下載)。
- **方式**:使用 Laravel Sanctum 核發之 **User Token**
- **Header**`Authorization: Bearer <user_token>`。
@ -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)

View File

@ -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 <user_token>',
'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'],