简介

本模块面向 DouPHP 小程序的订单页面，覆盖从购物车、订单确认（结算）、收银台支付、离线付款到订单详情与状态管理的完整流程。重点包括：

• 订单确认页的地址选择、商品信息展示、优惠券使用、运费计算等交互与后端重算逻辑
• 支付集成流程：微信支付发起、回调处理、离线付款凭证上传
• 订单状态管理：待付款、已付款、已发货、已完成等状态转换与操作入口
• 开发示例：下单创建、支付发起、订单查询、取消与物流单号提交
• 异常处理：支付失败重试、订单超时取消、退款相关场景说明

项目结构

小程序端订单相关页面位于 miniprogram/company/pages/order，包含购物车、结算、收银台、离线付款、订单详情等；后端 API 控制器位于 api/controller/order，提供购物车、结算下单、收银台支付等接口。

graph TB
subgraph "小程序端"
A["购物车 order.ts"]
B["结算 checkout.ts"]
C["收银台 cashier.ts"]
D["离线付款 offlinepay.ts"]
E["订单详情 show.ts"]
end
subgraph "后端API"
F["OrderController.php"]
G["CheckoutController.php"]
H["CashierController.php"]
end
A --> F
B --> G
C --> H
D --> H
E --> H

图表来源

• order.ts:38-49
• checkout.ts:23-62
• cashier.ts:19-37
• offlinepay.ts:35-48
• show.ts:35-54
• OrderController.php:46-59
• CheckoutController.php:55-91
• CashierController.php:63-80

章节来源

• order.ts:1-176
• checkout.ts:1-214
• cashier.ts:1-87
• offlinepay.ts:1-104
• show.ts:1-188
• OrderController.php:1-78
• CheckoutController.php:1-260
• CashierController.php:1-177

核心组件

• 购物车与订单列表
  • 小程序侧：order.ts 负责加载购物车数据、数量增减、删除、滑动交互等
  • 后端侧：OrderController::index 返回当前用户购物车数据
• 结算与下单
  • 小程序侧：checkout.ts 获取结算数据、选择收货地址、配送方式、优惠券，提交下单
  • 后端侧：CheckoutController 提供结算数据、下单提交、成功页、切换配送与优惠券重算
• 收银台与支付
  • 小程序侧：cashier.ts 获取订单并发起微信支付；offlinepay.ts 支持离线付款凭证上传
  • 后端侧：CashierController 提供收银台订单信息、离线付款记录创建与凭证上传保存
• 订单详情与状态管理
  • 小程序侧：show.ts 展示订单详情、支付校验、物流单号提交、订单取消、再次支付
  • 后端侧：通过工作区相关接口（由 show.ts 调用）完成状态变更与物流信息更新

章节来源

• order.ts:38-69
• OrderController.php:46-59
• checkout.ts:23-96
• CheckoutController.php:55-131
• cashier.ts:19-77
• CashierController.php:63-161
• show.ts:35-182

架构总览

订单流程从购物车进入结算，再到收银台支付或离线付款，最终在订单详情页查看状态并进行后续操作。

sequenceDiagram
participant U as "用户"
participant M as "小程序页面"
participant API as "后端API"
participant PAY as "支付服务"
U->>M : 打开购物车/结算
M->>API : 获取结算数据(地址/商品/运费/优惠券)
API-->>M : 返回结算数据
U->>M : 选择配送/优惠券并提交下单
M->>API : 提交下单
API-->>M : 返回收银台URL或订单号
U->>M : 进入收银台
M->>API : 获取订单信息
API-->>M : 返回订单与默认支付方式
U->>M : 选择微信支付
M->>PAY : 发起支付
PAY-->>M : 支付结果
M->>API : 刷新订单状态
API-->>M : 返回最新订单状态

图表来源

• checkout.ts:23-96
• CheckoutController.php:55-131
• cashier.ts:19-77
• CashierController.php:63-80

详细组件分析

订单确认（结算）页面

• 功能要点
  • 加载结算数据：商品清单、可配送方式、默认配送、可用优惠券、金额明细（运费、优惠、订单总额）
  • 地址选择：拉取联系人列表与详情，支持弹窗选择与自动填充
  • 运费计算：切换配送方式时触发后端重算，实时更新金额
  • 优惠券使用：选择优惠券触发后端重算，更新优惠金额与订单总额
  • 提交下单：携带联系方式、配送方式、优惠券、邮编、是否更新用户信息等参数
• 关键流程
  • 页面初始化：鉴权后请求结算数据，设置标题与表单初始值
  • 交互事件：radioShipping、useCoupon、contactSelect、orderSuccess
  • 错误处理：统一捕获网络与业务错误并提示

flowchart TD
Start(["进入结算页"]) --> Auth["登录态校验"]
Auth --> LoadData["请求结算数据"]
LoadData --> ShowUI["渲染商品/地址/配送/优惠券/金额"]
ShowUI --> ChangeShip{"切换配送?"}
ChangeShip --> |是| RecalcShip["请求重算运费"]
RecalcShip --> UpdateAmount["更新金额显示"]
ChangeShip --> |否| UseCoupon{"选择优惠券?"}
UseCoupon --> |是| RecalcCoupon["请求应用优惠券并重算"]
RecalcCoupon --> UpdateAmount
UseCoupon --> |否| Submit{"提交下单"}
Submit --> CreateOrder["调用下单接口"]
CreateOrder --> Redirect["跳转收银台或成功页"]
UpdateAmount --> ShowUI

图表来源

• checkout.ts:23-96
• CheckoutController.php:55-207

章节来源

• checkout.ts:1-214
• CheckoutController.php:55-207

收银台与支付处理

• 功能要点
  • 收银台加载：根据订单号获取订单信息与默认支付方式
  • 微信支付：调用支付接口获取签名参数，唤起小程序支付
  • 离线付款：生成或复用 pending 支付记录，上传付款凭证并关联 payment_sn
• 关键流程
  • 支付发起：cashier.ts 调用 user.weixin.pay，传入 order_sn，成功后提示并跳转
  • 离线付款：offlinepay.ts 选择图片并上传至 order.cashier.pay_evidence，成功后返回订单列表

sequenceDiagram
participant P as "小程序"
participant S as "CashierController"
participant W as "微信支付"
P->>S : 获取订单信息(order_sn)
S-->>P : 返回订单与默认支付
P->>W : 发起微信支付(user.weixin.pay)
W-->>P : 支付结果
P->>S : 上传离线付款凭证(可选)
S-->>P : 保存凭证并返回

图表来源

• cashier.ts:19-77
• CashierController.php:63-161
• offlinepay.ts:35-94

章节来源

• cashier.ts:1-87
• CashierController.php:63-161
• offlinepay.ts:1-104

订单详情与状态管理

• 功能要点
  • 订单详情：展示订单基本信息、支付信息、物流单号、是否需要支付校验
  • 支付校验：针对线下收款场景，管理员/工作人员可标记为已收款
  • 物流单号：选择物流公司并填写运单号，提交后刷新订单状态
  • 订单取消：允许用户在特定状态下取消订单
  • 再次支付：对未支付订单再次发起微信支付
• 关键流程
  • 加载详情：调用 order.work.show 获取订单与支付信息
  • 物流提交：order.work.tracking 提交物流信息
  • 支付校验：order.work.pay_check 标记收款
  • 取消订单：order.user.cancel 执行取消

stateDiagram-v2
[*] --> 待付款
待付款 --> 已付款 : "支付成功/线下收款校验"
已付款 --> 已发货 : "提交物流单号"
已发货 --> 已完成 : "确认收货(业务规则)"
待付款 --> 已取消 : "用户取消/超时取消"
已付款 --> 已取消 : "退款/取消(业务规则)"

图表来源

• show.ts:35-182

章节来源

• show.ts:1-188

购物车页面

• 功能要点
  • 加载购物车数据：显示商品项、数量、总价
  • 数量调整：增加/减少数量，实时刷新
  • 删除商品：滑动删除或点击删除
• 关键流程
  • 加载数据：order.ts 调用 order 接口获取购物车
  • 更新数量：PUT 更新购物车项
  • 删除项：DEL 删除购物车项

章节来源

• order.ts:1-176
• OrderController.php:46-59

依赖关系分析

• 小程序页面依赖后端 API 路由与控制器
• 控制器依赖服务层（如 CheckoutService、CashierService、PaymentService）与数据库访问
• 支付流程依赖微信支付的 SDK/插件能力（user.weixin.pay）

graph LR
O["order.ts"] --> OC["OrderController.php"]
C["checkout.ts"] --> CC["CheckoutController.php"]
K["cashier.ts"] --> KC["CashierController.php"]
L["offlinepay.ts"] --> KC
S["show.ts"] --> KC

图表来源

• order.ts:38-49
• checkout.ts:23-96
• cashier.ts:19-77
• offlinepay.ts:35-94
• show.ts:35-182
• OrderController.php:46-59
• CheckoutController.php:55-131
• CashierController.php:63-161

章节来源

• OrderController.php:1-78
• CheckoutController.php:1-260
• CashierController.php:1-177

性能考虑

• 前端缓存与最小化请求
  • 结算页仅在必要时请求重算（切换配送/优惠券），避免频繁刷新
  • 购物车数量变更采用局部更新，减少全量刷新
• 后端重算优化
  • 运费与优惠券重算通过独立接口实现，降低主流程耦合
  • 使用 Session 暂存中间金额，提升响应速度
• 支付流程
  • 微信支付参数一次性下发，减少往返次数
  • 离线付款幂等创建 pending 支付记录，避免重复上传导致的数据不一致

故障排查指南

• 登录态失效
  • 现象：所有接口返回未授权错误
  • 处理：确保小程序侧 authStore.ensureLogin 成功，检查 token 存储与有效期
• 结算数据为空
  • 现象：进入结算页提示购物车为空
  • 处理：检查购物车是否有有效商品项，确认后端返回 cart 数据
• 运费/优惠券重算失败
  • 现象：金额未更新或报错
  • 处理：核对 shipping_id、coupon_id 合法性，检查后端重算逻辑与 Session 值
• 支付失败
  • 现象：微信支付唤起失败或支付失败回调
  • 处理：检查 user.weixin.pay 返回参数完整性，重试支付或引导用户重新发起
• 离线付款凭证上传失败
  • 现象：上传后无反馈或提示失败
  • 处理：确认 order_sn 与 payment_sn 正确，检查文件类型与大小限制
• 订单状态异常
  • 现象：订单无法推进到下一状态
  • 处理：检查权限与工作流配置，确认必要字段（如物流单号）已填写

章节来源

• checkout.ts:53-55
• cashier.ts:53-77
• offlinepay.ts:50-94
• show.ts:64-182

结论

本模块以清晰的页面与服务分层实现了从小程序购物车到订单完成的闭环流程。通过独立的结算与收银台控制器，结合灵活的运费与优惠券重算机制，以及微信支付与离线付款双通道，满足了多样化的交易场景。订单详情页提供了状态管理与后续操作入口，便于用户与工作人员协同推进订单生命周期。建议在后续迭代中增强异常提示与重试机制，完善退款与售后流程的接入。

附录

• 常用接口参考（基于实际调用）
  • 购物车：GET order（OrderController::index）
  • 结算数据：POST order.checkout（CheckoutController::index）
  • 提交下单：POST order.checkout.checkout_post（CheckoutController::checkoutPost）
  • 切换配送：POST order.checkout.change_shipping（CheckoutController::changeShipping）
  • 使用优惠券：POST order.checkout.use_coupon（CheckoutController::useCoupon）
  • 收银台：POST order.cashier（CashierController::index）
  • 离线付款：GET order.cashier.pay（CashierController::pay）
  • 上传凭证：POST order.cashier.pay_evidence（CashierController::payEvidence）
  • 订单详情：GET order.work.show（show.ts 调用）
  • 物流提交：POST order.work.tracking（show.ts 调用）
  • 支付校验：POST order.work.pay_check（show.ts 调用）
  • 取消订单：POST order.user.cancel（show.ts 调用）
  • 微信支付：POST user.weixin.pay（cashier.ts/show.ts 调用）

章节来源

• OrderController.php:46-59
• CheckoutController.php:55-207
• CashierController.php:63-161
• checkout.ts:23-96
• cashier.ts:19-77
• offlinepay.ts:35-94
• show.ts:35-182