新增全量迁移892-without-redis设计文档

doc/2026-04-15-全量迁移892-without-redis分支功能设计文档.md

@@ -0,0 +1,403 @@
+# 全量迁移 `892-without-redis` 分支功能设计文档
+
+## 1. 背景
+
+当前分支为 `892-jdk-8-without-redis`，已经完成 JDK8 适配与 Redis 移除改造。目标分支 `origin/892-without-redis` 包含贷款定价业务、登录安全、部署脚本、生产初始化 SQL、文档与实施记录等多类改动。
+
+本次需求已确认如下：
+
+- 迁移范围为目标分支中的全部功能，不只限于贷款定价主链
+- 迁移目标以“功能行为完全对齐目标分支”为准
+- 不要求提交历史一致，也不要求逐文件原样搬运
+- 当前分支已完成的 JDK8 与去 Redis 基线必须保留，不能被回退
+
+由于两个分支不存在共同 `merge base`，不能按常规增量合并处理。本次应采用“以当前分支为基线，按功能行为对齐迁移”的方式落地。
+
+## 2. 已确认约束
+
+- 当前分支保留：
+  - JDK8 运行基线
+  - 去 Redis 后的内存缓存实现
+- 目标分支中的所有业务能力、脚本能力、初始化能力都要迁入当前分支
+- 迁移完成的判断标准是“当前分支行为与目标分支一致”，不是“文件内容完全一致”
+- 不采用补丁式兜底方案，不引入额外兼容分支
+- 所有本次改动需要在 `doc/` 目录留下文档记录
+- 前后端同时涉及改动时，后续必须分别输出前端实施计划和后端实施计划
+
+## 3. 现状分析
+
+### 3.1 分支关系现状
+
+当前仓库中：
+
+- 本地分支：`892-jdk-8-without-redis`
+- 远端参考分支：`origin/892-without-redis`
+
+两者没有共同合并基线，说明不能通过简单 `merge`、`cherry-pick` 或三点 diff 来安全迁移全部功能。
+
+### 3.2 目标分支改动构成
+
+经核对，目标分支包含以下几类内容：
+
+1. 贷款定价主业务
+- 流程列表的测算利率、执行利率、更新时间
+- 流程详情字段补齐与详情卡片顺序调整
+- 个人最终测算利率展示
+- 个人测算入参对齐
+- 敏感信息存储加密、接口脱敏、模型调用前解密
+
+2. 登录与账号相关
+- 登录页默认账号密码移除
+- 登录密码传输相关前后端改造
+
+3. 运行与部署相关
+- 后端重启脚本
+- 生产一键部署脚本
+- 压缩包目录结构与进程识别规则调整
+- 多环境配置文件补充
+
+4. 数据初始化与数据库脚本
+- 贷款定价相关表结构脚本
+- 菜单初始化脚本
+- 生产初始化数据库脚本
+
+5. 文档与测试资产
+- 业务设计文档、实施计划、实施记录
+- `test_api` 示例
+- 前端静态测试脚本
+
+### 3.3 当前分支迁移风险
+
+如果直接套用目标分支文件，会出现以下风险：
+
+- 覆盖当前分支已经完成的去 Redis 实现
+- 引入不适配 JDK8 的实现方式
+- 将目标分支中与当前分支冲突的配置整文件覆盖
+- 把脚本和 SQL 迁进来但没有同步前后端行为，导致联调失败
+
+因此，本次需要以“保留当前底座、按业务行为重建目标功能”的方式推进。
+
+## 4. 方案对比
+
+### 方案一：按业务域做行为对齐迁移
+
+做法：
+
+- 以当前分支为基线
+- 按功能域拆分迁移目标分支能力
+- 对于冲突文件采用手工整合
+- 最终以页面表现、接口行为、脚本效果与目标分支一致为准
+
+优点：
+
+- 最适合当前两条独立历史的情况
+- 可以稳定保住当前分支 JDK8 与去 Redis 基线
+- 更容易分块验证与回归
+
+缺点：
+
+- 需要逐模块核对行为
+- 人工整合成本高于直接覆盖
+
+### 方案二：大面积覆盖目标分支文件后回补当前基线
+
+做法：
+
+- 尽量把目标分支文件整体覆盖到当前分支
+- 再回头修复 JDK8 和去 Redis 冲突
+
+优点：
+
+- 前期拷贝速度快
+
+缺点：
+
+- 极易冲掉当前分支已经验证过的基础改造
+- 后置修复成本高
+- 很难确认哪些回归来自覆盖行为
+
+### 方案三：按提交批量迁移
+
+做法：
+
+- 尝试对目标分支提交做 `cherry-pick` 或补丁迁移
+
+优点：
+
+- 理论上来源更清晰
+
+缺点：
+
+- 两个分支无共同基线，冲突会非常多
+- 目标分支提交混杂，难以按提交边界安全迁移
+
+## 5. 设计结论
+
+采用方案一：按业务域做行为对齐迁移。
+
+核心原则如下：
+
+- 保留当前分支的 JDK8 与去 Redis 基线
+- 迁移目标分支中的全部功能，但不强求原样搬代码
+- 所有冲突位置以“行为一致 + 当前底座不回退”为判定标准
+- 迁移顺序固定为“基线对齐 -> 后端能力 -> 前端行为 -> 验证收口”
+
+## 6. 迁移边界设计
+
+本次将目标分支改动拆分为 5 个迁移包：
+
+### 6.1 贷款定价主业务包
+
+包含：
+
+- 流程列表字段与刷新行为
+- 详情展示与卡片顺序调整
+- 个人与企业建单链路
+- 个人测算入参对齐
+- 最终测算利率展示
+- 敏感信息加密、脱敏、模型调用链路
+- 相关 SQL 脚本与测试文件
+
+### 6.2 登录与账号包
+
+包含：
+
+- 登录页默认账号密码移除
+- 登录密码传输相关前后端链路
+- 控制器、API、工具函数与测试
+
+### 6.3 部署与运行包
+
+包含：
+
+- 重启脚本
+- 生产一键部署脚本
+- 环境安装脚本
+- 目录结构与 jar 进程识别规则
+- 多环境配置文件
+
+### 6.4 初始化与交付包
+
+包含：
+
+- 生产初始化数据库脚本
+- 菜单脚本
+- 表结构变更脚本
+- `deploy/` 目录与交付物配置
+
+### 6.5 文档与验证包
+
+包含：
+
+- 本次迁移设计文档
+- 前端实施计划
+- 后端实施计划
+- 本次迁移实施记录
+- 必要测试说明
+
+## 7. 迁移顺序设计
+
+### 7.1 第一阶段：基线对齐
+
+目标：
+
+- 锁定当前分支可保留的 JDK8 与去 Redis 底座
+- 识别目标分支需要补入的依赖、配置、脚本、SQL 基础设施
+
+输出：
+
+- 迁移差异清单
+- 需整合的配置与脚本列表
+
+### 7.2 第二阶段：后端能力迁移
+
+目标：
+
+- 先完成贷款定价、登录安全、脚本能力、初始化 SQL 的后端与脚本迁移
+
+原因：
+
+- 前端页面行为依赖后端接口契约
+- 先稳定接口、字段和脚本能力，后续前端才能一次性对齐
+
+### 7.3 第三阶段：前端行为迁移
+
+目标：
+
+- 完成 `ruoyi-ui` 页面、API、工具函数、页面测试脚本迁移
+
+重点页面：
+
+- 贷款定价流程列表
+- 流程详情
+- 个人/企业建单弹窗
+- 登录页
+- 缓存监控页
+
+### 7.4 第四阶段：验证与收口
+
+目标：
+
+- 对迁移后的当前分支做构建、测试与关键链路核验
+- 输出实施文档并确认最终行为一致
+
+## 8. 冲突处理设计
+
+### 8.1 Redis 冲突处理
+
+凡是目标分支使用 Redis 的旧实现，统一保留当前分支的内存缓存能力，只迁移与业务行为相关的部分，不回退技术实现。
+
+### 8.2 JDK8 冲突处理
+
+凡是目标分支中使用高版本 JDK 写法的地方，统一改为当前分支可运行的 JDK8 写法，保持行为一致即可。
+
+### 8.3 同文件多来源冲突处理
+
+如果同一文件同时存在：
+
+- 当前分支的去 Redis/JDK8 适配
+- 目标分支的新业务功能
+
+则采用手工整合，不做整文件覆盖。
+
+### 8.4 脚本与环境冲突处理
+
+部署脚本与环境配置以目标分支行为为目标，但需要重新核对：
+
+- 端口
+- 目录
+- 进程识别规则
+- 当前仓库的启动方式
+
+### 8.5 文档路径处理
+
+目标分支中存在 `docs/superpowers/...` 路径文档，但当前仓库规范要求将本次文档统一落到 `doc/`。因此文档只迁移内容，不沿用目标分支文档目录结构。
+
+## 9. 详细迁移清单
+
+### 9.1 贷款定价主业务
+
+- 列表：
+  - 测算利率
+  - 执行利率
+  - 更新时间
+  - 返回列表自动刷新
+- 详情：
+  - 个人详情字段补齐
+  - 详情卡片顺序调整
+  - 最终测算利率展示
+- 建单：
+  - 个人测算入参对齐
+  - 创建请求字段与模型调用字段统一
+- 安全：
+  - `custName`
+  - `idNum`
+  - 存储加密、查询脱敏、模型调用前解密
+- 数据：
+  - 流程表、输出表字段脚本
+  - 菜单脚本
+  - 测试 API 文件
+
+### 9.2 登录与账号相关
+
+- 登录页默认账号密码移除
+- 密码传输工具函数
+- 登录、注册、个人中心、用户管理相关前后端接口对齐
+- 对应测试补齐
+
+### 9.3 运行与部署相关
+
+- `bin/restart_java_backend.sh`
+- `bin/prod/*`
+- `deploy/*`
+- 环境配置文件
+- 目录结构与压缩包处理
+- 启停测试脚本
+
+### 9.4 初始化与交付物
+
+- 初始化数据库脚本
+- 贷款定价菜单脚本
+- 生产交付压缩包相关目录
+- 其他目标分支新增 SQL
+
+## 10. 验收口径
+
+迁移完成需同时满足以下条件：
+
+### 10.1 后端
+
+- 受影响模块测试可通过
+- 新增关键测试覆盖关键行为
+- 当前分支能正常启动后端服务
+
+### 10.2 前端
+
+- `ruoyi-ui` 在 `nvm use` 后可安装依赖
+- `npm run build:prod` 成功
+- 登录、流程列表、详情、建单、缓存监控等关键页面可正常访问
+
+### 10.3 业务行为
+
+- 贷款定价链路行为与目标分支一致
+- 登录行为与目标分支一致
+- 部署脚本的执行逻辑与目标分支一致
+- 目标分支新增 SQL 在当前分支具备等价能力
+
+### 10.4 文档
+
+- 在 `doc/` 目录补齐本次：
+  - 设计文档
+  - 后端实施计划
+  - 前端实施计划
+  - 实施记录
+
+## 11. 测试与验证设计
+
+### 11.1 后端验证
+
+- 单元或控制器测试：
+  - 列表字段返回
+  - 详情脱敏
+  - 登录密码传输
+  - 缓存监控接口
+- 配置与脚本核对：
+  - 多环境配置
+  - 端口
+  - 路径
+  - 进程识别规则
+- 启动验证：
+  - 至少确认迁移后可正常启动
+
+### 11.2 前端验证
+
+- 静态构建验证：
+  - `nvm use`
+  - `npm install`
+  - `npm run build:prod`
+- 页面链路验证：
+  - 登录
+  - 流程列表
+  - 流程详情
+  - 个人建单
+  - 缓存监控页
+
+### 11.3 进程清理要求
+
+若验证过程中启动前后端进程，验证结束后统一关闭，不保留测试进程。
+
+## 12. 非目标
+
+- 不追求与目标分支逐文件完全一致
+- 不迁移目标分支 git 历史
+- 不为了复刻目标分支而回退当前 JDK8 或去 Redis 基线
+- 不新增需求之外的兼容或降级逻辑
+
+## 13. 后续实施方式
+
+设计确认后，后续实施将拆分为两份计划：
+
+- 后端实施计划
+- 前端实施计划
+
+实施时采用“分包迁移 + 每包自验证”的方式推进，逐块完成并验证，不做一次性大批量落地后再集中排错。