529 lines
10 KiB
Markdown
529 lines
10 KiB
Markdown
|
# 订单管理 API 文档
|
|||
|
|
|
|||
|
|
## 1. 概述
|
|||
|
|
|
|||
|
|
本文档描述了订单管理服务的 API 接口，包括订单的创建、查询、更新、删除，以及订单状态流转、售后处理等功能。
|
|||
|
|
|
|||
|
|
## 2. 基础信息
|
|||
|
|
|
|||
|
|
- **API 基础路径**: `/api/v1/orders`
|
|||
|
|
- **认证方式**: JWT Token + Trace Context
|
|||
|
|
- **权限要求**: 不同接口需要不同的权限，详见各接口说明
|
|||
|
|
|
|||
|
|
## 3. 核心接口
|
|||
|
|
|
|||
|
|
### 3.1 订单管理
|
|||
|
|
|
|||
|
|
#### 创建订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"shop_id": "string",
|
|||
|
|
"platform": "SHOPIFY",
|
|||
|
|
"platform_order_id": "string",
|
|||
|
|
"customer_name": "string",
|
|||
|
|
"customer_email": "string",
|
|||
|
|
"shipping_address": {"street": "string", "city": "string"},
|
|||
|
|
"items": [{"skuId": "string", "title": "string", "price": 100, "quantity": 1}],
|
|||
|
|
"total_amount": 100,
|
|||
|
|
"currency": "USD",
|
|||
|
|
"status": "PAID",
|
|||
|
|
"payment_status": "COMPLETED",
|
|||
|
|
"fulfillment_status": "PENDING",
|
|||
|
|
"trace_id": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"orderId": "ORD-12345-67890"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 获取订单详情
|
|||
|
|
- **方法**: GET
|
|||
|
|
- **路径**: `/api/v1/orders/:id`
|
|||
|
|
- **权限**: `order:read`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"id": "ORD-12345-67890",
|
|||
|
|
"tenant_id": "tenant1",
|
|||
|
|
"shop_id": "shop1",
|
|||
|
|
"platform": "SHOPIFY",
|
|||
|
|
"platform_order_id": "12345",
|
|||
|
|
"customer_name": "Test Customer",
|
|||
|
|
"shipping_address": {"street": "123 Test St"},
|
|||
|
|
"items": [{"skuId": "SKU001", "title": "Test Product"}],
|
|||
|
|
"total_amount": 100,
|
|||
|
|
"currency": "USD",
|
|||
|
|
"status": "PAID",
|
|||
|
|
"payment_status": "COMPLETED",
|
|||
|
|
"fulfillment_status": "PENDING",
|
|||
|
|
"created_at": "2026-03-17T00:00:00.000Z",
|
|||
|
|
"updated_at": "2026-03-17T00:00:00.000Z"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 更新订单
|
|||
|
|
- **方法**: PUT
|
|||
|
|
- **路径**: `/api/v1/orders/:id`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "SHIPPED",
|
|||
|
|
"fulfillment_status": "SHIPPED"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order updated successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 删除订单
|
|||
|
|
- **方法**: DELETE
|
|||
|
|
- **路径**: `/api/v1/orders/:id`
|
|||
|
|
- **权限**: `order:delete`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order deleted successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 获取订单列表
|
|||
|
|
- **方法**: GET
|
|||
|
|
- **路径**: `/api/v1/orders`
|
|||
|
|
- **权限**: `order:read`
|
|||
|
|
- **查询参数**:
|
|||
|
|
- `page`: 页码 (默认: 1)
|
|||
|
|
- `pageSize`: 每页数量 (默认: 20)
|
|||
|
|
- `status`: 订单状态
|
|||
|
|
- `platform`: 平台
|
|||
|
|
- `startDate`: 开始日期
|
|||
|
|
- `endDate`: 结束日期
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"orders": [/* 订单列表 */],
|
|||
|
|
"total": 100
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 批量操作
|
|||
|
|
|
|||
|
|
#### 批量更新订单
|
|||
|
|
- **方法**: PUT
|
|||
|
|
- **路径**: `/api/v1/orders/batch`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"orderIds": ["ORD-1", "ORD-2"],
|
|||
|
|
"updates": {
|
|||
|
|
"status": "PAID"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"success": 2,
|
|||
|
|
"failed": 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 批量审核订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/batch/audit`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"orderIds": ["ORD-1", "ORD-2"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"success": 2,
|
|||
|
|
"failed": 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 批量发货
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/batch/ship`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"orderIds": ["ORD-1", "ORD-2"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"success": 2,
|
|||
|
|
"failed": 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 订单状态管理
|
|||
|
|
|
|||
|
|
#### 订单状态流转
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/status`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "SHIPPED",
|
|||
|
|
"reason": "Order shipped"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order status updated successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 标记订单为异常
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/exception`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"reason": "Out of stock"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order marked as exception"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 自动改派订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/reroute`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order rerouted successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 重试异常订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/retry`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order retried successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 取消订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/cancel`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"reason": "Customer cancelled"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order cancelled successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 完成订单
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/complete`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Order completed successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.4 售后管理
|
|||
|
|
|
|||
|
|
#### 申请退款
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/refund`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"reason": "Product damaged",
|
|||
|
|
"amount": 100
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"refundId": "REF-12345"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 审批退款
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/refund/:id/approve`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"approved": true,
|
|||
|
|
"note": "Refund approved"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Refund processed successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 申请售后
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/:id/after-sales`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "REFUND",
|
|||
|
|
"reason": "Product damaged",
|
|||
|
|
"items": [{"skuId": "SKU001", "quantity": 1}]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"serviceId": "SVC-12345"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 处理售后申请
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/after-sales/:id/process`
|
|||
|
|
- **权限**: `order:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"action": "APPROVE",
|
|||
|
|
"note": "After-sales service approved"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "After-sales service processed successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.5 订单同步
|
|||
|
|
|
|||
|
|
#### 平台 Webhook 接收
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/webhook/:platform`
|
|||
|
|
- **说明**: 接收来自不同平台的订单 Webhook 推送
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"orderId": "ORD-12345-67890"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 手动触发同步
|
|||
|
|
- **方法**: POST
|
|||
|
|
- **路径**: `/api/v1/orders/sync`
|
|||
|
|
- **权限**: `trade:write`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"platform": "SHOPIFY",
|
|||
|
|
"shopId": "shop1"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"message": "Manual sync triggered for SHOPIFY"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 获取订单统计
|
|||
|
|
- **方法**: GET
|
|||
|
|
- **路径**: `/api/v1/orders/stats`
|
|||
|
|
- **权限**: `trade:read`
|
|||
|
|
- **响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"status_counts": [
|
|||
|
|
{"status": "PAID", "count": 10},
|
|||
|
|
{"status": "SHIPPED", "count": 5}
|
|||
|
|
],
|
|||
|
|
"total_revenue": 1500
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 数据模型
|
|||
|
|
|
|||
|
|
### 4.1 订单模型
|
|||
|
|
|
|||
|
|
| 字段名 | 类型 | 描述 |
|
|||
|
|
|-------|------|------|
|
|||
|
|
| id | string | 订单ID |
|
|||
|
|
| tenant_id | string | 租户ID |
|
|||
|
|
| shop_id | string | 店铺ID |
|
|||
|
|
| platform | string | 平台 |
|
|||
|
|
| site | string | 站点 |
|
|||
|
|
| platform_order_id | string | 平台订单ID |
|
|||
|
|
| customer_name | string | 客户名称 |
|
|||
|
|
| customer_email | string | 客户邮箱 |
|
|||
|
|
| shipping_address | json | 收货地址 |
|
|||
|
|
| items | json | 订单商品 |
|
|||
|
|
| total_amount | decimal(15,2) | 总金额 |
|
|||
|
|
| currency | string | 货币 |
|
|||
|
|
| status | string | 订单状态 |
|
|||
|
|
| payment_status | string | 支付状态 |
|
|||
|
|
| fulfillment_status | string | 物流状态 |
|
|||
|
|
| exception_reason | string | 异常原因 |
|
|||
|
|
| auto_heal_status | string | 自愈状态 |
|
|||
|
|
| profit_snapshot | json | 利润快照 |
|
|||
|
|
| trace_id | string | 追踪ID |
|
|||
|
|
| created_at | datetime | 创建时间 |
|
|||
|
|
| updated_at | datetime | 更新时间 |
|
|||
|
|
|
|||
|
|
### 4.2 订单状态
|
|||
|
|
|
|||
|
|
- **UNPAID**: 未支付
|
|||
|
|
- **PAID**: 已支付
|
|||
|
|
- **PENDING_AUDIT**: 待审核
|
|||
|
|
- **WAITING_SHIPMENT**: 待发货
|
|||
|
|
- **READY_TO_SHIP**: 准备发货
|
|||
|
|
- **PROCESSING**: 处理中
|
|||
|
|
- **SHIPPED**: 已发货
|
|||
|
|
- **DELIVERED**: 已送达
|
|||
|
|
- **CANCELLED**: 已取消
|
|||
|
|
- **EXCEPTION**: 异常
|
|||
|
|
|
|||
|
|
### 4.3 支付状态
|
|||
|
|
|
|||
|
|
- **PENDING**: 待支付
|
|||
|
|
- **COMPLETED**: 已完成
|
|||
|
|
- **REFUNDED**: 已退款
|
|||
|
|
- **FAILED**: 支付失败
|
|||
|
|
|
|||
|
|
### 4.4 物流状态
|
|||
|
|
|
|||
|
|
- **PENDING**: 待处理
|
|||
|
|
- **PROCESSING**: 处理中
|
|||
|
|
- **SHIPPED**: 已发货
|
|||
|
|
- **PARTIAL_SHIPPED**: 部分发货
|
|||
|
|
- **FAILED**: 发货失败
|
|||
|
|
|
|||
|
|
## 5. 错误处理
|
|||
|
|
|
|||
|
|
| 错误码 | 描述 |
|
|||
|
|
|-------|------|
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未授权 |
|
|||
|
|
| 403 | 权限不足 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
## 6. 性能指标
|
|||
|
|
|
|||
|
|
- **订单创建**: < 200ms
|
|||
|
|
- **订单查询**: < 50ms (缓存命中) / < 100ms (缓存未命中)
|
|||
|
|
- **批量操作**: < 500ms (100个订单以内)
|
|||
|
|
- **状态流转**: < 100ms
|
|||
|
|
|
|||
|
|
## 7. 安全考虑
|
|||
|
|
|
|||
|
|
- 所有API端点都需要适当的权限验证
|
|||
|
|
- 敏感操作需要额外的安全检查
|
|||
|
|
- 订单数据需要加密存储
|
|||
|
|
- 防止SQL注入和XSS攻击
|
|||
|
|
|
|||
|
|
## 8. 集成指南
|
|||
|
|
|
|||
|
|
### 8.1 前端集成
|
|||
|
|
|
|||
|
|
前端应用可以通过以下步骤集成订单管理API：
|
|||
|
|
|
|||
|
|
1. 获取认证Token
|
|||
|
|
2. 设置Trace Context头
|
|||
|
|
3. 调用相应的API端点
|
|||
|
|
4. 处理响应和错误
|
|||
|
|
|
|||
|
|
### 8.2 第三方平台集成
|
|||
|
|
|
|||
|
|
第三方平台可以通过Webhook方式与订单系统集成：
|
|||
|
|
|
|||
|
|
1. 在平台设置Webhook URL: `https://your-domain.com/api/v1/orders/webhook/:platform`
|
|||
|
|
2. 确保包含必要的认证信息
|
|||
|
|
3. 按照平台的格式发送订单数据
|
|||
|
|
|
|||
|
|
## 9. 监控与日志
|
|||
|
|
|
|||
|
|
- 所有API调用都有详细的日志记录
|
|||
|
|
- 关键操作有审计追踪
|
|||
|
|
- 性能指标实时监控
|
|||
|
|
- 异常情况自动告警
|
|||
|
|
|
|||
|
|
## 10. 版本控制
|
|||
|
|
|
|||
|
|
- **v1**: 当前版本
|
|||
|
|
- 后续版本将通过URL路径进行区分
|