Files

wurenzhi 136c2fa579 feat: 初始化项目结构并添加核心功能模块

- 新增文档模板和导航结构
- 实现服务器基础API路由和控制器
- 添加扩展插件配置和前端框架
- 引入多租户和权限管理模块
- 集成日志和数据库配置
- 添加核心业务模型和类型定义

2026-03-17 22:07:19 +08:00

10 KiB

Raw Blame History

订单管理 API 文档

1. 概述

本文档描述了订单管理服务的 API 接口，包括订单的创建、查询、更新、删除，以及订单状态流转、售后处理等功能。

2. 基础信息

API 基础路径: /api/v1/orders
认证方式: JWT Token + Trace Context
权限要求: 不同接口需要不同的权限，详见各接口说明

3. 核心接口

3.1 订单管理

创建订单

方法: POST
路径: /api/v1/orders
权限: order:write

请求体:

{
  "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"
}

响应:

{
  "success": true,
  "orderId": "ORD-12345-67890"
}

获取订单详情

方法: GET
路径: /api/v1/orders/:id
权限: order:read

响应:

{
  "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

请求体:

{
  "status": "SHIPPED",
  "fulfillment_status": "SHIPPED"
}

响应:

{
  "success": true,
  "message": "Order updated successfully"
}

删除订单

方法: DELETE
路径: /api/v1/orders/:id
权限: order:delete

响应:

{
  "success": true,
  "message": "Order deleted successfully"
}

获取订单列表

方法: GET
路径: /api/v1/orders
权限: order:read
查询参数:
- page: 页码 (默认: 1)
- pageSize: 每页数量 (默认: 20)
- status: 订单状态
- platform: 平台
- startDate: 开始日期
- endDate: 结束日期

响应:

{
  "success": true,
  "data": {
    "orders": [/* 订单列表 */],
    "total": 100
  }
}

3.2 批量操作

批量更新订单

方法: PUT
路径: /api/v1/orders/batch
权限: order:write

请求体:

{
  "orderIds": ["ORD-1", "ORD-2"],
  "updates": {
    "status": "PAID"
  }
}

响应:

{
  "success": true,
  "data": {
    "success": 2,
    "failed": 0
  }
}

批量审核订单

方法: POST
路径: /api/v1/orders/batch/audit
权限: order:write
请求体:
```
{
  "orderIds": ["ORD-1", "ORD-2"]
}
```

响应:

{
  "success": true,
  "data": {
    "success": 2,
    "failed": 0
  }
}

批量发货

方法: POST
路径: /api/v1/orders/batch/ship
权限: order:write
请求体:
```
{
  "orderIds": ["ORD-1", "ORD-2"]
}
```

响应:

{
  "success": true,
  "data": {
    "success": 2,
    "failed": 0
  }
}

3.3 订单状态管理

订单状态流转

方法: POST
路径: /api/v1/orders/:id/status
权限: order:write

请求体:

{
  "status": "SHIPPED",
  "reason": "Order shipped"
}

响应:

{
  "success": true,
  "message": "Order status updated successfully"
}

标记订单为异常

方法: POST
路径: /api/v1/orders/:id/exception
权限: order:write
请求体:
```
{
  "reason": "Out of stock"
}
```

响应:

{
  "success": true,
  "message": "Order marked as exception"
}

自动改派订单

方法: POST
路径: /api/v1/orders/:id/reroute
权限: order:write

响应:

{
  "success": true,
  "message": "Order rerouted successfully"
}

重试异常订单

方法: POST
路径: /api/v1/orders/:id/retry
权限: order:write

响应:

{
  "success": true,
  "message": "Order retried successfully"
}

取消订单

方法: POST
路径: /api/v1/orders/:id/cancel
权限: order:write
请求体:
```
{
  "reason": "Customer cancelled"
}
```

响应:

{
  "success": true,
  "message": "Order cancelled successfully"
}

完成订单

方法: POST
路径: /api/v1/orders/:id/complete
权限: order:write

响应:

{
  "success": true,
  "message": "Order completed successfully"
}

3.4 售后管理

申请退款

方法: POST
路径: /api/v1/orders/:id/refund
权限: order:write

请求体:

{
  "reason": "Product damaged",
  "amount": 100
}

响应:

{
  "success": true,
  "refundId": "REF-12345"
}

审批退款

方法: POST
路径: /api/v1/orders/refund/:id/approve
权限: order:write

请求体:

{
  "approved": true,
  "note": "Refund approved"
}

响应:

{
  "success": true,
  "message": "Refund processed successfully"
}

申请售后

方法: POST
路径: /api/v1/orders/:id/after-sales
权限: order:write

请求体:

{
  "type": "REFUND",
  "reason": "Product damaged",
  "items": [{"skuId": "SKU001", "quantity": 1}]
}

响应:

{
  "success": true,
  "serviceId": "SVC-12345"
}

处理售后申请

方法: POST
路径: /api/v1/orders/after-sales/:id/process
权限: order:write

请求体:

{
  "action": "APPROVE",
  "note": "After-sales service approved"
}

响应:

{
  "success": true,
  "message": "After-sales service processed successfully"
}

3.5 订单同步

平台 Webhook 接收

方法: POST
路径: /api/v1/orders/webhook/:platform
说明: 接收来自不同平台的订单 Webhook 推送

响应:

{
  "success": true,
  "orderId": "ORD-12345-67890"
}

手动触发同步

方法: POST
路径: /api/v1/orders/sync
权限: trade:write

请求体:

{
  "platform": "SHOPIFY",
  "shopId": "shop1"
}

响应:

{
  "success": true,
  "message": "Manual sync triggered for SHOPIFY"
}

获取订单统计

方法: GET
路径: /api/v1/orders/stats
权限: trade:read

响应:

{
  "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：

获取认证Token
设置Trace Context头
调用相应的API端点
处理响应和错误

8.2 第三方平台集成

第三方平台可以通过Webhook方式与订单系统集成：

在平台设置Webhook URL: https://your-domain.com/api/v1/orders/webhook/:platform
确保包含必要的认证信息
按照平台的格式发送订单数据

9. 监控与日志

所有API调用都有详细的日志记录
关键操作有审计追踪
性能指标实时监控
异常情况自动告警

10. 版本控制

v1: 当前版本
后续版本将通过URL路径进行区分

10 KiB Raw Blame History Unescape Escape

订单管理 API 文档

1. 概述

2. 基础信息

3. 核心接口

3.1 订单管理

创建订单

获取订单详情

更新订单

删除订单

获取订单列表

3.2 批量操作

批量更新订单

批量审核订单

批量发货

3.3 订单状态管理

订单状态流转

标记订单为异常

自动改派订单

重试异常订单

取消订单

完成订单

3.4 售后管理

申请退款

审批退款

申请售后

处理售后申请

3.5 订单同步

平台 Webhook 接收

手动触发同步

获取订单统计

4. 数据模型

4.1 订单模型

4.2 订单状态

4.3 支付状态

4.4 物流状态

5. 错误处理

6. 性能指标

7. 安全考虑

8. 集成指南

8.1 前端集成

8.2 第三方平台集成

9. 监控与日志

10. 版本控制

10 KiB

Raw Blame History