40aec884b0
1. 優化 ProcessHeartbeat 溫度處理邏輯，改為「變動即記錄」並標準化為整數型態。 2. 在 Machine Model 中新增 temperature 欄位的 integer cast。 3. 更新 MQTT 與 API 技術規格技能文件 (SKILL.md)，同步最新的溫度記錄規則。 4. 更新 config/api-docs.php，明確標註心跳上報之溫度規格與日誌規則。 5. 移除 routes/api.php 中已廢棄之 B600 與機台日誌 REST API 路由。 6. 清理 docs 目錄，將初期計畫文件遷移至 docs/plan/。
279 lines
12 KiB
Markdown
279 lines
12 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)
|
||
本系統採用兩階段認證模式：
|
||
|
||
### 2.1 維運人員認證 (User Authentication)
|
||
- **核發端點**：B000 (登入)。
|
||
- **使用端點**：B014 (參數下載)。
|
||
- **方式**：使用 Laravel Sanctum 核發之 **User Token**。
|
||
- **Header**：`Authorization: Bearer <user_token>`。
|
||
|
||
### 2.2 機台通訊認證 (Machine Authentication)
|
||
- **適用 API**：B012, B009 等後續通訊。
|
||
- **方式**：使用機台專屬之 **api_token**。
|
||
- **Header**：`Authorization: Bearer <api_token>`。
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| token | String | **臨時身份認證 Token** (用於 B014) | 1|abcdefg... |
|
||
|
||
---
|
||
|
||
### 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)
|
||
當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
|
||
|
||
|
||
|
||
- **URL**: PUT /api/v1/app/products/supplementary/B009
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| 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.5 B012: 商品配置與商品主檔同步 (Unified Sync)
|
||
用於機台端獲取目前所有可販售商品的詳細配置。
|
||
|
||
- **URL**: GET /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: [DEPRECATED / REMOVED] 機台故障與異常狀態上報
|
||
> [!WARNING]
|
||
> **此 REST API 已廢棄並移除**。機台異常上報已全面遷移至 **MQTT** 即時通訊架構。
|
||
> 詳細錯誤代碼請參閱：[MQTT 通訊規範 - B013 硬體代碼對照表](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#32-異常與錯誤上報-b013)
|
||
|
||
### 3.12 B010: [DEPRECATED / REMOVED] 心跳上報與狀態同步
|
||
> [!WARNING]
|
||
> **此 REST API 已廢棄並移除**。機台心跳上報與指令下發已全面遷移至 **MQTT** 架構。
|
||
> (註：溫度數據已標準化為 **Integer**，且雲端採「變動即記錄」規則)。
|
||
> 詳細格式請參閱：[MQTT 通訊規範 - B010 心跳上報](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#31-心跳上報-b010)
|
||
|
||
---
|
||
|
||
### 3.7 B014: 機台參數與金鑰下載 (Config Download)
|
||
用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。
|
||
|
||
- **URL**: GET /api/v1/app/machine/setting/B014
|
||
- **Authentication**: **User Token** (Sanctum Header)
|
||
- **Request Body:** 無 (由 Query String 帶入 `machine` 參數)
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| machine | String | 是 | 機台編號 (serial_no) | M-001 |
|
||
|
||
- **Response Body (Success 200):**
|
||
|
||
| 欄位 (Key) | 說明 | 備註 |
|
||
| :--- | :--- | :--- |
|
||
| **t050v01** | 機台序號 | 即 machine_id |
|
||
| **api_token** | **機台正式 Token** | 初始化後應存於本地，後續 API 認證用 |
|
||
| **t050v41** | 玉山特店編號 | ESUN Merchant ID |
|
||
| **t050v42** | 玉山終端編號 | ESUN Terminal ID |
|
||
| **t050v43** | 玉山 Hash Key | ESUN Hash |
|
||
| **t050v34** | 發票特店 ID | Invoice Merchant ID |
|
||
| **t050v35** | 發票 Hash Key | Invoice Key |
|
||
| **t050v36** | 發票 Hash IV | Invoice IV |
|
||
| **TP_APP_ID** | 趨勢支付 AppID | TrendPay ID |
|
||
| **TP_APP_KEY** | 趨勢支付 Key | TrendPay Key |
|
||
|
||
> [!CAUTION]
|
||
> **安全性規範**：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。
|
||
|
||
---
|
||
|
||
### 3.8 B017: 貨道庫存同步 (Slot Synchronization)
|
||
用於機台端**主動**向遠端後台拉取目前所有貨道的最新庫存、效期與配置狀態。通常發生於機台開機初始化、補貨/維護模式結束，或是機台需要確保本地端庫存資料與雲端一致時主動請求。
|
||
|
||
- **URL**: GET /api/v1/app/machine/reload_msg/B017
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
- **Response Body:**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否成功 | true |
|
||
| code | Integer | 200 | 200 |
|
||
| data | Array | 貨道數據陣列 (依 slot_no 排序) | 見下表 |
|
||
|
||
**data 陣列內部欄位：**
|
||
|
||
| 欄位 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| tid | String | 貨道編號 | "1" |
|
||
| num | Integer | 當前庫存數量 | 10 |
|
||
| expiry_date | String | 商品效期 | "2026-12-31" |
|
||
| batch_no | String | 批號 | "B202604" |
|
||
| product_id | Integer | 商品 ID | 1 |
|
||
| capacity | Integer | 貨道容量上限 | 15 |
|
||
| status | String | 貨道狀態 ("1": 啟用, "0": 停用) | "1" |
|
||
|
||
---
|
||
|
||
### 3.9 B024: 取貨碼/通行碼驗證與消耗回報 (Access Code Verify & Report)
|
||
用於處理機台端的代碼取貨流程。包含驗證代碼有效性（驗證階段）與確認出貨完成後的狀態消耗（回報階段）。
|
||
|
||
- **URL**: POST|PUT /api/v1/app/sell/access-code/B024
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body (POST - 驗證階段):**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| passCode | String | 是 | 使用者輸入的取貨碼/通行碼 | "12345678" |
|
||
|
||
- **Response Body (POST - 驗證成功 200):**
|
||
雲端將回傳該碼對應的權限或待出貨商品資訊。
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| res1 | String | 該代碼在雲端的關聯 ID | "99" |
|
||
| res2 | String | 操作模式 (1: 出貨, 2: 僅驗證) | "1" |
|
||
| res3 | String | 預計出貨商品 ID | "5" |
|
||
| res4 | String | 折扣金額或活動標籤 | "0.0" |
|
||
|
||
- **Request Body (PUT - 回報階段):**
|
||
當機台端確認實體出貨成功後，必須發送此請求以耗刷該代碼。
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| accessCodeId | String | 是 | 驗證階段取得的 res1 (ID) | "99" |
|
||
| status | String | 是 | 出貨結果 (1: 成功, 0: 失敗) | "1" |
|
||
|
||
---
|
||
|
||
### 3.10 B027: 贈品碼/優惠券驗證與消耗回報 (Free Gift Verify & Report)
|
||
用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。
|
||
|
||
- **URL**: POST|PUT /api/v1/app/sell/free-gift/B027
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **運作模式**:
|
||
- **POST**: 提交 `passCode` 驗證該贈品券是否有效。成功後雲端會回傳對應活動 ID 與商品配置。
|
||
- **PUT**: 當該贈品（0 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。
|
||
|
||
> [!NOTE]
|
||
> B027 與 B024 的邏輯具備高度對稱性，區別在於 B027 通常綁定的是特定的行銷活動 (Campaign) 與 0 元出貨邏輯。
|
||
|
||
---
|
||
|
||
|
||
## 4. 已遷移至 MQTT 的端點索引
|
||
|
||
以下端點的 HTTP REST API 已廢棄，改為透過 MQTT 即時通訊架構處理。詳細的 Payload 定義請參閱 [MQTT 通訊規範](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md)。
|
||
|
||
| 原 API 代碼 | 名稱 | MQTT Topic | 備註 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| B010 | 心跳上報 | `machine/{serial_no}/heartbeat` | [已廢棄](#312-b010-deprecated--removed-心跳上報與狀態同步) |
|
||
| B013 | 異常上報 | `machine/{serial_no}/error` | [已廢棄](#36-b013-deprecated--removed-機台故障與異常狀態上報) |
|
||
| B600 | 交易建立 | `machine/{serial_no}/transaction` | `action: create` |
|
||
| B601 | 發票紀錄 | `machine/{serial_no}/transaction` | `action: invoice` |
|
||
| B602 | 出貨結果 | `machine/{serial_no}/transaction` | `action: dispense` |
|
||
| B055 (PUT) | 遠端出貨回報 | `machine/{serial_no}/command/ack` | GET 查詢路由保留 |
|