272 lines
4.8 KiB
Markdown
272 lines
4.8 KiB
Markdown
# 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 | 系统异常 |
|