Files
user-system/docs/PRD.md

744 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 用户管理系统产品需求文档 (PRD)
## 文档信息
| 项目 | 内容 |
|------|------|
| 产品名称 | 用户管理系统 (User Management System) |
| 文档版本 | v1.0 |
| 创建日期 | 2026-03-10 |
| 最后更新 | 2026-03-11 |
| 文档状态 | 草稿 |
---
## 产品概述
### 背景
在企业级应用开发中,用户管理是几乎所有系统都必需的基础模块。然而,许多企业重复开发相似的用户管理系统,造成大量资源浪费。同时,现有的开源解决方案往往功能过于臃肿、依赖复杂、或性能无法满足大规模需求。
### 产品定位
用户管理系统是一套标准化的、可快速集成的企业级用户管理解决方案,旨在解决重复开发用户管理系统造成的资源浪费问题。系统采用轻量级架构,极简第三方依赖,支持容器化部署,能够快速集成到各类业务系统中。
### 核心价值
- **降本增效**:避免重复开发,节省 60%+ 的用户管理开发时间
- **极简部署**:一键启动,无需复杂配置,支持独立数据库部署
- **高性能**:支持 10 亿用户规模和 10 万级并发访问
- **可扩展**:支持多社交平台登录,插件化架构易于扩展
- **安全可靠**:企业级安全设计,符合 GDPR 等数据保护法规
### 目标用户
- **企业开发者**:需要快速集成用户管理系统的企业开发团队
- **SaaS 平台**:需要标准用户认证和权限管理的 SaaS 服务商
- **创业公司**:需要快速启动产品 MVP 的创业团队
- **个人开发者**:需要完整用户管理功能的独立开发者
### 使用场景
1. **电商系统**:用户注册登录、购物车权限、订单权限
2. **SaaS 平台**:多租户用户管理、角色权限控制
3. **社交应用**:用户资料管理、社交账号登录
4. **企业内部系统**:员工账号管理、权限分级控制
5. **移动应用**App 用户认证、设备管理
---
## 核心功能
### 1. 用户注册与登录
#### 1.1 多种注册方式
- **邮箱注册**
- 邮箱地址验证(发送验证邮件)
- 邮箱唯一性校验
- 支持国际邮箱格式
- **手机号注册**
- 短信验证码校验
- 手机号唯一性校验
- 支持国际区号(+86、+1 等)
- **用户名注册**
- 用户名规则配置(长度、字符限制)
- 用户名唯一性校验
- 支持中英文、数字、下划线
#### 1.2 多种登录方式
- **密码登录**
- 用户名/邮箱/手机号 + 密码
- 密码错误次数限制
- 记住登录状态(可选)
- **验证码登录**
- 手机号/邮箱 + 验证码
- 验证码有效期控制5 分钟)
- 防刷机制
- **社交账号登录**
- 微信/QQ/支付宝/抖音/GitHub/Google 登录
- 一键授权,自动注册
- 社交账号与系统账号绑定
#### 1.3 多因素认证2FA
- **短信验证码**:登录时发送短信验证码
- **邮箱验证码**:登录时发送邮箱验证码
- **TOTP 认证**:支持 Google Authenticator 等应用
#### 1.4 密码安全
- **密码强度验证**
- 最小长度要求(可配置)
- 必须包含大小写字母、数字、特殊字符
- 实时密码强度提示
- **密码加密存储**
- 推荐算法Argon2id
- 备选算法bcrypt
- 不可逆加密,加盐处理
- **密码重置**
- 邮箱重置链接
- 手机验证码重置
- 安全问题验证(可选)
- **密码修改**
- 需要验证旧密码
- 新密码强度校验
- 密码历史记录(防止重复使用)
#### 1.5 用户信息管理
- **个人资料完善**
- 昵称、头像、性别、生日
- 个性签名、所在地区
- 自定义字段扩展
- **头像上传**
- 支持多种图片格式JPG、PNG、GIF
- 图片大小限制2MB
- 自动生成缩略图
- **账号绑定与解绑**
- 绑定/解绑手机号
- 绑定/解绑邮箱
- 绑定/解绑社交账号
---
### 2. 社交登录集成
#### 2.1 支持的社交平台
| 平台 | 授权方式 | 获取信息 |
|------|----------|----------|
| 微信 | 公众号授权、PC 扫码、小程序授权 | openid、unionid、昵称、头像 |
| QQ | PC 扫码、移动端授权 | openid、昵称、头像 |
| 支付宝 | OAuth2.0 | user_id、昵称、头像 |
| 抖音 | OAuth2.0 | open_id、昵称、头像 |
| GitHub | OAuth2.0 | id、login、avatar_url |
| Google | OAuth2.0 | sub、name、picture |
#### 2.2 社交账号绑定与解绑
- **绑定社交账号**
- 扫码或点击授权
- 验证当前用户身份
- 绑定成功后可用社交账号登录
- **解绑社交账号**
- 需要验证密码或其他登录方式
- 至少保留一种登录方式
- 解绑后无法用该社交账号登录
#### 2.3 多社交账号关联
- 支持同一系统账号绑定多个社交账号
- 社交账号之间可以互相切换登录
- 统一的用户身份管理
---
### 3. 授权与认证
#### 3.1 JWT 无状态认证
- **Access Token**
- 有效期2 小时(可配置)
- 签名算法RS256
- 包含用户 ID、角色、权限等信息
- **Refresh Token**
- 有效期30 天(可配置)
- 用于刷新 Access Token
- 存储Redis 或数据库
- **Token 黑名单**
- 支持主动吊销 Token
- 存储方式Redis
- 过期时间:对应 Token 过期时间
#### 3.2 OAuth 2.0 支持
- **授权码模式**Authorization Code
- **简化模式**Implicit
- **密码模式**Resource Owner Password Credentials
#### 3.3 SSO 单点登录
- 支持跨系统单点登录
- 统一认证中心
- Session 共享机制
- 支持 CAS、SAML 协议(可选)
#### 3.4 设备管理
- **多设备登录**
- 支持同一账号多设备登录
- 设备类型识别PC、手机、平板
- 设备信息记录IP、位置、浏览器
- **设备信任**
- 勾选"记住此设备"
- 信任设备免二次验证
- 信任期限可配置7-30 天)
- **设备移除**
- 查看已登录设备列表
- 远程强制下线指定设备
- 一键下线所有其他设备
---
### 4. 权限管理(基础版 RBAC
#### 4.1 用户-角色-权限模型
```
用户 (User) ──┬── 多对多 ─── 角色 (Role)
└── 多对多 ─── 权限 (Permission)
```
#### 4.2 角色管理
- **角色 CRUD**
- 创建角色:角色名称、描述、状态
- 编辑角色:修改名称、描述、状态
- 删除角色:需检查是否有关联用户
- 查询角色:列表查询、分页、排序
- **角色继承**
- 支持父角色和子角色
- 子角色自动继承父角色权限
- 继承深度可配置
- **默认角色**
- 新注册用户默认角色(如"普通用户"
- 管理员角色(如"超级管理员"
- 角色模板支持
#### 4.3 权限定义
- **权限格式**:资源:操作(如 `user:read``user:write``user:delete`
- **资源类型**系统模块、数据表、API 接口、页面、按钮
- **操作类型**read、write、delete、execute
- **权限分组**:按业务模块分组(如用户管理、订单管理)
#### 4.4 用户角色分配
- 一个用户可以分配多个角色
- 支持临时角色(设置有效期)
- 支持角色生效时间范围
- 角色分配/移除记录审计日志
#### 4.5 权限校验
- **API 接口权限**
- 基于 Token 中的权限信息校验
- 支持注解式权限控制
- 支持 URL 模式匹配
- **页面访问权限**
- 前端路由权限控制
- 菜单权限控制
- 页面按钮权限控制
- **操作权限**
- 按钮显示/隐藏
- 表单字段权限
- 数据范围权限
---
### 5. 用户管理
#### 5.1 用户列表查询
- **分页查询**
- 每页数量可配置10/20/50/100
- 总数统计
- 支持快速跳转页码
- **排序功能**
- 按注册时间、最后登录时间排序
- 按用户名、邮箱排序
- 升序/降序切换
- **高级筛选**
- 按用户名/邮箱/手机号搜索
- 按用户状态筛选(正常、锁定、禁用、待激活)
- 按注册时间范围筛选
- 按角色筛选
- 组合筛选条件
#### 5.2 用户信息管理
- **创建用户**
- 管理员手动创建用户
- 支持设置初始密码或发送激活邮件
- 支持分配默认角色
- **编辑用户**
- 修改用户基本信息
- 修改用户角色
- 修改用户状态
- **禁用/启用用户**
- 禁用用户后无法登录
- 保留用户数据
- 记录操作日志
- **删除用户**
- 软删除(逻辑删除)
- 支持数据保留期配置
- 重要用户删除需要二次确认
#### 5.3 用户状态管理
| 状态 | 说明 | 行为限制 |
|------|------|----------|
| 正常 | 用户正常使用 | 无限制 |
| 锁定 | 多次登录失败或异常 | 无法登录,需管理员解锁 |
| 禁用 | 管理员禁用 | 无法登录,系统功能受限 |
| 待激活 | 新注册未激活 | 无法登录,需激活 |
#### 5.4 用户操作日志
- **登录日志**
- 登录时间、IP 地址、设备信息
- 登录方式(密码、验证码、社交账号)
- 登录成功/失败记录
- 异常登录检测(异地登录、异常设备)
- **操作记录**
- 用户操作行为记录
- 权限变更记录
- 资料修改记录
- 角色分配记录
- **审计日志**
- 管理员操作记录
- 敏感操作记录(删除用户、修改权限)
- 数据导出记录
#### 5.5 用户导入导出
- **批量导入**
- 支持 Excel 格式
- 模板下载
- 数据验证
- 导入结果反馈(成功/失败明细)
- **批量导出**
- 支持 Excel、CSV 格式
- 支持字段选择
- 支持筛选导出
- 大数据量分批导出
---
### 6. 系统集成
#### 6.1 RESTful API
- 统一的 API 风格
- 支持 JSON 格式
- 版本控制(/api/v1/
- 完整的错误码体系
- 接口文档自动生成Swagger/OpenAPI
#### 6.2 SDK 支持
- **Java SDK**
- Maven/Gradle 依赖
- 封装 API 调用
- 提供便捷方法
- 示例代码
- **Go SDK**
- Go Modules 支持
- 完整的类型定义
- 并发安全
- 示例代码
- **Rust SDK**
- Cargo crate
- 类型安全
- 异步支持
- 示例代码
#### 6.3 Webhook 事件通知
- **事件类型**
- 用户注册
- 用户登录
- 用户资料修改
- 角色分配/移除
- 用户禁用/删除
- **事件格式**
- JSON 格式
- 签名验证
- 重试机制
- 事件去重
#### 6.4 自定义字段扩展
- 支持用户自定义字段
- JSON 格式存储
- 字段类型支持(字符串、数字、布尔、日期)
- 字段验证规则配置
#### 6.5 自定义主题配置
- 支持自定义登录页面样式
- 支持 Logo 替换
- 支持主题色配置
- 支持自定义 CSS
#### 6.6 Admin 管理后台
- 用户管理界面
- 角色权限管理界面
- 系统配置界面
- 日志查询界面
- 统计报表界面
---
### 7. 安全与风控
#### 7.1 登录安全
- **登录失败限制**
- 连续失败 5 次锁定账户 30 分钟
- 失败次数可配置
- 锁定时间可配置
- **验证码防刷**
- 图形验证码
- 滑动验证码
- 行为验证(可选)
- **IP 黑白名单**
- 支持配置 IP 白名单
- 支持配置 IP 黑名单
- 支持 IP 段配置
#### 7.2 接口防刷
- **接口限流**
- 基于令牌桶算法
- 按用户限流
- 按接口限流
- 限流阈值可配置
- **防重放攻击**
- 请求时间戳校验
- Nonce 机制
- 请求签名验证(可选)
#### 7.3 异常登录检测
- **异地登录检测**
- 记录常用登录地区
- 异地登录触发安全通知
- 邮件/短信提醒
- **异常设备检测**
- 设备指纹识别
- 新设备登录验证
- 异常设备登录告警
#### 7.4 敏感操作二次验证
- 修改密码需验证旧密码
- 修改邮箱需发送验证码
- 解绑社交账号需验证密码
- 删除账号需二次确认
---
### 8. 监控与运维
#### 8.1 系统监控
- **业务指标**
- 在线用户数
- 今日注册数
- 今日登录数
- API 调用量
- **性能指标**
- API 响应时间P50、P99
- 系统吞吐量QPS
- 错误率
- 系统负载
#### 8.2 日志管理
- **访问日志**
- 请求路径、参数、响应时间
- 客户端信息IP、User-Agent
- 请求 ID链路追踪
- **错误日志**
- 异常堆栈信息
- 错误码、错误信息
- 关联请求 ID
- **审计日志**
- 操作人、操作时间
- 操作类型、操作对象
- 操作前值、操作后值
#### 8.3 健康检查
- 健康检查接口:`/health`
- 检查项数据库连接、Redis 连接、外部依赖
- 返回状态UP/DOWN
#### 8.4 指标导出
- 指标接口:`/metrics`
- 格式Prometheus
- 指标类型Counter、Gauge、Histogram
- 支持集成 Grafana
---
## 非功能性需求
### 性能指标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 用户规模 | 10 亿 | 支持的最大用户数 |
| 并发访问 | 10 万 | 支持的峰值并发数 |
| API 响应时间P99 | < 500ms | 99% 的请求响应时间 |
| 系统可用性 | 99.99% | 年度停机时间 < 52.56 分钟 |
| 吞吐量 | 10 万 QPS | 每秒处理请求数 |
### 部署要求
- **单机部署**
- 支持单台服务器运行
- 默认使用 SQLite 数据库
- 无需额外中间件
- 支持安装包一键部署
- 提供健康检查和自检脚本
- **容器化部署**
- Docker 镜像打包
- Docker Compose 一键启动
- 支持镜像仓库
- 可选使用 PostgreSQL/MySQL
- **集群部署**
- 支持多实例部署
- 支持负载均衡
- 支持水平扩展
- 需要外部数据库PostgreSQL/MySQL和 Redis
- **安装包部署**
- 提供 Linux/Windows/macOS 安装包
- 一键安装脚本
- 自动依赖检查
- 内嵌数据库SQLite
- **独立数据库**
- 支持独立部署数据库PostgreSQL/MySQL
- 数据库连接配置
- 读写分离支持
- **运维自动化**
- 自动健康检查
- 自动日志轮转
- 自动备份脚本
- 自动服务重启(故障恢复)
### 技术约束
- **后端语言**
- Java 17+ 或
- Go 1.21+ 或
- Rust
- **数据库**
- MySQL 8.0+ 或
- PostgreSQL 14+ 或
- MongoDB 6.0+
- **缓存**
- Redis 7.0+
- **第三方依赖**
- 极小依赖
- 核心依赖:< 10 个
- 优先使用标准库
### 安全要求
- **数据传输加密**
- 强制使用 HTTPS
- TLS 1.2+
- 证书自动续期
- **敏感数据加密**
- 密码加密存储
- 手机号脱敏
- 身份证号加密
- **安全审计**
- 定期安全审计
- 漏洞扫描
- 渗透测试
- **合规性要求**
- 符合 GDPR
- 符合个人信息保护法
- 符合网络安全法
---
## 后续迭代功能
### 规则引擎(权限管理增强)
#### 功能描述
规则引擎是对基础 RBAC 权限模型的增强,支持更灵活的权限控制规则。
#### 核心特性
- **可视化规则配置界面**
- 拖拽式规则编辑器
- 规则测试功能
- 规则版本管理
- **复杂权限规则定义**
- 条件表达式AND、OR、NOT
- 时间限制(工作日/周末、时间段)
- 地域限制IP、城市、国家
- 数据范围限制(部门、项目)
- **动态权限规则**
- 运行时规则加载
- 规则热更新
- 规则优先级配置
- **权限模板**
- 预定义权限模板
- 模板复制与继承
- 模板应用范围
- **权限版本管理**
- 规则版本控制
- 版本回滚
- 版本对比
#### 应用场景
- **数据权限**
- 只能查看自己创建的数据
- 只能查看本部门的数据
- 只能查看特定时间段的数据
- **时间权限**
- 只能在工作时间访问
- 临时权限(限时生效)
- 周期性权限(每天/每周)
- **地域权限**
- 只能在公司内网访问
- 只能在特定城市访问
- VPN 访问权限
### 高级功能
#### 账号合并
- 支持将多个账号合并为一个账号
- 合并历史数据
- 保留主要账号信息
#### 用户画像
- 用户行为分析
- 用户标签管理
- 用户分群
#### 风控引擎
- 实时风险评估
- 异常行为识别
- 自动拦截与人工审核
#### 生物识别登录
- 指纹登录
- 人脸识别登录
- 声纹识别登录
#### 区块链身份认证
- 去中心化身份DID
- 数字身份证书
- 身份验证上链
---
## 附录
### 术语表
| 术语 | 英文 | 说明 |
|------|------|------|
| JWT | JSON Web Token | 一种开放标准RFC 7519用于在各方之间安全地传输信息 |
| OAuth 2.0 | Open Authorization 2.0 | 授权框架,允许第三方应用获取用户资源访问权限 |
| RBAC | Role-Based Access Control | 基于角色的访问控制 |
| SSO | Single Sign-On | 单点登录 |
| TOTP | Time-based One-Time Password | 基于时间的一次性密码 |
| 2FA | Two-Factor Authentication | 双因素认证 |
| API | Application Programming Interface | 应用程序接口 |
| SDK | Software Development Kit | 软件开发工具包 |
| GDPR | General Data Protection Regulation | 通用数据保护条例 |
### 参考文档
- OAuth 2.0 规范https://oauth.net/2/
- JWT 规范https://jwt.io/
- OpenID Connecthttps://openid.net/connect/
- GDPR 合规https://gdpr-info.eu/
- 个人信息保护法http://www.npc.gov.cn/npc/c30834/202108/a8c4e3672c74491a80b53a172bb753fe.shtml
---
*本文档持续更新中,如有疑问请联系产品团队。*