简介

本开发文档面向 DouPHP 小程序“用户中心”模块，覆盖登录注册、个人中心、收藏夹、钱包管理、积分系统等用户相关功能。重点说明：

• 用户认证流程的安全实现（验证码、防重放、会话与令牌）
• 个人信息编辑与头像上传
• 收藏内容的管理与分类
• 钱包余额充值与提现记录
• 积分获取与消耗的历史查询
• 数据安全存储与隐私保护（敏感信息加密、会话管理、权限控制）
• 微信登录集成、表单验证、数据同步等开发示例
• 交互体验优化（操作反馈、错误提示、加载状态）
• 常见问题解决方案（登录状态保持、数据同步冲突、权限验证失败）

项目结构

用户中心在前后端分离的架构下由两部分组成：

• 后端 Web 控制器：负责会员首页、登录注册、找回密码、文件上传等能力
• 小程序前端页面：提供用户中心入口、钱包、积分、收藏等交互界面

graph TB
subgraph "小程序前端"
U["pages/user/user.ts"]
M["pages/money/money.ts"]
P["pages/point/point.ts"]
F["pages/favorites/favorites.ts"]
end
subgraph "后端Web层"
UC["UserController<br/>会员中心首页/地区/文件上传"]
AC["AuthController<br/>登录/注册/找回密码/退出"]
end
U --> UC
M --> UC
P --> UC
F --> UC

核心组件

• 用户中心首页（小程序 user.ts 调用后端 user/index）
• 认证子系统（登录、注册、手机验证码登录、找回密码、退出）
• 文件上传（头像、内容图片等）
• 钱包支付码轮询（money.ts）
• 积分列表分页（point.ts）
• 收藏夹占位页（favorites.ts）

架构总览

用户中心采用“小程序页面 -> 后端控制器 -> 服务/模型”的分层架构。小程序通过统一 HTTP 客户端发起请求；后端控制器负责鉴权、参数校验、业务编排与安全策略；视图与模板渲染由后端完成，小程序侧仅做展示与交互。

sequenceDiagram
participant WX as "小程序页面"
participant API as "后端控制器"
participant Svc as "服务层"
participant DB as "数据库"
WX->>API : 请求用户中心首页
API->>Svc : 获取用户信息与欢迎语
Svc->>DB : 读取用户资料/配置
DB-->>Svc : 用户数据
Svc-->>API : 组装响应
API-->>WX : JSON(用户信息/导航/链接)
Note over WX,API : 所有受保护接口需携带会话或令牌

详细组件分析

用户认证流程（登录/注册/手机登录/找回密码/退出）

• 账号密码登录：支持验证码开关、Honeypot 防机器人、凭据校验后写入会话，并可选绑定第三方账号
• 手机验证码登录：校验短信验证码与图形验证码时效，自动建号时保留推广关系
• 注册：支持邮箱/手机号模式，强制验证码校验与协议页存在性检查，成功后自动登录
• 找回密码：分两步校验账户存在性与验证码时效，重置密码后吊销该用户全部 API Token
• 退出：清除会话并重定向

sequenceDiagram
participant C as "客户端"
participant A as "AuthController"
participant L as "LoginService"
participant R as "RegistrationService"
participant S as "Session/Token"
C->>A : POST 登录/注册/手机登录
A->>A : 表单校验/Honeypot/验证码
A->>L : 校验凭据(账号密码/手机+验证码)
L-->>A : 结果(成功/错误)
alt 成功
A->>S : 写入会话/令牌
A->>R : 必要时绑定SNS/记录推广关系
A-->>C : 跳转/返回JSON
else 失败
A-->>C : 错误消息
end

个人中心与文件上传（头像/内容图）

• 会员中心首页：未登录重定向至登录；已登录渲染用户信息与欢迎语
• 文件上传：支持草稿态与正式态两种场景，按业务字段命名、限制数量、水印与尺寸处理；删除草稿/正式附件后回显剩余列表

flowchart TD
Start(["进入个人中心"]) --> CheckAuth{"是否已登录?"}
CheckAuth --> |否| ToLogin["重定向到登录页"]
CheckAuth --> |是| LoadData["加载用户信息/导航/SEO"]
LoadData --> Render["渲染用户中心首页"]
Render --> Upload{"是否需要上传文件?"}
Upload --> |是| DraftOrReal{"草稿还是正式?"}
DraftOrReal --> |草稿| StoreDraft["存储草稿附件"]
DraftOrReal --> |正式| StoreReal["存储正式附件(限次/水印/尺寸)"]
StoreDraft --> GalleryDraft["按草稿Token回显"]
StoreReal --> GalleryReal["按item_id回显"]
Upload --> |否| End(["结束"])

钱包管理（支付码轮询与充值）

• 进入钱包页先确保登录
• 定时拉取支付码并渲染条形码/二维码
• 轮询期间显示加载状态，异常时提示并恢复样式

sequenceDiagram
participant P as "money.ts"
participant H as "http"
participant R as "后端路由"
P->>P : ensureLogin()
P->>H : GET 获取支付码
H->>R : 请求
R-->>H : 返回{pay_code,user,total}
H-->>P : 解析并渲染条码/二维码
P->>H : 定时轮询(60s)

积分系统（列表与分页）

• 进入积分页先确保登录
• 支持排序筛选与下拉加载更多
• 网络异常时设置加载状态并提示

flowchart TD
Show["onShow"] --> Auth{"ensureLogin"}
Auth --> |通过| Reset["重置page=1,nomore=false"]
Reset --> Load["GET 积分列表(含b/s/page)"]
Load --> Merge{"concat?"}
Merge --> |是| Append["追加列表项"]
Merge --> |否| Replace["替换列表"]
Append --> Done["更新UI"]
Replace --> Done

收藏夹（占位页）

• 当前为最小化实现，预留路由与数据结构，后续可接入收藏列表与分类管理

依赖关系分析

• 小程序 user.ts 依赖 http、authStore、commonStore、route、ui、page_title、navScroll 等行为与工具
• money.ts 依赖 grcode 生成条码/二维码
• point.ts 依赖分页与排序逻辑
• 后端 UserController 依赖 ProfileService、UserCenterPresenter、NavigationBuilder、BreadcrumbBuilder、SeoResolver
• 后端 AuthController 依赖 RegistrationService、LoginService、Captcha、Session、ApiTokenService

graph LR
UTS["user.ts"] --> HTTP["http.js"]
UTS --> AUTH["authStore"]
UTS --> COMMON["commonStore"]
MTS["money.ts"] --> GR["grcode"]
PTS["point.ts"] --> HTTP
AC["AuthController"] --> RS["RegistrationService"]
AC --> LS["LoginService"]
AC --> CAP["Captcha"]
AC --> SES["Session"]
AC --> AT["ApiTokenService"]
UC["UserController"] --> PS["ProfileService"]
UC --> UP["UserCenterPresenter"]

性能考虑

• 列表分页与增量合并：积分页使用 page/nomore 控制分页，避免一次性加载大量数据
• 轮询节流：钱包支付码每 60 秒轮询一次，减少服务器压力
• 图片处理：文件上传支持尺寸压缩与水印，降低带宽占用
• 缓存与会话：登录后复用会话，减少重复鉴权开销

故障排查指南

• 登录状态保持

  • 现象：刷新后仍保持登录
  • 原因：服务端会话持久化；小程序侧本地缓存清理仅在退出时执行
  • 建议：检查退出逻辑是否调用 clearStorageSync 与 authStore.logout
  • 参考
    • miniprogram/default/pages/user/user.ts:90-95
    • front/controller/user/AuthController.php:595-604

• 数据同步冲突

  • 现象：多端同时修改导致数据不一致
  • 原因：并发写或弱一致性
  • 建议：对关键资源（如余额、积分）使用事务与版本号控制；前端重试与乐观更新
  • 参考
    • miniprogram/default/pages/money/money.ts:43-80
    • miniprogram/default/pages/point/point.ts:49-103

• 权限验证失败

  • 现象：访问个人中心被重定向到登录
  • 原因：未登录或会话失效
  • 建议：在进入受保护页面前调用 ensureLogin；检查后端鉴权中间件
  • 参考
    • miniprogram/default/pages/money/money.ts:17-23
    • front/controller/user/UserController.php:86-96

• 验证码/表单校验失败

  • 现象：提交时报错或超时
  • 原因：验证码过期、Honeypot 检测、表单校验失败
  • 建议：重新获取验证码；检查时间戳与输入格式
  • 参考
    • front/controller/user/AuthController.php:159-232
    • front/controller/user/AuthController.php:285-353

• 文件上传失败

  • 现象：头像/内容图无法保存
  • 原因：类型/大小限制、草稿Token无效、已达上限
  • 建议：检查上传参数、草稿Token、数量限制与存储路径
  • 参考
    • front/controller/user/UserController.php:150-244

结论

DouPHP 小程序用户中心模块在后端提供了完善的认证、资料与文件管理能力，在前端以清晰的分页、轮询与状态管理实现良好的用户体验。建议在后续迭代中完善收藏夹功能、增强错误提示与加载状态的一致性，并对关键资金与积分操作引入更强的幂等与审计机制。

附录

• 安全要点
  • 敏感信息：密码使用哈希存储；重置密码后吊销全部 API Token
  • 会话管理：登录态由服务端会话维持；退出时清理本地缓存与会话
  • 权限控制：受保护页面/接口需鉴权，未登录重定向或返回错误
  • 防刷与防护：验证码、Honeypot、频率限制（可在网关/中间件扩展）
• 开发示例
  • 微信登录集成：可通过插件入口跳转到对应 SNS 登录流程（见登录页参数）
  • 表单验证：使用 FormRequest 与服务端校验，结合前端提示
  • 数据同步：分页与增量合并，轮询与重试策略
• 交互体验优化
  • 操作反馈：成功/失败 Toast，加载中 Loading
  • 错误提示：统一错误消息与友好文案
  • 加载状态：分页 loading、轮询背景闪烁等视觉反馈