简介

本文件面向电商平台开发者，提供订单处理流程的完整API参考。内容覆盖：

• 订单创建接口的参数校验、业务规则（商品、收货地址、配送方式等）
• 订单状态流转机制（待支付到已完成等）
• 订单查询接口（按订单号、用户ID、时间范围等多维度）
• 订单修改与取消流程（库存释放、优惠券回滚等业务规则）
• 订单详情接口（商品明细、价格计算、优惠信息）
• 订单列表分页查询与筛选
• 数据一致性与异常处理机制

项目结构

订单相关API采用"路由 + 控制器 + 服务"的分层组织：

• 路由层：集中声明订单域的所有端点及子模块（user/cart/checkout/cashier/work）
• 控制器层：负责鉴权、参数校验、调用服务并返回统一响应
• 服务层：封装结算、下单、支付、核销、购物车、我的订单等业务逻辑
• 基础能力：订单状态枚举、金额格式化、附件上传、支付服务等

graph TB
A["客户端"] --> B["路由: api/route/order.php"]
B --> C["控制器: Order/Checkout/Cashier/User/Cart/Work"]
C --> D["服务: CheckoutService / CashierService / CartService / UserService / WorkOrderService"]
D --> E["核心能力: OrderStatus / PaymentService / Attachment / DB / Session"]

图表来源

• api/route/order.php:39-87
• api/controller/order/CheckoutController.php:49-53
• api/controller/order/CashierController.php:53-60
• api/controller/order/CartController.php:41-44
• api/controller/order/UserController.php:41-44
• api/controller/order/WorkController.php:51-58

章节来源

• api/route/order.php:39-87

核心组件

• 路由与分组：以 order 为根路径，通过 sub 前缀区分 user/cart/checkout/cashier/work 子模块
• 控制器职责：
  • OrderController：承载购物车首页入口（获取当前用户购物车）
  • CartController：购物车数量、增删改
  • CheckoutController：结算页数据、下单提交、成功页、切换配送、使用优惠券重算
  • CashierController：收银台、离线支付、凭证上传
  • UserController：我的订单列表、详情、取消
  • WorkController：工作台订单列表、详情、取消、线下支付审核、发货/物流更新
• 基础能力：
  • OrderStatus：订单状态常量与迁移校验
  • PaymentService：支付记录创建与查询
  • Attachment：凭证附件存储
  • DB/Session：数据与临时金额缓存

章节来源

• api/route/order.php:39-87
• core/foundation/Order/OrderStatus.php:21-67

架构总览

订单API遵循"请求进入路由 -> 控制器鉴权与入参校验 -> 调用服务完成业务 -> 返回统一ApiResponse"的流程。关键交互如下：

sequenceDiagram
participant U as "客户端"
participant R as "路由(order.php)"
participant C as "控制器(CheckoutController)"
participant S as "服务(CheckoutService)"
participant P as "支付服务(PaymentService)"
participant DB as "数据库"
U->>R : POST /api?route=order/checkout/checkout_post
R->>C : 解析参数/鉴权
C->>S : createOrder(用户, 收货, 配送, 优惠券, 邮编, 是否更新资料)
S->>DB : 校验库存/价格/优惠
S-->>C : {ok, order_sn, mode}
alt 在线支付
C->>P : 创建支付单(可选)
P-->>C : payment_sn
C-->>U : {cashier_url, order_sn, mode}
else 离线支付
C-->>U : {order_sn, mode}
end

图表来源

• api/route/order.php:65-68
• api/controller/order/CheckoutController.php:99-131
• api/controller/order/CashierController.php:91-126

详细接口说明

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

• GET /api?route=order/cart/cart_number
  • 功能：获取当前登录用户的购物车商品总数；未登录时返回 cart_number=0
  • 鉴权：非必须（未登录静默返回）
  • 返回：cart_number
• POST /api?route=order/cart
  • 功能：添加商品到购物车
  • 必填参数：module（默认 product）、item_id、item_number（默认1）、mode（money/point，默认 money）、action（默认 addtocart）
  • 规格参数：att_* 键值对收集
  • 返回：mode
• PUT /api?route=order/cart/{id}
  • 功能：更新购物车项数量
  • 参数：action（plus/minus/input），input 时需附带 item_number
  • 返回：更新后的购物车项或空对象
• DELETE /api?route=order/cart/{id}
  • 功能：删除购物车项
  • 返回：空对象

章节来源

• api/controller/order/CartController.php:53-63
• api/controller/order/CartController.php:71-92
• api/controller/order/CartController.php:100-129
• api/controller/order/CartController.php:137-183

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

• GET /api?route=order/checkout
  • 功能：获取结算页数据（购物车、配送方式、可用优惠券、初始金额）
  • 鉴权：必须登录
  • 返回：cart、shipping_list、shipping_id、coupon_list、coupon_id、order、amount（含运费、优惠券金额、订单金额格式化）
• POST /api?route=order/checkout/checkout_post
  • 功能：提交下单
  • 必填参数：contact_id、shipping_id（合法字符）、mode（money/point）、coupon_id、postcode
  • 可选参数：update_user_information（布尔）、user_update_data（phone/contact/address/postcode）
  • 返回：cashier_url（在线支付跳转）、order_sn、mode
• GET /api?route=order/checkout/success
  • 功能：下单成功页数据
  • 鉴权：必须登录
  • 返回：order（包含 order_amount_format）
• POST /api?route=order/checkout/change_shipping
  • 功能：切换配送方式并重算金额
  • 参数：shipping_id、coupon_amount
  • 返回：amount（运费、优惠券金额、订单金额格式化）
• POST /api?route=order/checkout/use_coupon
  • 功能：使用优惠券并重算金额
  • 参数：coupon_id、shipping_fee
  • 返回：amount（运费、优惠券金额、订单金额格式化）

更新 结账服务增强了用户地址获取逻辑，增加了user对象和用户联系信息的存在性检查，防止空引用错误并提高结账流程的健壮性。在createOrder方法中，对用户联系信息的处理增加了更严格的验证：

// 收货人信息
$userContact = DB::table('user_contact')
    ->where('id', $contactId)
    ->where('user_id', $userId)
    ->find();
$contact = isset($userContact['name']) ? $userContact['name'] : '';
$phone = isset($userContact['phone']) ? $userContact['phone'] : '';
$address = (user() && !empty($userContact)) ? user()->addressFull($userContact) : '';

flowchart TD
Start(["开始"]) --> Auth["校验登录态"]
Auth --> CheckCart{"购物车是否为空?"}
CheckCart -- 否 --> BuildData["构建结算数据<br/>cart/shipping/coupon/amount"]
BuildData --> Submit["提交下单<br/>createOrder(...)"]
Submit --> ValidateUser{"用户和联系信息验证"}
ValidateUser -- 通过 --> Result{"下单成功?"}
ValidateUser -- 失败 --> Err["返回业务错误 422"]
Result -- 否 --> Err
Result -- 是 --> Mode{"mode=online?"}
Mode -- 是 --> PayUrl["生成支付链接 casher_url"]
Mode -- 否 --> Offline["返回 order_sn/mode"]
PayUrl --> End(["结束"])
Offline --> End
Err --> End

图表来源

• api/controller/order/CheckoutController.php:61-91
• api/controller/order/CheckoutController.php:99-131
• api/controller/order/CheckoutController.php:139-153
• api/controller/order/CheckoutController.php:161-207
• front/service/order/CheckoutService.php:329-337

章节来源

• api/controller/order/CheckoutController.php:61-91
• api/controller/order/CheckoutController.php:99-131
• api/controller/order/CheckoutController.php:139-153
• api/controller/order/CheckoutController.php:161-207

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

• GET /api?route=order/cashier
  • 功能：获取收银台订单信息
  • 鉴权：必须登录
  • 返回：order、payment（默认支付方式）
• GET /api?route=order/cashier/pay
  • 功能：离线支付页（幂等创建 pending offlinepay 支付记录）
  • 鉴权：必须登录
  • 返回：order（含 payment_sn）
• POST /api?route=order/cashier/pay_evidence
  • 功能：上传付款凭证
  • 鉴权：必须登录
  • 必填参数：order_sn、payment_sn、文件 pay_evidence
  • 返回：空对象

sequenceDiagram
participant U as "客户端"
participant W as "CashierController"
participant OS as "OrderService"
participant PS as "PaymentService"
participant ATT as "Attachment"
U->>W : GET /cashier/pay?order_sn=...
W->>OS : writePayId(order_sn, 'offlinepay')
W->>PS : findActivePending(order_id)
alt 存在有效记录
PS-->>W : payment_sn
else 不存在
W->>PS : createForOrder(order_id, order_sn, 'offlinepay', amount, timeout)
PS-->>W : payment_sn
end
W-->>U : {order, payment_sn}
U->>W : POST /cashier/pay_evidence (order_sn, payment_sn, 文件)
W->>ATT : store('order', order_sn, file, ...)
W->>W : savePayEvidence(...)
W-->>U : {}

图表来源

• api/controller/order/CashierController.php:69-80
• api/controller/order/CashierController.php:91-126
• api/controller/order/CashierController.php:134-161

章节来源

• api/controller/order/CashierController.php:69-80
• api/controller/order/CashierController.php:91-126
• api/controller/order/CashierController.php:134-161

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

• GET /api?route=order/user
  • 功能：我的订单列表（分页、按状态筛选）
  • 鉴权：必须登录
  • 参数：page（默认1）、status（all 或合法状态值）
  • 返回：title、order_list、status_list、payment
• GET /api?route=order/user/show/{order_sn}
  • 功能：订单详情
  • 鉴权：必须登录
  • 参数：order_sn（数字）
  • 返回：title、order、payment
• POST /api?route=order/user/cancel
  • 功能：取消订单
  • 鉴权：必须登录
  • 参数：order_sn（数字）
  • 返回：{ok: true}

sequenceDiagram
participant U as "客户端"
participant UC as "UserController"
participant US as "UserService"
U->>UC : GET /user?page=&status=
UC->>US : buildOrderListData(user_id, page, '', status)
US-->>UC : {list, status_list}
UC-->>U : {title, order_list, status_list, payment}
U->>UC : GET /user/show/{order_sn}
UC->>US : buildOrderShowData(user_id, order_sn)
US-->>UC : order
UC-->>U : {title, order, payment}
U->>UC : POST /user/cancel (order_sn)
UC->>US : cancelOrder(user_id, order_sn)
US-->>UC : {ok}
UC-->>U : {ok : true}

图表来源

• api/controller/order/UserController.php:52-81
• api/controller/order/UserController.php:89-108
• api/controller/order/UserController.php:116-129

章节来源

• api/controller/order/UserController.php:52-81
• api/controller/order/UserController.php:89-108
• api/controller/order/UserController.php:116-129

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

• GET /api?route=order/work
  • 功能：工作台订单列表（支持按状态筛选、分页）
  • 鉴权：必须登录且具备工作端权限
  • 参数：status（all 或合法状态值）、page（默认1）
  • 返回：title、列表数据
• GET /api?route=order/work/{order_sn}
  • 功能：工作台订单详情
  • 鉴权：必须登录且具备工作端权限
  • 返回：order_sn、title、order、payment、shipping_list、need_pay_check（仅当 pay_id=offlinepay 且状态为等待确认时为真）
• POST /api?route=order/work/order_cancel
  • 功能：取消订单（工作端）
  • 鉴权：必须登录且具备工作端权限
  • 参数：order_sn（数字）
  • 返回：空对象
• POST /api?route=order/work/pay_check
  • 功能：线下支付审核通过
  • 鉴权：必须登录且具备工作端权限
  • 参数：order_id（数字）
  • 返回：空对象
• POST /api?route=order/work/tracking
  • 功能：发货/更新物流
  • 鉴权：必须登录且具备工作端权限
  • 参数：order_id（数字）、shipping_id、tracking_no
  • 返回：空对象

章节来源

• api/controller/order/WorkController.php:67-77
• api/controller/order/WorkController.php:85-102
• api/controller/order/WorkController.php:110-121
• api/controller/order/WorkController.php:129-142
• api/controller/order/WorkController.php:150-165

六、订单状态流转

• 状态定义与语义：
  • pending：下单成功，等待付款
  • awaiting_confirmation：离线付款已上传凭证，等待管理员审核
  • paid：已付款
  • completed：已完成（无物流从 paid 直接到 completed；有物流在发货完成后到 completed）
  • cancelled：已取消（含自动取消未付款超时订单）
  • refunding：退款中
  • refunded：已全额退款（终态）
  • partial_refunded：已部分退款（仍可继续退至 refunded）
• 迁移规则（表驱动校验）：
  • pending → awaiting_confirmation | paid | cancelled
  • awaiting_confirmation → paid | pending | cancelled
  • paid → completed | refunding
  • completed → refunding
  • refunding → refunded | partial_refunded | paid
  • partial_refunded → refunding
  • refunded / cancelled 为终态，不可再迁移

stateDiagram-v2
[*] --> pending
pending --> awaiting_confirmation : "上传离线凭证"
pending --> paid : "在线支付成功"
pending --> cancelled : "超时/主动取消"
awaiting_confirmation --> paid : "审核通过"
awaiting_confirmation --> pending : "审核驳回"
awaiting_confirmation --> cancelled : "取消"
paid --> completed : "发货完成/无物流"
paid --> refunding : "发起售后"
completed --> refunding : "发起售后"
refunding --> refunded : "全额退款"
refunding --> partial_refunded : "部分退款"
refunding --> paid : "退款驳回"
partial_refunded --> refunding : "继续退款"

图表来源

• core/foundation/Order/OrderStatus.php:21-67
• core/foundation/Order/OrderStatus.php:76-84

章节来源

• core/foundation/Order/OrderStatus.php:21-67
• core/foundation/Order/OrderStatus.php:76-84

依赖关系分析

• 控制器依赖服务：
  • CheckoutController 依赖 CheckoutService、OrderCore
  • CashierController 依赖 CashierService、OrderCore、PaymentService
  • CartController 依赖 CartService
  • UserController 依赖 UserService
  • WorkController 依赖 WorkService、WorkOrderService、OrderCore
• 公共能力：
  • ApiResponse：统一响应封装
  • Request：参数读取与校验
  • DB/Session：数据访问与临时金额缓存
  • Module：模块开关判断（如 order/coupon）
  • Plugin：默认支付方式获取

graph LR
CCtl["CheckoutController"] --> CSvc["CheckoutService"]
CCtl --> OCore["OrderCore"]
KCtl["CashierController"] --> KSvc["CashierService"]
KCtl --> OCore
KCtl --> PSvc["PaymentService"]
CTl["CartController"] --> CS["CartService"]
UTl["UserController"] --> US["UserService"]
WTl["WorkController"] --> WS["WorkService"]
WTl --> WOS["WorkOrderService"]
WTl --> OCore

图表来源

• api/controller/order/CheckoutController.php:49-53
• api/controller/order/CashierController.php:53-60
• api/controller/order/CartController.php:41-44
• api/controller/order/UserController.php:41-44
• api/controller/order/WorkController.php:51-58

章节来源

• api/controller/order/CheckoutController.php:49-53
• api/controller/order/CashierController.php:53-60
• api/controller/order/CartController.php:41-44
• api/controller/order/UserController.php:41-44
• api/controller/order/WorkController.php:51-58

性能与一致性

• 参数校验与类型安全：
  • 使用 Request 的类型化读取方法（digits/integer/alpha/postcode/alpha）确保输入合法性
  • 正则校验 shipping_id 防止非法字符注入
• 会话与缓存：
  • 运费与优惠券金额通过 Session 暂存，减少重复计算开销
• 幂等性：
  • 离线支付页幂等创建 pending 支付记录，避免重复创建
• 数据一致性：
  • 下单与支付流程由服务层保证事务边界（具体实现位于服务层）
  • 订单状态迁移通过 OrderStatus 表驱动校验，防止非法状态跳变
• 用户数据安全性增强：
  • 结账服务中增加了user对象和用户联系信息的存在性检查，防止空引用错误
  • 用户联系人数据处理采用防御性编程，确保即使数据缺失也不会导致系统崩溃
  • UserContactQuery服务提供了标准化的默认联系人快照获取方法，保证数据格式一致性

故障排查指南

• 常见错误码与场景：
  • 401 UNAUTHORIZED：未登录或登录过期（多个控制器 mustLoginUserId）
  • 403 FORBIDDEN：工作端无权限（WorkController mustLoginAndPermission）
  • 400 INVALID_PARAMS：参数缺失或格式错误（如缺少 order_id、文件为空）
  • 404 NOT_FOUND：订单不存在（详情页校验）
  • 422 BUSINESS_RULE_VIOLATION：业务规则不满足（如购物车为空、取消失败、支付凭证提示）
• 新增的用户数据相关错误：
  • 用户联系信息缺失：当用户没有有效的收货地址时，系统会返回相应的错误提示
  • 用户对象为空：在结账流程中，如果用户对象验证失败，会阻止订单创建
• 定位建议：
  • 检查路由是否正确映射到对应控制器动作
  • 核对请求参数类型与命名（如 digits/integer/alpha）
  • 查看 Session 中的金额字段是否与预期一致
  • 关注订单状态是否符合迁移规则
  • 离线支付流程需确认 payment_sn 是否正确回传与落库
  • 检查用户联系信息是否存在：确保用户有有效的收货地址信息

章节来源

• api/controller/order/CheckoutController.php:67-69
• api/controller/order/CheckoutController.php:118-120
• api/controller/order/CashierController.php:140-155
• api/controller/order/UserController.php:124-126
• api/controller/order/WorkController.php:180-187

结论

本API文档基于仓库实际代码梳理出订单全链路接口与状态流转，覆盖购物车、结算下单、支付、我的订单与工作台的完整闭环。最新的更新增强了结账服务的健壮性，通过增加用户对象和用户联系信息的存在性检查，有效防止了空引用错误，提高了系统的稳定性。 开发者可据此快速集成前端小程序或第三方系统，并结合服务层扩展实现更复杂的促销、库存与售后策略。建议在接入时重点关注参数校验、状态迁移与幂等设计，以及用户数据的安全性保障，以确保交易的一致性与稳定性。