init

2026-02-02 14:43:39 +08:00
parent c85c6315dc
commit e13b25ffcd
8 changed files with 505 additions and 0 deletions
--- a/api.md
+++ b/api.md
@@ -0,0 +1,193 @@
+# API 接口文檔
+
+## 訂單管理系統 API 接口文檔
+
+### 1. 添加訂單
+
+#### 接口信息
+- **接口路徑**: `POST /api/orders`
+- **功能描述**: 添加新的訂單記錄
+- **請求格式**: JSON
+- **響應格式**: JSON
+
+#### 請求參數
+| 參數名 | 類型 | 必填 | 說明 |
+|--------|------|------|------|
+| customer_name | String | 是 | 客戶姓名 |
+| product_name | String | 是 | 商品名稱 |
+| quantity | Number | 是 | 商品數量，必須大於0 |
+| price | Number | 是 | 商品單價，必須大於0 |
+| status | String | 否 | 訂單狀態，默認為"pending" |
+
+#### 響應參數
+| 參數名 | 類型 | 說明 |
+|--------|------|------|
+| success | Boolean | 請求是否成功 |
+| message | String | 響應消息 |
+| data | Object | 返回的數據對象 |
+| data.id | Number | 新增訂單的ID |
+| data.customer_name | String | 客戶姓名 |
+| data.product_name | String | 商品名稱 |
+| data.quantity | Number | 商品數量 |
+| data.price | Number | 商品單價 |
+| data.status | String | 訂單狀態 |
+| data.created_at | String | 創建時間 |
+
+#### 成功響應示例
+```json
+{
+  "success": true,
+  "message": "訂單創建成功",
+  "data": {
+    "id": 6,
+    "customer_name": "陳八",
+    "product_name": "HomePod Mini",
+    "quantity": 1,
+    "price": 99.99,
+    "status": "pending",
+    "created_at": "2023-12-01 10:30:00"
+  }
+}
+```
+
+#### 失敗響應示例
+```json
+{
+  "success": false,
+  "message": "缺少必需字段或字段值無效"
+}
+```
+
+#### Curl 請求示例
+```bash
+curl -X POST http://localhost:3000/api/orders \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{
+    "customer_name": "陳八",
+    "product_name": "HomePod Mini",
+    "quantity": 1,
+    "price": 99.99,
+    "status": "pending"
+  }'
+```
+
+### 2. 查詢訂單列表
+
+#### 接口信息
+- **接口路徑**: `GET /api/orders`
+- **功能描述**: 查詢訂單列表，支持條件篩選和分頁
+- **請求格式**: Query String
+- **響應格式**: JSON
+
+#### 查詢參數
+| 參數名 | 類型 | 必填 | 默認值 | 說明 |
+|--------|------|------|--------|------|
+| page | Number | 否 | 1 | 頁碼 |
+| pageSize | Number | 否 | 10 | 每頁顯示數量 |
+| customerName | String | 否 | - | 客戶姓名模糊匹配 |
+| productName | String | 否 | - | 商品名稱模糊匹配 |
+| status | String | 否 | - | 訂單狀態精確匹配 |
+
+#### 響應參數
+| 參數名 | 類型 | 說明 |
+|--------|------|------|
+| success | Boolean | 請求是否成功 |
+| data | Object | 返回的數據對象 |
+| data.orders | Array | 訂單列表 |
+| data.pagination | Object | 分頁信息 |
+| data.pagination.page | Number | 當前頁碼 |
+| data.pagination.pageSize | Number | 每頁顯示數量 |
+| data.pagination.total | Number | 總記錄數 |
+| data.pagination.totalPages | Number | 總頁數 |
+
+#### 成功響應示例
+```json
+{
+  "success": true,
+  "data": {
+    "orders": [
+      {
+        "id": 1,
+        "customer_name": "張三",
+        "product_name": "iPhone 15",
+        "quantity": 1,
+        "price": 999.99,
+        "status": "completed",
+        "created_at": "2023-12-01 10:30:00"
+      },
+      {
+        "id": 2,
+        "customer_name": "李四",
+        "product_name": "MacBook Pro",
+        "quantity": 1,
+        "price": 1999.99,
+        "status": "pending",
+        "created_at": "2023-12-01 10:25:00"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 10,
+      "total": 2,
+      "totalPages": 1
+    }
+  }
+}
+```
+
+#### Curl 請求示例
+
+##### 查詢所有訂單（默認分頁）
+```bash
+curl "http://localhost:3000/api/orders"
+```
+
+##### 分頁查詢
+```bash
+curl "http://localhost:3000/api/orders?page=1&pageSize=5"
+```
+
+##### 按客戶姓名查詢
+```bash
+curl "http://localhost:3000/api/orders?customerName=張"
+```
+
+##### 按商品名稱查詢
+```bash
+curl "http://localhost:3000/api/orders?productName=iPhone"
+```
+
+##### 按狀態查詢
+```bash
+curl "http://localhost:3000/api/orders?status=pending"
+```
+
+##### 組合條件查詢
+```bash
+curl "http://localhost:3000/api/orders?page=1&pageSize=10&customerName=張&status=completed"
+```
+
+### 3. 錯誤碼說明
+
+| 錯誤碼 | 狀態碼 | 說明 |
+|--------|--------|------|
+| 400 | 400 Bad Request | 請求參數錯誤 |
+| 404 | 404 Not Found | 路由不存在 |
+| 500 | 500 Internal Server Error | 服務器內部錯誤 |
+
+### 4. 公共響應格式
+
+所有接口響應都遵循以下格式：
+
+```json
+{
+  "success": true/false,
+  "message": "響應消息",
+  "data": {}
+}
+```
+
+- `success`: 請求是否成功的布爾值
+- `message`: 響應消息，成功時可選，失敗時必填
+- `data`: 返回的業務數據，根據接口不同而異