简介

本技术文档聚焦 DouPHP 的订单服务，围绕订单生命周期管理、支付处理、物流跟踪与售后服务等核心业务展开。重点说明 OrderService 的职责边界、状态流转、支付回调处理、退款流程以及与支付、物流、用户服务的集成方式；并提供创建订单、支付确认、发货处理、订单取消等典型场景的开发示例。同时给出事务管理、并发控制、异常处理与性能优化策略，帮助开发者在扩展与维护中保持数据一致性与系统稳定性。

项目结构

订单相关代码按“入口控制器 → 前台/后台服务层 → 核心服务门面 → 领域子服务”分层组织：

• API 控制器负责路由与参数校验，调用前台或后台服务完成具体业务。
• 前台服务（结算与收银）封装下单、运费/优惠券计算、支付台账与状态推进。
• 后台服务提供订单列表、详情、发货、线下付款审核、批量操作等能力。
• 核心 OrderService 作为薄编排门面，组合购物车、状态机、库存、定时任务、结算选项等子服务，对外暴露稳定接口。

graph TB
subgraph "API 层"
AC["OrderController"]
CC["CashierController"]
OC["CheckoutController"]
CTC["CartController"]
end
subgraph "前台服务"
CS["CheckoutService"]
KS["CashierService"]
end
subgraph "核心服务门面"
OS["OrderService(核心)"]
end
subgraph "后台服务"
AOS["Admin OrderService"]
end
AC --> OS
CC --> KS
OC --> CS
CTC --> CS
CC --> OS
OC --> OS
AOS --> OS

核心组件

• 核心订单服务门面（OrderService）：聚合购物车查询、状态机、订单明细、库存守卫、定时任务与结算选项，统一对外签名，屏蔽内部复杂度。
• 前台结算服务（CheckoutService）：负责结算页数据组装、运费重算、优惠券试算与下单事务（含价格防篡改、库存校验、地址快照、优惠券核销、订单与明细写入）。
• 前台收银服务（CashierService）：负责收银台订单读取、余额+网关混合支付预览与执行、线下凭证保存与状态推进、货到付款处理。
• 后台订单服务（Admin OrderService）：提供订单列表筛选、详情组装、线下付款审核（通过/驳回）、发货与物流信息维护、批量删除与取消、自动任务触发、退款委托。
• API 控制器：将 HTTP 请求映射到上述服务，进行鉴权、参数校验与响应格式化。

架构总览

订单服务采用“薄门面 + 多子服务”的组合模式：

• 核心 OrderService 仅做组合与对外稳定签名，不直接持有复杂业务细节。
• 状态机、库存、购物车、定时任务、结算选项分别由独立子服务实现，便于测试与演进。
• 前台/后台服务面向不同使用方，复用核心门面能力，避免重复逻辑。
• 支付与物流通过 PaymentService 与插件体系解耦，订单只关注结果与状态推进。

classDiagram
class OrderService {
+getCart(user_id)
+clearCart(user_id)
+changeStatus(order_sn, new_status)
+writePayId(order_sn, pay_id)
+createOrderSn(user_sn)
+getOrderItem(order_id, user_id)
+checkStock(module, item_id, number)
+realTimeStock(module, item_id)
+autoCancelOrder()
+autoUpdateAftersaleStatus()
+autoUpdateComment()
+getPaymentList()
+getShippingList()
+payTimeLimit(created_at, short, only_number)
+retryPaidEffects(order_sn)
+adminRefund(order_id, amount, remark)
}
class CheckoutService {
+getCheckoutData(userId, mode)
+recalculateShipping(uniqueId, itemAmount, couponSession)
+applyCoupon(couponId, cart, shippingFee, userId)
+createOrder(userId, form)
}
class CashierService {
+getCashierOrder(userId, orderSn)
+getPayOrder(userId, orderSn)
+previewWalletSplit(userId, order)
+payWithWalletAndGateway(userId, orderSn)
+savePayEvidence(userId, orderSn, paymentSn, payEvidencePath)
+submitCod(userId, orderSn, paymentSn)
}
class Admin_OrderService {
+buildOrderListData(input)
+buildOrderViewData(orderId)
+payCheck(orderId)
+payReject(orderId, reason)
+tracking(data)
+action(data)
+processRefund(orderId, amount, remark)
+runAutoTasks()
}
OrderService <.. CheckoutService : "被调用"
OrderService <.. CashierService : "被调用"
OrderService <.. Admin_OrderService : "被调用"

详细组件分析

核心订单服务门面（OrderService）

• 职责：聚合购物车、状态机、订单明细、库存守卫、定时任务与结算选项，对外提供稳定的方法签名。
• 关键能力：
  • 购物车：获取与清空购物车、积分展示。
  • 状态机：变更订单状态、写支付方式、生成订单号、分销奖励派发、重试付款后联动。
  • 订单明细：获取订单条目视图、判断是否可评价。
  • 库存：校验库存、实时可售库存。
  • 定时任务：自动取消未付款、自动更新售后标记、自动评价。
  • 结算选项：获取支付方式/配送方式列表、时间限制文案。
  • 后台退款：占位方法，实际由各支付插件实现。

前台结算服务（CheckoutService）

• 职责：结算页数据组装、运费重算、优惠券试算与下单事务。
• 关键流程：
  • 结算数据：从购物车装配数据，计算运费，加载默认收货信息与可用优惠券。
  • 运费重算：根据配送插件配置与金额阈值计算运费。
  • 优惠券试算：基于资格谓词计算抵扣金额并缓存会话。
  • 下单事务：
    • 库存校验与价格防篡改验证。
    • 生成订单号，开启事务。
    • 积分兑换扣减（如适用）。
    • 优惠券核销与明细写入。
    • 计算运费与订单金额，记录分销奖励比例。
    • 写入订单、订单明细、收货地址快照、优惠券明细。
    • 可选同步更新会员默认收货信息。
    • 提交事务；对 0 元订单直接推进到已支付。
    • 清理购物车。
    • 异常回滚并记录日志。

flowchart TD
Start(["开始: createOrder"]) --> LoadCart["加载购物车"]
LoadCart --> CartEmpty{"购物车为空?"}
CartEmpty --> |是| ReturnEmpty["返回错误: 购物车为空"]
CartEmpty --> |否| StockCheck["逐项库存校验"]
StockCheck --> StockOk{"库存通过?"}
StockOk --> |否| ReturnStock["返回错误: 库存不足"]
StockOk --> PriceCheck["价格防篡改验证"]
PriceCheck --> PriceOk{"价格一致?"}
PriceOk --> |否| ReturnPrice["返回错误: 价格变动"]
PriceOk --> TxnBegin["开启事务"]
TxnBegin --> PointMode{"积分兑换?"}
PointMode --> |是| DeductPoint["扣减积分"]
PointMode --> |否| CouponFlow["进入优惠券流程"]
DeductPoint --> CouponFlow
CouponFlow --> ApplyCoupon["校验并核销优惠券"]
ApplyCoupon --> CalcShipping["计算运费"]
CalcShipping --> WriteOrder["写入订单/明细/地址/优惠券明细"]
WriteOrder --> ZeroOrder{"0元订单?"}
ZeroOrder --> |是| AutoPaid["推进到已支付"]
ZeroOrder --> |否| ClearCart["清理购物车"]
AutoPaid --> ClearCart
ClearCart --> TxnCommit["提交事务"]
TxnCommit --> End(["结束"])
PriceOk --> |异常| Rollback["回滚事务并记录日志"]
Rollback --> End

前台收银服务（CashierService）

• 职责：收银台订单读取、余额+网关混合支付、线下凭证保存与状态推进、货到付款。
• 关键流程：
  • 获取收银台/支付页订单：限定待付款且属于当前用户。
  • 混合支付预览：读取余额，计算余额抵扣与网关支付金额。
  • 混合支付执行：先尝试余额支付，若订单金额未结清则返回网关支付金额供控制器继续发起网关支付。
  • 线下凭证保存：更新订单支付方式与支付时间，附加凭证到支付台账，推进到等待确认。
  • 货到付款：立即标记支付成功并记录审计字段，后续由状态机决定是否自动完成。

sequenceDiagram
participant Client as "客户端"
participant Controller as "CashierController"
participant Service as "CashierService"
participant PaySvc as "PaymentService"
participant Status as "OrderStatusTransition"
Client->>Controller : 请求离线支付页
Controller->>Service : getPayOrder(userId, orderSn)
Service-->>Controller : 订单信息
Controller->>Service : savePayEvidence(userId, orderSn, paymentSn, path)
Service->>PaySvc : attachPayEvidence(paymentSn, path)
Service->>Status : changeStatus(AWAITING_CONFIRMATION)
Status-->>Service : 状态推进完成
Service-->>Controller : 成功
Controller-->>Client : 返回成功

后台订单服务（Admin OrderService）

• 职责：订单列表筛选与详情组装、线下付款审核（通过/驳回）、发货与物流信息维护、批量删除与取消、自动任务触发、退款委托。
• 关键流程：
  • 列表数据：支持用户名、状态、订单号、收件人、时间范围筛选，分页返回。
  • 详情数据：组装订单、支付历史、优惠券、收货地址、可重试支付标识等。
  • 线下付款审核：
    • 通过：标记支付成功，联动推进订单状态。
    • 驳回：先回退订单到待付款，再标记支付失败，允许用户重新上传凭证。
  • 发货处理：首次填写物流信息时推进到已完成并解锁库存；非首次仅更新物流信息。
  • 批量操作：批量删除订单与关联模块行；批量取消未付款订单（事务内更新订单、明细与关联模块状态）。
  • 自动任务：自动取消超时未付款、自动更新售后标记、自动评价。
  • 退款：委托核心订单服务，由支付插件实现。

sequenceDiagram
participant Admin as "管理员"
participant AdminSvc as "Admin OrderService"
participant PaySvc as "PaymentService"
participant Core as "OrderService(核心)"
participant DB as "数据库"
Admin->>AdminSvc : payCheck(orderId)
AdminSvc->>PaySvc : findActivePending(orderId)
PaySvc-->>AdminSvc : pending支付记录
AdminSvc->>PaySvc : markSucceeded(paymentSn, "")
PaySvc->>Core : changeStatus(PAID/COMPLETED)
Core->>DB : 更新订单状态
DB-->>Core : 成功
Core-->>PaySvc : 成功
PaySvc-->>AdminSvc : 成功
AdminSvc-->>Admin : 跳转详情页
Admin->>AdminSvc : payReject(orderId, reason)
AdminSvc->>Core : changeStatus(PENDING)
Core->>DB : 更新订单状态
AdminSvc->>PaySvc : markFailed(paymentSn, reason)
PaySvc-->>AdminSvc : 成功
AdminSvc-->>Admin : 跳转详情页

API 控制器与入口

• OrderController：承载小程序订单一级动作（如购物车首页），调用核心订单服务获取购物车。
• CheckoutController：结算页数据与下单提交，调用 CheckoutService 完成下单事务。
• CashierController：收银台与离线支付页，调用 CashierService 完成支付台账与状态推进。
• CartController：购物车增删改查，调用 CartService（由 CheckoutService 复用）完成购物车操作。

依赖关系分析

• 核心 OrderService 依赖多个子服务（购物车、状态机、订单明细、库存守卫、定时任务、结算选项），形成高内聚低耦合的结构。
• 前台服务（CheckoutService、CashierService）依赖核心 OrderService 与支付服务（PaymentService），以及用户统计、定价、优惠券资格等外部能力。
• 后台服务依赖核心 OrderService、支付服务与订单模型，提供管理与运营功能。
• API 控制器仅承担路由与参数校验，业务逻辑下沉至服务层，保证可扩展性与可测试性。

graph LR
OS["OrderService(核心)"] --> ST["OrderStatusTransition"]
OS --> CQ["OrderCartQuery"]
OS --> IQ["OrderItemQuery"]
OS --> SG["OrderStockGuard"]
OS --> SC["OrderScheduledTasks"]
OS --> CO["OrderCheckoutOptions"]
CS["CheckoutService"] --> OS
CS --> PS["PaymentService"]
CS --> PR["PricingService"]
CS --> CE["CouponEligibility"]
KS["CashierService"] --> OS
KS --> PS
KS --> UStats["UserStatsService"]
AOS["Admin OrderService"] --> OS
AOS --> PS

性能考虑

• 列表查询优化：后台订单列表通过条件构造器与分页减少全表扫描；收件人搜索走子查询命中索引。
• 事务粒度：下单事务包含所有关键写入，确保一致性；异常时回滚并记录详细日志，便于定位。
• 库存与价格校验前置：在事务外进行库存与价格校验，降低锁竞争与回滚成本。
• 异步与批处理：自动任务（取消、售后标记、评价）批量执行，减少频繁 IO。
• 缓存与会话：运费与优惠券金额暂存会话，减少重复计算；支付剩余时间文案通过工具方法快速生成。
• 插件化：支付方式与配送方式以插件形式接入，避免核心逻辑膨胀。

故障排查指南

• 下单失败：检查库存校验、价格防篡改、优惠券资格与钱包余额；查看日志中的异常堆栈与入参。
• 支付未生效：确认支付台账是否存在 pending 记录；线下凭证是否正确附加；后台审核是否通过。
• 发货异常：确认订单状态是否为待付款或已支付；物流信息是否重复填写；库存锁定是否释放。
• 批量取消失败：检查选中订单是否均为待付款；事务是否回滚；关联模块状态是否更新。
• 退款问题：确认支付插件是否实现退款接口；退款金额与备注是否正确传递。

结论

DouPHP 订单服务通过清晰的分层与模块化设计，实现了订单生命周期管理、支付处理、物流跟踪与售后服务的完整闭环。核心 OrderService 作为门面聚合各子服务，前台与后台服务各司其职，API 控制器专注路由与校验。事务机制、前置校验与插件化设计保障了数据一致性与系统扩展性。建议在实际开发中遵循现有模式，新增能力优先通过子服务或插件扩展，避免破坏核心门面契约。

附录

• 典型场景示例（开发指引）：
  • 创建订单：调用 CheckoutController.checkoutPost → CheckoutService.createOrder，注意库存与价格校验、事务回滚与 0 元订单自动支付。
  • 支付确认：调用 CashierController.pay → CashierService.savePayEvidence，或 CashierService.submitCod；后台通过 Admin OrderService.payCheck/payReject 审核。
  • 发货处理：调用 Admin OrderService.tracking，首次填写物流信息时推进到已完成并解锁库存。
  • 订单取消：调用 Admin OrderService.action(cancel_all)，事务内更新订单、明细与关联模块状态。
• 状态机要点：
  • 待付款（PENDING）→ 已支付（PAID）→ 已完成（COMPLETED）→ 可申请售后（aftersale_status=2）。
  • 线下付款需经管理员审核（AWAITING_CONFIRMATION）后再推进。
• 并发控制：
  • 库存校验前置，事务内写入；支付台账与订单状态通过幂等方法与唯一键保障一致性。
• 异常处理：
  • 下单失败记录详细日志；后台审核失败抛出领域异常并提示重试；批量操作捕获异常并回滚。