star-cloud/.agents/rules/api-rules.md

trigger

trigger
always_on

Backend API Specification (api-rules.md)

---

🚀 1. 目標範圍與分類

本系統 API 分為兩大類，遵循不同的設計慣例：

• Admin/Web API (/api/v1/...): 供後台管理介面、APP UI 使用。遵循標準 RESTful 與 JSON 結構。
• Machine IoT API (/api/app/...): 供販賣機、計時器等硬體端點使用。需相容既有 PDF 規格（如 B010, B600），欄位命名多為 req1, req2 或特定縮寫。

---

🔐 2. 認證與安全性

• Admin API: 採用 Laravel Sanctum (Session/Token) 認證。
• Machine IoT API:
  • 核心機制: 必須在 Header 帶入 Authorization: Bearer <api_token> 進行身份驗證。
  • Phase 1 (兼容模式): 若為相容既有機動硬體，可暫時接受 Request 包含 key 欄位，但後端應過渡至 Bearer 驗證。
  • 安全性強化: 改用每台機台專屬的 api_token (透過 B010 初始化或派發)，並配合 serial_no (即 workid) 進行資料歸屬權驗證。
• 傳輸安全: 必須強制使用 HTTPS。

---

📦 3. 回應格式規範

3.1 標準回應 (Admin/Web API)

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": { ... }
}

3.2 IoT 指令回應 (B010/B055 等)

機台端通常透過 response 的 status 欄位或特定的 message 字串來執行動作：

• 成功但有指令: {"status": "49", "message": "reload B017"}
• 純資料回傳: 直接返回對象陣列或 PDF 定義的欄位。

---

🛠️ 4. 主要 Endpoints 與命名慣例

4.1 管理類 (Admin UI)

• GET /api/v1/users: 管理員清單
• GET /api/v1/machines: 機台清單
• PUT /api/v1/machines/{id}: 更新機台參數
• 遵循 kebab-case 路由與 snake_case JSON 欄位。

4.2 終端類 (IoT / Machine) — 須嚴格遵守 PDF 規格

• API 識別碼 (workid): URL 中的 {workid} 參數固定為該 API 的功能代碼 (如 B010, B017, B600)，不隨機台改變。
• 機台識別方式:
  1. Header: 透過 Authorization: Bearer <api_token> 識別。
  2. Request Body: 透過 machine 或 serial_no 等欄位識別具體機台。
• 主要 Endpoint 範例:
  • 心跳上報 (B010): POST /api/app/machine/status/B010
  • 交易回傳 (B600): POST /api/app/B600 (Body 欄位 req2 為機台編號)
  • 貨道庫存 (B017): POST /api/app/machine/reload_msg/B017
  • 遠端出貨 (B055): POST /api/app/machine/dispense/B055

---

⚡ 5. 高併發處理與隊列

為了系統穩定性，以下 API 嚴禁直寫資料庫，必須進入 Redis Queue 異步處理：

1. B010: 心跳上傳（每 5-10 秒一次）。
2. B600 / B602: 交易與出貨紀錄。
3. B220: 零錢機庫存變動。
4. B710: 計時器狀態同步。

後端應立即回傳 202 Accepted 或業務定義的成功碼，由 Job 背景完成數據持久化。

---

📄 6. 交付與文件

• OpenAPI: 應區分 admin.yaml 與 iot.yaml。
• Postman: 提供帶有環境變數（機台金鑰、Base URL）的 Collection。