230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# 项目升级与优化方案（UPDATE）
|
||
|
||
> **版本**: v1.1.0 (2025-01-XX)
|
||
>
|
||
> **更新日志**:
|
||
> - v1.1.0: 新增商城模块完善章节，记录商城系统模块拆分与功能实现进展
|
||
> - v1.0.0: 初始版本，聚焦认证安全与系统优化
|
||
|
||
---
|
||
|
||
## 目标与范围
|
||
- **目标**: 在不改变主业务的前提下，增强认证安全、可扩展性、性能稳定性与可观测能力，同时提升开发者体验与交付效率
|
||
- **范围**: Sys 后台端、App 用户端、MP 公众号、公共组件（认证策略、会话、缓存、日志、CI/CD、文档与测试）、商城系统模块拆分与完善
|
||
|
||
---
|
||
|
||
## 总体原则
|
||
- **最小入侵、增量演进**: 不推倒重来，尽量通过服务层与拦截器/过滤器扩展
|
||
- **枚举化与集中化**: 统一策略路由、Key 规范、限流与加密开关
|
||
- **可观测先行**: 指标、告警、健康检查与日志字段统一，便于稳定运营
|
||
- **先方案后实现**: 每个子项包含明确的改动点、验证方法与风险控制
|
||
|
||
---
|
||
|
||
## 认证与安全（高优先）
|
||
|
||
### grantType 枚举化与策略映射
|
||
- **内容**: 用枚举或常量表统一 Sys/App 的 grantType 与策略映射，移除魔法字符串
|
||
- **改动点**: 策略注册与查找入口、客户端配置校验
|
||
- **验证**: 枚举覆盖所有现有策略，错误入参返回一致错误码
|
||
|
||
### 风险登录与强制改密
|
||
- **内容**: 登录成功后比对 IP 归属地变化（日志/邮件告警）；密码超期标记 Session，拦截除改密外所有接口
|
||
- **改动点**: 在登录服务增加策略执行方法；新增 WebMvc 拦截器
|
||
- **验证**: 模拟超期与非超期用户行为；确保拦截仅放行改密与登出
|
||
|
||
### 验证码策略（保持现状）
|
||
- **内容**: 当前阶段 App 密码策略不启用验证码，保持与现状一致；但保留验证码校验逻辑与开关，后续在前端加密与交互链路完善后可一键开启，与 Sys 保持一致
|
||
- **改动点**: 不改动 App 端验证码逻辑（保留关闭状态）；保留校验方法与配置开关（示例：app.auth.captcha.enabled=false）
|
||
- **验证**: 无功能改动；后续启用时按开关置为 true 并执行联调（验证码生成/校验、错误次数累加与锁定、生效范围与白名单）
|
||
- **准备项**: 前端加密到位、验证码生成与传输链路打通、联调用例与回归清单就绪
|
||
|
||
### 接口加密与防刷
|
||
- **内容**: App 端在前端加密准备就绪后启用 ApiEncrypt；登录/验证码/二维码轮询加限流
|
||
- **改动点**: 控制器方法注解与网关规则
|
||
- **验证**: 压测防刷路径、请求速率下服务稳定性
|
||
|
||
---
|
||
|
||
## App 信息补全（高优先）
|
||
- **内容**: 登录后资料未完善仅放行白名单接口（个人信息查询、绑定手机号），其他接口返回 403_INFO_INCOMPLETE
|
||
- **改动点**: 新增 App 过滤器 + 配置项白名单；登录成功后写入 Session 标记
|
||
- **验证**: 未完善资料用户访问白名单成功、非白名单拦截；完善后恢复正常
|
||
|
||
---
|
||
|
||
## 会话管理与事件（中优先）
|
||
- **内容**: 完善第 6 章会话 API（活跃列表、终止、心跳续期、SSE 事件）；令牌 TTL 与 Redis TTL 同步，避免“僵尸会话”
|
||
- **改动点**: App 会话服务持久化实现；统一 Key 前缀与 TTL
|
||
- **验证**: 多设备并发登录、心跳续期、终止事件推送的端到端验证
|
||
|
||
---
|
||
|
||
## 第三方授权与绑定（中优先）
|
||
- **内容**: justauth 登录与绑定流程的鲁棒化（source 与 state 校验、重复绑定幂等）；MP 二维码的 scene_str 规范（sys_user:{userId}）
|
||
- **改动点**: 社交授权回调控制器、绑定服务的重复校验；MP 配置与二维码接口
|
||
- **验证**: 常见平台的授权成功/失败、重复绑定、解绑与重新绑定
|
||
|
||
---
|
||
|
||
## 数据层与性能（中优先）
|
||
|
||
### MyBatis-Plus 警告修复
|
||
- **内容**: 为缺少 @TableId 的实体（如 AppUserRole）补注解，恢复 ById 系列方法可用
|
||
- **验证**: 编译无警告且 CRUD 正常
|
||
|
||
### 索引与热点查询优化
|
||
- **内容**: 用户、角色关联、社交绑定等常查表加必要索引；分页与条件查询走服务层统一封装
|
||
- **验证**: 压测主要查询场景，慢查与扫描下降
|
||
|
||
---
|
||
|
||
## 可观测与告警（中优先）
|
||
|
||
### 指标与健康检查
|
||
- **内容**: 暴露登录成功率、锁定次数、验证码命中率、会话活跃数；完善 actuator 健康检查
|
||
- **改动点**: Micrometer 指标埋点；Spring Boot Admin 端点配置
|
||
- **验证**: 仪表板查看与阈值告警验证
|
||
|
||
### 日志与链路追踪
|
||
- **内容**: 统一日志字段（traceId、userId、clientId、grantType）；社交授权与二维码流程关键点日志
|
||
- **验证**: 问题复盘路径明确、跨模块调用链可追踪
|
||
|
||
---
|
||
|
||
## 开发者体验与文档（中优先）
|
||
|
||
### 文档
|
||
- **内容**: 在登录综合指南中加入响应结构说明与“grantType→策略类→入口路径”对照表；升级与优化指南形成统一入口
|
||
- **验证**: 联调工程师可按文档快速定位与调用
|
||
|
||
### 测试
|
||
- **内容**: 策略单测覆盖验证码开关、停用用户、第三方失败分支；集成测试覆盖 /auth/login、/app/auth/login 的典型入参与响应
|
||
- **验证**: 持续集成跑通、关键路径不回归
|
||
|
||
---
|
||
|
||
## 交付与构建（低优先但必要）
|
||
|
||
### CI/CD 稳定性
|
||
- **内容**: 分模块并行构建与独立重试；对 clean 阶段的目标目录锁定增加占用检测；缓存 Maven 仓库
|
||
- **验证**: 全量构建时间缩短、偶发失败模块可重试成功
|
||
|
||
### 配置与密钥管理
|
||
- **内容**: 区分 dev/prod 配置；禁止密钥进入日志；构建衍生文件与敏感清单进入 .gitignore
|
||
- **验证**: 审计通过、漏洞扫描无高危项
|
||
|
||
---
|
||
|
||
## 风险与回滚
|
||
- **风险**:
|
||
- 拦截策略误拦截、授权流程改动影响兼容
|
||
- 商城模块拆分可能影响现有代码调用（已采用渐进式迁移策略，保留原有代码）
|
||
- **回滚**:
|
||
- 按模块独立开关与配置回退；拦截器与过滤器具备开关与白名单；社交绑定保留幂等校验
|
||
- 商城模块：保留原有代码在 `ruoyi-mall/src` 目录，新功能在新子模块开发，可平滑回退
|
||
|
||
---
|
||
|
||
## 阶段产出与验证
|
||
|
||
### 阶段 1（高优先）：grantType 枚举、风险登录与强制改密、App 信息补全过滤器、验证码一致化
|
||
- **验证**: 编译通过、用例跑通、预览可访问，关键接口行为与文档一致
|
||
|
||
### 阶段 2（中优先）：会话 API、第三方授权鲁棒化、数据层优化、指标与健康检查
|
||
- **验证**: 压测与监控数据达标、授权与绑定流程无异常
|
||
|
||
### 阶段 3（持续）：测试完善、CI/CD 优化、文档与示例更新
|
||
|
||
### 阶段 4（已完成）：商城系统模块拆分与核心功能实现 ✅
|
||
- **验证**: 各子模块功能完整、API接口可用、数据库表结构正确、文档完善
|
||
- **成果**:
|
||
- 5 个子模块基础结构完整
|
||
- 商品中心、交易中心、优惠券中心功能完整实现
|
||
- 营销中心活动管理和秒杀功能实现
|
||
- 完整的 API 接口和文档
|
||
|
||
---
|
||
|
||
## 商城系统模块拆分与完善（高优先，已完成核心功能）✅
|
||
|
||
### 模块结构重构
|
||
- **内容**: 按照领域驱动设计原则，将 `ruoyi-mall` 模块拆分为 5 个子模块，实现模块化架构
|
||
- **改动点**:
|
||
- 创建子模块目录结构（product、trade、coupon、promotion、statistics）
|
||
- 配置各子模块的 Maven 依赖关系
|
||
- 创建各子模块的 AutoConfiguration 类和 spring.factories
|
||
- 扩展数据库表结构，支持完整业务场景
|
||
- **验证**: 各子模块可独立编译、自动配置生效、数据库表结构完整
|
||
|
||
### 商品中心模块 (ruoyi-mall-product) ✅
|
||
- **已完成功能**:
|
||
- ✅ 商品(SPU)和SKU的完整CRUD操作
|
||
- ✅ 商品分类管理（三级分类树形结构）
|
||
- ✅ 品牌管理
|
||
- ✅ 商品上架/下架、浏览量和销量统计
|
||
- **数据库表**: `mall_product`, `mall_sku`, `mall_category`, `mall_brand`
|
||
- **API接口**: 管理端和移动端完整的商品、分类、品牌接口
|
||
|
||
### 交易中心模块 (ruoyi-mall-trade) ✅
|
||
- **已完成功能**:
|
||
- ✅ 购物车管理（添加、删除、数量修改、选中状态）
|
||
- ✅ 订单管理（创建、查询、取消、状态流转）
|
||
- ✅ 售后管理（退款、退货、换货申请及审核流程）
|
||
- ✅ 订单评价（评价提交、审核、回复）
|
||
- ✅ 订单支付集成（与支付中心集成）
|
||
- **数据库表**: `mall_cart`, `mall_order`, `mall_order_item`, `mall_after_sale`, `mall_order_evaluate`, `mall_order_coupon`
|
||
- **API接口**: 完整的订单、售后、评价管理接口
|
||
|
||
### 优惠券中心模块 (ruoyi-mall-coupon) ✅
|
||
- **已完成功能**:
|
||
- ✅ 优惠券管理（满减、折扣、现金券类型）
|
||
- ✅ 用户优惠券（领券、使用、退还）
|
||
- ✅ 优惠券过期处理（定时任务方法已实现）
|
||
- **数据库表**: `mall_coupon`, `mall_coupon_user`
|
||
- **API接口**: 完整的优惠券和用户优惠券管理接口
|
||
|
||
### 营销中心模块 (ruoyi-mall-promotion) ⚠️
|
||
- **已完成功能**:
|
||
- ✅ 营销活动管理（活动类型、规则配置、时间管理）
|
||
- ✅ 秒杀功能（秒杀活动创建、库存管理、状态管理）
|
||
- **部分实现**:
|
||
- ⚠️ 拼团功能（表结构已创建，业务逻辑待实现）
|
||
- ⚠️ 砍价功能（表结构已创建，业务逻辑待实现）
|
||
- **数据库表**: `mall_promotion`, `mall_seckill`, `mall_group_buy`, `mall_group_buy_order`, `mall_bargain`, `mall_bargain_record`, `mall_bargain_help`
|
||
|
||
### 统计中心模块 (ruoyi-mall-statistics) ⚠️
|
||
- **状态**: 框架已创建，基础结构完善
|
||
- **待实现**: 交易分析、会员分析、商品分析、营销分析等统计功能
|
||
|
||
### 文档完善 ✅
|
||
- ✅ 各子模块 README.md 文档完整
|
||
- ✅ 模块结构说明文档（MODULE_STRUCTURE.md）
|
||
- ✅ API接口详细说明
|
||
- ✅ 数据库表结构说明
|
||
|
||
---
|
||
|
||
## 行动清单（优先顺序）
|
||
|
||
### 已完成 ✅
|
||
- ✅ 商城模块结构拆分与基础功能实现
|
||
- ✅ 商品中心模块完整实现（商品、SKU、分类、品牌）
|
||
- ✅ 交易中心模块完整实现（订单、售后、评价）
|
||
- ✅ 优惠券中心模块完整实现
|
||
- ✅ 营销中心模块部分实现（活动管理、秒杀）
|
||
|
||
### 进行中 / 待完成
|
||
1. 实现风险登录检测与强制改密拦截（Sys）
|
||
2. 统一 App 信息补全过滤器与白名单
|
||
3. 修复 MyBatis-Plus 警告（补充缺失的 @TableId）
|
||
4. 统一 grantType 枚举化与策略映射表
|
||
5. App 启用验证码开关，与 Sys 行为一致
|
||
6. 完善会话指标与健康检查，接入告警
|
||
7. 补充集成测试与 Postman 集合，提高联调效率
|
||
8. CI 并行构建与清理增强，提升交付稳定性
|
||
9. 完善营销中心模块（拼团、砍价功能实现）
|
||
10. 实现统计中心模块数据分析功能
|
||
11. 商城模块代码迁移（将现有代码迁移到新子模块结构，可选）
|