sky121113
a599b14df1
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m6s
1. 修復帳號管理與角色權限頁面搜尋功能，支援 Enter 鍵快捷提交。 2. 完成 B013 (機台故障上報) API 實作，改用非同步隊列 (ProcessMachineError) 處理日誌上報。 3. 精簡 B013 API 參數，移除冗餘的 message 欄位，統一由雲端對照表翻譯。 4. 更新技術規格文件 (SKILL.md) 與系統 API 文件配置 (api-docs.php)。 5. 修正平台管理員帳號在搜尋過濾時的資料隔離邏輯。
219 lines
9.1 KiB
Markdown
219 lines
9.1 KiB
Markdown
---
|
||
name: API 技術規格與通訊協議規範
|
||
description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與後端 (Cloud) 通訊的 API 細節、參數命名規則、狀態代碼對照與認證機制，作為系統開發的唯一規格來源。
|
||
---
|
||
|
||
# API 技術規格與通訊協議規範 (API Technical Specs)
|
||
|
||
本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。
|
||
|
||
## 1. 核心命名原則
|
||
- **語意化優先**：捨棄舊版 M_ 前綴，統一使用 snake_case (如 firmware_version)。
|
||
- **類型嚴格**：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。
|
||
|
||
## 2. 身份認證 (Authentication)
|
||
- **Bearer Token**：所有 API 必須在 Header 帶入 Authorization: Bearer <api_token>。
|
||
- **身分綁定**：後端透過 Token 自動識別 machine_id，禁止在 Body 帶入 machine 或 key 欄位。
|
||
|
||
---
|
||
|
||
## 3. 機台核心 API (IoT Endpoints)
|
||
|
||
### 3.1 B000: 機台本地管理員同步登入
|
||
用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。
|
||
|
||
- **URL**: POST /api/v1/app/admin/login/B000
|
||
- **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 |
|
||
|
||
- **Response Body:**
|
||
> [!IMPORTANT]
|
||
> 為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 Success。
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| message | String | 驗證結果 (Success 或 Failed) | Success |
|
||
|
||
---
|
||
|
||
### 3.2 B005: 廣告清單同步
|
||
用於機台端獲取目前應播放的廣告檔案 URL 清單。
|
||
|
||
- **URL**: GET /api/v1/app/machine/ad/B005
|
||
- **Request Body:** 無 (GET 請求)
|
||
|
||
- **Response Body:**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否成功 | true |
|
||
| code | Integer | 內部業務狀態碼 | 200 |
|
||
| data | Array | 廣告物件陣列 | [{"t070v04": "https://..."}] |
|
||
|
||
**data 陣列內部欄位：**
|
||
- t070v01: 廣告名稱 (Name)
|
||
- t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
|
||
- t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
|
||
- t070v04: 廣告 URL。
|
||
- t070v05: 播放順位 (Sort Order)。
|
||
|
||
---
|
||
|
||
### 3.3 B009: 貨道庫存即時回報 (Supplementary Report)
|
||
當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
|
||
|
||
#### B009 權限驗證邏輯 (RBAC Compliance)
|
||
系統會依據 account 欄位進行三層式權限核查：
|
||
1. **系統層 (System Admin)**：當 company_id 為 null 時，具備全局管理權限，直接放行。
|
||
2. **公司層 (Company Admin)**：當 is_admin 為 true 時，檢查機台的 company_id 是否與該帳號一致。
|
||
3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 machine_user 授權表，確認該帳號有被分配至此機台。
|
||
|
||
- **URL**: PUT /api/v1/app/products/supplementary/B009
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| account | String | 是 | 操作人員帳號 | 0999123456 |
|
||
| data | Array | 是 | 貨道數據陣列 | [{"tid":"1", "t060v00":"1", "num":"10"}] |
|
||
|
||
- **data 陣列內部欄位：**
|
||
|
||
| 欄位 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| tid | Integer | 貨道編號 (Slot No) | 1 |
|
||
| t060v00 | String | 商品資料庫 ID (或是 Barcode) | "1" |
|
||
| num | Integer | 實體剩餘庫存數量 | 10 |
|
||
| type | Integer | 貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。 | 1 |
|
||
|
||
> [!TIP]
|
||
> **自動化上限同步邏輯**：
|
||
> 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。
|
||
|
||
- **Response Body (Success 200):**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 同步是否成功 | true |
|
||
| code | Integer | 內部業務狀態碼 | 200 |
|
||
| message | String | 回應訊息 | Slot report synchronized success |
|
||
| status | String | 固定回傳 49 代表同步完成 | "49" |
|
||
|
||
---
|
||
|
||
### 3.4 B010: 心跳上報與狀態同步
|
||
用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
|
||
|
||
- **URL**: POST /api/v1/app/machine/status/B010
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| current_page | Integer | 是 | 當前頁面代碼 (見下表) | 1 |
|
||
| firmware_version | String | 是 | 韌體版本號 | 1.0.5 |
|
||
| model | String | 是 | 機台型號 | STAR-V1 |
|
||
| temperature | Float | 否 | 環境溫度 | 25.5 |
|
||
| door_status | Integer | 否 | 門狀態 (0:關 / 1:開) | 0 |
|
||
| log | String | 否 | 事件日誌簡述 | Door opened |
|
||
| log_level | String | 否 | info, warn, error | info |
|
||
| log_payload | Object | 否 | 額外日誌 JSON 對象 | {"code":500} |
|
||
|
||
- **Response Body:**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否處理成功 | true |
|
||
| code | Integer | 內部業務狀態碼 | 200 |
|
||
| message | String | 回應訊息 | OK |
|
||
| status | String | **雲端指令代碼** (見下表) | 49 |
|
||
|
||
#### B010 代碼對照表
|
||
|
||
**頁面代碼 (current_page)：**
|
||
- 0: 離線 / 1: 主頁面 / 2: 販賣頁 / 3: 管理頁
|
||
- 4: 補貨頁 / 5: 教學頁 / 6: 購買中 / 7: 鎖定頁
|
||
- 60: 出貨成功 / 61: 貨道測試 / 62: 付款選擇
|
||
- 63: 等待付款 / 64: 出貨 / 65: 收據簽單
|
||
- 66: 通行碼 / 67: 取貨碼 / 68: 訊息顯示
|
||
- 69: 取消購買 / 610: 購買結束 / 611: 來店禮
|
||
- 612: 出貨失敗
|
||
|
||
**雲端指令代碼 (status)：**
|
||
- 49: reload B017 (貨道同步)
|
||
- 51: reboot (重啟系統)
|
||
- 60: reboot card machine (刷卡機重啟)
|
||
- 61: checkout (觸發結帳)
|
||
- 70: unlock (解鎖)
|
||
- 71: lock (鎖定)
|
||
- 85: reload B0552 (遠端出貨)
|
||
|
||
---
|
||
|
||
### 3.5 B012: 商品配置與商品主檔同步 (Unified Sync)
|
||
用於機台端獲取目前所有可販售商品的詳細配置。App 端應依據呼叫的方法決定數據處理方式。
|
||
|
||
- **URL**: GET|PATCH /api/v1/app/machine/products/B012
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
#### 運作邏輯 (Client-side Logic):
|
||
- **GET**：執行 **全量同步**。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
|
||
- **PATCH**：執行 **增量更新**。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。
|
||
|
||
| 欄位 | 型別 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| t060v00 | String | 商品資料庫 ID | "1" |
|
||
| t060v01 | String | 商品名稱 | 可口可樂 330ml |
|
||
| t060v01_en | String | 英文名稱 | Coca Cola |
|
||
| t060v01_jp | String | 日文名稱 | コカコーラ |
|
||
| t060v03 | String | 商品規格/簡述 | Cold Drink |
|
||
| t060v06 | String | 圖片 URL | https://.../coke.png |
|
||
| t060v09 | Float | 標準零售價 | 25.0 |
|
||
| t060v11 | Integer | **貨道庫存上限** (預設履帶) | 10 |
|
||
| t060v30 | Float | 會員價 | 20.0 |
|
||
| t063v03 | Float | 本機銷售價格 (同定價) | 25.0 |
|
||
| t060v40 | String | 行銷計畫 (Marketing Plan) | Buy 1 Get 1 |
|
||
| t060v41 | String | 物料編碼 (Material Code) | SKU-001 |
|
||
| spring_limit | Integer | **彈簧貨道上限** (建議使用此欄位) | 10 |
|
||
| track_limit | Integer | **履帶貨道上限** (建議使用此欄位) | 15 |
|
||
|
||
---
|
||
|
||
### 3.6 B013: 機台故障與異常狀態上報 (Error/Status Report)
|
||
用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關），並自動由雲端後端翻譯為易讀日誌。
|
||
|
||
- **URL**: POST /api/v1/app/machine/error/B013
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| tid | Integer | 否 | 涉及之貨道編號 (Slot No) | 12 |
|
||
| error_code | String | 是 | 硬體狀態代碼 (4 位 16 進位) | "0403" |
|
||
|
||
- **回應 (Success 202):**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求已接收 | true |
|
||
| code | Integer | 200 | 200 |
|
||
|
||
#### B013 硬體代碼對照表 (由 MachineService 自動翻譯)
|
||
|
||
| 代碼 | 英文 Key (i18n) | 級別 | 範例繁中翻譯 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **0402** | Dispense successful | info | 出貨成功 |
|
||
| **0403** | Slot jammed | error | **貨道卡貨** (重大異常) |
|
||
| **0202** | Product empty | warning | 貨道缺貨 |
|
||
| **0412** | Elevator rise error | error | 昇降機上升異常 |
|
||
| **0415** | Pickup door error | error | 取貨門異常 |
|
||
| **5402** | Pickup door not closed | warning | **取貨門未關** (警告) |
|
||
| **5403** | Elevator failure | error | 昇降系統故障 |
|