diff --git a/.agents/rules/api-rules.md b/.agents/rules/api-rules.md index fbd203d..af9fe18 100644 --- a/.agents/rules/api-rules.md +++ b/.agents/rules/api-rules.md @@ -2,208 +2,82 @@ trigger: always_on --- -# Backend API Specification (backend.md) +# Backend API Specification (api-rules.md) --- -## 目標範圍 +## 🚀 1. 目標範圍與分類 -* 使用 Laravel (RESTful API) -* 資料庫:MySQL(migration + seeder) -* 提供給現有 Android 團隊的完整 API 規格(JSON 格式) +本系統 API 分為兩大類,遵循不同的設計慣例: + +* **Admin/Web API (`/api/v1/...`)**: 供後台管理介面、APP UI 使用。遵循標準 RESTful 與 JSON 結構。 +* **Machine IoT API (`/api/app/...`)**: 供販賣機、計時器等硬體端點使用。需相容既有 PDF 規格(如 B010, B600),欄位命名多為 `req1`, `req2` 或特定縮寫。 --- -## 認證與安全 +## 🔐 2. 認證與安全性 -* 採用 JWT 或 Laravel Sanctum -* 所有需要授權的 API 回傳 401/403 規範 -* Error 格式: - -```json -{ - "success": false, - "code": 401, - "message": "Unauthorized", - "errors": null -} -``` +* **Admin API**: 採用 **Laravel Sanctum (Session/Token)** 認證。 +* **Machine IoT API**: + * **核心機制**: 必須在 Header 帶入 `Authorization: Bearer ` 進行身份驗證。 + * **Phase 1 (兼容模式)**: 若為相容既有機動硬體,可暫時接受 Request 包含 `key` 欄位,但後端應過渡至 Bearer 驗證。 + * **安全性強化**: 改用每台機台專屬的 `api_token` (透過 B010 初始化或派發),並配合 `serial_no` (即 `workid`) 進行資料歸屬權驗證。 +* **傳輸安全**: 必須強制使用 **HTTPS**。 --- -## 一般回應格式 - -成功: +## 📦 3. 回應格式規範 +### 3.1 標準回應 (Admin/Web API) ```json { "success": true, "code": 200, "message": "OK", - "data": { } + "data": { ... } } ``` -錯誤:同上 Error 範例 +### 3.2 IoT 指令回應 (B010/B055 等) +機台端通常透過 response 的 `status` 欄位或特定的 `message` 字串來執行動作: +* **成功但有指令**: `{"status": "49", "message": "reload B017"}` +* **純資料回傳**: 直接返回對象陣列或 PDF 定義的欄位。 --- -## API 清單(建議先開發順序) +## 🛠️ 4. 主要 Endpoints 與命名慣例 -1. Auth (登入/登出/註冊/權杖) -2. User / Profile -3. Device / Machine (機台管理、狀態回傳、日誌) -4. Order / ShoppingCart(若需) -5. Notification / Push 訊息 -6. Activity / Campaign -7. Report / Analytics -8. Admin CRUD for resources +### 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 ` 識別。 + 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` --- -## 主要 Endpoints 範例 +## ⚡ 5. 高併發處理與隊列 -### 1) Auth +為了系統穩定性,以下 API **嚴禁直寫資料庫**,必須進入 **Redis Queue** 異步處理: +1. **B010**: 心跳上傳(每 5-10 秒一次)。 +2. **B600 / B602**: 交易與出貨紀錄。 +3. **B220**: 零錢機庫存變動。 +4. **B710**: 計時器狀態同步。 -* POST /api/v1/auth/login - - * request: - - ```json - {"email":"user@example.com","password":"pa55"} - ``` - - * response: - - ```json - {"success":true,"code":200,"data":{"token":"...","user":{"id":1,"name":"..."}}} - ``` - -* POST /api/v1/auth/logout - - * header: Authorization: Bearer - * response: 200 - -* POST /api/v1/auth/refresh +後端應立即回傳 `202 Accepted` 或業務定義的成功碼,由 Job 背景完成數據持久化。 --- -### 2) User / Profile - -* GET /api/v1/users/{id} -* PUT /api/v1/users/{id} -* GET /api/v1/users (admin) - -Request / Response 均採 JSON,個資欄位請遵守最小授權原則。 - ---- - -### 3) Machine (機台) - -* **GET /api/v1/machines** - * Params: page, per_page, status -* **GET /api/v1/machines/{id}** -* **POST /api/v1/machines/{id}/logs** (IoT) - * 用於機台回傳日誌,後端固定走 **Redis Queue 異步寫入**。 - * 回傳 `202 Accepted` 表示任務已接收,由 `ProcessMachineLog` 背景處理。 - * Request Example: - ```json - { - "level": "info", - "message": "Temperature stabilized at 23C", - "context": { "temp": 23.0 } - } - ``` - ---- - -### 4) Orders / ShoppingCart - -* POST /api/v1/cart/add -* GET /api/v1/cart -* POST /api/v1/orders -* GET /api/v1/orders/{id} - -支付與第三方串接請另行設計 callback endpoint。 - ---- - -### 5) Notification - -* POST /api/v1/notifications/send (admin) -* GET /api/v1/notifications (user) - -Payload for push could include: title, body, target_user_ids, data - ---- - -### 6) Activity / Campaign - -* GET /api/v1/campaigns -* POST /api/v1/campaigns -* PUT /api/v1/campaigns/{id} - ---- - -### 7) Report / Analytics - -* GET /api/v1/reports/machines/summary?from=YYYY-MM-DD&to=YYYY-MM-DD -* GET /api/v1/reports/sales/summary - -Response should include aggregated numbers and paginated lists when needed. - ---- - -## Database 基本表(初步) - -* users -* roles -* machines -* machine_logs -* orders -* order_items -* carts -* notifications -* campaigns -* activity_logs -* translations (i18n) - -(每張表建議 migration 欄位、index、外鍵,請於開發前定稿) - ---- - -## API 規格輸出 - -* 建議產出 Swagger (OpenAPI 3.0) 與 Postman Collection -* 每個 endpoint 必要欄位、範例、error code、rate limit - ---- - -## 測試建議 - -* Unit tests:Laravel Feature tests for API -* Contract tests:與 Android 團隊一同建立 contract tests(或使用 Postman tests) - ---- - -## 部署與運營 - -* 建議使用 queue 與 cache(Redis)處理非同步任務 -* Logging: Sentry or similar -* 定期備份 MySQL - ---- - -## 交付項目清單 - -1. 完整 Laravel 專案(註冊、登入、ACL) -2. MySQL migration + seeders -3. Swagger/OpenAPI 文件 -4. Postman Collection -5. 後台管理系統(Star Cloud) -6. 測試報告 -7. 部署腳本與上線說明 - ---- - -*註:本檔為初版 backend.md,若要我把 Excel 的每一列功能自動轉成對應的 API endpoint(含 request/response 範例),我可以直接在此檔案中展開更詳細的 endpoint 清單。* \ No newline at end of file +## 📄 6. 交付與文件 +* **OpenAPI**: 應區分 `admin.yaml` 與 `iot.yaml`。 +* **Postman**: 提供帶有環境變數(機台金鑰、Base URL)的 Collection。 diff --git a/.agents/rules/framework.md b/.agents/rules/framework.md index 6d54f56..2dd951a 100644 --- a/.agents/rules/framework.md +++ b/.agents/rules/framework.md @@ -52,15 +52,24 @@ trigger: always_on * 優先使用 **Alpine.js** (`x-data`, `x-show`, `@click` 等) 在 HTML 標籤內完成簡單的 DOM 狀態切換與互動邏輯。 * 避免在 Blade 內撰寫冗長的 ` -@endsection diff --git a/resources/views/layouts/admin.blade.php b/resources/views/layouts/admin.blade.php index 0754491..8578075 100644 --- a/resources/views/layouts/admin.blade.php +++ b/resources/views/layouts/admin.blade.php @@ -39,7 +39,7 @@ x-cloak> -
+