主题
用户管理 PRD
文档信息
| 项目 | 内容 |
|---|---|
| 产品名称 | PMForge - 用户管理 |
| 文档版本 | v2.0 |
| 创建日期 | 2026-09-11 |
| 最后更新 | 2026-09-24 |
| 文档状态 | 评审中 |
| 优先级 | P0 |
一、功能概述
1.1 功能定位
用户管理是 PMForge 平台的"人员花名册"——所有使用系统的人，从注册到离职，他们的账号信息、组织归属、角色权限都在这里统一管理。它就像公司 HR 系统里的员工档案库，但面向的是数字平台上的每一个账号。
1.2 目标用户与核心诉求
| 用户类型 | 使用场景 | 核心诉求 |
|---|---|---|
| 超级管理员 | 管理全平台所有用户 | 不受租户限制，能管理任何人；能创建租户管理员 |
| 租户管理员 | 管理自己公司/组织内的用户 | 只能看到和操作自己租户下的人，数据不串 |
| 部门管理员 | 管理本部门的人员 | 能看到本部门及下属部门的人员，方便日常管理 |
| 普通用户 | 使用系统的员工 | 能查看和修改自己的资料、改密码、换头像 |
1.3 业务价值
| 价值维度 | 具体表现 |
|---|---|
| 统一管理 | 一个入口管理所有用户账号，避免多系统数据不一致 |
| 权限基础 | 用户是权限体系的载体——没有用户，角色和权限就无处挂载 |
| 组织映射 | 用户归属部门、岗位，真实反映公司组织架构 |
| 效率提升 | 批量导入/导出，一次处理数百人，告别逐条手工录入 |
| 安全合规 | 离职禁用、密码重置、操作留痕，满足安全审计要求 |
1.4 功能范围
| 功能分类 | 后台管理端（管理员用） | 前台用户端（本人用） |
|---|---|---|
| 查看用户列表 | ✅ 分页查看、搜索筛选 | ❌ |
| 新增用户 | ✅ 填写信息、分配角色部门 | ❌ |
| 编辑用户 | ✅ 修改用户信息 | ❌ |
| 删除用户 | ✅ 逻辑删除，保留历史数据 | ❌ |
| 批量导入用户 | ✅ Excel上传，批量创建 | ❌ |
| 批量导出用户 | ✅ 导出当前筛选结果 | ❌ |
| 重置密码 | ✅ 管理员帮用户重置 | ❌ |
| 启用/禁用用户 | ✅ 控制用户能否登录 | ❌ |
| 查看个人信息 | ❌ | ✅ 看自己的资料 |
| 修改个人信息 | ❌ | ✅ 改昵称、性别 |
| 修改手机号 | ❌ | ✅ 需验证码验证 |
| 修改邮箱 | ❌ | ✅ 需邮件验证 |
| 修改密码 | ❌ | ✅ 需验证旧密码 |
| 修改头像 | ❌ | ✅ 上传裁剪 |
| 绑定/解绑社交账号 | ❌ | ✅ 微信、钉钉等 |
二、用户场景
2.1 核心使用场景
场景1：HR 批量导入新员工账号
角色：租户管理员 小王 背景：公司新招了 50 人，下周一入职，需要提前在系统里创建好账号
操作步骤：
- 小王登录后台，进入「用户管理」页面
- 点击「导入」按钮，弹窗提示操作步骤
- 点击「下载模板」，得到一份 Excel 模板文件
- 打开模板，按格式填写 50 人的姓名、用户名、手机号、部门、岗位等信息
- 回到弹窗，上传填好的 Excel 文件
- 系统自动校验：格式是否正确、用户名是否重复、手机号是否已存在、部门名称是否对得上
- 校验完成后显示预览：「可导入 48 条，异常 2 条」
- 小王点击「确认导入」，48 个账号创建成功
- 异常 2 条可以下载查看原因（比如「手机号已被 zhangsan 使用」）
- 系统自动为每个新用户生成初始密码，小王可选择是否发送密码邮件到员工邮箱
期望：50 人的账号 5 分钟内搞定，异常数据有明确提示，不需要逐条排查。
异常处理：
- Excel 格式不对 → 提示「请使用下载的模板填写」
- 部门名称不存在 → 提示「第 X 行部门「XX」不存在，请检查」
- 超过 1000 条 → 提示「单次最多导入 1000 条，请分批导入」
场景2：管理员处理员工离职
角色：租户管理员 小王 背景：员工张三下周离职，需要处理他的系统账号
操作步骤：
- 小王在用户列表搜索「张三」，找到对应账号
- 小王选择「禁用」而不是「删除」——因为张三经手的项目记录、审批单据需要保留
- 禁用后，张三立即无法登录系统，他当前正在使用的页面下次操作时会被强制退出
- 如果后续需要，小王可以随时重新启用这个账号
- 如果确认要删除，小王点击「删除」，系统弹出确认框：「删除后该用户所有 Token 失效，确定删除？」
- 确认后，账号被逻辑删除（数据库里还在，只是标记为已删除），张三的所有登录凭证立即失效
期望：禁用而非删除，保留历史数据可追溯；操作即时生效，不会有「禁用后还能用几分钟」的窗口期。
关键决策：
- 为什么推荐「禁用」而不是「删除」？因为张三创建的项目、提交的审批、上传的文件都需要保留记录。删除用户后，这些数据的创建者信息会变成空值，影响数据完整性。
场景3：新员工第一次登录修改个人信息
角色：普通用户 小李（新入职员工） 背景：小李收到管理员发的初始密码，第一次登录系统
操作步骤：
- 小李打开系统登录页，输入用户名和初始密码，登录成功
- 系统检测到是首次登录（或密码是初始密码），提示「建议修改初始密码」
- 小李点击右上角头像，进入「个人中心」
- 看到自己的基本信息：用户名（不可改）、昵称、部门、岗位、角色等
- 小李修改昵称为「李哥」，上传了一张头像照片
- 点击「修改密码」，输入初始密码和新密码，修改成功
- 系统提示「密码修改成功，请重新登录」，跳转到登录页
- 小李用新密码登录，看到右上角已经显示自己设置的头像和昵称
期望：流程简单直观，不需要看说明书就能完成；头像修改后即时生效，不用刷新页面。
场景4：部门经理查看本部门人员
角色：部门管理员 张经理（研发部负责人） 背景：张经理想了解研发部目前有多少人，各自的角色和岗位
操作步骤：
- 张经理登录后台，进入「用户管理」页面
- 左侧部门树自动展开到张经理有权限的「研发部」
- 点击「研发部」，右侧列表自动筛选出研发部的所有用户
- 张经理可以看到每个人的用户名、昵称、岗位、角色、手机号、状态等信息
- 展开子部门「前端组」，可以看到前端组的成员
- 张经理在搜索框输入「前端」，进一步筛选岗位包含「前端」的用户
- 点击「导出」，把当前筛选结果导出为 Excel，用于部门会议
期望：只能看到自己有权限管理部门的人，看不到其他部门的数据；搜索和筛选要快，不能等好几秒。
权限边界：
- 张经理能看到：研发部、前端组、后端组（研发部的子部门）的所有用户
- 张经理看不到：产品部、市场部等其他部门的用户
- 超级管理员能看到：全公司所有部门的用户
场景5：用户更换绑定手机号
角色：普通用户 小陈 背景：小陈换了新手机号，需要更新系统中的绑定手机
操作步骤：
- 小陈进入「个人中心」→「安全设置」→「修改手机号」
- 系统先验证身份：向原手机号发送验证码
- 小陈输入原手机号收到的验证码
- 输入新手机号，点击「获取验证码」
- 输入新手机号收到的验证码
- 系统校验：新手机号是否已被其他账号使用？→ 没有，通过
- 修改成功，系统提示「手机号已更新」
- 出于安全考虑，系统让所有设备的登录状态失效，小陈需要重新登录
期望：整个流程 2 分钟内完成；如果新手机号已被占用，要明确告知。
异常处理：
- 原手机号已停用，收不到验证码 → 提供「手机号不可用？联系管理员解绑」入口
- 新手机号已被其他账号使用 → 提示「该手机号已被注册，请直接登录或使用其他手机号」
场景6：管理员重置用户密码
角色：租户管理员 小王 背景：员工老赵忘记密码，打电话找管理员重置
操作步骤：
- 小王在用户列表找到「老赵」
- 点击操作列的「重置密码」按钮
- 弹窗出现，有两个选项：
- 「自动生成」：系统随机生成一个 12 位包含字母数字的密码
- 「手动输入」：小王自己设一个密码
- 小王选择「自动生成」，系统生成密码
Kx9mP2vL5nQ8 - 勾选「发送密码到用户邮箱」
- 点击确认，密码重置成功
- 老赵的邮箱收到一封邮件：「您的密码已被重置为：Kx9mP2vL5nQ8，登录后请及时修改」
- 老赵原来的登录状态全部失效，需要用新密码重新登录
期望：1 分钟内完成；密码通过安全渠道（邮件）发送，不在聊天工具里明文传递。
场景7：超级管理员查看全平台用户分布
角色：超级管理员 背景：平台运营半年，超级管理员想了解用户增长情况
操作步骤：
- 超级管理员进入用户管理页面
- 不选择任何部门筛选，看到全平台用户列表
- 通过创建时间筛选，查看本月新增用户
- 通过状态筛选，查看有多少用户被禁用
- 导出全量用户数据，用于运营分析
期望：超管不受租户限制，能看到所有数据；大数据量导出时不能卡死系统。
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.1 后台管理端
3.1.1 功能清单
| 功能 | 优先级 | 说明 |
|---|---|---|
| 用户列表 | P0 | 分页展示用户，支持多维度搜索筛选 |
| 新增用户 | P0 | 创建新用户账号，分配部门和角色 |
| 编辑用户 | P0 | 修改用户信息（用户名不可改） |
| 删除用户 | P0 | 逻辑删除，保留历史数据 |
| 批量删除 | P1 | 勾选多个用户批量删除 |
| 用户导入 | P1 | Excel 批量导入，支持预览和错误下载 |
| 用户导出 | 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 | 不能禁用超级管理员账号 | 所有管理员 |
列表数据字段：
| 字段名 | 类型 | 说明 | 列表展示 |
|---|---|---|---|
| id | Long | 用户ID | 不展示，内部使用 |
| username | String | 用户名 | 展示 |
| nickname | String | 昵称 | 展示 |
| deptName | String | 部门名称 | 展示 |
| postNames | String[] | 岗位名称列表 | 展示，多个用逗号分隔 |
| roleNames | String[] | 角色名称列表 | 展示，多个用逗号分隔 |
| mobile | String | 手机号 | 脱敏展示（138****1234） |
| String | 邮箱 | 脱敏展示 | |
| status | Integer | 状态（0-正常 1-停用） | 开关组件，可直接切换 |
| sex | Integer | 性别（0-未知 1-男 2-女） | 按需展示 |
| avatar | String | 头像URL | 可选展示头像列 |
| loginIp | String | 最后登录IP | 展示 |
| loginDate | DateTime | 最后登录时间 | 展示 |
| createTime | DateTime | 创建时间 | 展示 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取用户分页 | GET | /admin-api/system/user/page | 分页查询用户列表 |
| 获取用户详情 | GET | /admin-api/system/user/get | 获取单个用户完整信息（用于编辑回显） |
| 获取用户精简列表 | GET | /admin-api/system/user/simple-list | 仅返回 ID + 昵称，用于下拉选择（如选择创建者） |
分页查询请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | String | 否 | 用户名（模糊匹配） |
| mobile | String | 否 | 手机号（模糊匹配） |
| status | Integer | 否 | 状态（0-正常 1-停用） |
| deptId | Long | 否 | 部门ID（自动包含子部门） |
| createTime | DateTime[] | 否 | 创建时间范围 [开始, 结束] |
| pageNo | Integer | 是 | 页码，从 1 开始 |
| pageSize | Integer | 是 | 每页条数，默认 10 |
分页查询返回结果：
| 字段名 | 类型 | 说明 |
|---|---|---|
| list | User[] | 用户列表（字段见上方列表数据字段） |
| total | Long | 符合条件的总记录数 |
用户详情返回结果（用于编辑弹窗回显）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | Long | 用户ID |
| username | String | 用户名 |
| nickname | String | 昵称 |
| remark | String | 备注 |
| deptId | Long | 部门ID |
| postIds | Long[] | 岗位ID列表 |
| mobile | String | 手机号（完整，非脱敏） |
| String | 邮箱（完整，非脱敏） | |
| avatar | String | 头像URL |
| status | Integer | 状态 |
| sex | Integer | 性别 |
| roleIds | Long[] | 角色ID列表 |
| loginIp | String | 最后登录IP |
| loginDate | DateTime | 最后登录时间 |
| createTime | DateTime | 创建时间 |
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 | 创建新用户 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | String | 是 | 用户名 |
| nickname | String | 是 | 昵称 |
| password | String | 否 | 密码（不传则使用默认密码） |
| deptId | Long | 是 | 部门ID |
| postIds | Long[] | 否 | 岗位ID列表 |
| mobile | String | 是 | 手机号 |
| String | 否 | 邮箱 | |
| sex | Integer | 否 | 性别（0-未知 1-男 2-女） |
| roleIds | Long[] | 是 | 角色ID列表 |
| remark | String | 否 | 备注 |
返回结果：
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | Long | 新创建的用户ID |
3.1.4 编辑用户
页面描述：
- 弹窗形式，预填当前用户的所有信息
- 用户名置灰不可修改（显示但不可编辑，旁注「用户名创建后不可修改」）
- 其他字段同新增用户
与新增的区别：
- 没有密码字段（密码修改走「重置密码」功能）
- 用户名不可修改
- 提交后更新原有记录，不创建新记录
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 更新用户 | PUT | /admin-api/system/user/update | 更新用户信息 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 用户ID |
| nickname | String | 是 | 昵称 |
| deptId | Long | 是 | 部门ID |
| postIds | Long[] | 否 | 岗位ID列表 |
| mobile | String | 是 | 手机号 |
| String | 否 | 邮箱 | |
| sex | Integer | 否 | 性别 |
| roleIds | Long[] | 是 | 角色ID列表 |
| remark | String | 否 | 备注 |
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 | 批量删除多个用户 |
请求参数（单个删除）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 用户ID |
请求参数（批量删除）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ids | Long[] | 是 | 用户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 | 重置用户密码 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 用户ID |
| password | String | 是 | 新密码（前端加密后传输） |
3.1.7 状态切换
页面描述：
- 在用户列表的「状态」列，直接展示一个开关组件
- 点击开关即可切换状态，弹窗二次确认
业务规则：
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 禁用后该用户无法登录 | 基本安全需求 |
| R-02 | 禁用后该用户的所有 Token 立即失效 | 确保即时生效，不存在「禁用后还能用几分钟」的窗口 |
| R-03 | 不能禁用自己的账号 | 防止管理员把自己锁在外面 |
| R-04 | 不能禁用超级管理员 | 防止误操作导致系统无法管理 |
| R-05 | 切换状态前弹窗确认 | 防止误触，提示「确定禁用用户 XXX 吗？」 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 更新用户状态 | PUT | /admin-api/system/user/update-status | 更新用户状态 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | Long | 是 | 用户ID |
| status | Integer | 是 | 状态（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-09 | Excel 模板包含示例数据 | 让填写者一目了然知道格式要求 |
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 | 异步导出（大数据量） |
请求参数（与分页查询的筛选条件一致）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | String | 否 | 用户名筛选 |
| mobile | String | 否 | 手机号筛选 |
| status | Integer | 否 | 状态筛选 |
| deptId | Long | 否 | 部门筛选 |
| createTime | DateTime[] | 否 | 创建时间范围 |
3.2 前台用户端（个人中心）
3.2.1 功能清单
| 功能 | 优先级 | 说明 |
|---|---|---|
| 查看个人信息 | P0 | 查看自己的基本信息、部门、岗位、角色 |
| 修改个人信息 | P0 | 修改昵称、性别 |
| 修改手机号 | P0 | 更换绑定手机号，需验证码验证 |
| 修改邮箱 | P1 | 更换绑定邮箱，需邮件验证 |
| 修改密码 | P0 | 修改登录密码，需验证旧密码 |
| 修改头像 | P1 | 上传并裁剪头像图片 |
| 绑定社交账号 | P1 | 绑定微信、钉钉等社交账号 |
| 解绑社交账号 | P1 | 解绑已绑定的社交账号 |
3.2.2 查看个人信息
页面描述：
数据字段：
| 字段名 | 类型 | 说明 | 展示方式 |
|---|---|---|---|
| username | String | 用户名 | 完整展示，不可修改 |
| nickname | String | 昵称 | 完整展示 |
| avatar | String | 头像URL | 展示头像图片 |
| deptName | String | 部门名称 | 完整展示（含部门路径） |
| postNames | String[] | 岗位名称列表 | 多个逗号分隔 |
| roleNames | String[] | 角色名称列表 | 多个逗号分隔 |
| mobile | String | 手机号 | 脱敏展示（138****1234） |
| String | 邮箱 | 脱敏展示（zh****@example.com） | |
| sex | Integer | 性别 | 展示文字（男/女/未知） |
| loginIp | String | 最后登录IP | 完整展示 |
| loginDate | DateTime | 最后登录时间 | 格式化展示 |
| createTime | DateTime | 注册时间 | 格式化展示 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取个人信息 | GET | /admin-api/system/user/profile/get | 获取当前登录用户的个人信息 |
返回结果：
| 字段名 | 类型 | 说明 |
|---|---|---|
| user | Object | 用户基本信息 |
| dept | Object | 部门信息（ID、名称、路径） |
| posts | Object[] | 岗位列表（ID、名称） |
| roles | Object[] | 角色列表（ID、名称、编码） |
| socialUsers | Object[] | 已绑定的社交账号列表（平台类型、绑定时间） |
3.2.3 修改个人信息
页面描述：
- 编辑表单，仅允许修改昵称和性别
- 用户名、手机号、邮箱需通过专门流程修改，不在此处
业务规则：
| 规则编号 | 规则描述 |
|---|---|
| R-01 | 用户名不可修改（是账号的唯一标识） |
| R-02 | 手机号需通过「修改手机号」流程修改（需验证码验证） |
| R-03 | 邮箱需通过「修改邮箱」流程修改（需邮件验证） |
| R-04 | 修改后即时生效，刷新页面即可看到最新信息 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 修改个人信息 | PUT | /admin-api/system/user/profile/update | 修改当前用户的个人信息 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| nickname | String | 是 | 昵称（1-30字符） |
| sex | Integer | 否 | 性别（0-未知 1-男 2-女） |
3.2.4 修改手机号
页面描述：
业务流程：
- 验证原手机号：向当前绑定的手机号发送验证码，用户输入验证码确认身份
- 输入新手机号：填写新的手机号，获取并输入新手机号的验证码
- 完成：系统校验新手机号未被占用，更新绑定，所有设备退出登录
业务规则：
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 新手机号不能与其他用户重复 | 手机号是账号唯一标识之一 |
| R-02 | 新手机号需短信验证码验证 | 确保用户确实拥有该手机号 |
| R-03 | 修改成功后所有设备退出登录 | 安全考虑：如果在非本人设备上操作，确保原设备无法继续使用 |
| R-04 | 验证码 60 秒内只能发送一次 | 防止短信轰炸和恶意刷短信 |
| R-05 | 验证码有效期 10 分钟 | 平衡安全性和用户体验 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 修改手机号 | PUT | /admin-api/system/user/profile/update-mobile | 修改当前用户的手机号 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mobile | String | 是 | 新手机号 |
| code | Integer | 是 | 新手机号的短信验证码 |
| oldCode | Integer | 否 | 原手机号的短信验证码（系统可配置是否强制验证） |
3.2.5 修改邮箱
业务流程：
- 输入新邮箱地址
- 系统发送验证邮件到新邮箱，包含 6 位验证码
- 用户输入邮件中的验证码
- 系统校验通过，更新邮箱绑定
业务规则：
| 规则编号 | 规则描述 |
|---|---|
| R-01 | 新邮箱不能与其他用户重复 |
| R-02 | 邮箱需通过验证邮件验证 |
| R-03 | 验证邮件 60 秒内只能发送一次 |
| R-04 | 验证码有效期 10 分钟 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 修改邮箱 | PUT | /admin-api/system/user/profile/update-email | 修改当前用户的邮箱 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| String | 是 | 新邮箱地址 | |
| code | Integer | 是 | 邮件验证码 |
3.2.6 修改密码
页面描述：
业务规则：
| 规则编号 | 规则描述 | 为什么这样设计 |
|---|---|---|
| R-01 | 当前密码必须正确 | 防止他人在用户未锁屏时恶意修改密码 |
| R-02 | 新密码不能与最近 3 次密码相同 | 防止用户反复使用同一个密码，提升安全性 |
| R-03 | 修改成功后所有设备退出登录 | 安全考虑：确保所有终端使用新密码重新验证 |
| R-04 | 确认密码必须与新密码一致 | 防止输入错误 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 修改密码 | PUT | /admin-api/system/user/profile/update-password | 修改当前用户的密码 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| oldPassword | String | 是 | 当前密码（前端加密后传输） |
| newPassword | String | 是 | 新密码（前端加密后传输） |
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 | 上传并更新头像 |
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | File | 是 | 头像图片文件（jpg/png，不超过5MB） |
返回结果：
| 字段名 | 类型 | 说明 |
|---|---|---|
| avatar | String | 新头像的访问URL |
四、非功能需求
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.1 核心数据模型
用户表（system_users）
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT | PK, AUTO_INCREMENT | 用户ID |
| username | VARCHAR(30) | UNIQUE, NOT NULL | 用户名（全局唯一，创建后不可修改） |
| password | VARCHAR(100) | NOT NULL | 密码（BCrypt 加密存储） |
| nickname | VARCHAR(30) | NOT NULL | 昵称 |
| remark | VARCHAR(200) | 备注 | |
| dept_id | BIGINT | INDEX | 部门ID（关联部门表） |
| post_ids | VARCHAR(255) | 岗位ID列表（逗号分隔，冗余字段） | |
| VARCHAR(50) | UNIQUE | 邮箱（全局唯一，可为空） | |
| mobile | VARCHAR(11) | UNIQUE, NOT NULL | 手机号（全局唯一） |
| sex | TINYINT | DEFAULT 0 | 性别（0-未知 1-男 2-女） |
| avatar | VARCHAR(512) | 头像URL | |
| status | TINYINT | DEFAULT 0, NOT NULL | 状态（0-正常 1-停用） |
| user_type | TINYINT | DEFAULT 1, NOT NULL | 用户类型（1-会员 2-管理员） |
| login_ip | VARCHAR(50) | 最后登录IP | |
| login_date | DATETIME | 最后登录时间 | |
| tenant_id | BIGINT | INDEX, NOT NULL | 租户ID（多租户隔离关键字段） |
| creator | VARCHAR(64) | 创建者 | |
| create_time | DATETIME | INDEX, NOT NULL | 创建时间 |
| updater | VARCHAR(64) | 更新者 | |
| update_time | DATETIME | NOT NULL | 更新时间 |
| deleted | BIT | DEFAULT 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）
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT | PK, AUTO_INCREMENT | 编号 |
| user_id | BIGINT | INDEX, NOT NULL | 用户ID |
| role_id | BIGINT | INDEX, NOT NULL | 角色ID |
| creator | VARCHAR(64) | 创建者 | |
| create_time | DATETIME | NOT NULL | 创建时间 |
| updater | VARCHAR(64) | 更新者 | |
| update_time | DATETIME | NOT NULL | 更新时间 |
| deleted | BIT | DEFAULT 0, NOT NULL | 逻辑删除标记 |
索引设计：
idx_user_id：user_id 普通索引idx_role_id：role_id 普通索引uk_user_role：(user_id, role_id) 联合唯一索引（防止重复分配）
用户-岗位关联表（system_user_post）
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT | PK, AUTO_INCREMENT | 编号 |
| user_id | BIGINT | INDEX, NOT NULL | 用户ID |
| post_id | BIGINT | INDEX, NOT NULL | 岗位ID |
| creator | VARCHAR(64) | 创建者 | |
| create_time | DATETIME | NOT NULL | 创建时间 |
| updater | VARCHAR(64) | 更新者 | |
| update_time | DATETIME | NOT NULL | 更新时间 |
| deleted | BIT | DEFAULT 0, NOT NULL | 逻辑删除标记 |
索引设计：
idx_user_id：user_id 普通索引idx_post_id：post_id 普通索引uk_user_post：(user_id, post_id) 联合唯一索引
5.2 数据字典
| 字典类型 | 字典值 | 说明 |
|---|---|---|
| system_user_sex | 0-未知、1-男、2-女 | 性别选项 |
| system_user_status | 0-正常、1-停用 | 用户账号状态 |
| system_user_type | 1-会员、2-管理员 | 用户类型区分 |
六、跨模块联动
用户管理作为系统核心模块，与多个模块存在数据交互和业务联动：
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.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.0 | 2026-09-11 | 初始版本 | PM Team |
| v2.0 | 2026-09-19 | 全面增强：补充7个详细业务场景、12条可量化验收标准、跨模块联动（6个模块）、名词解释（12项）、接口汇总表（19个接口） | PM Team |
本文档为用户管理模块 PRD，如有问题请联系产品负责人。