first commit

.agent/rules/api-rules.md

@@ -0,0 +1,222 @@
+---
+trigger: always_on
+---
+
+# Backend API Specification (backend.md)
+
+---
+
+## 目標範圍
+
+* 使用 Laravel (RESTful API)
+* 資料庫：MySQL（migration + seeder）
+* 提供給現有 Android 團隊的完整 API 規格（JSON 格式）
+
+---
+
+## 認證與安全
+
+* 採用 JWT 或 Laravel Sanctum
+* 所有需要授權的 API 回傳 401/403 規範
+* Error 格式：
+
+```json
+{
+  "success": false,
+  "code": 401,
+  "message": "Unauthorized",
+  "errors": null
+}
+```
+
+---
+
+## 一般回應格式
+
+成功：
+
+```json
+{
+  "success": true,
+  "code": 200,
+  "message": "OK",
+  "data": { }
+}
+```
+
+錯誤：同上 Error 範例
+
+---
+
+## API 清單（建議先開發順序）
+
+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
+
+---
+
+## 主要 Endpoints 範例
+
+### 1) Auth
+
+* 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 <token>
+  * response: 200
+
+* POST /api/v1/auth/refresh
+
+---
+
+### 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
+
+* PUT /api/v1/machines/{id}
+
+* DELETE /api/v1/machines/{id}
+
+* POST /api/v1/machines/{id}/status
+
+  * 用於下位機或 APP 回傳機台狀態
+  * request example:
+
+  ```json
+  {
+    "temperature": 23.4,
+    "status_code": "OK",
+    "firmware_version": "1.2.3",
+    "timestamp": "2025-11-20T15:00:00Z"
+  }
+  ```
+
+* GET /api/v1/machines/{id}/logs
+
+---
+
+### 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 清單。*