用户系统 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

用户系统

简介

本开发文档面向 DouPHP 用户系统的开发者，围绕用户注册登录、权限与状态控制、会员等级、积分与 VIP 等能力进行系统化说明。重点覆盖：

认证流程与会话管理（前台会话端 + API 无状态端）
密码安全与多端登录
会员等级体系与升级条件
积分获取与消耗（结合模块组织）
VIP 权益管理与扩展方式
用户行为追踪、数据分析与个性化推荐思路
如何扩展现有模型、添加自定义权限与新增会员等级规则
新增：领域模型的状态枚举设计与迁移管理，包括UserStatus和WithdrawStatus的完整实现

项目结构

DouPHP 采用前后端分离的模块化设计：

front：前台业务服务层（注册、登录、个人资料等）
api：API 控制器与中间件（小程序/第三方客户端）
admin：后台模型与服务（用户、等级、日志等）
core：框架基础能力（ORM、配置、安全、服务等）
config：全局配置（数据库、应用密钥、调试开关等）

graph TB
subgraph "前端入口"
A["front/service/user/*"]
B["api/controller/user/*"]
end
subgraph "核心能力"
C["core/service/*"]
D["core/foundation/*"]
E["core/domain/*"]
end
subgraph "数据与配置"
F["admin/model/user/*"]
G["config/config.php"]
end
A --> B
B --> C
A --> C
C --> D
C --> E
B --> F
A --> F
F --> G

图表来源

UserController.php:121-371
LoginService.php:75-162
RegistrationService.php:80-183
User.php:29-86
config.php:15-52

章节来源

config.php:15-52

核心组件

登录服务（LoginService）：负责账号密码校验、手机验证码登录、IP 限流、账户锁定、状态检查、审计日志记录。
注册服务（RegistrationService）：负责注册参数组装、事务创建用户、SNS 绑定/解绑、协议单页保障、API 验证码 token 生成。
API 用户控制器（UserController）：统一对外暴露注册、登录、资料编辑、密码修改、退出、头像上传、登录态检查等接口。
用户模型（User）：定义 user 表字段白名单、关联等级、列表筛选器、常用查询方法。
等级模型（UserLevel）：维护会员等级元数据（名称、升级类型、升级条件、折扣、图标等）。
新增：领域模型（UserStatus、WithdrawStatus）：提供状态枚举与迁移校验逻辑，确保状态转换的合法性和一致性。

章节来源

LoginService.php:31-162
RegistrationService.php:27-183
UserController.php:121-371
User.php:29-86
UserLevel.php:24-83

架构总览

用户系统以"控制器 → 服务 → 模型/基础设施"的分层模式组织，关键路径如下：

注册：API 控制器接收请求 → 注册服务组装数据并入库 → 返回用户信息
登录：API 控制器调用登录服务校验凭据 → 鉴权服务签发会话/Token → 返回用户上下文
资料/密码：API 控制器执行业务校验 → 调用对应服务更新数据
等级/积分/VIP：通过 service 与 model 组合实现，可在现有基础上扩展
新增：状态管理：通过领域模型枚举确保状态转换的合法性，提供表驱动的状态迁移机制

sequenceDiagram
participant Client as "客户端"
participant API as "UserController"
participant LoginSvc as "LoginService"
participant Auth as "UserAuthService"
participant DB as "数据库"
Client->>API : POST /user/login_post
API->>LoginSvc : validateLoginCredentials(用户名, 密码, IP)
LoginSvc->>DB : 查询用户
LoginSvc->>Auth : ipRateLimit/isLocked/loginFail/loginSuccess
LoginSvc-->>API : {ok, user, errors}
API->>Auth : login(user, field)
Auth-->>Client : {token, user}

图表来源

UserController.php:298-324
LoginService.php:75-162

详细组件分析

登录与认证流程

账号密码登录
- 输入识别邮箱或手机号，查询用户
- 若命中旧 md5 密码则自动升级为 bcrypt
- 校验账户状态（active/suspended/deactivated）
- 失败计数与 IP 限流，审计日志记录
手机验证码登录
- 校验验证码与时效
- 未注册用户自动创建并登记分销关系
- 同样执行状态检查与审计日志
会话/令牌
- 前台会话端由 Controller 写入 session
- API 无状态端通过 UserAuthService::login 签发 Token 返回客户端

flowchart TD
Start(["开始"]) --> Identify["识别账号类型<br/>邮箱/手机"]
Identify --> Query["查询用户"]
Query --> Locked{"是否被锁定?"}
Locked -- 是 --> FailLock["返回锁定提示"]
Locked -- 否 --> PwdCheck{"密码正确?"}
PwdCheck -- 否 --> IncFail["失败计数+1<br/>审计日志"] --> EndFail["结束(失败)"]
PwdCheck -- 是 --> StatusCheck{"状态允许登录?"}
StatusCheck -- 否 --> EndFail
StatusCheck -- 是 --> Success["成功<br/>记录成功日志"] --> EndOk["结束(成功)"]

图表来源

LoginService.php:75-162
LoginService.php:176-266

章节来源

LoginService.php:75-162
LoginService.php:176-266
UserController.php:298-371

注册流程

保障用户协议单页存在
生成 API 验证码 token 对（captcha_token/storage_captcha_token）
组装插入数据（email/mobile、密码哈希、推广关系）
事务内创建用户，可选绑定 SNS，默认收货地址电话落库
成功后登记分销关系树

sequenceDiagram
participant Client as "客户端"
participant API as "UserController"
participant RegSvc as "RegistrationService"
participant DB as "数据库"
Client->>API : POST /user/register_post
API->>RegSvc : buildRegisterInsertData(...)
API->>RegSvc : createUser(insertData, field, sns?)
RegSvc->>DB : 事务插入 user/user_sns/contact
RegSvc-->>API : {ok, user}
API->>API : recordPromotionRelation(...)
API-->>Client : {user, auth}

图表来源

RegistrationService.php:80-183
UserController.php:193-281

章节来源

RegistrationService.php:80-183
UserController.php:193-281

会员等级体系

等级模型提供等级元数据（名称、升级类型、升级条件、折扣、图标）
用户模型通过 level_id 关联等级，支持按状态、ID 筛选与预加载等级
建议将等级规则（如消费额、活跃度）在 service 层集中计算，避免散落在控制器

classDiagram
class User {
+int level_id
+string status
+level() BelongsTo
}
class UserLevel {
+string name
+string upgrade_type
+string upgrade_condition
+float good_discount
+string icon
}
User --> UserLevel : "belongsTo(level_id)"

图表来源

User.php:79-86
UserLevel.php:24-83

章节来源

User.php:79-86
UserLevel.php:24-83

积分系统与 VIP 服务（模块视角）

积分：位于 point 模块，通常包含积分流水、获取/消耗规则、兑换策略等
VIP：位于 vip 模块，通常包含套餐、有效期、权益清单、购买/续费流程
与用户系统的集成点：
- 用户模型扩展字段（如 vip_expire_at、point_total）
- 服务层在订单完成、活动参与时触发积分增减与等级/VIP 判定
- 权限/展示层根据当前等级/VIP 状态渲染差异化内容

（本节为概念性说明，不直接引用具体代码文件）

权限管理与多端登录

权限：基于角色/权限点控制后台访问；前台可通过用户状态、等级、VIP 状态做功能可见性控制
多端登录：
- 前台会话端：使用 Session 维持登录态
- API 端：使用 Token（Bearer）无状态登录，支持吊销与状态检查
安全要点：
- 密码使用 bcrypt 存储，历史 md5 自动升级
- IP 限流与失败次数限制，防止暴力破解
- 验证码 token 防重放（storage_captcha_token）

章节来源

UserController.php:537-547
UserController.php:711-724
LoginService.php:75-162

密码安全

存储：bcrypt 哈希
迁移：登录时检测到 md5 自动升级
重置：邮件链接含一次性 token，过期失效
修改：需验证旧密码后更新

章节来源

LoginService.php:118-133
UserController.php:391-414
UserController.php:516-535

用户行为追踪与数据分析

审计日志：登录成功/失败、账户锁定、验证码错误等事件均记录
建议扩展：
- 注册渠道、设备指纹、地理位置
- 页面浏览、点击热区、转化漏斗
- 积分/VIP 相关行为埋点（领取、消耗、续费）

章节来源

LoginService.php:82-89
LoginService.php:145-160
LoginService.php:230-264

个性化推荐（高级功能）

数据源：用户行为日志、订单/浏览历史、积分/VIP 状态
算法建议：协同过滤、内容相似度、规则引擎（等级/VIP 加权）
落地方式：在服务层聚合推荐结果，通过 API 输出到前端

（本节为概念性说明，不直接引用具体代码文件）

领域模型

用户状态枚举（UserStatus）

用户状态枚举定义了用户账户的生命周期状态及其合法迁移规则：

状态定义：
- ACTIVE：正常状态，可登录、可下单
- SUSPENDED：被管理员停用，可被恢复为 ACTIVE
- DEACTIVATED：注销状态，终态，账户失效，不可恢复
状态迁移规则：
- ACTIVE → SUSPENDED/DEACTIVATED
- SUSPENDED → ACTIVE/DEACTIVATED
- DEACTIVATED → 无（终态）
核心方法：
- isValid()：验证状态值是否合法
- canTransit()：验证状态迁移是否合法
- all()：获取所有状态值列表

章节来源

UserStatus.php:35-94

提现状态枚举（WithdrawStatus）

提现状态枚举定义了提现申请的处理流程状态：

状态定义：
- PENDING：待审核，余额已在申请时扣除，等待管理员处理
- APPROVED：已通过，管理员核准，款项将线下打款
- PAID：已打款，线下转账完成（终态）
- REJECTED：已驳回，管理员驳回，须把申请时扣除的余额原路退回（终态）
状态迁移规则：
- PENDING → APPROVED/REJECTED
- APPROVED → PAID
- PAID/REJECTED → 无（终态）
核心方法：
- isValid()：验证状态值是否合法
- canTransit()：验证状态迁移是否合法
- badgeClass()：获取状态对应的展示样式类名

章节来源

WithdrawStatus.php:32-117

领域模型的使用示例

领域模型在系统中的主要使用场景：

用户状态管理：
- 后台用户状态变更时验证迁移合法性
- 登录时检查用户状态是否允许登录
- 列表筛选时验证状态过滤条件
提现流程控制：
- 提现申请状态流转验证
- 管理员审核时的状态转换控制
- 资金回退的事务性保证

stateDiagram-v2
[*] --> PENDING
PENDING --> APPROVED : 审核通过
PENDING --> REJECTED : 审核拒绝
APPROVED --> PAID : 标记已打款
REJECTED --> [*]
PAID --> [*]
note right of PENDING : 待审核<br/>余额已扣除
note right of APPROVED : 已通过<br/>等待打款
note right of PAID : 已打款<br/>终态
note right of REJECTED : 已驳回<br/>余额退回

图表来源

WithdrawStatus.php:46-51

章节来源

UserService.php:203-229
WithdrawService.php:191-230

依赖关系分析

UserController 依赖：
- RegistrationService、LoginService、ProfileService、PasswordResetService
- UserAuthService、ApiTokenService、UserService
- Captcha、Config、Module 等基础设施
LoginService 依赖：
- UserAuthService、UserContactQuery、审计与日志
- 新增：UserStatus 领域模型用于状态验证
模型层：
- User 与 UserLevel 通过 ORM 关联
- 列表查询通过 scope 组合条件，减少 N+1
- 新增：领域模型提供状态枚举与迁移校验

graph LR
UC["UserController"] --> LS["LoginService"]
UC --> RS["RegistrationService"]
UC --> PS["ProfileService"]
UC --> PRS["PasswordResetService"]
UC --> UA["UserAuthService"]
UC --> ATS["ApiTokenService"]
UC --> US["UserService"]
LS --> UA
LS --> UQ["UserContactQuery"]
LS --> USR["UserStatus"]
UM["User Model"] --> UL["UserLevel Model"]
WS["WithdrawService"] --> WSR["WithdrawStatus"]

图表来源

UserController.php:55-119
LoginService.php:49-63
User.php:79-86
UserService.php:21-22
WithdrawService.php:20-21

章节来源

UserController.php:55-119
LoginService.php:49-63
User.php:79-86

性能考虑

数据库
- 使用 scope 预加载等级，避免 N+1
- 合理索引：user(email/moblie)、user_log(user_id)
缓存
- 等级配置、VIP 套餐可缓存
- 验证码 token 短期缓存
限流
- IP 级登录限流，防止爆破
异步
- 邮件发送、积分发放、行为统计可异步化
新增：领域模型优化
- 状态枚举使用静态常量，避免重复计算
- 迁移规则表驱动，便于维护和扩展
- 状态验证在内存中进行，减少数据库查询

（本节提供通用指导，不直接引用具体代码文件）

故障排查指南

登录失败
- 检查 IP 限流与失败计数
- 核对验证码与时效
- 查看审计日志定位原因
注册失败
- 检查唯一约束（email/mobile）
- 查看事务异常日志
密码问题
- 确认 bcrypt 升级逻辑
- 重置邮件是否送达
权限/状态
- 检查用户状态（active/suspended/deactivated）
- 确认等级/VIP 状态与权益匹配
新增：状态迁移问题
- 检查 UserStatus::canTransit() 验证逻辑
- 确认当前状态和目标状态的迁移合法性
- 查看状态变更的审计日志
- 验证 WithdrawStatus::canTransit() 在提现流程中的应用

章节来源

LoginService.php:82-89
LoginService.php:145-160
RegistrationService.php:136-183
UserController.php:391-414
UserService.php:222-224
WithdrawService.php:195-197

结论

DouPHP 用户系统以清晰的分层与职责划分，提供了安全的认证、灵活的注册、完善的等级与可扩展的积分/VIP 能力。新增的领域模型设计进一步增强了状态管理的规范性和安全性：

扩展用户模型：增加字段、关联新实体
新增权限：在服务层集中判断，配合 UI 控制
新增等级规则：在 service 层实现评估逻辑，联动等级变更
行为追踪与推荐：基于日志与用户画像构建推荐管线
新增：状态管理：通过领域模型确保状态转换的合法性和一致性，提供表驱动的状态迁移机制，支持用户状态和提现状态的完整生命周期管理

附录

配置项参考
- 数据库连接、表前缀、字符集、应用密钥、调试开关
常见扩展示例（路径指引）
- 扩展用户模型字段：User.php
- 新增等级规则：在 service 层实现评估函数，调用 UserLevel 与 User 关联
- 新增积分规则：在 point 模块 service 中实现获取/消耗逻辑
- 新增 VIP 权益：在 vip 模块 service 中定义权益清单与校验
- 新增：扩展状态枚举：在 core/domain 目录下添加新的状态类，遵循 UserStatus 的设计模式

章节来源

config.php:15-52
User.php:29-86
UserLevel.php:24-83
UserStatus.php:35-94
WithdrawStatus.php:32-117

添加日期：2026-10-05