Files

2025-11-21 17:15:27 +08:00

3.8 KiB

Raw Permalink Blame History

trigger

trigger
always_on

Backend API Specification (backend.md)

目標範圍

使用 Laravel (RESTful API)
資料庫：MySQL（migration + seeder）
提供給現有 Android 團隊的完整 API 規格（JSON 格式）

認證與安全

採用 JWT 或 Laravel Sanctum
所有需要授權的 API 回傳 401/403 規範
Error 格式：

{
  "success": false,
  "code": 401,
  "message": "Unauthorized",
  "errors": null
}

一般回應格式

成功：

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

錯誤：同上 Error 範例

API 清單（建議先開發順序）

Auth (登入/登出/註冊/權杖)
User / Profile
Device / Machine (機台管理、狀態回傳、日誌)
Order / ShoppingCart（若需）
Notification / Push 訊息
Activity / Campaign
Report / Analytics
Admin CRUD for resources

主要 Endpoints 範例

1) Auth

POST /api/v1/auth/login

request:

{"email":"user@example.com","password":"pa55"}

response:

{"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

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:

{
  "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

交付項目清單

完整 Laravel 專案（註冊、登入、ACL）
MySQL migration + seeders
Swagger/OpenAPI 文件
Postman Collection
後台管理系統（Star Cloud）
測試報告
部署腳本與上線說明

註：本檔為初版 backend.md，若要我把 Excel 的每一列功能自動轉成對應的 API endpoint（含 request/response 範例），我可以直接在此檔案中展開更詳細的 endpoint 清單。

3.8 KiB Raw Permalink Blame History Unescape Escape