Skip to content

用户管理 PRD ​

文档信息 ​

项目内容
文档编号PRD-01-02
文档名称用户管理
产品名称PMForge 项目管理平台
所属模块system
文档版本v2.2
最后更新2026-11-18
文档状态已更新
实施状态已实现(接入 server)
优先级P0

1. 功能概述 ​

1.1 功能定位 ​

用户管理是 PMForge 平台的"人员花名册"——所有使用系统的人,从注册到离职,他们的账号信息、组织归属、角色权限都在这里统一管理。它就像公司 HR 系统里的员工档案库,但面向的是数字平台上的每一个账号。

1.2 目标用户与核心诉求 ​

用户类型使用场景核心诉求
超级管理员管理全平台所有用户不受租户限制,能管理任何人;能创建租户管理员
租户管理员管理自己公司/组织内的用户只能看到和操作自己租户下的人,数据不串
部门管理员管理本部门的人员能看到本部门及下属部门的人员,方便日常管理
普通用户使用系统的员工能查看和修改自己的资料、改密码、换头像

1.3 业务价值 ​

价值维度具体表现
统一管理一个入口管理所有用户账号,避免多系统数据不一致
权限基础用户是权限体系的载体——没有用户,角色和权限就无处挂载
组织映射用户归属部门、岗位,真实反映公司组织架构
效率提升批量导入/导出,一次处理数百人,告别逐条手工录入
安全合规离职禁用、密码重置、操作留痕,满足安全审计要求

1.4 功能范围 ​

功能分类后台管理端(管理员用)前台用户端(本人用)
查看用户列表✅ 分页查看、搜索筛选❌
新增用户✅ 填写信息、分配角色部门❌
编辑用户✅ 修改用户信息❌
删除用户✅ 逻辑删除,保留历史数据❌
批量导入用户✅ Excel上传,批量创建❌
批量导出用户✅ 导出当前筛选结果❌
重置密码✅ 管理员帮用户重置❌
启用/禁用用户✅ 控制用户能否登录❌
查看个人信息❌✅ 看自己的资料
修改个人信息❌✅ 改昵称、性别
修改手机号❌✅ 需验证码验证
修改邮箱❌✅ 需邮件验证
修改密码❌✅ 需验证旧密码
修改头像❌✅ 上传裁剪
绑定/解绑社交账号❌✅ 微信、钉钉等

2. 用户场景 ​

2.1 核心使用场景 ​

场景1:HR 批量导入新员工账号 ​

角色:租户管理员 小王 背景:公司新招了 50 人,下周一入职,需要提前在系统里创建好账号

操作步骤:

  1. 小王登录后台,进入「用户管理」页面
  2. 点击「导入」按钮,弹窗提示操作步骤
  3. 点击「下载模板」,得到一份 Excel 模板文件
  4. 打开模板,按格式填写 50 人的姓名、用户名、手机号、部门、岗位等信息
  5. 回到弹窗,上传填好的 Excel 文件
  6. 系统自动校验:格式是否正确、用户名是否重复、手机号是否已存在、部门名称是否对得上
  7. 校验完成后显示预览:「可导入 48 条,异常 2 条」
  8. 小王点击「确认导入」,48 个账号创建成功
  9. 异常 2 条可以下载查看原因(比如「手机号已被 zhangsan 使用」)
  10. 系统自动为每个新用户生成初始密码,小王可选择是否发送密码邮件到员工邮箱

期望:50 人的账号 5 分钟内搞定,异常数据有明确提示,不需要逐条排查。

异常处理:

  • Excel 格式不对 → 提示「请使用下载的模板填写」
  • 部门名称不存在 → 提示「第 X 行部门「XX」不存在,请检查」
  • 超过 1000 条 → 提示「单次最多导入 1000 条,请分批导入」

场景2:管理员处理员工离职 ​

角色:租户管理员 小王 背景:员工张三下周离职,需要处理他的系统账号

操作步骤:

  1. 小王在用户列表搜索「张三」,找到对应账号
  2. 小王选择「禁用」而不是「删除」——因为张三经手的项目记录、审批单据需要保留
  3. 禁用后,张三立即无法登录系统,他当前正在使用的页面下次操作时会被强制退出
  4. 如果后续需要,小王可以随时重新启用这个账号
  5. 如果确认要删除,小王点击「删除」,系统弹出确认框:「删除后该用户所有 Token 失效,确定删除?」
  6. 确认后,账号被逻辑删除(数据库里还在,只是标记为已删除),张三的所有登录凭证立即失效

期望:禁用而非删除,保留历史数据可追溯;操作即时生效,不会有「禁用后还能用几分钟」的窗口期。

关键决策:

  • 为什么推荐「禁用」而不是「删除」?因为张三创建的项目、提交的审批、上传的文件都需要保留记录。删除用户后,这些数据的创建者信息会变成空值,影响数据完整性。

场景3:新员工第一次登录修改个人信息 ​

角色:普通用户 小李(新入职员工) 背景:小李收到管理员发的初始密码,第一次登录系统

操作步骤:

  1. 小李打开系统登录页,输入用户名和初始密码,登录成功
  2. 系统检测到是首次登录(或密码是初始密码),提示「建议修改初始密码」
  3. 小李点击右上角头像,进入「个人中心」
  4. 看到自己的基本信息:用户名(不可改)、昵称、部门、岗位、角色等
  5. 小李修改昵称为「李哥」,上传了一张头像照片
  6. 点击「修改密码」,输入初始密码和新密码,修改成功
  7. 系统提示「密码修改成功,请重新登录」,跳转到登录页
  8. 小李用新密码登录,看到右上角已经显示自己设置的头像和昵称

期望:流程简单直观,不需要看说明书就能完成;头像修改后即时生效,不用刷新页面。


场景4:部门经理查看本部门人员 ​

角色:部门管理员 张经理(研发部负责人) 背景:张经理想了解研发部目前有多少人,各自的角色和岗位

操作步骤:

  1. 张经理登录后台,进入「用户管理」页面
  2. 左侧部门树自动展开到张经理有权限的「研发部」
  3. 点击「研发部」,右侧列表自动筛选出研发部的所有用户
  4. 张经理可以看到每个人的用户名、昵称、岗位、角色、手机号、状态等信息
  5. 展开子部门「前端组」,可以看到前端组的成员
  6. 张经理在搜索框输入「前端」,进一步筛选岗位包含「前端」的用户
  7. 点击「导出」,把当前筛选结果导出为 Excel,用于部门会议

期望:只能看到自己有权限管理部门的人,看不到其他部门的数据;搜索和筛选要快,不能等好几秒。

权限边界:

  • 张经理能看到:研发部、前端组、后端组(研发部的子部门)的所有用户
  • 张经理看不到:产品部、市场部等其他部门的用户
  • 超级管理员能看到:全公司所有部门的用户

场景5:用户更换绑定手机号 ​

角色:普通用户 小陈 背景:小陈换了新手机号,需要更新系统中的绑定手机

操作步骤:

  1. 小陈进入「个人中心」→「安全设置」→「修改手机号」
  2. 系统先验证身份:向原手机号发送验证码
  3. 小陈输入原手机号收到的验证码
  4. 输入新手机号,点击「获取验证码」
  5. 输入新手机号收到的验证码
  6. 系统校验:新手机号是否已被其他账号使用?→ 没有,通过
  7. 修改成功,系统提示「手机号已更新」
  8. 出于安全考虑,系统让所有设备的登录状态失效,小陈需要重新登录

期望:整个流程 2 分钟内完成;如果新手机号已被占用,要明确告知。

异常处理:

  • 原手机号已停用,收不到验证码 → 提供「手机号不可用?联系管理员解绑」入口
  • 新手机号已被其他账号使用 → 提示「该手机号已被注册,请直接登录或使用其他手机号」

场景6:管理员重置用户密码 ​

角色:租户管理员 小王 背景:员工老赵忘记密码,打电话找管理员重置

操作步骤:

  1. 小王在用户列表找到「老赵」
  2. 点击操作列的「重置密码」按钮
  3. 弹窗出现,有两个选项:
    • 「自动生成」:系统随机生成一个 12 位包含字母数字的密码
    • 「手动输入」:小王自己设一个密码
  4. 小王选择「自动生成」,系统生成密码 Kx9mP2vL5nQ8
  5. 勾选「发送密码到用户邮箱」
  6. 点击确认,密码重置成功
  7. 老赵的邮箱收到一封邮件:「您的密码已被重置为:Kx9mP2vL5nQ8,登录后请及时修改」
  8. 老赵原来的登录状态全部失效,需要用新密码重新登录

期望:1 分钟内完成;密码通过安全渠道(邮件)发送,不在聊天工具里明文传递。


场景7:超级管理员查看全平台用户分布 ​

角色:超级管理员 背景:平台运营半年,超级管理员想了解用户增长情况

操作步骤:

  1. 超级管理员进入用户管理页面
  2. 不选择任何部门筛选,看到全平台用户列表
  3. 通过创建时间筛选,查看本月新增用户
  4. 通过状态筛选,查看有多少用户被禁用
  5. 导出全量用户数据,用于运营分析

期望:超管不受租户限制,能看到所有数据;大数据量导出时不能卡死系统。


2.2 用户故事与验收标准 ​

编号用户故事优先级验收标准
US-01作为管理员,我希望能分页查看所有用户列表,以便快速找到目标用户P0① 默认每页 10 条,支持切换 20/50/100 ② 默认按创建时间倒序 ③ 支持按用户名、手机号模糊搜索 ④ 支持按部门、状态、创建时间筛选 ⑤ 列表加载时间 < 500ms
US-02作为管理员,我希望能新增用户,以便为新员工创建账号P0① 必填项:用户名、昵称、部门、角色、手机号 ② 用户名 4-30 位字母数字下划线,全局唯一 ③ 手机号 11 位,全局唯一 ④ 用户名创建后不可修改 ⑤ 不填密码时使用系统默认密码
US-03作为管理员,我希望能批量导入用户,以便一次性创建大量账号P1① 支持 xlsx/xls 格式 ② 单次上限 1000 条 ③ 导入前预览校验结果 ④ 重复数据跳过 ⑤ 失败记录可下载查看原因
US-04作为管理员,我希望能导出用户数据,以便进行线下分析P1① 导出当前筛选条件下的所有用户 ② 单次上限 10000 条 ③ 不导出密码字段 ④ 超过 1000 条异步导出,完成后通知下载
US-05作为管理员,我希望能重置用户密码,以便用户忘记密码时处理P0① 支持自动生成随机密码 ② 支持手动输入新密码 ③ 重置后所有 Token 失效 ④ 可选择邮件通知用户
US-06作为用户,我希望能修改个人信息,以便更新我的资料P0① 可修改:昵称、性别 ② 用户名不可修改 ③ 修改后即时生效
US-07作为用户,我希望能修改密码,以便保障账号安全P0① 需验证当前密码 ② 新密码不能与最近 3 次相同 ③ 修改后所有设备退出登录
US-08作为用户,我希望能修改头像,以便展示个人形象P1① 支持 jpg/png 格式 ② 图片不超过 5MB ③ 支持裁剪为正方形 ④ 上传后即时显示
US-09作为管理员,我希望能按部门筛选用户,以便查看部门人员P0① 左侧部门树展示 ② 点击部门自动筛选该部门及子部门用户 ③ 筛选响应时间 < 300ms
US-10作为管理员,我希望能禁用/启用用户,以便控制访问权限P0① 禁用后用户无法登录 ② 禁用后所有 Token 立即失效 ③ 不能禁用自己 ④ 不能禁用超级管理员
US-11作为用户,我希望能修改绑定手机号,以便更换手机号后继续使用P0① 需验证原手机号 ② 新手机号不能与其他用户重复 ③ 修改后所有设备退出登录
US-12作为用户,我希望能绑定微信/钉钉等社交账号,以便下次快速登录P1① 支持绑定微信、钉钉、企业微信、飞书等 ② 一个平台类型只能绑定一个 ③ 绑定后可通过社交账号快捷登录

3. 功能需求 ​

3.1 后台管理端 ​

3.1.1 功能清单 ​

功能优先级说明
用户列表P0分页展示用户,支持多维度搜索筛选
新增用户P0创建新用户账号,分配部门和角色
编辑用户P0修改用户信息(用户名不可改)
删除用户P0逻辑删除,保留历史数据
批量删除P1勾选多个用户批量删除
用户导入P1Excel 批量导入,支持预览和错误下载
用户导出P1导出筛选结果,大数据量异步导出
重置密码P0管理员为用户重置密码
状态切换P0启用/禁用用户,即时生效

3.1.2 用户列表 ​

页面布局描述:

业务规则:

规则编号规则描述影响角色
R-01默认按创建时间倒序排列,最新的在最前面所有管理员
R-02点击部门节点,筛选该部门及所有子部门的用户所有管理员
R-03用户名和手机号支持模糊搜索(输入「张」能搜到「张三」)所有管理员
R-04状态筛选:全部 / 正常 / 停用所有管理员
R-05创建时间支持范围筛选所有管理员
R-06超级管理员可以看到全平台所有用户,不受租户限制超级管理员
R-07租户管理员只能看到本租户下的用户租户管理员
R-08部门管理员只能看到本部门及下属部门的用户部门管理员
R-09列表中手机号、邮箱脱敏显示(中间4位用*替代)所有管理员
R-10不能删除超级管理员账号所有管理员
R-11不能禁用自己的账号(防止把自己锁在外面)所有管理员
R-12不能禁用超级管理员账号所有管理员

列表数据字段:

字段名类型说明列表展示
idLong用户ID不展示,内部使用
usernameString用户名展示
nicknameString昵称展示
deptNameString部门名称展示
postNamesString[]岗位名称列表展示,多个用逗号分隔
roleNamesString[]角色名称列表展示,多个用逗号分隔
mobileString手机号脱敏展示(138****1234)
emailString邮箱脱敏展示
statusInteger状态(0-正常 1-停用)开关组件,可直接切换
sexInteger性别(0-未知 1-男 2-女)按需展示
avatarString头像URL可选展示头像列
loginIpString最后登录IP展示
loginDateDateTime最后登录时间展示
createTimeDateTime创建时间展示

接口设计:

接口名称请求方式接口路径说明
获取用户分页GET/admin-api/system/user/page分页查询用户列表
获取用户详情GET/admin-api/system/user/get获取单个用户完整信息(用于编辑回显)
获取用户精简列表GET/admin-api/system/user/simple-list仅返回 ID + 昵称,用于下拉选择(如选择创建者)

分页查询请求参数:

参数名类型必填说明
usernameString否用户名(模糊匹配)
mobileString否手机号(模糊匹配)
statusInteger否状态(0-正常 1-停用)
deptIdLong否部门ID(自动包含子部门)
createTimeDateTime[]否创建时间范围 [开始, 结束]
pageNoInteger是页码,从 1 开始
pageSizeInteger是每页条数,默认 10

分页查询返回结果:

字段名类型说明
listUser[]用户列表(字段见上方列表数据字段)
totalLong符合条件的总记录数

用户详情返回结果(用于编辑弹窗回显):

字段名类型说明
idLong用户ID
usernameString用户名
nicknameString昵称
remarkString备注
deptIdLong部门ID
postIdsLong[]岗位ID列表
mobileString手机号(完整,非脱敏)
emailString邮箱(完整,非脱敏)
avatarString头像URL
statusInteger状态
sexInteger性别
roleIdsLong[]角色ID列表
loginIpString最后登录IP
loginDateDateTime最后登录时间
createTimeDateTime创建时间

3.1.3 新增用户 ​

页面描述:

表单字段:

字段类型必填校验规则
用户名输入框是4-30位,仅字母、数字、下划线;全局唯一;创建后不可修改
昵称输入框是1-30 字符
密码输入框否不填则使用系统默认密码(可在系统配置中设置)
所属部门树形选择是必须选择一个部门
岗位下拉多选否可选择多个岗位
手机号输入框是11位手机号格式;全局唯一
邮箱输入框否标准邮箱格式;全局唯一(如果填写)
性别单选否男 / 女 / 未知(默认未知)
角色下拉多选是至少选择一个角色
备注文本域否最多 200 字符

业务规则:

规则编号规则描述
R-01用户名全局唯一,创建后不可修改(类似身份证号,是用户的永久标识)
R-02手机号全局唯一,一个手机号只能绑定一个账号
R-03邮箱全局唯一(如果填写了的话),一个邮箱只能绑定一个账号
R-04不填密码时,使用系统默认密码(在「基础设施 - 配置管理」中设置)
R-05创建成功后,可勾选「发送密码到用户邮箱」,系统自动发一封包含初始密码的邮件
R-06创建用户时,该用户自动归属到当前管理员所在的租户

接口设计:

接口名称请求方式接口路径说明
创建用户POST/admin-api/system/user/create创建新用户

请求参数:

参数名类型必填说明
usernameString是用户名
nicknameString是昵称
passwordString否密码(不传则使用默认密码)
deptIdLong是部门ID
postIdsLong[]否岗位ID列表
mobileString是手机号
emailString否邮箱
sexInteger否性别(0-未知 1-男 2-女)
roleIdsLong[]是角色ID列表
remarkString否备注

返回结果:

字段名类型说明
idLong新创建的用户ID

3.1.4 编辑用户 ​

页面描述:

  • 弹窗形式,预填当前用户的所有信息
  • 用户名置灰不可修改(显示但不可编辑,旁注「用户名创建后不可修改」)
  • 其他字段同新增用户

与新增的区别:

  • 没有密码字段(密码修改走「重置密码」功能)
  • 用户名不可修改
  • 提交后更新原有记录,不创建新记录

接口设计:

接口名称请求方式接口路径说明
更新用户PUT/admin-api/system/user/update更新用户信息

请求参数:

参数名类型必填说明
idLong是用户ID
nicknameString是昵称
deptIdLong是部门ID
postIdsLong[]否岗位ID列表
mobileString是手机号
emailString否邮箱
sexInteger否性别
roleIdsLong[]是角色ID列表
remarkString否备注

3.1.5 删除用户 ​

业务规则:

规则编号规则描述为什么这样设计
R-01逻辑删除,不物理删除保留历史数据:该用户创建的项目、提交的审批等记录不受影响
R-02不能删除超级管理员防止系统失去最高权限管理者
R-03删除前需二次确认防止误操作,弹窗提示「确定删除用户 XXX 吗?」
R-04删除后该用户的所有 Token 立即失效安全考虑,确保被删除的用户立即无法访问系统
R-05批量删除时,跳过不可删除的用户(如超管)批量操作中如果因为一个超管导致整批失败,体验很差

接口设计:

接口名称请求方式接口路径说明
删除用户DELETE/admin-api/system/user/delete删除单个用户
批量删除用户DELETE/admin-api/system/user/batch-delete批量删除多个用户

请求参数(单个删除):

参数名类型必填说明
idLong是用户ID

请求参数(批量删除):

参数名类型必填说明
idsLong[]是用户ID列表

3.1.6 重置密码 ​

页面描述:

业务规则:

规则编号规则描述
R-01「自动生成」生成 12 位包含大小写字母、数字的随机密码
R-02「手动输入」需满足密码强度要求(8-20位,包含字母和数字)
R-03重置成功后,该用户的所有 Token 立即失效(所有设备退出登录)
R-04勾选「发送邮件」后,系统向用户邮箱发送包含新密码的邮件
R-05重置密码操作记录到操作日志中(审计需要)

接口设计:

接口名称请求方式接口路径说明
重置密码PUT/admin-api/system/user/update-password重置用户密码

请求参数:

参数名类型必填说明
idLong是用户ID
passwordString是新密码(前端加密后传输)

3.1.7 状态切换 ​

页面描述:

  • 在用户列表的「状态」列,直接展示一个开关组件
  • 点击开关即可切换状态,弹窗二次确认

业务规则:

规则编号规则描述为什么这样设计
R-01禁用后该用户无法登录基本安全需求
R-02禁用后该用户的所有 Token 立即失效确保即时生效,不存在「禁用后还能用几分钟」的窗口
R-03不能禁用自己的账号防止管理员把自己锁在外面
R-04不能禁用超级管理员防止误操作导致系统无法管理
R-05切换状态前弹窗确认防止误触,提示「确定禁用用户 XXX 吗?」

接口设计:

接口名称请求方式接口路径说明
更新用户状态PUT/admin-api/system/user/update-status更新用户状态

请求参数:

参数名类型必填说明
idLong是用户ID
statusInteger是状态(0-正常 1-停用)

3.1.8 用户导入 ​

页面描述:

业务规则:

规则编号规则描述为什么这样设计
R-01支持 xlsx、xls 格式覆盖主流 Excel 版本
R-02单次最多导入 1000 条防止大数据量导入导致系统长时间阻塞
R-03用户名已存在则跳过该条用户名不可重复,但不能因为一条重复就全部失败
R-04手机号已存在则跳过该条手机号不可重复
R-05导入结果:成功 X 条,失败 Y 条,跳过 Z 条让管理员清楚知道每条数据的处理结果
R-06失败记录可下载,包含失败原因方便管理员修正后重新导入,不用逐条排查
R-07部门名称在系统中不存在则报错防止用户被分配到不存在的部门
R-08角色名称在系统中不存在则报错防止分配不存在的角色
R-09Excel 模板包含示例数据让填写者一目了然知道格式要求

Excel 模板字段:

列名必填说明示例
用户名是4-30位字母数字下划线zhangsan
昵称是最多30字符张三
部门名称是必须与系统中部门名称完全一致研发部/前端组
岗位名称否必须与系统中岗位名称一致高级工程师
手机号是11位手机号13812345678
邮箱否标准邮箱格式zhangsan@example.com
性别否男/女/未知男
角色名称是多个用逗号分隔普通用户,部门管理员
备注否最多200字符新入职员工

接口设计:

接口名称请求方式接口路径说明
下载导入模板GET/admin-api/system/user/import-template下载 Excel 模板文件
导入用户POST/admin-api/system/user/import上传 Excel 并导入

3.1.9 用户导出 ​

页面描述:

  • 点击「导出」按钮,导出当前搜索条件下的所有用户
  • 小数据量(1000条以内):直接下载
  • 大数据量(超过1000条):异步导出,后台生成文件,完成后在「我的导出记录」中下载

业务规则:

规则编号规则描述
R-01导出格式为 xlsx
R-02单次最多导出 10000 条
R-03密码字段不导出(安全考虑)
R-04导出的数据与当前筛选条件一致(不是全量,而是筛选后的结果)
R-05手机号、邮箱在导出文件中完整显示(管理员需要完整数据做分析)

接口设计:

接口名称请求方式接口路径说明
导出用户GET/admin-api/system/user/export同步导出(小数据量)
异步导出用户POST/admin-api/system/user/export-async异步导出(大数据量)

请求参数(与分页查询的筛选条件一致):

参数名类型必填说明
usernameString否用户名筛选
mobileString否手机号筛选
statusInteger否状态筛选
deptIdLong否部门筛选
createTimeDateTime[]否创建时间范围

3.2 前台用户端(个人中心) ​

3.2.1 功能清单 ​

功能优先级说明
查看个人信息P0查看自己的基本信息、部门、岗位、角色
修改个人信息P0修改昵称、性别
修改手机号P0更换绑定手机号,需验证码验证
修改邮箱P1更换绑定邮箱,需邮件验证
修改密码P0修改登录密码,需验证旧密码
修改头像P1上传并裁剪头像图片
绑定社交账号P1绑定微信、钉钉等社交账号
解绑社交账号P1解绑已绑定的社交账号

3.2.2 查看个人信息 ​

页面描述:

数据字段:

字段名类型说明展示方式
usernameString用户名完整展示,不可修改
nicknameString昵称完整展示
avatarString头像URL展示头像图片
deptNameString部门名称完整展示(含部门路径)
postNamesString[]岗位名称列表多个逗号分隔
roleNamesString[]角色名称列表多个逗号分隔
mobileString手机号脱敏展示(138****1234)
emailString邮箱脱敏展示(zh****@example.com)
sexInteger性别展示文字(男/女/未知)
loginIpString最后登录IP完整展示
loginDateDateTime最后登录时间格式化展示
createTimeDateTime注册时间格式化展示

接口设计:

接口名称请求方式接口路径说明
获取个人信息GET/admin-api/system/user/profile/get获取当前登录用户的个人信息

返回结果:

字段名类型说明
userObject用户基本信息
deptObject部门信息(ID、名称、路径)
postsObject[]岗位列表(ID、名称)
rolesObject[]角色列表(ID、名称、编码)
socialUsersObject[]已绑定的社交账号列表(平台类型、绑定时间)

3.2.3 修改个人信息 ​

页面描述:

  • 编辑表单,仅允许修改昵称和性别
  • 用户名、手机号、邮箱需通过专门流程修改,不在此处

业务规则:

规则编号规则描述
R-01用户名不可修改(是账号的唯一标识)
R-02手机号需通过「修改手机号」流程修改(需验证码验证)
R-03邮箱需通过「修改邮箱」流程修改(需邮件验证)
R-04修改后即时生效,刷新页面即可看到最新信息

接口设计:

接口名称请求方式接口路径说明
修改个人信息PUT/admin-api/system/user/profile/update修改当前用户的个人信息

请求参数:

参数名类型必填说明
nicknameString是昵称(1-30字符)
sexInteger否性别(0-未知 1-男 2-女)

3.2.4 修改手机号 ​

页面描述:

业务流程:

  1. 验证原手机号:向当前绑定的手机号发送验证码,用户输入验证码确认身份
  2. 输入新手机号:填写新的手机号,获取并输入新手机号的验证码
  3. 完成:系统校验新手机号未被占用,更新绑定,所有设备退出登录

业务规则:

规则编号规则描述为什么这样设计
R-01新手机号不能与其他用户重复手机号是账号唯一标识之一
R-02新手机号需短信验证码验证确保用户确实拥有该手机号
R-03修改成功后所有设备退出登录安全考虑:如果在非本人设备上操作,确保原设备无法继续使用
R-04验证码 60 秒内只能发送一次防止短信轰炸和恶意刷短信
R-05验证码有效期 10 分钟平衡安全性和用户体验

接口设计:

接口名称请求方式接口路径说明
修改手机号PUT/admin-api/system/user/profile/update-mobile修改当前用户的手机号

请求参数:

参数名类型必填说明
mobileString是新手机号
codeInteger是新手机号的短信验证码
oldCodeInteger否原手机号的短信验证码(系统可配置是否强制验证)

3.2.5 修改邮箱 ​

业务流程:

  1. 输入新邮箱地址
  2. 系统发送验证邮件到新邮箱,包含 6 位验证码
  3. 用户输入邮件中的验证码
  4. 系统校验通过,更新邮箱绑定

业务规则:

规则编号规则描述
R-01新邮箱不能与其他用户重复
R-02邮箱需通过验证邮件验证
R-03验证邮件 60 秒内只能发送一次
R-04验证码有效期 10 分钟

接口设计:

接口名称请求方式接口路径说明
修改邮箱PUT/admin-api/system/user/profile/update-email修改当前用户的邮箱

请求参数:

参数名类型必填说明
emailString是新邮箱地址
codeInteger是邮件验证码

3.2.6 修改密码 ​

页面描述:

业务规则:

规则编号规则描述为什么这样设计
R-01当前密码必须正确防止他人在用户未锁屏时恶意修改密码
R-02新密码不能与最近 3 次密码相同防止用户反复使用同一个密码,提升安全性
R-03修改成功后所有设备退出登录安全考虑:确保所有终端使用新密码重新验证
R-04确认密码必须与新密码一致防止输入错误

接口设计:

接口名称请求方式接口路径说明
修改密码PUT/admin-api/system/user/profile/update-password修改当前用户的密码

请求参数:

参数名类型必填说明
oldPasswordString是当前密码(前端加密后传输)
newPasswordString是新密码(前端加密后传输)

3.2.7 修改头像 ​

页面描述:

业务规则:

规则编号规则描述
R-01支持 jpg、png 格式
R-02图片大小不超过 5MB
R-03上传后系统自动压缩到合适尺寸(建议 200x200)
R-04支持拖拽裁剪区域,裁剪为正方形
R-05上传成功后即时更新头像显示

接口设计:

接口名称请求方式接口路径说明
上传头像POST/admin-api/system/user/profile/update-avatar上传并更新头像

请求参数:

参数名类型必填说明
fileFile是头像图片文件(jpg/png,不超过5MB)

返回结果:

字段名类型说明
avatarString新头像的访问URL

4. 非功能需求 ​

4.1 性能要求 ​

指标要求说明
用户列表查询响应时间< 500ms包含部门树加载 + 列表数据
用户详情查询响应时间< 200ms单个用户完整信息
创建用户响应时间< 500ms含密码加密、角色关联创建
导入 1000 条用户响应时间< 30s含数据校验、入库
导出 10000 条用户响应时间< 60s异步导出场景
状态切换响应时间< 200ms含 Token 失效处理
部门树加载时间< 300ms用户管理页打开时

4.2 安全要求 ​

要求说明实现方式
权限控制只能管理权限范围内的用户数据权限:超管看全部、租户管理员看本租户、部门管理员看本部门
数据隔离租户间数据完全隔离所有查询自动拼接 tenant_id 条件
敏感信息脱敏手机号、邮箱在列表中脱敏显示中间4位用 * 替代
操作日志所有用户管理操作记录操作日志新增、编辑、删除、重置密码、状态切换均记录
密码安全密码加密存储,传输加密BCrypt 加密存储,HTTPS 传输
防越权不能操作权限范围外的用户接口层校验目标用户是否在当前管理员的管理范围内

4.3 兼容性要求 ​

端要求
PC 浏览器(后台管理端)Chrome 80+、Firefox 75+、Safari 13+、Edge 80+
移动端浏览器(前台用户端)iOS Safari 12+、Android Chrome 80+
微信内置浏览器支持个人中心相关功能

5. 数据设计 ​

5.1 核心数据模型 ​

用户表(system_users) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT用户ID
usernameVARCHAR(30)UNIQUE, NOT NULL用户名(全局唯一,创建后不可修改)
passwordVARCHAR(100)NOT NULL密码(BCrypt 加密存储)
nicknameVARCHAR(30)NOT NULL昵称
remarkVARCHAR(200)备注
dept_idBIGINTINDEX部门ID(关联部门表)
post_idsVARCHAR(255)岗位ID列表(逗号分隔,冗余字段)
emailVARCHAR(50)UNIQUE邮箱(全局唯一,可为空)
mobileVARCHAR(11)UNIQUE, NOT NULL手机号(全局唯一)
sexTINYINTDEFAULT 0性别(0-未知 1-男 2-女)
avatarVARCHAR(512)头像URL
statusTINYINTDEFAULT 0, NOT NULL状态(0-正常 1-停用)
user_typeTINYINTDEFAULT 1, NOT NULL用户类型(1-会员 2-管理员)
login_ipVARCHAR(50)最后登录IP
login_dateDATETIME最后登录时间
tenant_idBIGINTINDEX, NOT NULL租户ID(多租户隔离关键字段)
creatorVARCHAR(64)创建者
create_timeDATETIMEINDEX, NOT NULL创建时间
updaterVARCHAR(64)更新者
update_timeDATETIMENOT NULL更新时间
deletedBITDEFAULT 0, NOT NULL逻辑删除标记(0-未删除 1-已删除)

索引设计:

  • uk_username:username 唯一索引
  • uk_mobile:mobile 唯一索引
  • uk_email:email 唯一索引(允许为空)
  • idx_tenant_id:tenant_id 普通索引(租户查询加速)
  • idx_dept_id:dept_id 普通索引(部门查询加速)
  • idx_create_time:create_time 普通索引(时间排序加速)

用户-角色关联表(system_user_role) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT编号
user_idBIGINTINDEX, NOT NULL用户ID
role_idBIGINTINDEX, NOT NULL角色ID
creatorVARCHAR(64)创建者
create_timeDATETIMENOT NULL创建时间
updaterVARCHAR(64)更新者
update_timeDATETIMENOT NULL更新时间
deletedBITDEFAULT 0, NOT NULL逻辑删除标记

索引设计:

  • idx_user_id:user_id 普通索引
  • idx_role_id:role_id 普通索引
  • uk_user_role:(user_id, role_id) 联合唯一索引(防止重复分配)

用户-岗位关联表(system_user_post) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT编号
user_idBIGINTINDEX, NOT NULL用户ID
post_idBIGINTINDEX, NOT NULL岗位ID
creatorVARCHAR(64)创建者
create_timeDATETIMENOT NULL创建时间
updaterVARCHAR(64)更新者
update_timeDATETIMENOT NULL更新时间
deletedBITDEFAULT 0, NOT NULL逻辑删除标记

索引设计:

  • idx_user_id:user_id 普通索引
  • idx_post_id:post_id 普通索引
  • uk_user_post:(user_id, post_id) 联合唯一索引

5.2 数据字典 ​

字典类型字典值说明
system_user_sex0-未知、1-男、2-女性别选项
system_user_status0-正常、1-停用用户账号状态
system_user_type1-会员、2-管理员用户类型区分

6. 跨模块联动 ​

用户管理作为系统核心模块,与多个模块存在数据交互和业务联动:

6.1 与认证授权模块的联动 ​

联动场景触发条件联动动作说明
用户被禁用管理员禁用用户该用户所有 Token 立即失效通过认证模块的 Token 管理接口实现
用户被删除管理员删除用户该用户所有 Token 失效,登录记录保留登录日志不随用户删除而清除
重置密码管理员重置密码所有 Token 失效,需重新登录确保密码重置后立即生效
用户修改密码用户本人修改密码所有设备退出登录安全考虑

6.2 与角色权限模块的联动 ​

联动场景触发条件联动动作说明
分配角色新增/编辑用户时选择角色在 user_role 关联表中创建/更新记录用户获得对应角色的菜单权限和数据权限
移除角色编辑用户时取消某角色在 user_role 关联表中删除对应记录用户失去该角色的权限
角色被删除管理员删除某角色自动清除该角色与所有用户的关联防止出现「孤儿」关联数据

6.3 与组织架构模块的联动 ​

联动场景触发条件联动动作说明
分配部门新增/编辑用户时选择部门更新用户的 dept_id用户归属到指定部门
部门被删除管理员删除某部门该部门下的用户需要处理(转移到上级部门或禁止删除)防止用户变成「无部门」状态
部门树展示打开用户管理页面加载部门树,展示部门层级部门树数据来自组织架构模块
岗位分配新增/编辑用户时选择岗位在 user_post 关联表中创建记录岗位信息来自组织架构模块

6.4 与租户管理模块的联动 ​

联动场景触发条件联动动作说明
租户创建创建新租户时自动创建租户管理员账号租户管理员是租户内的最高权限用户
用户归属租户在租户内创建用户用户的 tenant_id 自动设为当前租户实现数据隔离
租户被禁用禁用某租户该租户下所有用户无法登录租户级别的全局禁用
账号额度租户有用户数上限创建用户时检查是否超过额度超出额度则拒绝创建

6.5 与消息通知模块的联动 ​

联动场景触发条件联动动作说明
发送初始密码创建用户时勾选「发送邮件」调用邮件发送接口将初始密码发送到用户邮箱
密码重置通知重置密码时勾选「发送邮件」调用邮件发送接口将新密码发送到用户邮箱
短信验证码修改手机号时调用短信发送接口向新手机号发送验证码
邮箱验证码修改邮箱时调用邮件发送接口向新邮箱发送验证码

6.6 与日志审计模块的联动 ​

联动场景触发条件记录内容
操作日志新增/编辑/删除用户操作人、操作时间、操作类型、变更内容
操作日志重置密码/状态切换操作人、目标用户、操作类型
操作日志导入/导出用户操作人、导入数量/导出数量

7. 附录 ​

7.1 名词解释 ​

术语解释类比
逻辑删除不真正从数据库中删除数据,而是通过一个标记字段(deleted)标记为「已删除」。数据还在,但查询时自动过滤掉像把文件放进「回收站」而不是永久删除
数据权限根据用户所属部门/角色,控制其能看到哪些数据。比如部门经理只能看到本部门的数据像每个楼层的门禁卡,只能开自己楼层的门
租户隔离SaaS 模式下,不同公司(租户)的数据完全隔离。A 公司的管理员看不到 B 公司的用户像同一栋办公楼里的不同公司,各自独立
Token用户登录后系统发放的「通行证」,后续每次请求都带着它,系统通过它识别你是谁像游乐场的腕带,戴着就能玩项目
BCrypt一种密码加密算法,把明文密码变成不可逆的密文。即使数据库被拖库,也无法直接看到用户密码像把信放进碎纸机,碎了就拼不回来
脱敏对敏感信息(手机号、邮箱等)进行部分遮挡处理,防止信息泄露像 138****1234,中间四位看不到
默认密码管理员创建用户时如果不指定密码,系统自动使用的一个预设密码。可在系统配置中修改像新手机的出厂密码
用户类型区分「会员」(普通 C 端用户)和「管理员」(有后台管理权限的用户)像商场的「普通顾客」和「VIP 会员」
异步导出大数据量导出时,系统在后台生成文件,完成后通知用户下载,而不是让用户一直等着像餐厅的「外卖」——下单后不用在柜台等,做好了通知你取
关联表记录两个实体之间关系的数据表。比如 user_role 表记录「哪个用户拥有哪个角色」像通讯录里「某人的电话号码」,连接了人和号码
树形结构像家谱一样的层级结构。部门就是典型的树形:总公司 - 研发部 - 前端组像文件夹的层级:C盘 - 工作 - 项目文档
下拉多选UI 组件,允许用户从一个列表中选择多个选项(区别于单选)像自助餐厅选菜,可以选好几种

7.2 接口汇总 ​

模块接口名称方式路径
后台-列表获取用户分页GET/admin-api/system/user/page
后台-列表获取用户详情GET/admin-api/system/user/get
后台-列表获取用户精简列表GET/admin-api/system/user/simple-list
后台-新增创建用户POST/admin-api/system/user/create
后台-编辑更新用户PUT/admin-api/system/user/update
后台-删除删除用户DELETE/admin-api/system/user/delete
后台-删除批量删除用户DELETE/admin-api/system/user/batch-delete
后台-密码重置密码PUT/admin-api/system/user/update-password
后台-状态更新用户状态PUT/admin-api/system/user/update-status
后台-导入下载导入模板GET/admin-api/system/user/import-template
后台-导入导入用户POST/admin-api/system/user/import
后台-导出导出用户GET/admin-api/system/user/export
后台-导出异步导出用户POST/admin-api/system/user/export-async
前台-信息获取个人信息GET/admin-api/system/user/profile/get
前台-信息修改个人信息PUT/admin-api/system/user/profile/update
前台-手机修改手机号PUT/admin-api/system/user/profile/update-mobile
前台-邮箱修改邮箱PUT/admin-api/system/user/profile/update-email
前台-密码修改密码PUT/admin-api/system/user/profile/update-password
前台-头像上传头像POST/admin-api/system/user/profile/update-avatar

7.3 变更记录 ​

版本日期修改内容修改人
v1.02026-09-11初始版本PM Team
v2.02026-09-19全面增强:补充7个详细业务场景、12条可量化验收标准、跨模块联动(6个模块)、名词解释(12项)、接口汇总表(19个接口)PM Team

本文档为用户管理模块 PRD,如有问题请联系产品负责人。

代码对齐(自动生成) ​

本节由 tools/docs/prd-align.mjs 从源码与 SQL 解析生成,请勿手工编辑;重跑 npm run prd:align 会整体替换。

1. 模块规模 ​

控制器接口权限点数据表
352088932

2. 控制器清单 ​

控制器基础路径接口数权限点数代码位置
AppAreaController/system/area10modules/system/src/main/java/com/pmforge/module/system/controller/app/ip/AppAreaController.java
AppDictDataController/system/dict-data10modules/system/src/main/java/com/pmforge/module/system/controller/app/dict/AppDictDataController.java
AppTenantController/system/tenant10modules/system/src/main/java/com/pmforge/module/system/controller/app/tenant/AppTenantController.java
AreaController/system/area20modules/system/src/main/java/com/pmforge/module/system/controller/admin/ip/AreaController.java
AuthController/system/auth100modules/system/src/main/java/com/pmforge/module/system/controller/admin/auth/AuthController.java
CaptchaController/system/captcha20modules/system/src/main/java/com/pmforge/module/system/controller/admin/captcha/CaptchaController.java
DeptController/system/dept84modules/system/src/main/java/com/pmforge/module/system/controller/admin/dept/DeptController.java
DictDataController/system/dict-data95modules/system/src/main/java/com/pmforge/module/system/controller/admin/dict/DictDataController.java
DictTypeController/system/dict-type94modules/system/src/main/java/com/pmforge/module/system/controller/admin/dict/DictTypeController.java
LoginLogController/system/login-log32modules/system/src/main/java/com/pmforge/module/system/controller/admin/logger/LoginLogController.java
MailAccountController/system/mail-account84modules/system/src/main/java/com/pmforge/module/system/controller/admin/mail/MailAccountController.java
MailLogController/system/mail-log21modules/system/src/main/java/com/pmforge/module/system/controller/admin/mail/MailLogController.java
MailTemplateController/system/mail-template95modules/system/src/main/java/com/pmforge/module/system/controller/admin/mail/MailTemplateController.java
MenuController/system/menu84modules/system/src/main/java/com/pmforge/module/system/controller/admin/permission/MenuController.java
NoticeController/system/notice74modules/system/src/main/java/com/pmforge/module/system/controller/admin/notice/NoticeController.java
NotifyMessageController/system/notify-message71modules/system/src/main/java/com/pmforge/module/system/controller/admin/notify/NotifyMessageController.java
NotifyTemplateController/system/notify-template95modules/system/src/main/java/com/pmforge/module/system/controller/admin/notify/NotifyTemplateController.java
OAuth2ClientController/system/oauth2-client64modules/system/src/main/java/com/pmforge/module/system/controller/admin/oauth2/OAuth2ClientController.java
OAuth2OpenController/system/oauth250modules/system/src/main/java/com/pmforge/module/system/controller/admin/oauth2/OAuth2OpenController.java
OAuth2TokenController/system/oauth2-token32modules/system/src/main/java/com/pmforge/module/system/controller/admin/oauth2/OAuth2TokenController.java
OAuth2UserController/system/oauth2/user20modules/system/src/main/java/com/pmforge/module/system/controller/admin/oauth2/OAuth2UserController.java
OperateLogController/system/operate-log32modules/system/src/main/java/com/pmforge/module/system/controller/admin/logger/OperateLogController.java
PermissionController/system/permission53modules/system/src/main/java/com/pmforge/module/system/controller/admin/permission/PermissionController.java
PostController/system/post95modules/system/src/main/java/com/pmforge/module/system/controller/admin/dept/PostController.java
RoleController/system/role95modules/system/src/main/java/com/pmforge/module/system/controller/admin/permission/RoleController.java
SmsCallbackController/system/sms/callback40modules/system/src/main/java/com/pmforge/module/system/controller/admin/sms/SmsCallbackController.java
SmsChannelControllersystem/sms-channel84modules/system/src/main/java/com/pmforge/module/system/controller/admin/sms/SmsChannelController.java
SmsLogController/system/sms-log32modules/system/src/main/java/com/pmforge/module/system/controller/admin/sms/SmsLogController.java
SmsTemplateController/system/sms-template106modules/system/src/main/java/com/pmforge/module/system/controller/admin/sms/SmsTemplateController.java
SocialClientController/system/social-client74modules/system/src/main/java/com/pmforge/module/system/controller/admin/socail/SocialClientController.java
SocialUserController/system/social-user51modules/system/src/main/java/com/pmforge/module/system/controller/admin/socail/SocialUserController.java
TenantController/system/tenant105modules/system/src/main/java/com/pmforge/module/system/controller/admin/tenant/TenantController.java
TenantPackageController/system/tenant-package84modules/system/src/main/java/com/pmforge/module/system/controller/admin/tenant/TenantPackageController.java
UserController/system/user167modules/system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java
UserProfileController/system/user/profile30modules/system/src/main/java/com/pmforge/module/system/controller/admin/user/UserProfileController.java

3. 接口对照 ​

本文引用 19 个接口,代码中存在 12 个(命中率 63%)。

本文接口代码中对应真实接口
/system/user/page✅
/system/user/get✅
/system/user/simple-list✅
/system/user/create✅
/system/user/update✅
/system/user/delete✅
/system/user/batch-delete❌—
/system/user/update-password✅
/system/user/update-status✅
/system/user/import-template❌—
/system/user/import✅
/system/user/export❌—
/system/user/export-async❌—
/system/user/profile/get✅
/system/user/profile/update✅
/system/user/profile/update-mobile❌/member/user/update-mobile
/system/user/profile/update-email❌—
/system/user/profile/update-password✅
/system/user/profile/update-avatar❌—

❌ 记 7 个接口在代码中不存在:可能是尚未实现(应移入「规划」),也可能是命名与实现不一致(以「对应真实接口」列修正)。

4. 数据表 ​

表名说明
system_deptDeptDO
system_dict_dataDictDataDO
system_dict_typeDictTypeDO
system_login_logLoginLogDO
system_mail_accountMailAccountDO
system_mail_logMailLogDO
system_mail_templateMailTemplateDO
system_menuMenuDO
system_noticeNoticeDO
system_notify_messageNotifyMessageDO
system_notify_templateNotifyTemplateDO
system_oauth2_access_tokenOAuth2AccessTokenDO
system_oauth2_approveOAuth2ApproveDO
system_oauth2_clientOAuth2ClientDO
system_oauth2_codeOAuth2CodeDO
system_oauth2_refresh_tokenOAuth2RefreshTokenDO
system_operate_logOperateLogDO
system_postPostDO
system_roleRoleDO
system_role_menuRoleMenuDO
system_sms_channelSmsChannelDO
system_sms_codeSmsCodeDO
system_sms_logSmsLogDO
system_sms_templateSmsTemplateDO
system_social_clientSocialClientDO
system_social_userSocialUserDO
system_social_user_bindSocialUserBindDO
system_tenantTenantDO
system_tenant_packageTenantPackageDO
system_user_postUserPostDO
system_user_roleUserRoleDO
system_usersAdminUserDO

5. 说明 ​

  • 模块码:system(系统管理);PRD 编号:01-02。
  • 「接口对照」只统计本文用反引号显式写出的 /admin-api/... 路径;未写接口的章节不代表没有实现。
  • 代码位置为相对仓库根的路径,行号可在功能卡或 docs/code/api/ 中查到。