订单系统

概述

订单系统位于 yudao-module-mall 模块下的 yudao-module-trade-biz，负责商品交易的全生命周期管理。核心控制器为 AppTradeOrderController，路径前缀 /trade/order/。

订单生命周期

提交订单（结算） → 校验限购 → 创建订单 → 待支付
    ↓
支付成功 → 待发货 → 已发货 → 待收货 → 已完成 → 已评价
    ↓                    ↓
取消订单              申请售后 → 退款/退货

核心接口

1. 订单结算

接口：POST /app-api/trade/order/settlement

获取订单结算信息，包含商品金额、优惠金额、运费、最终支付价等。

// 请求体
{
  "items": [
    { "spuId": 1, "skuId": 10, "count": 2 }
  ],
  "couponId": null,           // 优惠券 ID
  "deliveryType": 1,          // 配送方式：1=快递，2=自提
  "addressId": null,          // 收货地址 ID
  "pointStatus": false        // 是否使用积分
}

返回关键字段：

字段	说明
price	商品原价
discountPrice	优惠金额
deliveryPrice	运费
payPrice	最终支付金额
items	结算商品列表（含活动价格）

2. 校验限购

接口：POST /app-api/trade/order/validateIsToBuy

创建订单前校验商品限购规则（活动库存、每人限购数量等）。

[
  { "spuId": 1, "skuId": 10, "count": 2 }
]

3. 创建订单

接口：POST /app-api/trade/order/create

{
  "items": [
    { "spuId": 1, "skuId": 10, "count": 2 }
  ],
  "couponId": null,
  "deliveryType": 1,
  "addressId": 100,
  "pointStatus": false,
  "remark": "请尽快发货"
}

返回：

{
  "id": 10001,        // 订单 ID
  "payOrderId": 20001 // 支付订单 ID
}

4. 订单列表

接口：POST /app-api/trade/order/page

支持按订单状态筛选分页查询。

5. 订单详情

接口：POST /app-api/trade/order/getOrderDetail

返回完整订单信息，包含：

• 订单基本信息（状态、金额、时间）
• 商品明细列表
• 物流信息
• 售后状态

6. 取消订单

接口：POST /app-api/trade/order/cancel

仅"待支付"状态的订单可以取消。

7. 删除订单

接口：POST /app-api/trade/order/delete

仅"已完成"或"已取消"状态的订单可以删除（逻辑删除）。

8. 确认收货

接口：POST /app-api/trade/order/receive

将订单状态更新为"已完成"。

9. 商品结算信息

接口：GET /app-api/trade/order/settlement-product?spuIds=1,2,3

用于商品列表/详情页，获取参与活动后的价格信息。此接口标记为 @PermitAll，无需登录。

售后系统

申请售后

接口：POST /app-api/trade/after-sale/create

售后类型：

• 仅退款：无需退货，直接退款
• 退货退款：退回货物后退款

售后列表

接口：POST /app-api/trade/after-sale/page

售后详情

接口：POST /app-api/trade/after-sale/get

取消售后

接口：POST /app-api/trade/after-sale/cancel

退货物流

接口：POST /app-api/trade/after-sale/delivery

填写退货物流公司和运单号。

售后日志

接口：POST /app-api/trade/after-sale-log/list

查看售后操作的完整记录。

物流相关

获取物流公司列表

接口：GET /app-api/trade/delivery/express/getDeliveryExpressList

返回所有可用的物流公司。

物流轨迹查询

通过 DeliveryExpressService 对接第三方物流查询服务：

服务商	配置键
快递鸟	kd-niao
快递100	kd100
阿里云快递API	ali-kdi（当前使用）

yudao:
  trade:
    express:
      client: ali_kdi
      ali-kdi:
        kdi-path: https://wuliu.market.alicloudapi.com/kdi
        app-code: xxx

订单评价

接口：POST /app-api/trade/order/item/createOrderItemComment

对订单中的每个商品项进行评价，支持上传图片和评分。

订单状态枚举

状态	值	可执行操作
待支付	0	支付、取消
待发货	10	退款（申请售后）
已发货	20	确认收货、退款/退货
已完成	30	评价、申请售后、删除
已取消	40	删除

订单超时配置

yudao:
  trade:
    order:
      pay-expire-time: 24h      # 未支付自动取消：24 小时
      receive-expire-time: 14d  # 发货后自动确认收货：14 天
      comment-expire-time: 7d   # 完成后自动好评：7 天

交易配置

接口：GET /app-api/trade/config/get

返回售后原因配置：

{
  "afterSaleRefundReasons": ["不想买了", "价格太贵", ...],
  "afterSaleReturnReasons": ["质量问题", "与描述不符", ...]
}

前端订单流程

// 1. 结算 - 获取价格信息
const settlement = await post('trade/order/settlement', { items, addressId, ... })

// 2. 校验限购
await post('trade/order/validateIsToBuy', [{ spuId, skuId, count }])

// 3. 创建订单
const { id, payOrderId } = await post('trade/order/create', { ... })

// 4. 发起支付（调用微信支付/钱包支付）
await payOrder(payOrderId)

// 5. 支付成功回调 → 更新订单状态为已支付

支付回调

接口：POST /app-api/trade/order/update-paid

由支付模块在支付成功后回调，更新订单状态。

分销佣金

订单系统集成了分销佣金功能，通过 BrokerageUserServiceApi 接口与分销模块交互。用户下单后，系统自动计算并记录推广佣金。