简介

本文件面向移动端与Web前端开发者，提供"用户管理模块"的完整API文档。内容覆盖用户注册、登录（账号密码与手机验证码）、信息获取、修改密码、退出登录、头像上传、第三方账号绑定、省市区数据等能力；并说明请求参数、响应格式、错误处理与安全注意事项。对于需要后台管理的状态操作（激活、禁用、删除），在本文末尾给出建议路径与对接方式。

项目结构

用户管理相关能力由"API端"和"前端页面端"共同实现：

• API端：以 /api/?route=user 为入口，提供JSON接口，供小程序/APP/Web调用。
• 前端端：以 /user 为入口，提供表单页面与流程控制，支持浏览器会话登录与资料维护。

graph TB
Client["客户端<br/>小程序/APP/Web"] --> API["API路由<br/>/api/?route=user"]
API --> UC["UserController<br/>注册/登录/资料/文件/地区"]
API --> WX["WeixinController<br/>微信相关"]
API --> WORK["WorkController<br/>工作相关"]
API --> CONTACT["ContactController<br/>联系人"]
Client --> Front["前端路由<br/>/user/*"]
Front --> AUTH["AuthController<br/>登录/注册/找回密码"]
Front --> PROFILE["ProfileController<br/>资料/密码/SNS"]
Front --> VERIFY["VerificationController<br/>验证码/改手机/改邮箱"]

核心组件

• API用户控制器：负责会员中心首页、注册、登录、找回密码、个人资料保存、修改密码、退出登录、SNS绑定、省市区、文件上传/删除、头像上传、登录态检查等。
• 前端认证控制器：提供注册/登录/找回密码/退出的页面流程与校验。
• 前端资料控制器：提供个人资料编辑、修改密码、第三方账号管理等页面流程。
• 前端验证控制器：提供验证码核验、修改手机号/邮箱的流程。

架构总览

API端采用"声明式路由 + 控制器 + 服务"的分层模式：

• 路由层：api/route/user.php 定义 /api/?route=user 下的GET/POST动作。
• 控制器层：UserController 接收请求、参数校验、调用服务、返回统一响应。
• 服务层：RegistrationService、LoginService、ProfileService、PasswordResetService、UserAuthService、UserPasswordService、UserService、ApiTokenService 等封装业务逻辑。

sequenceDiagram
participant C as "客户端"
participant R as "API路由"
participant U as "UserController"
participant S as "各类Service"
participant DB as "数据库/存储"
C->>R : POST /api/?route=user/register_post
R->>U : registerPost()
U->>S : RegistrationService : : createUser(...)
S->>DB : 写入用户/推广关系
S-->>U : 创建结果
U->>S : UserAuthService : : login(...)
S-->>U : 登录态/用户信息
U-->>C : ApiResponse : : success({user, dou.auth})

详细组件分析

注册与登录

• 注册表单

  • URL: GET /api/?route=user/register
  • 作用：返回注册页所需配置（验证码token、登录模式、是否启用邮箱/短信等）。
  • 关键参数：无必需参数；可选 promotion_user_sn、sns_token。
  • 响应：包含 captcha_token、storage_captcha_token、promotion_user_sn、login_mode、mail_username、sms_accessKeyId 等。

• 注册提交

  • URL: POST /api/?route=user/register_post
  • 作用：校验并创建用户，自动登记推广关系，完成登录并返回用户信息。
  • 必填字段：password、email或mobile（二选一）；如开启验证码需 verification_data。
  • 校验规则：
    • password：必填、符合密码强度、confirmed（确认密码）。
    • email/mobile：必填、唯一性校验。
    • verification_data：当启用邮箱或短信时必填，含 code/account/ontime。
  • 响应：成功返回 user 与 dou.auth.is_work；失败抛出领域异常并附带字段级错误。

• 账号密码登录

  • URL: POST /api/?route=user/login_post
  • 作用：凭据校验后登录，返回用户信息与鉴权标识。
  • 必填字段：username、password。
  • 响应：user 与 dou.auth.is_work。

• 手机验证码登录

  • URL: POST /api/?route=user/login_phone_post
  • 作用：基于手机号+验证码登录，未命中账号可自动建号。
  • 必填字段：mobile、verification、verification_data。
  • 响应：user 与 dou.auth.is_work。

• 登录态检查

  • URL: POST /api/?route=user/check_login_state
  • 作用：校验当前Bearer Token的登录状态。
  • 响应：包含 login_state 等状态信息。

sequenceDiagram
participant C as "客户端"
participant U as "UserController"
participant LS as "LoginService"
participant UA as "UserAuthService"
C->>U : POST login_post(username,password)
U->>LS : validateLoginCredentials(...)
LS-->>U : {user, field, errors?}
alt 有错误
U-->>C : DomainException(字段错误)
else 成功
U->>UA : login(user, field)
UA-->>U : 会话/令牌
U-->>C : success({user, dou.auth})
end

个人信息与资料管理

• 会员中心首页

  • URL: GET /api/?route=user
  • 作用：返回基础资料、鉴权状态、VIP/工作/分销详情等。
  • 权限：需登录（通过中间件鉴权）。
  • 响应：title、welcome、link_user_center、if_connect_plugin、dou.user、dou.auth、dou.vip/work/distribution。

• 个人资料编辑

  • URL: GET /api/?route=user/edit
  • 作用：返回可编辑的用户资料结构。
  • 权限：需登录。
  • 响应：title、user_info。

• 个人资料保存

  • URL: POST /api/?route=user/edit_post
  • 作用：更新昵称、联系方式、地址、邮编、性别、自定义字段等。
  • 校验：nickname/contact/phone 必填且非法字符过滤；昵称唯一性校验。
  • 响应：成功返回空数据；失败抛出领域异常并带字段错误。

• 修改密码

  • URL: GET /api/?route=user/password
  • URL: POST /api/?route=user/password_post
  • 作用：校验旧密码并设置新密码；成功后提示重新登录。
  • 校验：password、confirmed；旧密码校验在服务层完成。
  • 响应：成功返回 relogin=true；失败返回字段错误。

• 头像上传

  • URL: POST /api/?route=user/upload_avatar
  • 作用：上传头像并更新用户头像字段。
  • 权限：需登录。
  • 响应：file_url（头像URL）。

• 第三方账号管理

  • URL: POST /api/?route=user/sns
  • URL: GET /api/?route=user/sns_link
  • 作用：列出可用SNS插件、解绑指定SNS、引导绑定流程。
  • 权限：需登录。
  • 响应：title、plugin_list、remove标志。

• 省市区数据

  • URL: POST /api/?route=user/area
  • 作用：根据 type 返回 init/province/city/district 数据。
  • 参数：type、id/parent/current。
  • 响应：contact 或 area_list。

flowchart TD
Start(["edit_post 入口"]) --> Validate["校验 nickname/contact/phone 等"]
Validate --> NickCheck{"昵称是否变更且重复?"}
NickCheck -- 是 --> Err["抛出领域异常(字段错误)"]
NickCheck -- 否 --> BuildUpdate["构建更新数据(按语言切换字段)"]
BuildUpdate --> Update["调用 ProfileService::updateProfile"]
Update --> Done["返回成功"]

文件上传与删除

文件上传

• URL: POST /api/?route=user/filebox
• 作用：上传图片/内容附件，支持草稿模式与图片尺寸/水印。
• 参数：module、folder、item_id、type、img_width、draft_token、boxfield 等。
• 响应：html（内容图）或 img_list（图片列表）。

文件删除

• URL: POST /api/?route=user/filedel
• 作用：删除指定文件编号的文件，并返回剩余列表。
• 参数：number（文件名编号）。
• 响应：img_list。

更新 文件删除功能已增强输入验证机制，引入numberRaw中间变量进行类型转换和格式验证，提升了文件标识符的安全性处理。

新增安全验证流程

• numberRaw：原始输入值，强制转换为字符串类型
• number：经过正则表达式 /^[a-z0-9.]+$/ 验证后的安全值
• 验证规则：仅允许小写字母、数字和点号的组合
• 安全措施：防止SQL注入和路径遍历攻击

flowchart TD
Start(["filedel 入口"]) --> GetInput["获取 number 参数"]
GetInput --> TypeConvert["numberRaw = (string) input('number', '')"]
TypeConvert --> RegexValidate["preg_match('/^[a-z0-9.]+$/', numberRaw)"]
RegexValidate --> ValidCheck{"验证通过?"}
ValidCheck -- 是 --> SetNumber["number = numberRaw"]
ValidCheck -- 否 --> SetEmpty["number = ''"]
SetNumber --> QueryDB["查询文件信息"]
SetEmpty --> QueryDB
QueryDB --> DeleteFile["attachment()->delete(number)"]
DeleteFile --> ReturnList["返回剩余文件列表"]

退出登录

• URL: POST /api/?route=user/logout
• 作用：吊销当前设备的API会话token。
• 权限：需登录。
• 响应：成功返回空数据。

前端页面端（补充）

• 注册/登录/找回密码/退出：front/controller/user/AuthController.php
• 资料编辑/修改密码/SNS：front/controller/user/ProfileController.php
• 验证码核验/改手机/改邮箱：front/controller/user/VerificationController.php
• 路由映射：front/route/user.php

依赖关系分析

• 控制器依赖的服务：
  • RegistrationService：注册流程、SNS绑定、推广关系解析。
  • LoginService：凭据校验、手机验证码登录。
  • ProfileService：资料读取/更新、昵称唯一性校验。
  • PasswordResetService：重置密码邮件发送。
  • UserAuthService：登录态与会话/令牌管理。
  • UserPasswordService：旧密码校验与新密码设置。
  • UserService：推广关系记录、角色判断（如 isWork）。
  • ApiTokenService：吊销/刷新API token。
  • Captcha：验证码生成与时效校验。
  • Storage/Attachment：文件存储与缩略图/水印。

classDiagram
class UserController {
+index()
+register()
+registerPost()
+loginPost()
+loginPhonePost()
+passwordResetPost()
+edit()
+editPost()
+password()
+passwordPost()
+logout()
+sns()
+area()
+filebox()
+filedel()
+checkLoginState()
+uploadAvatar()
}
class RegistrationService
class LoginService
class ProfileService
class PasswordResetService
class UserAuthService
class UserPasswordService
class UserService
class ApiTokenService
class Captcha
class Attachment
UserController --> RegistrationService : "使用"
UserController --> LoginService : "使用"
UserController --> ProfileService : "使用"
UserController --> PasswordResetService : "使用"
UserController --> UserAuthService : "使用"
UserController --> UserPasswordService : "使用"
UserController --> UserService : "使用"
UserController --> ApiTokenService : "使用"
UserController --> Captcha : "使用"
UserController --> Attachment : "使用"

性能考虑

• 验证码与限流：注册/登录/找回密码均结合验证码与时效校验，避免暴力破解。
• 文件上传：支持草稿模式与图片尺寸限制，减少无效传输与存储压力。
• 数据最小化：会员中心首页按需聚合VIP/工作/分销详情，避免冗余数据。
• 缓存与索引：建议在用户表、推广关系表上建立合理索引以提升查询效率。

故障排查指南

• 常见错误类型
  • 参数校验失败：如必填缺失、格式不符、昵称重复等，会抛出领域异常并携带字段级错误。
  • 验证码错误/过期：verification_wrong、verification_outtime。
  • 邮箱不存在：NOT_FOUND 404。
  • 服务器错误：如邮件发送失败返回 SERVER_ERROR 500。
• 定位步骤
  • 检查请求参数是否符合接口要求（参考附录）。
  • 查看日志中的领域异常消息与字段错误。
  • 核对验证码流程是否按顺序执行（发码→校验→时效）。
  • 文件上传问题检查 module/folder/type 与草稿 token 是否正确。
  • 文件删除失败检查 number 参数格式是否符合安全验证规则。

结论

本模块提供了完整的用户生命周期API：注册、登录、资料维护、密码管理、文件与头像上传、第三方账号绑定、地区数据等。通过统一的响应结构与严格的参数校验，确保前后端交互稳定可靠。特别地，文件删除功能已通过增强的输入验证机制提升了安全性，有效防止了潜在的安全风险。对于后台状态管理（激活、禁用、删除），建议通过管理员后台或专用管理API进行，不在本公开API中暴露。

附录：接口清单与示例

API端接口清单（/api/?route=user）

• 注册
  • GET /api/?route=user/register
  • POST /api/?route=user/register_post
• 登录
  • POST /api/?route=user/login_post
  • POST /api/?route=user/login_phone_post
  • POST /api/?route=user/check_login_state
• 资料
  • GET /api/?route=user
  • GET /api/?route=user/edit
  • POST /api/?route=user/edit_post
  • POST /api/?route=user/upload_avatar
• 密码
  • GET /api/?route=user/password
  • POST /api/?route=user/password_post
  • POST /api/?route=user/password_reset_post
• 其他
  • POST /api/?route=user/logout
  • POST /api/?route=user/sns
  • GET /api/?route=user/sns_link
  • POST /api/?route=user/area
  • POST /api/?route=user/filebox
  • POST /api/?route=user/filedel

请求与响应约定

• 请求头
  • Authorization: Bearer <token>（需要登录的接口）
  • Content-Type: application/x-www-form-urlencoded 或 multipart/form-data（文件上传）
• 响应体
  • 成功：ApiResponse::success(data)，data 为业务对象数组
  • 失败：抛出领域异常，包含 message 与 fields 错误

典型场景示例（文字描述）

• 注册成功
  • 请求：POST /api/?route=user/register_post，包含 email/mobile、password、password_confirmation、verification_data（如启用）
  • 响应：{ user: {...}, dou: { auth: { is_work: true/false } } }
• 登录失败（密码错误）
  • 请求：POST /api/?route=user/login_post，包含 username、password
  • 响应：抛出领域异常，message 为错误提示，fields 可能为空
• 修改资料失败（昵称重复）
  • 请求：POST /api/?route=user/edit_post，包含 nickname 等
  • 响应：抛出领域异常，fields.nickname 为重复提示
• 头像上传成功
  • 请求：POST /api/?route=user/upload_avatar，multipart 包含 avatar
  • 响应：{ file_url: "https://.../avatar.jpg" }
• 文件删除成功
  • 请求：POST /api/?route=user/filedel，包含 number（符合 /^[a-z0-9.]+$/ 格式）
  • 响应：{ img_list: [...] }
• 文件删除失败（参数格式错误）
  • 请求：POST /api/?route=user/filedel，包含 number（不符合安全验证规则）
  • 响应：{ img_list: [] }

用户状态管理（激活、禁用、删除）

• 说明：当前公开API未直接暴露激活/禁用/删除用户的接口。此类敏感操作应通过管理员后台或专用管理API执行，以避免安全风险。
• 建议路径
  • 管理员后台：进入用户管理界面进行批量或单条状态变更。
  • 管理API：如需程序化操作，请通过内部管理系统提供的受控接口（非公开API）执行，并配合权限与审计。

安全与隐私

• 密码安全：密码哈希存储，修改密码需校验旧密码。
• 验证码：注册/登录/找回密码均结合验证码与时效校验，防止自动化攻击。
• 输入过滤：对昵称、联系方式等字段进行非法字符过滤与XSS防护。
• 会话安全：退出登录吊销设备token；重置密码后吊销该用户全部API token。
• 文件安全：文件删除接口采用严格的输入验证，仅允许安全的文件标识符格式。
• 隐私保护：仅返回必要字段；头像与文件访问通过受控路径。

新增安全特性

• 文件标识符验证：filedel接口使用正则表达式 /^[a-z0-9.]+$/ 严格验证文件编号
• 类型转换：所有输入参数强制转换为字符串类型，防止类型混淆攻击
• 白名单机制：仅允许小写字母、数字和点号的组合，有效防止路径遍历和SQL注入