docs: project docs, scripts, deployment configs, and evidence

docs/PRD.md

@@ -0,0 +1,743 @@
+# 用户管理系统产品需求文档 (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 Connect：https://openid.net/connect/
+- GDPR 合规：https://gdpr-info.eu/
+- 个人信息保护法：http://www.npc.gov.cn/npc/c30834/202108/a8c4e3672c74491a80b53a172bb753fe.shtml
+
+---
+
+*本文档持续更新中，如有疑问请联系产品团队。*