简介

本开发文档面向 DouPHP 前台用户域，围绕“用户控制器”展开，覆盖用户注册、登录认证、个人信息管理、密码修改、账户设置（改手机/邮箱）、地址簿等核心功能。文档同时解释身份验证机制、会话管理、权限控制、安全防护与审计日志，并提供扩展实践：新增认证方式、第三方登录集成、用户画像分析等。文末给出密码加密、会话安全、防暴力破解等最佳实践建议。

项目结构

用户域由一组子控制器与服务组成，职责清晰分离：

• 会员中心入口与工具：UserController（会员中心首页、地区数据、文件上传）
• 认证流程：AuthController（注册、登录、找回密码、退出）
• 资料与安全：ProfileController（个人资料编辑、密码修改、第三方账号绑定）
• 验证码与敏感变更：VerificationController（验证码核验、改手机、改邮箱）
• 地址簿：ContactController（增删改查、默认地址、JSON 接口）
• 业务服务：LoginService、RegistrationService、ProfileService（校验、创建、更新、统计装配）

graph TB
subgraph "前台用户域"
UC["UserController"]
AC["AuthController"]
PC["ProfileController"]
VC["VerificationController"]
CC["ContactController"]
end
subgraph "业务服务"
LS["LoginService"]
RS["RegistrationService"]
PS["ProfileService"]
end
UC --> PS
AC --> LS
AC --> RS
PC --> PS
VC --> |校验/跳转| AC
CC --> |地址簿| PS

核心组件

• AuthController：负责注册、账号密码登录、手机验证码登录、找回密码、退出；整合表单校验、验证码、Honeypot、CSRF、推广关系、SNS 绑定与跳转。
• ProfileController：负责个人资料编辑、头像上传、密码修改、第三方账号管理与快捷登录引导。
• VerificationController：负责验证码核验页、改手机、改邮箱的二次校验与状态流转。
• UserController：会员中心首页、地区数据 JSON、文件上传/删除等会员工具。
• ContactController：地址簿 CRUD、默认地址设置、JSON 列表与详情接口。
• LoginService：凭据校验、IP 限流、账户锁定、状态检查、自动建号（手机登录）、审计日志。
• RegistrationService：注册数据组装、事务化创建用户、SNS 绑定/解绑、协议单页保障。
• ProfileService：资料更新、昵称占用检测、会员中心首页数据装配（含统计、等级、推广二维码等）。

架构总览

用户域采用“控制器 + 服务”的分层设计：

• 控制器负责请求解析、视图渲染、重定向、安全校验（CSRF/Honeypot/Captcha）、会话写入。
• 服务封装业务逻辑：校验、事务、统计、审计、联系人管理等。
• 通过 Facade/中间件完成鉴权、限流、安全头、CSRF 等横切关注点。

sequenceDiagram
participant U as "浏览器"
participant C as "AuthController"
participant S as "LoginService"
participant A as "审计/限流"
participant F as "auth('front')"
U->>C : POST 登录提交
C->>C : CSRF/Honeypot/Captcha 校验
C->>S : validateLoginCredentials(用户名, 密码, IP)
S->>A : IP 限流/失败计数
S-->>C : {ok,user,errors}
alt 成功
C->>F : login(user, remember)
C-->>U : 重定向到会员中心或工作区
else 失败
C-->>U : 返回错误信息
end

详细组件分析

认证控制器（AuthController）

• 注册：支持邮箱/手机号模式，强制用户协议单页，Honeypot 防护，验证码校验，推广关系记录，SNS 绑定，自动登录。
• 登录：账号密码与手机验证码双通道；IP 限流、账户锁定、状态检查、审计日志；成功后可自动绑定 SNS，并依据工作区配置跳转。
• 找回密码：分步流程，短信/邮箱验证码校验，重置后吊销 API Token。
• 退出：清理会话并重定向。

flowchart TD
Start(["注册提交"]) --> V["表单校验/CSRF/Honeypot"]
V --> Ver{"需要验证码?"}
Ver -- 是 --> CheckV["校验验证码+时效"]
CheckV --> Build["组装入库数据"]
Ver -- 否 --> Build
Build --> Create["事务创建用户/SNS绑定/默认联系人"]
Create --> Record["登记推广关系"]
Record --> Login["写入会话登录态"]
Login --> End(["完成"])

个人资料控制器（ProfileController）

• 编辑资料：读取可编辑字段，处理头像上传，XSS 过滤，按语言拆分收货字段写入默认联系人，更新用户资料。
• 修改密码：旧密码校验，成功后刷新会话壳以失效旧 Cookie。
• 第三方账号：管理绑定/解绑，提供快捷登录引导并透传推广参数。

sequenceDiagram
participant U as "浏览器"
participant PC as "ProfileController"
participant PS as "ProfileService"
participant DB as "数据库"
U->>PC : GET 编辑资料
PC->>PS : buildEditableUserInfo(userId)
PS-->>PC : 用户资料+联系人快照
PC-->>U : 渲染表单
U->>PC : POST 保存资料
PC->>PC : XSS过滤/头像上传
PC->>PS : updateProfile(userId, data)
PS->>DB : 更新用户表/默认联系人
PS-->>PC : 审计日志
PC-->>U : 提示成功

验证码控制器（VerificationController）

• 验证码核验：根据上下文选择短信/邮箱，校验验证码与时效，通过后进入下一步。
• 改手机/邮箱：严格校验验证码与会话一致性，更新用户联系方式并清理会话。

flowchart TD
Enter(["进入核验页"]) --> Load["加载check_account/next_url"]
Load --> Type{"类型 sms/email"}
Type --> SMS{"sms且无手机号?"}
SMS -- 是 --> RedirectE["重定向到邮箱核验"]
SMS -- 否 --> Show["渲染验证码表单"]
Show --> Submit["提交验证码"]
Submit --> Verify{"校验通过?"}
Verify -- 否 --> Error["抛出错误/重新校验"]
Verify -- 是 --> Next["跳转到下一步"]

会员中心控制器（UserController）

• 会员中心首页：获取用户信息，未登录则跳转登录；构建面包屑与 SEO 信息。
• 地区数据：调用 area 模块输出省市区 JSON。
• 文件上传/删除：支持草稿与正式附件，图片尺寸与水印，数量限制，按业务主键归属。

地址簿控制器（ContactController）

• 列表/新增/编辑/删除/设为默认：基于 ContactService 实现，支持 Vue 模式与 JSON 接口。
• JSON 列表/详情：自动 snake→camel 映射，便于前端使用。

依赖关系分析

• 控制器依赖服务：AuthController → LoginService/RegistrationService；ProfileController → ProfileService；UserController → ProfileService。
• 服务依赖基础设施：UserAuthService（限流/锁定）、UserLogQuery/Audit（审计）、UserContactQuery（联系人）、Attachment（附件）、Config（配置）。
• 跨端共享：LoginService/RegistrationService 被前台与 API 共用，保证一致的业务规则。

classDiagram
class AuthController
class ProfileController
class VerificationController
class UserController
class ContactController
class LoginService
class RegistrationService
class ProfileService
AuthController --> LoginService : "凭据校验"
AuthController --> RegistrationService : "注册/SNS绑定"
ProfileController --> ProfileService : "资料更新/装配"
UserController --> ProfileService : "首页数据"
ContactController --> ProfileService : "联系人查询"

性能考量

• 登录路径优化：先进行 IP 限流与账户锁定检查，避免无效密码比对；历史 md5 密码命中时即时升级为 bcrypt，减少后续风险。
• 注册事务：新用户创建、SNS 绑定、默认联系人写入在事务中执行，降低并发冲突与不一致概率。
• 资料更新拆分：将收货字段拆出写入默认联系人，减少冗余列更新。
• 附件上传：支持草稿模式与批量上传，限制数量与尺寸，提升用户体验与存储效率。

故障排查指南

• 登录失败：检查 IP 是否被限流、账户是否锁定、密码是否正确；查看审计日志定位失败原因。
• 验证码错误：核对 Session 中的 verification 数据与提交值是否一致，确认验证码时效；多次失败会清空验证码防止滥用。
• 找回密码失败：确保 check_account 与 Session 一致，验证码有效；重置后会吊销该用户全部 API Token。
• 资料更新异常：确认昵称唯一性、XSS 过滤生效、联系人字段拆分正确；头像上传路径与权限需检查。
• 地址簿操作：确认当前用户 ID 与记录归属一致，默认地址设置与 JSON 接口返回是否符合预期。

结论

DouPHP 用户域通过清晰的控制器与服务分层，实现了完整的用户生命周期管理：注册、登录、资料维护、密码修改、第三方绑定、地址簿等。系统内置了完善的防护机制（CSRF、Honeypot、Captcha、IP 限流、账户锁定、审计日志），并通过服务层复用保障前后端一致性。建议在扩展时遵循现有模式：新增认证方式或服务能力优先在服务层实现，控制器仅做编排与响应；对敏感操作增加二次校验与审计；对高频接口引入限流与缓存策略。

附录

扩展实践示例（思路与要点）

• 新增认证方式（如邮箱验证码登录）

  • 在 LoginService 中新增 validateEmailLogin，复用 IP 限流、账户锁定、状态检查与审计。
  • 在 AuthController 中添加路由与方法，复用 VerificationController 的验证码流程。
  • 参考路径：front/service/user/LoginService.php:164-266、front/controller/user/VerificationController.php:79-170

• 集成第三方登录（微信/QQ 等）

  • 利用 ProfileController 的 sns/snsLink 流程，结合 RegistrationService 的 bindSns/removeSnsBinding。
  • 在注册/登录流程中透传 sns_token，完成授权后关联账号。
  • 参考路径：front/controller/user/ProfileController.php:251-333、front/service/user/RegistrationService.php:185-221

• 用户画像分析

  • 通过 ProfileService.getUserInfo 聚合统计（积分、余额、优惠券、收藏、消费总额等），结合 UserStatsService 与 UserLevelService 生成成长进度与等级信息。
  • 可在服务层新增维度指标（如活跃度、偏好标签），并在会员中心展示。
  • 参考路径：front/service/user/ProfileService.php:118-192

• 行为追踪与登录日志

  • 登录成功/失败均通过审计写入，包含动作、详情标签与 IP；可用于风控与运营分析。
  • 参考路径：front/service/user/LoginService.php:145-162、front/service/user/LoginService.php:230-266

安全措施最佳实践

• 密码加密：统一使用 bcrypt；历史 md5 命中时自动升级。
• 会话安全：登录后刷新 shell，重置密码后吊销 API Token；退出清理会话。
• 防暴力破解：IP 限流、账户锁定、验证码时效、失败次数清零策略。
• 输入安全：CSRF、Honeypot、XSS 过滤、严格类型与格式校验。
• 审计与可观测：关键操作写入审计日志，便于回溯与告警。