sky121113 15b975efac [FEAT] 新增員工卡管理模組與 B012 API 文檔完善

1. 新增員工卡 (staff_cards) 與員工卡感應日誌 (staff_card_logs) 模型與遷移檔。
2. 實作 StaffCardController 與相關管理介面，支援狀態切換與 CRUD。
3. 擴充 routes/web.php 加入員工卡管理路由。
4. 更新 api-docs.php 文檔，補全 B012 (Unified Sync) 的商品同步回應範例。
5. 實作 PaymentTypeSeeder 並整合至 DatabaseSeeder 以標準化支付類型。
6. 優化銷售中心訂單標籤與倉庫機台庫存顯示邏輯。
7. 側邊欄選單加入員工卡管理入口。
8. 重構 TransactionService 以支援員工卡工作階段 (session_token) 驗證。

2026-05-05 14:06:43 +08:00

3.9 KiB

Raw Blame History

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 規格（如 B017, 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 (透過 B014 初始化或派發)，並配合 serial_no (即 workid) 進行資料歸屬權驗證。
傳輸安全: 必須強制使用 HTTPS。

📦 3. 回應格式規範

3.1 標準回應 (Admin/Web API)

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

3.2 IoT 指令回應 (B017/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 的功能代碼 (如 B017, B600)，不隨機台改變。
機台識別方式:
1. Header (推薦): 透過 Authorization: Bearer <api_token> 識別。針對 B017 等端點，雲端將自動關聯對應機台，不需額外帶入機台識別參數。
2. Request Body (相容/特定模式): 透過 machine 或 serial_no 等欄位識別。主要用於 B000 登入或尚未取得 Token 的引導階段 (如 B014)。
主要 Endpoint 範例:
- 交易回傳 (B600): POST /api/app/B600 (Body 欄位 req2 為機台編號)
- 貨道庫存 (B017): GET /api/app/machine/reload_msg/B017
- 遠端出貨 (B055): POST /api/app/machine/dispense/B055

⚡ 5. IoT 高併發流向與 MQTT Gateway 整合

為了系統穩定性與高吞吐量，機台通訊的架構依循以下規範，嚴禁直寫資料庫：

5.1 MQTT 通訊端點 (高頻與事件驅動)

以下高頻或即時事件，未來將全面改採 MQTT 協議，透過 EMQX 與 Go Gateway 橋接：

心跳事件：機台發布至 machine/{serial_no}/heartbeat。
異常與狀態 (B013)：機台發布至 machine/{serial_no}/error。
交易紀錄 (B600/B602)：機台發布至 machine/{serial_no}/transaction，推薦使用 action: finalize 整合上報。

處理管線： 機台 ➜ EMQX ➜ Go Gateway ➜ Redis List (mqtt_incoming_jobs) ➜ Laravel daemon (mqtt:listen) ➜ Job 異步寫入 DB

5.2 HTTP 通訊端點 (資料拉取與特殊事件)

基於歷史相容、大檔傳輸（如 B012 商品同步）或高度安全性（如 B014 金鑰下載）的端點，維持使用 HTTP REST API。若此類 API 產生寫入行為，後端應盡可能立即回傳 202 Accepted，並透過 Laravel Job 在背景完成數據持久化。

📄 6. 交付與文件

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

3.9 KiB Raw Blame History Unescape Escape