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