[DOCS] 建立獨立 API 技術規格技能 (api-technical-specs) 並精簡 IoT 通訊規範

.agents/rules/skill-trigger.md

@@ -15,6 +15,7 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
 | 觸發詞 / 情境 | 對應 Skill | 路徑 |
 |---|---|---|
 | 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報 | **IoT 通訊與高併發處理規範** | `.agents/skills/iot-communication/SKILL.md` |
+| B010, B017, B600, B055, API 規格, 通訊協議, 狀態碼, 頁面碼, 範例, JSON | **API 技術規格與通訊協議規範** | `.agents/skills/api-technical-specs/SKILL.md` |
 | 介面, UI, 設計, 佈局, CSS, Tailwind, 奢華, 深色模式, Light Mode, Dark Mode, Blade, 樣式, 間距, 陰影, 動畫, 畫面, 頁面 | **極簡奢華風 UI 實作規範** | `.agents/skills/ui-minimal-luxury/SKILL.md` |
 | 查詢、撈資料、Query、Controller、下拉選單、Eloquent、N+1、`->get()`、select、交易、Transaction、Bulk、分頁、索引 | **資料庫與 ORM 最佳實踐規範** | `/home/mama/.gemini/antigravity/global_skills/database-best-practices/SKILL.md` |
 | RBAC, 權限, 角色, 租戶, Tenant, Company, Access Control, 多租戶, 權限控管 | **多租戶與權限架構實作規範** | `.agents/rules/rbac-rules.md` |

.agents/skills/api-technical-specs/SKILL.md

@@ -0,0 +1,75 @@
+---
+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 B010: 心跳上報與狀態同步
+用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
+
+- **URL**: `POST /api/v1/app/machine/status/B010`
+- **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`: 收據簽單
+- `612`: 出貨失敗
+
+**雲端指令代碼 (status)：**
+- `49`: reload B017 (貨道同步)
+- `50`: reload B005 (基礎參數)
+- `51`: reboot (重啟系統)
+- `60`: reboot card machine (刷卡機重啟)
+- `61`: checkout (結帳)
+- `70`: unlock (解鎖) / `71`: lock (鎖定)
+- `72`: sellCode reload B023 (即期品)
+- `75`: exp reload B026 (效期)
+- `79`: read B050 (參數讀取)
+- `85`: reload B0552 (出貨腳本)
+
+---
+
+### 3.2 B017: 貨道與庫存同步 (規劃中)
+- **URL**: `POST /api/v1/app/machine/reload_msg/B017`
+- 說明：當機台收到 B010 回應 `status: 49` 時，應呼叫此 API 同步最新貨道佈局。
+
+### 3.3 B600: 交易數據回傳 (規劃中)
+- **URL**: `POST /api/v1/app/B600`
+- 說明：交易完成後提交支付方式、金額、商品與出貨結果。

.agents/skills/iot-communication/SKILL.md

@@ -61,84 +61,18 @@ public function handle(MachineService $service): void
 - [ ] 業務邏輯是否已封裝至 `App\Services`？
 - [ ] 是否使用了 Redis Queue 進行非同步處理？
 
-## 6. 核心 API 規格 (Core API Specs)
+## 6. API 規格定義 (API Specifications)
 
-### 6.1 B010: 心跳上報與狀態同步 (Finalized)
-這是機台最頻繁呼叫的端點，用於確認在線狀態、更新感測數據並獲取雲端指令。
+> [!IMPORTANT]
+> **規格分離原則**：本技能僅規範「通訊處理邏輯」。關於具體的 API 欄位、參數命名、狀態代碼對照與範例，請務必參閱專屬技能規範：
+> - **[API 技術規格與通訊協議規範](file:///home/mama/projects/star-cloud/.agents/skills/api-technical-specs/SKILL.md)**
 
-- **Endpoint**: `POST /api/v1/app/machine/status/B010`
-- **認證**: `Authorization: Bearer <api_token>` (必需)
-- **Content-Type**: `application/json`
+### 常見端點處理模式
+1.  **B010 (心跳)**：高頻點，必須進入 Redis Queue。更新 `last_heartbeat_at` 與感測器快照。
+2.  **B600 (交易)**：高價值點，必須進入任務隊列並支援重試。建立 `Transaction` 紀錄。
+3.  **B017 (貨道)**：回覆較大資料量，應確保 Service 層具備緩存 (Cache) 機制。
 
-**Request Body:**
-| 參數 | 類型 | 必填 | 說明 |
-| :--- | :--- | :--- | :--- |
-| `current_page` | Integer | 是 | 當前頁面編號 (對照見下表) |
-| `firmware_version` | String | 是 | 韌體版本號 |
-| `model` | String | 是 | 機台型號 (如 STAR-V1) |
-| `temperature` | Float | 否 | 環境溫度 |
-| `door_status` | Integer | 否 | 門狀態 (0: 關, 1: 開) |
-| `log` | String | 否 | 事件日誌訊息 |
-| `log_level` | String | 否 | 日誌等級 (info/warn/error) |
-| `log_payload` | Object | 否 | 額外日誌上下文 (JSON 對象) |
-
-**Response Body:**
-| 參數 | 類型 | 說明 |
-| :--- | :--- | :--- |
-| `success` | Boolean | 請求是否處理成功 |
-| `code` | Integer | 內部業務狀態碼 |
-| `message` | String | 回應訊息說明 |
-| `status` | String | 雲端指令代碼 (對照見下表) |
-
-### 狀態代碼對照表
-
-**頁面代碼 (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 (貨道同步)
-- `50`: reload B005 (基礎參數)
-- `51`: reboot (重啟)
-- `60`: reboot card machine (刷卡機重啟)
-- `61`: checkout (結帳)
-- `70`: unlock (解鎖)
-- `71`: lock (鎖定)
-- `72`: sellCode reload B023 (即期品)
-- `75`: exp reload B026 (效期)
-- `79`: read B050 (參數讀取)
-- `81`: sync timer status (B710)
-- `85`: reload B0552 (出貨腳本)
-
-```json
-{
-    "success": true,
-    "code": 200,
-    "message": "OK",
-    "status": "49"
-}
-```
-*   `status`: 若為字串 (如 "49") 代表有掛載指令，機台應執行對應動作。
-*   `202 Accepted`: 系統將以 202 或 200 回應，代表已進入 Redis Queue 異步處理。
+---
 
 > [!CAUTION]
-> **身份識別機制**：禁止在 Body 帶入 `machine` 或 `key`。系統完全透過 `Bearer Token` 識別機台身份並綁定資料。
+> **身份識別機制**：禁止在 Body 傳輸 `machine` 或 `key`。系統強制透過 `Bearer Token` 識別並自動關聯資料。