first commit

UPDATE.md

@@ -0,0 +1,229 @@
+# 项目升级与优化方案（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. 商城模块代码迁移（将现有代码迁移到新子模块结构，可选）