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