193 lines
4.6 KiB
Markdown
193 lines
4.6 KiB
Markdown
# 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`: 返回的業務數據，根據接口不同而異 |