电商页面模块 | DouPHP 开发手册 | 文档中心

电商页面模块

简介

本模块面向DouPHP小程序电商页面，覆盖商品展示、购物车、订单管理、售后服务等核心功能。文档从系统架构、数据流、处理逻辑、集成点与错误处理等方面展开，并结合代码级图示说明关键流程。同时提供开发示例（接口调用、本地存储、提交校验）、性能优化策略与常见问题解决方案，帮助开发者快速落地与维护。

项目结构

小程序前端：位于 miniprogram/default 下，包含 pages（页面）、stores（状态管理）、services（HTTP封装）、utils（工具）等。
API后端：位于 api/controller 下，按业务域划分控制器（product、order、aftersale 等）。
主题模板：front/theme 与 newtheme 提供Web端模板；小程序侧以TS+WXML为主。

graph TB
subgraph "小程序前端"
P["pages/*"] --> S["stores/*"]
P --> H["services/http.ts"]
P --> U["utils/*"]
end
subgraph "API后端"
PC["api/controller/product/*"]
OC["api/controller/order/*"]
AC["api/controller/aftersale/*"]
end
P --> H
H --> OC
H --> PC
H --> AC

图表来源

miniprogram/default/pages/product/product.ts:1-325
miniprogram/default/stores/cart.ts:1-78
miniprogram/default/pages/order/checkout.ts:1-214
api/controller/product/ProductController.php
api/controller/order/CartController.php
api/controller/order/CheckoutController.php
api/controller/aftersale/AftersaleController.php

章节来源

miniprogram/default/pages/product/product.ts:1-325
miniprogram/default/stores/cart.ts:1-78
miniprogram/default/pages/order/checkout.ts:1-214

核心组件

商品详情页：负责商品基础信息加载、规格选择、图片轮播、评论分页、收藏与优惠券领取、加入购物车/立即购买。
购物车：通过 store 维护角标数量，支持可选模块降级与未登录态静默处理。
结算页：负责收货地址选择、运费与优惠券计算、下单提交并跳转收银台。
售后：提供申请与跟踪能力（由对应控制器暴露接口）。

章节来源

miniprogram/default/pages/product/product.ts:1-325
miniprogram/default/stores/cart.ts:1-78
miniprogram/default/pages/order/checkout.ts:1-214
api/controller/aftersale/AftersaleController.php

架构总览

小程序前端通过统一HTTP服务调用后端API，控制器将请求路由到具体业务逻辑，返回结构化数据供页面渲染与交互。购物车数量在store中集中管理，并在tabBar处显示角标。

sequenceDiagram
participant UI as "商品详情页"
participant Store as "购物车Store"
participant HTTP as "HTTP服务"
participant API as "后端API"
UI->>HTTP : 获取商品详情(产品ID)
HTTP->>API : GET /product/show
API-->>HTTP : {product, defined, coupon_list}
HTTP-->>UI : 渲染商品详情
UI->>HTTP : 获取购物车数量
HTTP->>API : GET /order/cart_number
API-->>HTTP : {cart_number}
HTTP-->>Store : 更新角标数量
UI->>HTTP : 加入购物车/立即购买
HTTP->>API : POST /order/cart.store
API-->>HTTP : {mode, redirect_url}
HTTP-->>UI : 跳转结算或订单页

图表来源

miniprogram/default/pages/product/product.ts:65-127
miniprogram/default/stores/cart.ts:30-71
api/controller/product/ProductController.php
api/controller/order/CartController.php

详细组件分析

商品详情页（product.ts）

生命周期与初始化
- onShow：若启用订单模块则拉取购物车数量用于展示角标。
- onLoad：根据参数加载商品详情、属性列表、评论列表，设置分享标题与购买模式。
交互逻辑
- 规格选择：监听属性变化，动态刷新可用SKU与价格。
- 评论分页：支持下拉加载更多，避免重复请求。
- 收藏与领券：调用收藏与优惠券接口，更新本地状态。
- 加入购物车/立即购买：登录后发起下单前置动作，依据返回模式跳转结算或订单页。
图片轮播与自适应高度：基于swiper与图片加载事件计算高度，提升首屏体验。

flowchart TD
Start(["进入商品详情页"]) --> LoadDetail["加载商品详情"]
LoadDetail --> LoadAttrs["加载属性/SKU列表"]
LoadAttrs --> UserSelect{"用户选择规格?"}
UserSelect --> |是| UpdatePrice["更新价格与库存"]
UserSelect --> |否| WaitAction["等待操作"]
UpdatePrice --> AddCart{"加入购物车/立即购买"}
AddCart --> |加入购物车| GoOrder["跳转订单页"]
AddCart --> |立即购买| Checkout["跳转结算页"]
WaitAction --> End(["结束"])
GoOrder --> End
Checkout --> End

图表来源

miniprogram/default/pages/product/product.ts:65-145
miniprogram/default/pages/product/product.ts:183-197
miniprogram/default/pages/product/product.ts:101-127

章节来源

miniprogram/default/pages/product/product.ts:1-325

购物车（cart.ts）

职责
- 维护购物车数量与角标文案（0为空串，>99为“99+”）。
- 可选模块降级：当 features.order 非 true 时，直接置零并短路请求。
- 未登录态：无 token 时不请求，保持数量为0。
数据流
- refresh：尝试获取 route('order.cart')，解析 cart_number 并更新状态。
- reset：清空数量。

classDiagram
class CartStore {
+number : number
+badge : string
+refresh() Promise<void>
+reset() void
}
class CommonStore {
+features : object
}
class HttpService {
+get(url) Promise
}
CartStore --> CommonStore : "检查模块开关"
CartStore --> HttpService : "获取购物车数量"

图表来源

miniprogram/default/stores/cart.ts:15-77

章节来源

miniprogram/default/stores/cart.ts:1-78

结算页（checkout.ts）

职责
- 加载购物车与订单汇总信息（运费、优惠券、金额）。
- 选择收货地址与配送方式，实时计算费用。
- 提交订单并跳转至收银台进行支付。
关键流程
- onLoad：调用 order.checkout 获取结算数据。
- orderSuccess：提交订单（含联系人、地址、运费、优惠券），成功后跳转到 cashier_url。
- radioShipping/useCoupon：切换配送与使用优惠券，重新计算金额。

sequenceDiagram
participant UI as "结算页"
participant HTTP as "HTTP服务"
participant API as "后端API"
UI->>HTTP : POST /order/checkou
HTTP->>API : 获取购物车、运费、优惠券、订单汇总
API-->>HTTP : {cart, shipping_list, amount, order}
HTTP-->>UI : 渲染结算信息
UI->>HTTP : POST /order/checkout.checkout_post
HTTP->>API : 提交订单(联系人/地址/运费/优惠券)
API-->>HTTP : {cashier_url}
HTTP-->>UI : 跳转收银台

图表来源

miniprogram/default/pages/order/checkout.ts:33-95
miniprogram/default/pages/order/checkout.ts:98-134

章节来源

miniprogram/default/pages/order/checkout.ts:1-214

售后服务（AftersaleController）

职责
- 提供售后申请、查询、进度跟踪等接口。
- 与订单关联，支持状态流转（申请中、审核中、同意/拒绝、退款完成等）。
集成点
- 小程序售后页面通过HTTP调用相关接口，展示售后单列表与详情。

章节来源

api/controller/aftersale/AftersaleController.php

依赖关系分析

前端依赖
- product.ts 依赖 http、route、authStore、commonStore、ui/page_title 等工具与服务。
- cart.ts 依赖 commonStore 的 features 判断、http 获取数量、route 生成URL。
- checkout.ts 依赖 authStore、http、route、ui。
后端依赖
- ProductController 提供商品详情、属性列表等。
- CartController 提供购物车数量与增删改查。
- CheckoutController 提供结算与下单。
- AftersaleController 提供售后相关能力。

graph LR
A["product.ts"] --> B["http.ts"]
A --> C["route.ts"]
A --> D["authStore/commonStore"]
E["cart.ts"] --> B
E --> C
F["checkout.ts"] --> B
F --> C
F --> D
B --> G["ProductController"]
B --> H["CartController"]
B --> I["CheckoutController"]
B --> J["AftersaleController"]

图表来源

miniprogram/default/pages/product/product.ts:1-325
miniprogram/default/stores/cart.ts:1-78
miniprogram/default/pages/order/checkout.ts:1-214
api/controller/product/ProductController.php
api/controller/order/CartController.php
api/controller/order/CheckoutController.php
api/controller/aftersale/AftersaleController.php

章节来源

miniprogram/default/pages/product/product.ts:1-325
miniprogram/default/stores/cart.ts:1-78
miniprogram/default/pages/order/checkout.ts:1-214

性能考虑

图片懒加载与自适应高度：利用图片加载事件计算高度，减少重排与闪烁。
分页加载评论：按需追加数据，避免一次性加载大量内容。
购物车角标缓存：在store中维护数量，减少重复请求；未登录或模块关闭时短路。
路由与接口复用：通过统一的route与http封装，降低耦合与重复代码。
建议
- 对商品列表与详情实施CDN与缓存策略。
- 对高频接口增加服务端缓存与限流。
- 使用骨架屏与占位图提升感知性能。

故障排查指南

常见错误与处理
- 网络异常：统一捕获并提示“请求失败”，确保用户体验。
- 未登录态：在需要鉴权的操作中先执行 ensureLogin，失败则中断后续流程。
- 模块未启用：当 features.order 非 true 时，购物车相关逻辑短路，避免报错。
- 库存不足：在后端校验后返回明确错误消息，前端提示用户调整数量或更换规格。
- 支付失败重试：收银台返回错误码时，允许用户重试或切换支付方式。
- 订单超时取消：服务端定时任务清理超时未支付订单，前端轮询订单状态并提示。
定位方法
- 查看HTTP响应与错误消息，结合控制台日志定位问题。
- 检查路由是否正确映射到控制器与方法。
- 核对前后端字段命名与数据结构一致性。

章节来源

miniprogram/default/pages/product/product.ts:79-81
miniprogram/default/pages/product/product.ts:117-127
miniprogram/default/stores/cart.ts:54-71
miniprogram/default/pages/order/checkout.ts:53-55
miniprogram/default/pages/order/checkout.ts:90-95

结论

本模块围绕商品展示、购物车、订单与售后构建了完整的小程序电商闭环。通过清晰的职责划分、统一的服务封装与健壮的错误处理，确保了良好的可维护性与扩展性。建议在后续迭代中持续优化性能与用户体验，完善支付与售后流程的容错机制。

附录

开发示例参考路径
- 商品搜索接口调用：参见商品详情页中对商品详情与属性列表的调用。
- 购物车本地存储：参见购物车store的数量管理与角标更新。
- 订单提交验证：参见结算页对联系人、地址、运费、优惠券的校验与提交。
数据模型设计要点
- 商品SKU管理：通过属性列表与选择结果动态计算价格与库存。
- 订单状态机：从创建、待支付、已支付、发货、确认收货到完成/售后。
- 库存扣减逻辑：在下单与支付成功阶段扣减库存，失败或取消时回滚。
性能优化清单
- 图片懒加载、分页加载、接口缓存、CDN加速、骨架屏与占位图。

添加日期：2026-10-05