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

用户订单API

简介

本文件面向用户端应用开发者，提供“用户订单”相关API的完整参考。覆盖以下能力：

用户订单列表查询：支持按订单状态、分页等条件筛选（时间范围、商品类型等由模块层扩展）。
用户订单详情：包含订单基本信息、商品明细、物流信息、支付凭证、评价入口等。
用户订单操作：取消订单、结算下单、收银台支付、上传离线付款凭证等。
工作台订单：订单列表、详情、取消、线下支付审核、发货/更新物流。
购物车：数量查询、添加/更新/删除购物车项。
权限控制：所有用户侧接口均基于登录态校验，确保仅能访问自身订单数据；工作台接口需具备工作端权限。
通知机制：通过订单状态日志与回调点（如自动取消、自动售后状态更新、自动评价）驱动消息通知。

注意：本项目中未直接实现“导出Excel”和“收藏订单”两个独立API，但可通过现有订单列表/详情接口组合实现或作为后续扩展点。

项目结构

订单API采用声明式路由+控制器+服务层的分层组织：

路由层：集中定义 /api/?route=order/* 下的所有订单相关接口映射。
控制器层：按职责拆分为用户订单、购物车、结算、收银台、工作台等子控制器。
服务层：前端服务负责组装视图数据与业务规则，核心订单服务处理通用逻辑。

graph TB
A["客户端"] --> B["API 路由<br/>order.php"]
B --> C["UserController<br/>我的订单"]
B --> D["CartController<br/>购物车"]
B --> E["CheckoutController<br/>结算/下单"]
B --> F["CashierController<br/>收银台"]
B --> G["WorkController<br/>工作台"]
C --> H["UserService<br/>用户订单视图"]
D --> I["CartService"]
E --> J["CheckoutService"]
F --> K["CashierService"]
G --> L["WorkOrderService"]

核心组件

用户订单控制器与服务：提供订单列表、详情、取消等操作，并集成自动取消、自动售后状态更新、自动评价等后台任务触发。
购物车控制器与服务：提供购物车数量、增删改查，支持规格参数透传。
结算控制器与服务：提供结算页数据、下单提交、成功页、运费重算、优惠券使用重算。
收银台控制器与服务：提供支付页面、离线支付流程、凭证上传。
工作台控制器与服务：提供工作台订单列表、详情、取消、线下支付审核、发货/物流更新。

架构总览

订单API遵循“路由-控制器-服务”的分层模式，并通过模块开关（order/aftersale/coupon/payment）进行功能裁剪与降级。

sequenceDiagram
participant U as "用户"
participant R as "路由 order.php"
participant UC as "UserController"
participant US as "UserService"
participant M as "模块(order/aftersale/coupon)"
U->>R : GET /api/?route=order/user?page&status
R->>UC : index()
UC->>US : buildOrderListData(userId, page, status)
US->>M : 自动取消/售后状态/评价
US-->>UC : 订单列表+状态标签
UC-->>U : 响应(订单列表/状态列表/默认支付方式)

详细接口说明

一、用户订单列表

接口路径：GET /api/?route=order/user
鉴权：需要登录
请求参数
- page：页码，默认1
- status：订单状态筛选，all/0/1/10/-2（非法值回退为all）
返回字段（节选）
- title：标题
- order_list：订单列表（含订单号、金额、状态、收货人、支付方式、可售后标记、支付时限、商品明细等）
- status_list：状态标签列表（含链接）
- payment：默认支付方式标识
行为说明
- 若未启用订单模块，返回空列表与默认信息
- 列表构建时触发自动取消未付款订单、自动更新售后状态、自动更新评价
- 地址信息从 order_address 批量读取，避免N+1查询

二、用户订单详情

接口路径：GET /api/?route=order/user/{order_sn}
鉴权：需要登录
请求参数
- order_sn：订单号（数字校验）
返回字段（节选）
- title：标题
- order：订单详情（基本信息、收货地址、金额格式化、支付方式名、支付凭证、商品明细、售后入口、支付跳转等）
- payment：默认支付方式标识
行为说明
- 仅允许查看当前登录用户的订单
- 根据订单状态触发自动取消/售后状态更新/评价更新
- 状态时间线来自 order_status_log，展示每次状态变更的时间、操作人、原因

三、用户订单操作

取消订单
- 接口路径：POST /api/?route=order/user/cancel
- 鉴权：需要登录
- 请求参数：order_sn
- 行为：仅允许取消状态为“待付款”的订单；取消后释放库存、关联模块状态同步、钱包退款（混合支付场景）
- 返回：ok=true/false
结算页数据
- 接口路径：POST /api/?route=order/checkout/index
- 鉴权：需要登录
- 请求参数：mode（money/point）
- 返回：购物车、配送方式、优惠券列表、金额计算占位
提交下单
- 接口路径：POST /api/?route=order/checkout/checkout_post
- 鉴权：需要登录
- 请求参数：contact_id、shipping_id、mode、coupon_id、postcode、update_user_information、user_update_data
- 返回：cashier_url（支付页）、order_sn、mode
下单成功页
- 接口路径：POST /api/?route=order/checkout/success
- 鉴权：需要登录
- 请求参数：order_sn
- 返回：订单基础信息与金额格式化
切换配送方式重算
- 接口路径：POST /api/?route=order/checkout/change_shipping
- 鉴权：需要登录
- 请求参数：shipping_id、coupon_amount
- 返回：运费、优惠券金额、订单总额格式化
使用优惠券重算
- 接口路径：POST /api/?route=order/checkout/use_coupon
- 鉴权：需要登录
- 请求参数：coupon_id、shipping_fee
- 返回：运费、优惠券金额、订单总额格式化

四、收银台与支付

收银台
- 接口路径：GET /api/?route=order/cashier
- 鉴权：需要登录
- 请求参数：order_sn
- 返回：订单信息与默认支付方式
离线支付页
- 接口路径：GET /api/?route=order/cashier/pay
- 鉴权：需要登录
- 请求参数：order_sn
- 行为：幂等创建 pending offlinepay 支付记录，返回 payment_sn
- 返回：订单信息与 payment_sn
上传付款凭证
- 接口路径：POST /api/?route=order/cashier/pay_evidence
- 鉴权：需要登录
- 请求参数：order_sn、payment_sn、文件 pay_evidence
- 行为：存储图片并关联到对应支付记录
- 返回：成功空对象

五、工作台订单（运营/核销端）

工作台订单列表
- 接口路径：GET /api/?route=order/work
- 鉴权：需要登录且具备工作端权限
- 请求参数：status、page
- 返回：订单列表、状态标签、默认支付方式
工作台订单详情
- 接口路径：GET /api/?route=order/work/{order_sn}
- 鉴权：需要登录且具备工作端权限
- 请求参数：order_sn
- 返回：订单详情、支付方式名、配送方式、是否需要线下支付审核
取消订单
- 接口路径：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
- 行为：首次发货完成则置为已完成并开启售后；更新物流则记录物流公司单号与发货时间

六、购物车

购物车数量
- 接口路径：GET /api/?route=order/cart/cart_number
- 鉴权：未登录静默返回0，已登录返回总数
- 返回：cart_number
添加购物车
- 接口路径：POST /api/?route=order/cart
- 鉴权：需要登录
- 请求参数：module、item_id、itemnumber、mode、action、att* 规格参数
- 行为：调用 CartService.addToCart，失败返回业务错误
更新购物车数量
- 接口路径：PUT /api/?route=order/cart/{id}
- 鉴权：需要登录
- 请求参数：action（plus/minus/input）、item_number（当action=input）
- 行为：计算目标数量并更新
删除购物车项
- 接口路径：DELETE /api/?route=order/cart/{id}
- 鉴权：需要登录
- 行为：删除指定购物车项

七、权限控制

用户侧接口：通过 mustLoginUserId 或 auth('api')->id() 校验登录态，未登录返回401
工作台接口：mustLoginAndPermission 同时校验登录与工作端权限，无权限返回403
数据隔离：用户订单列表/详情严格以 user_id 过滤，确保只能访问自己的订单

八、消息通知机制

自动取消：在订单列表/详情构建时，对“待付款”订单执行自动取消
自动售后状态更新：在订单列表/详情构建时，根据规则更新售后状态
自动评价：在订单列表/详情构建时，触发评价更新
状态日志：订单状态变更记录于 order_status_log，可用于通知与审计

九、关于“收藏订单”与“导出Excel”

收藏订单：当前代码库未发现独立的“收藏订单”API；可在订单详情基础上扩展收藏表与接口，用于快速复购与分享。
导出Excel：当前代码库未发现订单导出API；可复用订单列表接口并结合服务端导出工具生成Excel下载。

依赖关系分析

路由到控制器：order.php 将 /api/?route=order/* 映射至各子控制器
控制器到服务：各控制器依赖相应 Service 完成业务逻辑
服务到模块：UserService/WorkOrderService 通过 Module::make('order'/'aftersale'/'coupon') 获取扩展能力
服务到数据库：通过 ORM/DB 访问 order、order_item、order_address、order_status_log、order_cart 等表

graph LR
R["路由 order.php"] --> C1["UserController"]
R --> C2["CartController"]
R --> C3["CheckoutController"]
R --> C4["CashierController"]
R --> C5["WorkController"]
C1 --> S1["UserService"]
C2 --> S2["CartService"]
C3 --> S3["CheckoutService"]
C4 --> S4["CashierService"]
C5 --> S5["WorkOrderService"]
S1 --> M["模块(order/aftersale/coupon)"]
S5 --> M

性能与扩展性

批量加载收货地址：通过收集 order_id 列表一次性查询 order_address，减少N+1查询
分页与筛选：列表接口使用 paginate，支持状态筛选与翻页参数保留
模块开关：未启用 order/aftersale/coupon 时优雅降级，避免无效查询
缓存建议：可考虑对常用配置（支付方式、配送方式）做短期缓存
扩展点：
- 时间范围筛选：可在 UserService.buildOrderListData 中增加 created_at 范围过滤
- 商品类型筛选：可在 Order::filterByStatus 基础上叠加 module/item 维度过滤
- 统计接口：可新增统计接口聚合消费金额、订单数、平均客单价等指标

故障排查指南

401 未登录：检查是否携带有效会话/令牌；确认 mustLoginUserId 或 auth('api')->id() 返回值
403 无权限：工作台接口需具备工作端权限；检查 workService.checkPermission
404 订单不存在：确认 order_sn 正确且属于当前用户；检查订单是否存在
422 业务规则违反：常见于购物车更新、下单提交、取消订单等；检查输入参数与订单状态
400 参数错误：检查必填参数与格式（如 postcode、shipping_id、order_id）
常见问题定位
- 订单列表为空：确认模块是否启用；检查自动取消是否影响订单状态
- 支付凭证未生效：确认 payment_sn 是否正确回传；检查附件存储与关联

结论

该订单API体系以清晰的层次划分与模块化解耦，提供了完整的用户订单生命周期管理能力。通过严格的权限控制与数据隔离，确保用户仅能访问自身订单；通过自动任务与状态日志，支撑消息通知与审计需求。对于“收藏订单”与“导出Excel”，可作为后续扩展点按需实现。

附录

关键状态枚举：PENDING、PAID、COMPLETED、CANCELLED（用于状态筛选与流转）
关键表：order、order_item、order_address、order_status_log、order_cart、order_coupon
关键服务：UserService、WorkOrderService、CartService、CheckoutService、CashierService

添加日期：2026-10-05