简介

本模块面向 DouPHP 小程序的页面功能，覆盖首页展示、商品浏览、订单管理（购物车/结算）、用户中心等内容。文档从系统架构、数据流、接口调用、交互流程、页面间导航与数据传递、开发示例、性能优化与常见问题等方面进行全面说明，帮助开发者快速理解并高效扩展小程序页面能力。

项目结构

小程序默认主题位于 miniprogram/default，核心入口为 app.ts 与 app.json；业务页面集中在 pages 目录下，按功能域划分（如 index、product、order、user 等）。站点运行配置由 config/site.ts 提供，统一暴露根地址与 API 地址等全局常量。

graph TB
A["小程序入口<br/>app.ts"] --> B["应用配置<br/>app.json"]
A --> C["站点配置<br/>config/site.ts"]
B --> D["底部TabBar<br/>首页/产品中心/购物车/会员中心"]
A --> E["HTTP拦截器/错误处理"]
E --> F["服务层 services/http.ts"]
F --> G["路由工具 utils/route.ts"]
G --> H["后端API /api/*"]

核心组件

• 应用生命周期与全局初始化
  • 注册 HTTP 错误拦截器，统一处理未授权登出。
  • 解析推广参数 user_sn，写入本地缓存供后续使用。
  • 引导全局 store（MobX），实现状态持久化与热更新。
  • 计算导航栏高度，适配不同设备。
  • 自动检查更新，提示用户重启。
  • 调试环境开启 vConsole 与未捕获异常弹窗。
• 站点配置
  • 暴露 root_url、mp_url、douLoading、debug_enable、rewrite_enable 等运行时开关与地址。
• 页面通用能力
  • 通过 route() 生成 API 路径，屏蔽前后端路由差异。
  • 通过 http 封装发起请求，统一错误提示与鉴权处理。
  • 通过 store 绑定 commonStore/authStore/cartStore，实现跨页面状态共享。

架构总览

小程序采用“页面 + Store + Service”的分层模式：

• 页面层：负责 UI 渲染与用户交互，调用 service 获取数据。
• 服务层：封装网络请求、鉴权、错误处理、路由映射。
• 状态层：使用 MobX 管理全局状态（用户、购物车、站点信息等），支持持久化与跨页面同步。
• 配置层：集中管理站点运行参数与域名信息。

sequenceDiagram
participant U as "用户"
participant P as "页面(index/product/order/user)"
participant S as "服务(http/route)"
participant ST as "状态(store)"
participant API as "后端API"
U->>P : 触发操作(加载/点击/滑动)
P->>S : 调用http.get/post/put/del(route(...))
S->>API : 发送请求
API-->>S : 返回数据或错误
S-->>P : Promise结果
P->>ST : 更新store(登录态/购物车/站点信息)
P-->>U : 刷新UI/跳转/提示

详细组件分析

首页（pages/index）

• 功能特性
  • 加载站点信息与分类列表，支持分类横滑与进度条指示。
  • 商品列表分页加载，触底自动追加。
  • 轮播图控制与分享菜单设置。
  • 进入时恢复登录态，若为工作台角色则重定向至工作区。
• 数据结构
  • 站点信息、语言、功能开关、导航列表来自 commonStore。
  • 商品列表 product_list、分页 page、是否还有更多 nomore。
• 接口调用
  • 首页聚合数据：route('index')
  • 商品列表：route('product')
• 交互流程
  • 分类点击：存储分类ID并切换到产品中心 Tab。
  • 商品项点击：跳转到商品详情。
  • 触底加载：延迟后继续拉取下一页。
• 导航关系
  • switchTab 到产品中心、购物车、会员中心。
  • navigateTo 到非 Tab 页面（如文章、下载等）。

flowchart TD
Start(["进入首页"]) --> LoadSite["加载站点与分类"]
LoadSite --> LoadProducts["加载商品列表(第1页)"]
LoadProducts --> Render["渲染分类/轮播/商品"]
Render --> UserAction{"用户操作?"}
UserAction --> |分类点击| SwitchCat["保存分类ID并切换Tab"]
UserAction --> |商品点击| ToDetail["跳转到商品详情"]
UserAction --> |触底| NextPage["加载下一页并追加"]
NextPage --> Render
SwitchCat --> End(["结束"])
ToDetail --> End

商品详情（pages/product）

• 功能特性
  • 展示商品详情、图片轮播、属性选择、优惠券领取、收藏、评论列表。
  • 支持加入购物车与立即购买，根据购买模式跳转不同页面。
  • 属性变化时动态刷新属性列表与价格盒。
• 数据结构
  • 商品对象 product、收藏 favorites、定义字段 defined、优惠券 coupon_list、属性 attribute_list、价格盒 box、评论 comment_list、分页 page/nomore。
• 接口调用
  • 商品详情：route('product.show', {id})
  • 属性列表：route('product.attribute_list')
  • 评论列表：route('comment.list')
  • 收藏：route('favorites.user.store')
  • 领券：route('coupon.claim')
  • 加入购物车/立即购买：route('order.cart.store')
• 交互流程
  • 选择属性 -> 刷新属性列表 -> 更新数量与价格。
  • 收藏/领券 -> 成功后更新本地状态并提示。
  • 加入购物车 -> 根据 mode 决定跳转购物车或结算页。
• 导航关系
  • switchTab 到购物车。
  • navigateTo 到结算页、评论列表等。

sequenceDiagram
participant U as "用户"
participant P as "商品详情页"
participant S as "服务(http/route)"
participant API as "后端API"
U->>P : 打开商品详情
P->>S : GET product.show(id)
S-->>P : 返回商品/属性/优惠券
P->>S : GET comment.list(module=product, item_id)
S-->>P : 返回评论列表
U->>P : 选择属性/数量
P->>S : GET product.attribute_list(...)
S-->>P : 返回新属性/价格盒
U->>P : 加入购物车/立即购买
P->>S : POST order.cart.store(mode, action)
S-->>P : 成功
P-->>U : 跳转购物车或结算页

购物车（pages/order）

• 功能特性
  • 登录后加载购物车数据，支持左右滑动删除、修改数量。
  • 角标由 cartStore.badge 驱动，保持与 TabBar 一致。
• 数据结构
  • 购物车列表 cart.list、标题 title、滑动状态 touch_move/touch_move_start。
• 接口调用
  • 获取购物车：route('order')
  • 修改数量：route('order.cart.update', {id})
  • 删除条目：route('order.cart.destroy', {id})
• 交互流程
  • onShow 先确保登录，再加载数据。
  • 滑动角度判断避免误触，阈值控制显示删除按钮。
  • 修改数量/删除后重新拉取数据以保持一致性。
• 导航关系
  • navigateTo 到结算页、订单详情等。

flowchart TD
Enter(["进入购物车"]) --> Auth["确保登录"]
Auth --> Fetch["加载购物车数据"]
Fetch --> Render["渲染列表/角标"]
Render --> Swipe{"滑动操作?"}
Swipe --> |左滑| ShowDel["显示删除按钮"]
Swipe --> |右滑| HideDel["隐藏删除按钮"]
Render --> ChangeQty{"修改数量?"}
ChangeQty --> Update["调用update接口并刷新"]
Render --> Delete{"删除条目?"}
Delete --> Destroy["调用destroy接口并刷新"]
Update --> Render
Destroy --> Render

用户中心（pages/user）

• 功能特性
  • 展示用户信息、登录态、VIP/分销/工作台状态。
  • 支持退出登录、下载图片、复制文本等操作。
  • 滚动行为通过 Behavior 统一管理导航透明度。
• 数据结构
  • dou.user、dou.auth、dou.vip、dou.work、dou.distribution、welcome、link_user_center、if_connect_plugin。
• 接口调用
  • 用户信息：route('user')
• 交互流程
  • onShow 拉取用户信息并刷新购物车角标。
  • 退出登录清空本地缓存、重置购物车、返回首页。
• 导航关系
  • navigateTo 到登录、注册、密码重置、联系人管理等子页面。

依赖关系分析

• 页面依赖
  • 所有页面依赖 services/http 进行网络请求，依赖 utils/route 生成 API 路径。
  • 页面通过 stores/index 引入 authStore、commonStore、cartStore，实现状态共享。
• 应用级依赖
  • app.ts 在启动时注册全局错误处理、推广解析、自动更新、调试开关。
  • app.json 声明页面路由、TabBar、自定义导航栏样式与全局组件。
• 外部依赖
  • 后端 API 地址由 config/site.ts 提供，便于统一切换环境。

graph LR
Index["index.ts"] --> Http["services/http.ts"]
Product["product.ts"] --> Http
Order["order.ts"] --> Http
User["user.ts"] --> Http
Http --> Route["utils/route.ts"]
Http --> Site["config/site.ts"]
Index --> Stores["stores/index.js"]
Product --> Stores
Order --> Stores
User --> Stores
App["app.ts"] --> Stores
App --> Http

性能与体验优化

• 首屏与状态持久化
  • 启动时引导 store 并 hydrate，减少重复请求，提升秒开体验。
• 网络与错误处理
  • 统一 HTTP 拦截器处理 UNAUTHORIZED 场景，自动登出并清理状态。
  • 页面内 catch 统一提示，避免白屏与无反馈。
• 列表与滚动优化
  • 首页与商品评论采用分页加载与触底追加，降低首屏压力。
  • 分类横滑仅计算必要尺寸，使用 nextTick 与 SelectorQuery 精准测量。
• 图片与媒体
  • 商品详情页根据屏幕宽度计算图片高度，避免布局抖动。
• 更新机制
  • 自动检查新版本，提示用户重启，保证功能一致性。
• 调试与可观测性
  • 调试环境启用 vConsole 与未捕获异常弹窗，快速定位问题。
  • 页面不存在时记录日志并在调试期弹窗提示。

故障排查指南

• 未授权导致页面空白或无法操作
  • 现象：接口返回 UNAUTHORIZED，页面被强制登出。
  • 处理：检查登录态与 token，确认后端认证配置；必要时清除本地缓存并重新登录。
• 路由不存在或拼写错误
  • 现象：onPageNotFound 触发，调试期弹窗显示 path。
  • 处理：核对 app.json 中 pages 列表与 wx.navigateTo/switchTab 的 url。
• 推广链接无效
  • 现象：扫码或分享进入后 user_sn 未生效。
  • 处理：检查 scene 或 query 中的 user_sn 是否正确编码与传递；确认 parsePromotionFromLaunchOptions 逻辑。
• 列表不更新或角标不一致
  • 现象：购物车数量与角标不同步。
  • 处理：确保 onShow 中调用 cartStore.refresh()，并在增删改后刷新数据。
• 图片高度异常或布局抖动
  • 现象：商品图片加载后高度不正确。
  • 处理：使用 imageLoad 事件计算高度，基于 windowWidth 与原始宽高比设置。

结论

DouPHP 小程序页面模块以清晰的分层与统一的网络/状态管理为基础，提供了完整的首页、商品、订单与用户中心能力。通过 store 持久化、HTTP 拦截器、分页加载与自动更新机制，兼顾了性能与用户体验。开发者可基于现有页面模板与工具函数快速扩展新功能，同时遵循统一的错误处理与调试策略，保障稳定性与维护性。

附录：页面清单与导航关系

• 底部 TabBar 页面
  • 首页：pages/index/index
  • 产品中心：pages/product_category/product_category
  • 购物车：pages/order/order
  • 会员中心：pages/user/user
• 常用页面
  • 商品详情：pages/product/product
  • 订单相关：pages/order/checkout、pages/order/show、pages/order/success、pages/order/user
  • 用户相关：pages/user/login_account、pages/user/register、pages/user/password_reset
  • 内容类：pages/article/article、pages/doc/doc、pages/download/download、pages/cases/cases
• 导航方式
  • switchTab：用于 TabBar 页面切换（首页、产品中心、购物车、会员中心）。
  • navigateTo：用于非 TabBar 页面跳转（如商品详情、订单详情、用户登录等）。
  • 参数传递：通过 URL query 或本地 storage（如 product_category_id、product_buy_mode、shareTitle）。