# Order Service API Documentation

## 基础信息

- **服务名称**: order-service
- **端口**: 8082
- **基础路径**: `/api/orders`

---

## 1. 订单查询

### 1.1 订单列表（分页）
```
GET /api/orders
```

**Query Parameters:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页条数，默认10 |
| platform | string | 否 | 平台筛选 |
| shop_id | long | 否 | 店铺ID |
| order_status | string | 否 | 订单状态 |
| audit_status | string | 否 | 审核状态 |
| delivery_status | string | 否 | 发货状态 |
| keyword | string | 否 | 关键词搜索 |
| start_date | date | 否 | 开始日期 |
| end_date | date | 否 | 结束日期 |

**响应示例:**
```json
{
  "code": 200,
  "data": {
    "list": [{
      "id": 1,
      "shortId": "O20240401ABC123",
      "platformOrderSn": "TB123456789",
      "platform": "taobao",
      "shopName": "官方旗舰店",
      "receiverName": "张三",
      "receiverPhone": "13800138000",
      "totalAmount": 199.00,
      "orderStatus": "pending",
      "orderStatusText": "待处理",
      "auditStatus": "pending",
      "deliveryStatus": "pending",
      "createdAt": "2024-04-01 10:00:00"
    }],
    "total": 100,
    "currentPage": 1,
    "lastPage": 10
  },
  "message": "success"
}
```

### 1.2 订单详情
```
GET /api/orders/{id}
```

---

## 2. 订单审核

### 2.1 单个审核
```
POST /api/orders/{id}/audit
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | approve/reject |
| comment | string | 否 | 审核意见（驳回时必填）|

### 2.2 批量审核
```
POST /api/orders/batch-audit
```
```json
{
  "orderIds": [1, 2, 3],
  "action": "approve",
  "comment": "批量审核通过"
}
```

---

## 3. 仓库与发货

### 3.1 设置仓库
```
PUT /api/orders/{id}/warehouse
```
```json
{
  "warehouseId": 1,
  "expressCompany": "顺丰速运",
  "expressName": "SF"
}
```

### 3.2 订单发货
```
POST /api/orders/{id}/ship
```
```json
{
  "expressCompany": "顺丰速运",
  "expressNo": "SF123456789",
  "isPrint": true
}
```
**说明:** 发货时会自动扣减库存

---

## 4. 订单状态流转

### 4.1 订单完成
```
POST /api/orders/{id}/complete
```

### 4.2 取消订单
```
POST /api/orders/{id}/cancel
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reason | string | 否 | 取消原因 |

**说明:** 只有待处理/审核中的订单可以取消，取消时会自动解锁库存

---

## 5. 批量操作

### 5.1 批量操作
```
POST /api/orders/batch-operation
```
```json
{
  "orderIds": [1, 2, 3],
  "operation": "ship",
  "data": {
    "expressCompany": "顺丰速运",
    "expressNo": "SF123456789"
  }
}
```
**operation 可选值:**
- `audit_approve`: 审核通过
- `audit_reject`: 审核驳回
- `set_warehouse`: 设置仓库
- `ship`: 发货
- `cancel`: 取消
- `delete`: 删除（仅已完成/已取消订单）

---

## 6. 拉取订单

### 6.1 从平台拉取订单
```
POST /api/orders/pull
```
```json
{
  "platform": "taobao",
  "shopId": 1,
  "pullType": "increment",
  "startTime": "2024-04-01 00:00:00",
  "endTime": "2024-04-01 23:59:59"
}
```
**pullType 可选值:**
- `all`: 全量拉取
- `increment`: 增量拉取
- `specify`: 指定订单（需配合orderIds）

---

## 7. 统计与导出

### 7.1 订单统计
```
GET /api/orders/statistics
```

### 7.2 仪表盘统计
```
GET /api/orders/dashboard
```

### 7.3 导出订单
```
GET /api/orders/export
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| export_type | string | 否 | excel/csv，默认excel |

---

## 8. 辅助接口

### 8.1 更新备注
```
PUT /api/orders/{id}/remark
```

### 8.2 获取操作日志
```
GET /api/orders/{id}/logs
```

### 8.3 同步到平台
```
POST /api/orders/{id}/sync
```

### 8.4 状态选项
```
GET /api/orders/options/status
GET /api/orders/options/audit-status
GET /api/orders/options/delivery-status
GET /api/orders/options/platforms
GET /api/orders/options/shops
```

---

## 订单状态说明

### 订单状态 (order_status)
| 状态值 | 显示文本 | 说明 |
|--------|----------|------|
| pending | 待处理 | 订单刚创建/拉取，待审核 |
| auditing | 审核中 | 审核通过，待发货 |
| shipped | 已发货 | 已发货出库 |
| completed | 已完成 | 交易完成 |
| cancelled | 已取消 | 订单取消 |

### 审核状态 (audit_status)
| 状态值 | 显示文本 |
|--------|----------|
| pending | 待审核 |
| approved | 已通过 |
| rejected | 已驳回 |

### 发货状态 (delivery_status)
| 状态值 | 显示文本 |
|--------|----------|
| pending | 待发货 |
| delivered | 已发货 |

---

## 错误码

| code | 说明 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 / 业务状态不允许 |
| 404 | 订单不存在 |
| 500 | 系统异常 |