商城交易订单

交易订单是 Mall 模块的履约中心，承接用户下单、支付、发货、自提核销、售后状态和商家备注等动作。RuoYi Office 当前管理端已经提供订单列表、详情、发货和备注能力，后端由 yudao-module-mall/yudao-module-trade-server 提供接口。

本文从代码边界、订单状态、管理端操作和联调排查四个角度说明如何使用与二次开发交易订单。

模块边界

层	路径 / 接口
后端模块	`ruoyi-office/yudao-module-mall/yudao-module-trade-server`
控制器	`controller/admin/order/TradeOrderController.java`
查询服务	`service/order/TradeOrderQueryService`
更新服务	`service/order/TradeOrderUpdateService`
管理端页面	`apps/web-antd/src/views/mall/trade/order`
管理端 API	`apps/web-antd/src/api/mall/trade/order/index.ts`
接口前缀	`/admin-api/trade/order`

订单业务链路

管理后台不直接创建普通商城订单，它主要负责订单查询、履约处理和异常修正。订单创建通常来自会员端、商城端或业务系统调用交易服务。

管理端能力

订单列表页位于 src/views/mall/trade/order/index.vue，使用 Page auto-content-height 和 useVbenVxeGrid 实现。页面顶部已经关联两个 DocAlert：

/mall/trade-order/：交易订单说明。
/mall/trade-cart/：购物车说明，待后续补齐。

当前页面支持：

功能	前端入口	后端接口	权限
分页查询	订单列表	`GET /trade/order/page`	`trade:order:query`
订单统计	查询区域统计	`GET /trade/order/summary`	`trade:order:query`
订单详情	“详情”按钮	`GET /trade/order/get-detail`	`trade:order:query`
物流轨迹	详情页物流信息	`GET /trade/order/get-express-track-list`	`trade:order:query`
订单发货	“发货”按钮	`PUT /trade/order/delivery`	`trade:order:update`
商家备注	“备注”按钮	`PUT /trade/order/update-remark`	`trade:order:update`
订单核销	自提订单核销	`PUT /trade/order/pick-up-by-id` / `pick-up-by-verify-code`	`trade:order:pick-up`

列表数据组成

TradeOrderController#getOrderPage 不只是查询订单主表，还会组合三类数据后返回给前端：

TradeOrderDO：订单主信息，例如订单号、状态、金额、收货信息、支付信息。
TradeOrderItemDO：订单商品明细，前端展开行展示商品图、规格、数量和售后状态。
MemberUserRespDTO：下单会员和推广人信息，通过 MemberUserApi 查询。

因此二次开发订单列表时，不建议只改 Mapper 返回字段，还要同步检查 Convert、RespVO、前端 MallOrderApi.Order 类型和表格列配置。

状态与金额字段

订单页会展示多种状态和金额，常见字段如下：

字段	含义	说明
`status`	订单状态	待支付、待发货、已发货、已完成、已取消等
`payStatus`	支付状态	与 Pay 模块回调相关
`afterSaleStatus`	售后状态	商品项和订单维度均可能使用
`totalPrice`	商品原价	单位为分，前端使用 `fenToYuan` 展示
`discountPrice`	优惠金额	包含活动、优惠券、会员等优惠
`deliveryPrice`	运费	配送模板计算结果
`adjustPrice`	订单调价	商家后台调整金额
`payPrice`	应付金额	最终支付金额

注意：金额在接口中通常以“分”为单位传输，页面展示前再转为“元”。新增字段时应保持这个约定，避免前后端重复换算。

发货与核销

订单支持快递发货和自提核销两类履约路径。

快递发货

列表页中只有满足以下条件的订单才显示“发货”入口：

deliveryType 为快递配送。
订单状态为待发货或已发货。

发货弹窗提交 TradeOrderDeliveryReqVO，至少需要订单编号、物流公司和物流单号。后端会调用 TradeOrderUpdateService#deliveryOrder 更新发货信息，并记录订单日志。

自提核销

自提订单可通过订单 ID 或核销码处理：

text

PUT /trade/order/pick-up-by-id?id={orderId}
PUT /trade/order/pick-up-by-verify-code?pickUpVerifyCode={code}
GET /trade/order/get-by-pick-up-verify-code?pickUpVerifyCode={code}

适合门店收银台、仓库前台或移动端扫码核销场景。二开时要注意 trade:order:pick-up 权限与当前登录用户门店范围的校验。

与支付、售后的关系

交易订单不是孤立模块，至少会和以下模块联动：

模块	关系
Pay 支付	订单支付成功后更新 `payStatus`、`payTime`、`payChannelCode` 等字段
Member 会员	订单展示会员昵称、头像；积分、余额、会员价也依赖会员能力
Product 商品	订单项保存 SPU/SKU 快照，避免商品后续修改影响历史订单
Promotion 营销	秒杀、拼团、优惠券、满减等会影响优惠金额和订单类型
After Sale 售后	售后状态影响订单项展示和退款流程

支付联调可参考支付功能开启。如果支付成功但订单仍停留在待支付，优先排查 Pay 回调、payNotifyJob 和交易订单更新日志。

二次开发建议

新增筛选条件：同步修改 TradeOrderPageReqVO、查询 Mapper/Service、useGridFormSchema。
新增列表列：先确认后端 RespVO 是否返回，再修改 useGridColumns 和 MallOrderApi.Order 类型。
新增订单动作：在 TradeOrderUpdateService 中封装业务校验，Controller 只保留参数接收和权限控制。
新增金额字段：后端统一以分存储和返回，前端展示用 fenToYuan。
新增状态流转：必须补充订单日志，方便客服、运营和开发排查。

排查清单

现象	优先检查
列表为空	菜单权限、租户数据、订单创建来源、查询条件
商品展开行无图或规格	订单项快照、商品图片 URL、SKU 属性转换
支付后状态不变	Pay 回调、`payNotifyJob`、交易订单支付回调逻辑
发货按钮不显示	配送方式、订单状态、当前用户权限
物流轨迹为空	物流公司配置、物流单号、第三方查询接口配置
金额显示异常	是否重复把分转换成元，或把元直接写入分字段

下一步

本页先补齐 /mall/trade-order/。后续建议继续迁移同一交易域下的：

/mall/trade-cart/：购物车与结算。
/mall/trade-aftersale/：售后与退款。
/mall/trade-brokerage/：分销推广。

商城交易订单 ​

模块边界 ​

订单业务链路 ​

管理端能力 ​

列表数据组成 ​

状态与金额字段 ​

发货与核销 ​

快递发货 ​

自提核销 ​

与支付、售后的关系 ​

二次开发建议 ​

排查清单 ​

下一步 ​