makemd/archive/handover/order-api.md

# 订单管理 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路径进行区分