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

全量迁移 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. 后续实施方式

设计确认后，后续实施将拆分为两份计划：

• 后端实施计划
• 前端实施计划

实施时采用“分包迁移 + 每包自验证”的方式推进，逐块完成并验证，不做一次性大批量落地后再集中排错。