简介

本组件文档面向 DouPHP 小程序端的“订单管理”能力，覆盖订单列表、订单详情、订单状态管理等关键页面与交互。重点说明：

• 订单数据获取、更新、删除的调用路径
• 订单状态流转（支付、发货、取消等）
• 支付集成（微信支付）与物流跟踪（物流公司+运单号）
• 组件配置项、事件回调与用户交互流程
• 前后端协作方式与错误处理策略

项目结构

小程序订单相关页面位于 miniprogram/default/pages/order，包含购物车入口、订单详情、会员订单列表等；后端 API 控制器位于 api/controller/order，提供购物车与订单相关接口。

graph TB
subgraph "小程序前端"
A["order.ts<br/>购物车入口"]
B["show.ts<br/>订单详情"]
C["user.ts<br/>我的订单列表"]
end
subgraph "后端API"
D["OrderController.php<br/>购物车首页(order)"]
end
A --> D
B -.->|"调用其他订单接口"| D
C -.->|"调用其他订单接口"| D

核心组件

• 购物车入口（order.ts）
  • 功能：展示购物车条目、数量增减、侧滑删除、跳转结算
  • 数据：通过 route('order') 获取购物车标题与条目
  • 操作：PUT 更新数量、DELETE 删除条目
• 订单详情（show.ts）
  • 功能：加载订单详情、支付校验（线下收款）、提交物流信息、预览支付凭证、取消订单、发起微信支付
  • 数据：route('order.work.show') 返回订单、支付方式、可选物流列表、是否需要支付校验等
  • 操作：POST 支付校验、POST 提交物流、POST 取消订单、POST 发起微信支付
• 我的订单列表（user.ts）
  • 功能：按状态筛选、分页加载、滚动到底自动加载更多、取消订单
  • 数据：route('order.user') 返回订单列表、状态枚举、支付方式等

架构总览

小程序订单模块采用“页面 + Store + HTTP + 路由”的分层组织：

• 页面层：order.ts / show.ts / user.ts 负责 UI 与交互
• 服务层：http.ts 封装网络请求，route.ts 生成后端路由
• 存储层：stores/index.js 中的 authStore、cartStore、commonStore 管理登录态、购物车刷新、站点语言等
• 后端：OrderController.php 承载购物车首页接口，其余订单接口由同目录下其他控制器实现

sequenceDiagram
participant U as "用户"
participant P as "小程序页面"
participant H as "HTTP服务"
participant R as "路由/鉴权"
participant C as "OrderController"
participant S as "OrderService(后端)"
U->>P : 打开购物车/订单页
P->>H : GET order (购物车首页)
H->>R : 鉴权
R-->>H : 通过/拒绝
H->>C : index()
C->>S : getCart(userId)
S-->>C : 购物车数据
C-->>H : 成功响应
H-->>P : 渲染购物车

详细组件分析

购物车入口（order.ts）

• 生命周期与初始化
  • onLoad：绑定 commonStore，设置购买模式为 money
  • onShow：确保登录成功后加载购物车数据
• 数据加载
  • 调用 route('order') 获取 title 与 cart
• 交互逻辑
  • 数量变更：PUT 更新数量，成功后重新加载
  • 侧滑删除：touchStart/touchMove/touchEnd 计算滑动距离与角度，达到阈值后执行删除
  • 删除条目：DELETE 删除后刷新列表
• 错误处理
  • 统一使用 douMsg 提示失败原因或默认文案

flowchart TD
Start(["进入购物车"]) --> Auth{"已登录?"}
Auth -- 否 --> Login["引导登录"]
Auth -- 是 --> Load["加载购物车数据"]
Load --> Interact{"用户操作"}
Interact -- 数量变化 --> Update["PUT 更新数量"]
Interact -- 侧滑删除 --> Delete["DELETE 删除条目"]
Update --> Reload["刷新列表"]
Delete --> Reload
Reload --> End(["完成"])

订单详情（show.ts）

• 数据加载
  • 调用 route('order.work.show', { order_sn }) 获取订单详情、支付方式、物流列表、是否需要支付校验等
• 业务操作
  • 支付校验（线下收款）：POST 到 order.work.pay_check，确认后刷新订单
  • 物流跟踪：选择物流公司并填写运单号，POST 到 order.work.tracking，成功后刷新
  • 取消订单：POST 到 order.user.cancel，成功后返回列表
  • 微信支付：POST 到 user.weixin.pay，获取支付参数后调用 wx.requestPayment，成功后刷新
• 错误处理
  • 统一使用 douMsg 提示失败原因或默认文案

sequenceDiagram
participant U as "用户"
participant P as "订单详情页"
participant H as "HTTP服务"
participant W as "微信客户端"
U->>P : 打开订单详情
P->>H : GET order.work.show(order_sn)
H-->>P : 返回订单/支付/物流信息
U->>P : 点击“确认收款”
P->>H : POST order.work.pay_check
H-->>P : 更新订单状态
U->>P : 填写物流并提交
P->>H : POST order.work.tracking
H-->>P : 提交成功
U->>P : 点击“立即支付”
P->>H : POST user.weixin.pay
H-->>P : 返回支付参数
P->>W : requestPayment(...)
W-->>P : 支付结果
P->>H : 刷新订单详情

我的订单列表（user.ts）

• 数据加载
  • 首次进入：onShow 中确保登录后重置分页并加载列表
  • 分页：onReachBottom 触发下一页加载，支持拼接数据
• 交互逻辑
  • 状态筛选：切换 status 并重新加载
  • 取消订单：POST 到 order.user.cancel 后刷新列表
• 错误处理
  • 统一使用 douMsg 提示失败原因或默认文案

flowchart TD
Enter["进入我的订单"] --> Auth{"已登录?"}
Auth -- 否 --> Login["引导登录"]
Auth -- 是 --> Init["初始化分页/状态"]
Init --> Load["GET order.user(status, page)"]
Load --> Render["渲染列表"]
Render --> Scroll{"触底?"}
Scroll -- 是 --> Next["page+1 并加载"]
Scroll -- 否 --> Action{"用户操作"}
Next --> Render
Action -- 切换状态 --> Load
Action -- 取消订单 --> Cancel["POST order.user.cancel"] --> Load

依赖关系分析

• 前端依赖
  • stores/index.js：authStore（登录态）、cartStore（购物车刷新）、commonStore（站点/语言/特性）
  • services/http.ts：统一网络请求封装
  • utils/route.ts：生成后端路由名
  • utils/ui.ts：统一消息提示
• 后端依赖
  • OrderController.php：购物车首页接口，内部依赖 OrderService
  • 其他订单接口（如 order.user、order.work.*、user.weixin.pay）由同目录控制器实现，被小程序页面通过 route 调用

graph LR
TS_order["order.ts"] --> RT["utils/route.ts"]
TS_show["show.ts"] --> RT
TS_user["user.ts"] --> RT
RT --> API["api/controller/order/*.php"]
API --> SVC["OrderService(后端)"]

性能考虑

• 分页与懒加载
  • 我的订单列表采用分页加载，避免一次性拉取大量数据
• 登录态复用
  • 通过 authStore.ensureLogin 在多个页面复用登录检查，减少重复鉴权开销
• 局部刷新
  • 购物车数量更新、删除等操作后仅刷新必要数据，降低重绘成本
• 网络请求合并
  • 建议将关联数据（如订单详情与物流列表）在一次请求中返回，减少往返次数

故障排查指南

• 常见错误提示
  • 请求失败：统一通过 douMsg 显示 err.message 或默认文案
  • 未登录：OrderController 中会抛出未授权错误，前端需引导登录
• 定位步骤
  • 检查 route 是否正确映射到后端控制器
  • 检查 http 请求是否携带必要的 token/会话
  • 查看后端日志与数据库记录，确认状态流转是否符合预期
• 常见问题
  • 微信支付失败：核对 user.weixin.pay 返回参数与签名
  • 物流提交失败：确认 shipping_id 与 tracking_no 非空且格式正确

结论

DouPHP 小程序订单管理组件以清晰的页面分层与统一的 HTTP/路由抽象，实现了购物车、订单详情与订单列表的核心能力。通过标准化的错误处理与状态流转（支付、物流、取消），配合后端 OrderService 与多控制器协同，满足常见的电商订单场景。建议在后续迭代中继续优化分页体验、合并请求与增强异常反馈，以提升用户体验与系统稳定性。

附录

订单数据结构（基于页面返回字段）

• 购物车（order.ts）
  • title：购物车标题
  • cart：购物车条目集合（含商品、数量、价格等）
• 订单详情（show.ts）
  • order：订单主体（含 order_sn、tracking_no 等）
  • payment：支付方式列表
  • need_pay_check：是否需要线下收款校验
  • shipping_list：可选物流公司列表
  • shipping_index：当前选中的物流公司索引
  • tracking_no：运单号
• 我的订单列表（user.ts）
  • order_list：订单列表
  • status_list：状态枚举
  • payment：支付方式列表

状态流转（支付、物流、取消）

stateDiagram-v2
[*] --> 待付款
待付款 --> 已付款 : "微信支付成功"
待付款 --> 已取消 : "用户取消"
已付款 --> 已发货 : "提交物流信息"
已发货 --> 已完成 : "确认收货(外部流程)"
已取消 --> [*]
已完成 --> [*]

[此图为概念性流程图，不直接映射具体代码文件]

支付集成（微信支付）

• 前端调用顺序
  • POST user.weixin.pay 获取支付参数
  • 调用 wx.requestPayment 发起支付
  • 支付成功后刷新订单详情
• 注意事项
  • 确保签名类型与参数一致
  • 处理支付成功与失败的分支逻辑

物流跟踪

• 前端输入
  • 选择物流公司（shipping_list）
  • 填写运单号（tracking_no）
• 提交接口
  • POST order.work.tracking
• 成功后
  • 提示提交成功并刷新订单详情