凌云用户中心 · 需求分析

提示

文档目标：描述凌云用户中心（User Center）的业务定位、范围、角色、功能与非功能需求，为后续设计、研发、测试与迭代提供统一依据

1. 项目概述

项目要素	内容
定位	企业级用户管理中台，覆盖账号生命周期（注册、登录、资料、安全、管理员运营）
使用场景	个人/团队学习前后端分离项目、作为小型 SaaS 的用户模块、与第三方系统解耦集成
技术架构	后端 Spring Boot 3.5.6 + MyBatis-Plus + MySQL 8；前端 React (Umi + Ant Design Pro 5/6) 与 Vue 3 (Vite + Ant Design Vue) 双实现；接口遵循 RESTful，配套 Knife4j 在线文档
运行模式	单体应用、HttpSession + Cookie 维护登录态，Nginx 负责反向代理静态资源、API 透传

1.1 目标

提供稳定、易扩展的用户账号基础能力，可直接集成到中小型业务中
以一致的 API、错误码与鉴权规范支撑多前端接入，降低前端改造成本
覆盖管理员常见运营动作（检索、分页、封禁、重置密码、头像审核等）
输出工程级示例：统一返回体、全局异常、限流、单元测试，提升团队编码规范

1.2 成功指标

账号体系满足 1 万量级用户的基本 CRUD 与分页性能需求
注册/登录/资料编辑等关键流程通过自动化或手工验收用例
React 与 Vue 两套前端均可无缝调用同一套接口规范
后端核心接口（登录、更新密码、头像上传）具备限流、审计日志等防护手段

2. 系统范围

2.1 范围内

账号注册、登录、退出、获取当前用户信息
个人信息维护：昵称、简介、联系方式、性别、星球编号
安全能力：密码修改（BCrypt）、头像上传（2MB、魔数校验）、管理员重置密码
管理端：新增用户、更新、逻辑删除、分页检索、封禁/解封、查看详情
统一返回体 BaseResponse、错误码 ResultCodeEnum、业务异常 BusinessException、全局异常处理
限流与权限：自定义注解 @RateLimit、@AuthCheck 控制接口访问频率与角色
API 文档：Springdoc + Knife4j；数据库脚本、部署说明、Nginx 与多环境配置

2.2 范围外

第三方 OAuth/扫码登录、短信/邮箱验证码
支付、积分、会员等级等业务
完整的 RBAC/ABAC、租户隔离、细粒度权限分配
分布式集群、微服务拆分与消息队列集成（可在未来版本评估）
数据可视化报表、埋点、BI 分析

2.3 核心交付物

后端 Spring Boot 服务及 Docker/部署脚本
React 与 Vue 前端应用及其构建配置
SQL 脚本（建库、建表、种子数据）
技术文档：需求分析（本文）、架构/数据库设计、API 文档、部署指南

3. 角色与利益相关者

角色	描述	关键权限
访客（Visitor）	未登录用户，访问公开页面及注册/登录功能	注册、登录、查看公开介绍
普通用户（User）	登录后可管理个人资料并消费业务功能	查看/修改个人资料、修改密码、上传头像、查看欢迎页
管理员（Admin）	平台运营者，维护所有用户数据	全量检索用户、分页、详情、创建、更新、逻辑删除、封禁/解封、重置密码、健康检查
系统运维	负责部署、监控、证书与日志	访问 Swagger/Knife4j、Nginx、日志、数据库

4. 核心业务流程与用例

4.1 全局流程梳理

访客浏览站点，通过注册创建账号（校验账号唯一、星球编号长度 ≤ 6、密码强度满足大/小写+数字+特殊字符）
登录成功后，将脱敏用户对象写入 HttpSession，键 userLoginState:，会话默认 24h 失效
用户可进入欢迎页、个人资料页，更新昵称/简介/联系信息、修改密码和上传头像
管理员通过后台查看所有用户，支持多条件检索、分页排序、逻辑删除、封禁与密码重置
所有接口统一使用 BaseResponse 包装，错误通过 ResultCodeEnum、BusinessException、GlobalExceptionHandler 抛出
@RateLimit 保护高风险接口（注册、登录、密码修改等），限制单位时间内的请求数（IP 或用户维度）
文件上传经过大小、MIME、扩展名及魔数校验，存储在 file.upload.uploadDir/avatar/{userId}，返回可公开访问的 URL

4.2 用例清单

UC-01 用户注册

触发者：访客
前置条件：访客未登录，满足浏览器/网络要求
主流程：
1. 填写账号（4-16 位、字母数字下划线）、星球编号（≤6 位）、密码与确认密码（8-20 位，满足复杂度）
2. 后端校验唯一性（账号、星球编号，is_delete=0 条件）、参数合法性
3. 密码使用 PasswordUtil (BCrypt) 加密后入库，默认头像/简介/角色为普通用户
4. 返回新用户 ID
失败路径：长度/格式/唯一性校验失败、限流触发（300s 内同 IP 最多 3 次）

UC-02 用户登录

触发者：访客
主流程：输入账号密码 → 校验格式 → 校验密码（BCrypt） → 检查 user_status 是否封禁 → Session 记录登录态 → 返回 UserLoginVO（无密码字段）
保护措施：IP 维度限流（60s 内最多 5 次），会话 24h 过期，可择机扩展“记住我”

UC-03 获取当前登录用户

触发者：已登录用户或前端初始化流程
主流程：校验 Session → 查询数据库最新数据（保证状态实时）→ 返回 UserLoginVO
失败路径：未登录返回 40100 NOT_LOGIN_ERROR

UC-04 用户注销

触发者：已登录用户
主流程：校验 Session → 清除 userLoginState: 属性 → 返回成功标识

UC-05 更新个人资料

触发者：已登录用户
主流程：
1. 用户提交可选字段（昵称、简介、性别、联系方式、星球编号等）
2. 后端校验 id 与当前登录用户一致，防止越权
3. 仅更新非空字段；保留旧值以防止覆盖
业务规则：星球编号仍需唯一；不可修改 userRole、userStatus 等敏感字段

UC-06 修改密码

触发者：已登录用户
主流程：输入原密码 + 新密码 + 确认密码 → 校验复杂度 → 校验原密码 → 写入新哈希
保护措施：用户维度限流（300s 内 ≤ 3 次）

UC-07 上传头像

触发者：已登录用户
校验：文件 ≤ 2MB、类型在 image/jpeg|png|jpg|gif 列表、扩展名与魔数匹配、图片可解析
存储：uploads/avatar/{userId}/timestamp_uuid.ext，URL = file.upload.accessPrefix/...
安全：用户维度限流（60s 内 ≤ 5 次），日志记录 IP、文件名、大小

UC-08 管理员用户管理

触发者：管理员
能力：
- 分页检索：按账号、昵称、角色、状态、性别、手机号、邮箱筛选，支持排序（见 AdminQueryUserRequest）
- 添加用户：创建时必须提供账号、密码、角色等，密码同样 BCypt 加密
- 查看/更新：支持更新除密码外的公开属性，限制字段白名单
- 逻辑删除：设置 is_delete=UNIX_TIMESTAMP()；默认查询过滤
- 封禁/解封：切换 user_status，被封禁用户无法登录
- 重置密码：生成安全密码并覆盖原值，触发日志
安全：所有接口需 @AuthCheck(mustRole = admin)，并附加用户维度限流（例如更新信息 60s/20 次）

UC-09 系统健康与 API 文档

触发者：运营/运维、自动化探针
内容：/health 返回服务状态；/swagger-ui.html、/doc.html（Knife4j）提供接口说明；sql/ 文件夹保证数据一致性

5. 功能需求矩阵

模块	功能	描述	关联接口示例
账号	注册	账号唯一、星球编号唯一、BCrypt 加密、限流	`POST /user/register`
账号	登录/注销/当前用户	Session 管理、脱敏返回、封禁校验	`POST /user/login`, `POST /user/logout`, `GET /user/loginUserInfo`
资料	查看/编辑	用户自身信息变更（昵称、简介、联系方式、星球编号）	`POST /user/updateUserInfo`
安全	修改密码	旧密码校验、复杂度校验、限流	`POST /user/updatePassword`
文件	头像上传	2MB 限制、MIME+魔数校验、唯一文件名、CDN 前缀	`POST /file/upload/avatar`
管理端	用户 CRUD	分页、条件过滤、详情、创建、更新、逻辑删除	`/user/adminGetUserInfoByPage`, `/user/addUser`, `/user/adminUpdateUserInfo`
管理端	安全动作	封禁/解封、重置密码	`/user/adminBanOrUnbanUser`, `/user/adminResetUserPassword`
系统	API 文档/健康检查	Knife4j 文档、健康探针	`/v3/api-docs`, `/health`

6. 数据与业务规则

核心表 user（详见 docs/src/design/database-design.md 与 sql/user-center-table.sql）：
- 唯一约束：(user_account, is_delete)、(planet_code, is_delete) 允许逻辑删除后重建账号
- 关键字段：user_role(ENUM user/admin)、user_status(0 正常/1 封禁)、is_delete(0/UNIX_TIMESTAMP)
- 索引：昵称、手机号、邮箱、创建时间、状态，保证后台分页性能
- 密码：长度 60 字符，存储 BCrypt 哈希
文件系统：默认 ./uploads/avatar/{userId}，最大 2MB，可通过 file.upload.* 配置项覆盖
会话键：userLoginState:（UserConstant.USER_LOGIN_STATE）作为 Session attribute，值为脱敏前用户对象
逻辑删除：通过 @TableLogic + MyBatis-Plus 全局配置，在查询中自动排除 is_delete != 0 的记录

7. 权限与安全要求

鉴权机制：HttpSession + @AuthCheck 注解；管理员角色常量 admin，其余默认为 user
密码策略：注册、修改密码与管理员重置均使用 PasswordUtil(BCrypt)；长度 8-20 位，需包含大小写+数字+特殊字符
限流：@RateLimit 支持 IP/用户维度，关键阈值示例：注册 300s/3 次（IP）、登录 60s/5 次（IP）、头像上传 60s/5 次（用户）、管理员更新 60s/20 次（用户）
数据脱敏：返回体 UserLoginVO 不含密码等敏感信息；导出/展示遵循最小化原则
异常与日志：GlobalExceptionHandler 统一捕获，结合 Slf4j 输出 warn/error 日志，记录关键操作（登录、上传、管理员动作）
文件安全：校验 MIME、扩展名、魔数与 ImageIO 可解析性，防止伪造脚本上传；目录基于用户 ID 隔离

8. 非功能需求

维度	需求
性能	Tomcat 线程池（max 200）与连接数（8192）支撑 1k QPS 峰值；分页接口默认 20 条/页，支持排序；限流保障热点接口稳定
可用性	Session 失效时间 86400s；健康检查 `/health` 供监控；日志滚动保留 2000 份、单文件 5MB
安全	HTTPS 由 Nginx 提供；统一错误码防止信息泄露；禁止外网直接访问后端（`server.address=127.0.0.1`，通过 Nginx 反代）
兼容性	前端通过 `config/proxy.ts`（React）与 Vite 代理（Vue）解决跨域；Node 18 需 `NODE_OPTIONS=--openssl-legacy-provider`
可维护性	统一代码风格（Spotless、Checkstyle）；常量集中管理（`UserConstant`/`ByteConstant`）；业务异常收敛在 `ThrowUtils`
可测试性	Spring Boot Test + Surefire 已覆盖注册、登录、注销、数据库连接等；前端提供 mock、cache 便于联调

9. 设计约束与依赖

语言/运行：Java 21、Spring Boot 3.5.6、MySQL 8.0+、Maven 构建
ORM：MyBatis-Plus（驼峰映射 + 逻辑删除 + 分页插件）
API 文档：Springdoc OpenAPI 3 + Knife4j（/doc.html）
前端：
- React 18 + Umi + Ant Design Pro（默认 V5，兼容 V6，需注意路由/请求差异）
- Vue 3 + Vite + Pinia + Ant Design Vue
构建工具：pnpm / npm、Husky 校验、ESLint/Prettier、Stylelint
部署：Nginx 配置位于 nginx/*.conf；上传目录需具备读写权限；生产环境需配置云存储/CDN 可选项

10. 优先级与迭代计划

阶段	内容	目标
MVP	注册、登录、注销、当前用户、管理员分页查询 + 逻辑删除、统一返回体、Swagger/Knife4j、数据库脚本	建立完整最小可用账号系统
Enhancement 1	个人资料编辑、头像上传、密码修改、管理员新增/更新/封禁/重置密码、限流/权限注解	覆盖主要安全与运营动作
Enhancement 2	前端体验（React/Vue 双实现）、自定义主题、脚手架优化、部署/监控脚本	提升易用性与部署体验
Backlog	国际化、第三方登录、短信/邮件通知、更多角色模型、分布式会话/缓存	视业务需要逐步落地

11. 验收标准

数据库中能看到新注册的账号，密码字段存储为 BCrypt 哈希，user_status=0，user_role=user
登录接口输入正确凭证返回 20000 + 脱敏数据；错误账号/密码返回 40000；封禁用户返回 40300
管理员接口需具备登录 + admin 角色方可访问，普通用户调用返回 40101分页接口默认过滤 is_delete != 0
头像上传满足大小/格式校验，生成可访问 URL，且原文件保存在 uploads/avatar/{userId} 目录中
删除用户为逻辑删除：数据库 is_delete 非 0，后续查询默认不可见，但账号/星球编号可重新注册
所有接口响应结构符合 BaseResponse{code, message, data, success}，错误由全局异常处理器拦截
React 与 Vue 前端均能完成注册→登录→资料编辑→退出的端到端流程

12. 已知风险与待办

Node 18 SSL 问题：需设置 NODE_OPTIONS=--openssl-legacy-provider 或使用 Node 16 LTS，后续可升级依赖彻底解决
跨域/同域 Cookie：本地调试需通过代理（config/proxy.ts、Vite proxy）保持 Cookie 可用；生产依赖 Nginx建议在部署说明中强调
文件存储：默认存在本地磁盘，生产建议接入对象存储或 CDN 并配置传输 HTTPS
高并发扩展：当前为单体 + Session，若未来需要横向扩展需引入共享会话（Redis）、JWT 或网关
安全增强：暂未接入验证码、2FA、登录/IP 白名单；可在安全评估后纳入迭代

凌云用户中心 · 需求分析 ​

1. 项目概述 ​

1.1 目标 ​

1.2 成功指标 ​

2. 系统范围 ​

2.1 范围内 ​

2.2 范围外 ​

2.3 核心交付物 ​

3. 角色与利益相关者 ​

4. 核心业务流程与用例 ​

4.1 全局流程梳理 ​

4.2 用例清单 ​

UC-01 用户注册 ​

UC-02 用户登录 ​

UC-03 获取当前登录用户 ​

UC-04 用户注销 ​

UC-05 更新个人资料 ​

UC-06 修改密码 ​

UC-07 上传头像 ​

UC-08 管理员用户管理 ​

UC-09 系统健康与 API 文档 ​

5. 功能需求矩阵 ​

6. 数据与业务规则 ​

7. 权限与安全要求 ​

8. 非功能需求 ​

9. 设计约束与依赖 ​

10. 优先级与迭代计划 ​

11. 验收标准 ​

12. 已知风险与待办 ​

凌云用户中心 · 需求分析

1. 项目概述

1.1 目标

1.2 成功指标

2. 系统范围

2.1 范围内

2.2 范围外

2.3 核心交付物

3. 角色与利益相关者

4. 核心业务流程与用例

4.1 全局流程梳理

4.2 用例清单

UC-01 用户注册

UC-02 用户登录

UC-03 获取当前登录用户

UC-04 用户注销

UC-05 更新个人资料

UC-06 修改密码

UC-07 上传头像

UC-08 管理员用户管理

UC-09 系统健康与 API 文档

5. 功能需求矩阵

6. 数据与业务规则

7. 权限与安全要求

8. 非功能需求

9. 设计约束与依赖

10. 优先级与迭代计划

11. 验收标准

12. 已知风险与待办