简介

本文件面向 DouPHP 小程序端的“业务功能组件”，聚焦商品展示、订单（购物车）、用户信息、表单等与业务强相关的页面级组件。文档从数据结构、接口调用、状态管理、错误处理、扩展点与定制化方法等维度，系统梳理各组件的职责边界、数据流与交互方式，帮助开发者快速集成与二次开发。

项目结构

小程序端采用“页面 + 服务层 + 状态管理”的分层组织：

• 页面层：按业务模块划分 pages/*，如 product、order、user、form。
• 服务层：统一网络请求封装 services/http.ts，提供 get/post/put/del、缓存、去重、拦截器能力。
• 状态管理：stores/* 基于 MobX 的轻量状态管理，包含 authStore、cartStore、commonStore 等。
• 应用入口：app.ts 负责全局初始化、推广解析、自动更新、全局错误钩子与 store 引导。

graph TB
subgraph "小程序入口"
A["app.ts"]
end
subgraph "服务层"
B["services/http.ts"]
end
subgraph "状态管理"
C["stores/index.ts"]
D["stores/auth.ts"]
end
subgraph "业务页面"
E["pages/product/product.ts"]
F["pages/order/order.ts"]
G["pages/user/user.ts"]
H["pages/form/form.ts"]
end
A --> B
A --> C
C --> D
E --> B
F --> B
G --> B
H --> B
E --> D
F --> D
G --> D

核心组件

• 商品展示组件（product）：负责商品详情加载、属性选择、评论分页、收藏、优惠券领取、加入购物车/立即购买等。
• 订单组件（order）：购物车列表、数量变更、滑动删除、跳转结算页。
• 用户信息组件（user）：用户中心首页，聚合登录态、VIP、员工、分销等标识，支持退出登录、图片下载、文本复制等。
• 表单组件（form）：动态表单列表展示与分页加载。

这些组件通过统一的 http 服务访问后端 API，并通过 stores 管理登录态、购物车角标等全局状态。

架构总览

小程序启动时，app.ts 注册 HTTP 错误拦截器、解析推广参数、引导全局 store、计算导航栏高度并开启自动更新。随后各业务页面按需加载数据，统一通过 http 服务发起请求；登录态由 authStore 维护，购物车角标由 cartStore 驱动并在 tabBar 上显示。

sequenceDiagram
participant App as "App(app.ts)"
participant Http as "HTTP(http.ts)"
participant Auth as "Auth(auth.ts)"
participant Store as "Stores(index.ts)"
participant Page as "业务页面"
App->>Http : 注册 onError 拦截器
App->>Store : bootstrapStores()
Store->>Auth : hydrate/restore
App-->>Page : 页面渲染
Page->>Http : 调用业务接口
Http-->>Page : 返回 data 或抛出 ApiError
Note over Http,Page : 失败时触发 onError 拦截器如 UNAUTHORIZED -> logout

详细组件分析

商品展示组件（product）

• 职责
  • 加载商品详情、属性列表、评论列表（支持分页）。
  • 处理收藏、优惠券领取、加入购物车/立即购买。
  • 根据 features.order 控制是否允许下单相关操作。
• 数据结构
  • 本地 data：product、favorites、attribute_list、comment_list、page、nomore、mode 等。
  • 服务端返回：product、defined、coupon_list、open、comment_list 等。
• 接口调用
  • 商品详情：GET product.show
  • 属性列表：GET product.attribute_list
  • 评论列表：GET comment.list（module=product）
  • 收藏：POST favorites.user.store
  • 优惠券：POST coupon.claim
  • 购物车：POST order.cart.store（加入购物车/立即购买）
• 状态管理
  • 使用 commonStore 读取 site/lang/data/param/features。
  • 通过 authStore.ensureLogin 保证登录后再执行敏感操作。
• 错误处理
  • 统一通过 http 抛出的 ApiError 捕获，使用 douMsg 提示。
• 扩展点
  • 通过 features.order 开关控制下单流程。
  • 可复用 attribute_data_box 实现多规格联动。
  • 评论分页逻辑可复用于其他列表场景。

sequenceDiagram
participant P as "Product 页面"
participant H as "HTTP"
participant A as "Auth"
P->>H : GET product.show(id)
H-->>P : {product, defined, coupon_list, open}
P->>H : GET product.attribute_list(id, mode, attribute_data)
H-->>P : {attribute_list, box}
P->>A : ensureLogin()
A-->>P : true/false
P->>H : POST order.cart.store({post, mode, action})
H-->>P : 成功 -> 跳转 checkout 或 购物车

订单组件（order）

• 职责
  • 展示购物车列表，支持数量增减、滑动删除、跳转结算。
  • 进入前确保登录态。
• 数据结构
  • 本地 data：startX/startY（滑动计算）、title、cart（含 list）。
  • 服务端返回：title、cart（list 项含 touch_move/touch_move_start 等）。
• 接口调用
  • 获取购物车：GET order
  • 更新数量：PUT order.cart.update/{id}
  • 删除条目：DELETE order.cart.destroy/{id}
• 状态管理
  • 通过 authStore.ensureLogin 保护写操作。
  • 购物车角标由 cartStore.badge 在 tabBar 统一驱动。
• 错误处理
  • 统一捕获 ApiError 并提示。
• 扩展点
  • 滑动删除阈值与动画可配置。
  • 可在 onShow 中增加增量刷新策略。

flowchart TD
Start(["进入购物车"]) --> Login{"已登录?"}
Login --> |否| Redirect["跳转登录页"]
Login --> |是| Load["加载购物车数据"]
Load --> Render["渲染列表"]
Render --> Action{"用户操作"}
Action --> |数量变更| Update["PUT 更新数量"]
Action --> |滑动删除| Delete["DELETE 删除条目"]
Update --> Reload["重新加载购物车"]
Delete --> Reload
Reload --> End(["完成"])

用户信息组件（user）

• 职责
  • 展示用户中心首页，聚合登录态、VIP、员工、分销等信息。
  • 提供退出登录、图片下载、文本复制等工具能力。
• 数据结构
  • 本地 data：dou.user、dou.auth、welcome、link_user_center、if_connect_plugin。
  • 服务端返回：dou（含 auth 标志）、welcome、link_user_center 等。
• 接口调用
  • 获取用户信息：GET user
• 状态管理
  • 通过 authStore 管理登录态；cartStore.refresh 刷新购物车角标。
• 错误处理
  • 统一捕获 ApiError 并提示。
• 扩展点
  • 可通过 link_user_center 配置快捷入口。
  • 下载/复制等工具方法可复用至其他页面。

表单组件（form）

• 职责
  • 展示动态表单列表，支持分页加载。
• 数据结构
  • 本地 data：form_list、page、nomore。
  • 服务端返回：form_list。
• 接口调用
  • 获取表单列表：GET form（带 page）
• 错误处理
  • 统一捕获 ApiError 并提示。
• 扩展点
  • 分页加载逻辑可复用于其他列表型页面。

依赖关系分析

• 页面依赖
  • product/order/user/form 均依赖 http.ts 进行网络请求。
  • product/order/user 依赖 authStore 进行鉴权检查。
  • order/user 依赖 cartStore 以同步购物车角标。
• 服务层依赖
  • http.ts 提供信封解析、缓存、去重、拦截器、调试增强。
• 状态管理依赖
  • index.ts 聚合 store，并在 app 启动时引导 hydrate/refresh。
  • auth.ts 维护 api_token、user_id、loginEd 及登录态标志。

graph LR
Product["product.ts"] --> Http["http.ts"]
Order["order.ts"] --> Http
User["user.ts"] --> Http
Form["form.ts"] --> Http
Product --> Auth["auth.ts"]
Order --> Auth
User --> Auth
Order --> Index["stores/index.ts"]
User --> Index

性能考虑

• 请求去重与缓存
  • http.ts 对相同 GET 请求在飞行中进行 Promise 复用，减少重复请求。
  • 可选内存缓存（cache + ttl），适合不频繁变化的列表数据。
• 首屏优化
  • stores/index.ts 先 hydrate（storage 秒开），再 refresh（网络刷新），提升冷启动体验。
• 角标更新
  • 购物车角标通过 autorun 统一绑定，避免多处重复 setTabBarBadge。
• 建议
  • 列表类数据优先启用 cache+revalidate 实现 SWR 刷新。
  • 大列表分页加载，避免一次性拉取过多数据。

故障排查指南

• 统一错误对象
  • http.ts 将网络异常、HTTP 非 2xx、业务码非 OK 统一包装为 ApiError，包含 code、message、errors、request_id。
• 未授权处理
  • app.ts 在 http.onError 中监听 UNAUTHORIZED，触发 authStore.logout 清理登录态。
• 调试增强
  • 调试环境下，http.ts 会将 request_id 附加到 message，并在服务端异常载荷下弹出 modal 便于定位问题。
• 常见问题定位
  • 若页面频繁提示“请求失败”，检查路由是否正确、features 是否禁用对应模块。
  • 若购物车角标不更新，确认 cartStore.refresh 是否被调用以及是否在 tabBar 页面。

结论

DouPHP 小程序的业务组件以“页面 + 服务层 + 状态管理”的分层架构清晰解耦了 UI、网络与状态。商品、订单、用户、表单等组件通过统一的 http 服务与 stores 协作，具备完善的错误处理与调试能力。开发者可基于现有扩展点（如 features 开关、store 引导、http 拦截器）进行定制与二次开发，快速构建稳定的小程序业务功能。

附录

• 常用接口路径参考（以 route('...') 形式调用）
  • 商品：product.show、product.attribute_list
  • 评论：comment.list
  • 收藏：favorites.user.store
  • 优惠券：coupon.claim
  • 购物车：order.cart.store、order.cart.update、order.cart.destroy
  • 订单：order
  • 用户：user
  • 表单：form
• 状态字段参考
  • authStore：api_token、user_id、loginEd、is_login、is_vip、is_work、is_distribution
  • cartStore：badge（用于 tabBar 角标）
  • commonStore：site、lang、data、param、features