订单管理API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

订单管理API

简介

本文件面向电商平台开发者，系统化梳理订单管理模块的 API 能力，覆盖购物车、结算下单、收银台支付、我的订单、工作台（发货/核销）等核心流程。文档基于路由定义与各控制器实现，给出接口清单、参数约定、返回结构与调用时序，并补充订单状态机与一致性保障要点。

项目结构

订单相关 API 采用“路由 + 子控制器”组织方式，统一以 route=order 为入口，按业务域拆分子控制器：

购物车：order/cart/*
结算下单：order/checkout/*
收银台支付：order/cashier/*
我的订单：order/user/*
工作台（发货/核销）：order/work/*

graph TB
R["路由: api/route/order.php"] --> OC["OrderController<br/>购物车首页(兼容)"]
R --> CC["CartController<br/>购物车增删改查"]
R --> ChC["CheckoutController<br/>结算页/下单/优惠券/运费重算"]
R --> CasC["CashierController<br/>收银台/离线支付凭证"]
R --> UC["UserController<br/>我的订单列表/详情/取消"]
R --> WC["WorkController<br/>工作台: 列表/详情/取消/审核/物流"]

图表来源

api/route/order.php:39-87

章节来源

api/route/order.php:15-87

核心组件

路由层：集中声明 order 子模块路由与 HTTP 方法映射。
控制器层：负责鉴权、参数校验、调用服务层并格式化响应。
服务层：
- CartService：购物车加购、数量更新、删除、库存与规格校验。
- CheckoutService：结算数据组装、创建订单、运费与优惠券重算。
- CashierService：收银台订单获取、离线支付流水生成与凭证上传、货到付款处理。
- OrderStatusTransition：订单状态机，封装状态迁移、事件派发与联动。
基础设施：
- OrderStatus：订单状态枚举与迁移规则。
- PaymentService：支付台账（dou_order_payment）与凭证附件。

章节来源

api/controller/order/CartController.php:30-199
api/controller/order/CheckoutController.php:34-260
api/controller/order/CashierController.php:34-177
api/controller/order/UserController.php:30-131
api/controller/order/WorkController.php:32-192
front/service/order/CartService.php:29-204
front/service/order/CashierService.php:45-261
_'/module/order/core/service/order/OrderStatusTransition.php:27-152
core/foundation/order/OrderStatus.php

架构总览

订单 API 遵循“控制器薄、服务厚”的分层设计：

控制器只做鉴权、入参清洗、调用服务与响应包装。
服务层聚合领域逻辑（库存、定价、优惠、运费、支付、状态机）。
状态机保证订单状态变更的合法性与可追溯性，并在必要时自动推进到完成态。

sequenceDiagram
participant C as "客户端"
participant R as "路由(order.php)"
participant Ctrl as "控制器"
participant Svc as "服务层"
participant DB as "数据库"
participant Pay as "支付服务"
participant State as "状态机"
C->>R : 请求 /api/?route=order/...
R->>Ctrl : 分发到对应控制器动作
Ctrl->>Svc : 执行业务(加购/下单/支付/查询)
Svc->>DB : 读写订单/购物车/支付记录
alt 需要支付
Svc->>Pay : 创建支付/标记成功
Pay-->>Svc : 支付结果
end
Svc->>State : changeStatus(合法迁移)
State-->>DB : 持久化状态与日志
Ctrl-->>C : 标准化JSON响应

图表来源

api/route/order.php:39-87
front/service/order/CashierService.php:45-261
_'/module/order/core/service/order/OrderStatusTransition.php:73-152

详细接口说明

一、购物车接口（order/cart）

GET /api/?route=order&sub=cart&act=cart_number
- 功能：获取当前用户购物车商品总数；未登录时静默返回 0。
- 鉴权：可选（未登录不抛错）。
- 返回：cart_number。
- 参考实现：CartController::cartNumber:46-63
POST /api/?route=order&sub=cart&act=store
- 功能：加入购物车；支持 module/item_id/item_number/mode/action 及 att_xxx 规格参数。
- 鉴权：必须登录。
- 返回：mode（money/point）。
- 错误：业务规则违反返回 422。
- 参考实现：CartController::store:65-92, CartService::addToCart:52-134
PUT /api/?route=order&sub=cart&act=update&id={id}
- 功能：修改购物车项数量；支持 action=input/plus/minus。
- 鉴权：必须登录。
- 返回：subtotal/total/item_number/item_amount 等。
- 参考实现：CartController::update:94-114, CartService::updateCartItem:136-190
DELETE /api/?route=order&sub=cart&act=destroy&id={id}
- 功能：删除购物车项。
- 鉴权：必须登录。
- 返回：空对象。
- 参考实现：CartController::destroy:116-129, CartService::deleteCartItem:192-204

章节来源

api/controller/order/CartController.php:46-129
front/service/order/CartService.php:52-204

二、结算与下单接口（order/checkout）

POST /api/?route=order&sub=checkout&act=index
- 功能：加载结算页数据（购物车、配送方式、可用优惠券、金额摘要）。
- 鉴权：必须登录。
- 返回：title/cart/shipping_list/shipping_id/coupon_list/coupon_id/order/amount。
- 参考实现：CheckoutController::index:55-91
POST /api/?route=order&sub=checkout&act=checkout_post
- 功能：提交下单；支持 contact_id、shipping_id、mode、coupon_id、postcode、是否更新用户信息等。
- 鉴权：必须登录。
- 返回：cashier_url/order_sn/mode。
- 参考实现：CheckoutController::checkoutPost:93-131
POST /api/?route=order&sub=checkout&act=success
- 功能：下单成功页数据（按 order_sn 查询订单）。
- 鉴权：必须登录。
- 返回：title/order。
- 参考实现：CheckoutController::success:133-153
POST /api/?route=order&sub=checkout&act=change_shipping
- 功能：切换配送方式并重算金额。
- 鉴权：必须登录。
- 返回：amount（含运费、优惠券、订单总额格式化）。
- 参考实现：CheckoutController::changeShipping:155-180
POST /api/?route=order&sub=checkout&act=use_coupon
- 功能：使用优惠券并重算金额。
- 鉴权：必须登录。
- 返回：amount（含运费、优惠券、订单总额格式化）。
- 参考实现：CheckoutController::useCoupon:182-207

章节来源

api/controller/order/CheckoutController.php:55-207

三、收银台与支付接口（order/cashier）

GET /api/?route=order&sub=cashier&act=pay
- 功能：获取待支付订单；若为离线支付则幂等创建 pending 支付记录并返回 payment_sn。
- 鉴权：必须登录。
- 返回：title/order（含 payment_sn）。
- 参考实现：CashierController::pay:82-126
POST /api/?route=order&sub=cashier&act=pay_evidence
- 功能：上传离线支付凭证；关联到对应 payment_sn。
- 鉴权：必须登录。
- 返回：空对象。
- 参考实现：CashierController::payEvidence:128-161
GET /api/?route=order&sub=cashier&act=index
- 功能：收银台页面数据（默认支付方式）。
- 鉴权：必须登录。
- 返回：title/order/payment。
- 参考实现：CashierController::index:63-80
货到付款（由 CashierService 内部处理）
- 语义：立即记支付成功，订单状态推进至 PAID，无物流插件或非商品模块时直接推进到 COMPLETED。
- 参考实现：CashierService::submitCod:222-261

章节来源

api/controller/order/CashierController.php:63-161
front/service/order/CashierService.php:222-261

四、我的订单接口（order/user）

GET /api/?route=order&sub=user&act=index
- 功能：我的订单列表（支持分页与状态筛选）。
- 鉴权：必须登录。
- 返回：title/order_list/status_list/payment。
- 参考实现：UserController::index:46-81
GET /api/?route=order&sub=user&act=show&order_sn={order_sn}
- 功能：订单详情。
- 鉴权：必须登录。
- 返回：title/order/payment。
- 参考实现：UserController::show:83-108
POST /api/?route=order&sub=user&act=cancel
- 功能：取消订单（仅允许在可取消状态下）。
- 鉴权：必须登录。
- 返回：ok=true/false。
- 参考实现：UserController::cancel:110-129

章节来源

api/controller/order/UserController.php:46-129

五、工作台接口（order/work）

GET /api/?route=order&sub=work&act=index
- 功能：工作台订单列表（需工作端权限）。
- 鉴权：必须登录且具备工作端权限。
- 返回：title 与工作订单列表。
- 参考实现：WorkController::index:61-77
GET /api/?route=order&sub=work&act=show&order_sn={order_sn}
- 功能：工作台订单详情（含发货列表、是否需要线下支付审核）。
- 鉴权：必须登录且具备工作端权限。
- 返回：order_sn/title/order/payment/shipping_list/need_pay_check。
- 参考实现：WorkController::show:79-102
POST /api/?route=order&sub=work&act=order_cancel
- 功能：取消订单（工作台侧）。
- 鉴权：必须登录且具备工作端权限。
- 返回：空对象或错误。
- 参考实现：WorkController::orderCancel:104-121
POST /api/?route=order&sub=work&act=pay_check
- 功能：线下支付审核通过（将 pending 支付标记为成功，联动推进订单状态）。
- 鉴权：必须登录且具备工作端权限。
- 返回：空对象或错误。
- 参考实现：WorkController::payCheck:123-142
POST /api/?route=order&sub=work&act=tracking
- 功能：发货/更新物流（填写 shipping_id 与 tracking_no）。
- 鉴权：必须登录且具备工作端权限。
- 返回：空对象或错误。
- 参考实现：WorkController::tracking:144-165

章节来源

api/controller/order/WorkController.php:61-165

依赖关系分析

路由到控制器的映射集中在 order.php，清晰划分 cart/checkout/cashier/user/work 子域。
控制器依赖 Front/Core 服务：
- CartController → CartService
- CheckoutController → CheckoutService + OrderCore
- CashierController → CashierService + PaymentService + OrderCore
- UserController → UserService
- WorkController → WorkService + WorkOrderService + OrderCore
状态机与枚举：
- OrderStatusTransition 负责状态迁移与事件派发，OrderStatus 提供合法值与迁移表驱动校验。

classDiagram
class OrderController
class CartController
class CheckoutController
class CashierController
class UserController
class WorkController
class CartService
class CheckoutService
class CashierService
class UserService
class WorkService
class WorkOrderService
class OrderCore
class PaymentService
class OrderStatusTransition
class OrderStatus
CartController --> CartService
CheckoutController --> CheckoutService
CheckoutController --> OrderCore
CashierController --> CashierService
CashierController --> PaymentService
CashierController --> OrderCore
UserController --> UserService
WorkController --> WorkService
WorkController --> WorkOrderService
WorkController --> OrderCore
CashierService --> OrderStatusTransition
OrderStatusTransition --> OrderStatus

图表来源

api/controller/order/CartController.php:30-199
api/controller/order/CheckoutController.php:34-260
api/controller/order/CashierController.php:34-177
api/controller/order/UserController.php:30-131
api/controller/order/WorkController.php:32-192
front/service/order/CashierService.php:45-261
_'/module/order/core/service/order/OrderStatusTransition.php:27-152
core/foundation/order/OrderStatus.php

章节来源

api/route/order.php:39-87

性能与并发

购物车数量统计：cart_number 通过聚合 sum(item_number) 计算，避免全量扫描。
库存校验：加入购物车与更新数量时均调用 checkStock，防止超卖。
状态机事务：状态迁移在事务内执行，确保 order 与 order_item 一致，并记录状态日志。
支付幂等：离线支付 pay 接口对同一订单的 pending offlinepay 支付记录进行幂等复用，避免重复创建。
建议：
- 高并发下单场景下，建议在服务层增加分布式锁（如基于 Redis）保护关键写路径（下单、扣库存、支付回调）。
- 对频繁读接口（订单列表、详情）考虑缓存热点数据，注意失效策略。
- 对支付回调与状态推进采用幂等键（payment_sn、order_sn）防重放。

章节来源

api/controller/order/CartController.php:46-63
front/service/order/CartService.php:108-134
_'/module/order/core/service/order/OrderStatusTransition.php:102-134
api/controller/order/CashierController.php:103-118

故障排查指南

未登录访问受保护接口：会返回 401 未授权。
业务规则违反（如库存不足、非法状态迁移）：返回 422 并附带错误信息。
资源不存在（如订单不存在）：返回 404。
参数非法（如缺少必要字段）：返回 400。
常见定位步骤：
- 检查路由是否正确匹配 sub/act。
- 核对鉴权是否通过（mustLoginUserId / mustLoginAndPermission）。
- 查看服务层返回的错误码与消息。
- 关注状态机日志（order_status_log）确认状态迁移是否被拒绝。

章节来源

api/controller/order/CartController.php:185-197
api/controller/order/CheckoutController.php:246-258
api/controller/order/CashierController.php:163-175
api/controller/order/UserController.php:110-129
api/controller/order/WorkController.php:167-190
_'/module/order/core/service/order/OrderStatusTransition.php:73-98

结论

本订单 API 以清晰的模块化路由与分层架构实现了购物车、结算下单、支付、订单查询与工作台操作的全链路能力。通过状态机与事务保障数据一致性，结合幂等设计与库存校验提升并发安全性。开发者可据此快速集成小程序或前端应用，并按需扩展支付与物流插件。

附录：状态流转与时序图

订单状态流转图

stateDiagram-v2
[*] --> 待付款 : "创建订单"
待付款 --> 已付款 : "支付成功"
已付款 --> 待发货 : "有物流插件且为商品模块"
已付款 --> 已完成 : "无物流插件或非商品模块"
待发货 --> 已发货 : "更新物流"
已发货 --> 已完成 : "签收/自动完成"
待付款 --> 已取消 : "取消订单"
已付款 --> 已取消 : "退款后取消(视业务)"
已完成 --> 售后中 : "申请售后"

图表来源

_'/module/order/core/service/order/OrderStatusTransition.php:105-113
core/foundation/order/OrderStatus.php

下单与支付时序图

sequenceDiagram
participant U as "用户"
participant API as "订单API"
participant CS as "CheckoutService"
participant OS as "OrderStatusTransition"
participant PS as "PaymentService"
U->>API : 提交结算(选择配送/优惠券)
API->>CS : createOrder(...)
CS->>OS : changeStatus(PENDING)
OS-->>CS : 成功
CS-->>API : 返回order_sn/mode
alt 在线支付
API->>PS : 创建支付/发起支付
PS-->>API : 支付结果
API->>OS : changeStatus(PAID)
OS-->>API : 成功(可能直接COMPLETED)
else 离线支付
API->>PS : 创建pending offlinepay
PS-->>API : 返回payment_sn
API-->>U : 展示表单/上传凭证
end

图表来源

api/controller/order/CheckoutController.php:93-131
front/service/order/CashierService.php:222-261
_'/module/order/core/service/order/OrderStatusTransition.php:73-152

添加日期：2026-10-05