222 lines
3.8 KiB
Markdown
222 lines
3.8 KiB
Markdown
---
|
||
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 清單。* |