迁移项目到 RuoYi-Vue springboot2 基线

doc/2026-04-14-ruoyi-vue-springboot2-migration-design.md

@@ -0,0 +1,120 @@
+# RuoYi-Vue springboot2 基线迁移设计
+
+## 1. 目标
+
+本次迁移以上游 `https://gitee.com/y_project/RuoYi-Vue/tree/springboot2` 为唯一框架基线，先将当前仓库整体回退并重对齐到该基线，再迁回现有业务模块与业务页面，最终形成一个“框架层跟随上游、业务层保留现状”的项目结构。
+
+本次迁移不采用兼容层、补丁层或双栈并存方案，不保留 Spring Boot 3 / Java 17 的框架实现。
+
+## 2. 现状与目标差异
+
+当前仓库已经是 RuoYi 多模块工程，但后端已升级到 `Spring Boot 3.5.x`、`Java 17`，并引入了以下业务定制：
+
+- 后端业务模块：`ruoyi-loan-pricing`
+- 前端业务页面：`ruoyi-ui/src/views/loanPricing`
+- 前端业务接口：`ruoyi-ui/src/api/loanPricing`
+- 管理端业务接入：`ruoyi-admin` 中的业务依赖与配置
+- 业务 SQL：`sql/loan_pricing_*`、`sql/model_*`、`sql/loan_pricing_menu.sql`
+
+目标上游 `springboot2` 分支采用：
+
+- `RuoYi-Vue 3.9.2`
+- `Spring Boot 2.5.15`
+- `Java 8`
+- `Vue 2 + Element UI`
+
+因此本次迁移的本质是：先将框架层彻底切回 Spring Boot 2 基线，再把利率定价业务重新挂载到新的基线上。
+
+## 3. 迁移范围
+
+### 3.1 框架层
+
+以下内容以上游 `springboot2` 版本为准：
+
+- 根目录框架文件与脚本
+- 根 `pom.xml`
+- `ruoyi-admin`
+- `ruoyi-common`
+- `ruoyi-framework`
+- `ruoyi-generator`
+- `ruoyi-quartz`
+- `ruoyi-system`
+- `ruoyi-ui`
+- 上游自带 `sql` 基础脚本
+
+### 3.2 业务层
+
+以下内容需要从当前仓库迁回到新基线：
+
+- `ruoyi-loan-pricing` 全模块
+- `ruoyi-admin` 中与 `loan-pricing` 相关的业务配置、业务依赖
+- `ruoyi-ui/src/views/loanPricing` 页面
+- `ruoyi-ui/src/api/loanPricing` 接口文件
+- `ruoyi-ui/src/router/index.js` 中的业务路由
+- 业务 SQL、部署脚本、项目文档
+
+## 4. 实施策略
+
+### 4.1 基线覆盖策略
+
+采用“上游覆盖 + 业务回贴”模式：
+
+1. 先备份当前业务目录与业务配置
+2. 将上游 `springboot2` 内容覆盖到当前仓库
+3. 恢复业务模块、业务页面、业务配置和业务 SQL
+4. 处理 Spring Boot 2 下的编译和运行差异
+
+### 4.2 后端回贴策略
+
+后端只保留一套 Spring Boot 2 实现，不额外保留 Spring Boot 3 兼容写法。若 `ruoyi-loan-pricing` 内存在 Boot 3 / Jakarta / SpringDoc 相关依赖或 API，则直接改回 Boot 2 可运行写法。
+
+### 4.3 前端回贴策略
+
+前端以 `springboot2` 上游 `ruoyi-ui` 为基础，回贴 `loanPricing` 页面、接口调用、路由和必要依赖；不保留与当前业务无关的历史定制。
+
+## 5. 风险点与处理原则
+
+### 5.1 框架依赖回退风险
+
+风险：
+
+- `springdoc`、`jakarta.*`、Boot 3 专用依赖不兼容 Boot 2
+- 测试依赖、插件版本、JDK 版本需要一并回退
+
+处理原则：
+
+- 以 Boot 2 上游依赖为准
+- 业务模块仅保留完成业务所必需的依赖
+
+### 5.2 业务接入点遗漏风险
+
+风险：
+
+- `ruoyi-admin` 配置遗漏
+- 前端路由、菜单、接口路径遗漏
+- SQL 脚本与权限菜单脚本遗漏
+
+处理原则：
+
+- 逐类枚举迁移对象
+- 迁移后通过编译、页面访问、接口调用进行闭环验证
+
+## 6. 验证标准
+
+迁移完成后至少满足以下条件：
+
+- Maven 多模块在 Spring Boot 2 / Java 8 环境下可编译
+- `ruoyi-admin` 可启动
+- `ruoyi-ui` 在指定 Node 版本下可安装并构建
+- `loanPricing` 页面路由可访问
+- 利率定价相关接口类与 Mapper 可通过编译
+- 业务 SQL 与菜单脚本仍保留在仓库内
+
+## 7. 产出物
+
+本次任务最终需产出：
+
+- 本设计文档
+- 后端实施计划文档
+- 前端实施计划文档
+- 迁移实施记录文档