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 清單。*
|