loan-pricing/doc/2026-04-16-TongWeb自启动适配后端设计文档.md

TongWeb 自启动适配后端设计文档

1. 背景

当前项目为 RuoYi-Vue 前后端分离架构，后端启动入口位于 ruoyi-admin 模块，现状采用 Spring Boot 自启动方式运行。根据 doc/tongweb.docx 的要求，本次需要将后端运行容器从默认 Tomcat 调整为 TongWeb，并接入 TongWeb license 文件。

本次改造范围已经确认如下：

• 只改后端，不涉及前端。
• 保持 Spring Boot 自启动模式，不改为外部 TongWeb 容器部署。
• 资源目录中直接使用 Tongweb_license.dat 文件名，不改名。
• TongWeb Starter 依赖坐标为 com.tongweb.springboot:tongweb-spring-boot-starter-2.x:7.0.E.7。

2. 目标

本次改造需要达成以下结果：

• 后端仍可通过 java -jar 方式启动。
• 运行时内嵌 Web 容器由默认 Tomcat 切换为 TongWeb。
• TongWeb license 文件随应用构建产物一起打包并可通过 classpath 访问。
• 新增 TongWeb license 配置后，现有业务模块与接口链路保持不变。

3. 设计原则

• 采用最短路径实现，只修改 TongWeb 适配所必需的内容。
• 改动集中在 ruoyi-admin 模块，避免无关模块受到影响。
• 不增加兼容性开关、双容器切换方案或补丁式旁路逻辑。
• 先完成容器替换与 license 接入，再通过启动验证确认链路闭环。

4. 方案对比

方案 A：仅在 ruoyi-admin 替换为 TongWeb 自启动

做法：

• 在 ruoyi-admin/pom.xml 中排除 Spring Boot 默认 Tomcat。
• 引入 TongWeb Starter 依赖。
• 将 Tongweb_license.dat 放入 ruoyi-admin/src/main/resources。
• 在环境配置中新增 server.tongweb.license.path。

优点：

• 改动范围最小，完全贴合当前需求。
• 不改变现有 main 方法启动链路。
• 对业务模块零侵入。

缺点：

• 需要验证现有 server.tomcat.* 配置在 TongWeb 下是否存在无效项。

方案 B：在父 pom 统一管理 TongWeb 版本，再由 ruoyi-admin 接入

做法：

• 在根 pom.xml 中增加 TongWeb 版本管理。
• 在 ruoyi-admin 声明依赖与资源处理。

优点：

• 依赖管理更集中。

缺点：

• 当前只有 ruoyi-admin 使用 TongWeb，额外抽象收益较低。
• 相比本次需求略显偏重。

方案 C：同时保留 Tomcat 与 TongWeb 切换能力

做法：

• 通过 Maven Profile 或可选依赖实现容器切换。

优点：

• 运行方式更灵活。

缺点：

• 明显超出当前需求。
• 会增加打包、启动、部署链路复杂度。

结论

采用方案 A。该方案满足当前需求且实现路径最短，符合本次改造边界。

5. 详细设计

5.1 模块范围

仅修改 ruoyi-admin 模块，保留现有业务模块、启动入口和打包主流程。

5.2 依赖调整

在 ruoyi-admin/pom.xml 中执行以下改造：

• 引入 com.tongweb.springboot:tongweb-spring-boot-starter-2.x:7.0.E.7。
• 排除 Spring Boot 默认内嵌 Tomcat 依赖，避免运行时容器冲突。
• 补充资源打包配置，确保 .dat 许可证文件进入构建产物。

依赖管理不下沉到父 pom，保持改造聚焦在当前实际使用模块。

5.3 资源文件接入

将仓库中的 doc/Tongweb_license.dat 复制到：

• ruoyi-admin/src/main/resources/Tongweb_license.dat

资源文件名保持为 Tongweb_license.dat，与用户确认结果一致，不额外重命名为 license.dat。

5.4 配置设计

由于项目当前按环境拆分配置文件，因此在以下文件中统一补充 TongWeb license 配置：

• ruoyi-admin/src/main/resources/application-dev.yml
• ruoyi-admin/src/main/resources/application-uat.yml
• ruoyi-admin/src/main/resources/application-pro.yml

新增配置位于 server 节点下，形式为：

server:
  tongweb:
    license:
      path: classpath:Tongweb_license.dat

这样可以确保 dev、uat、pro 三套环境在 TongWeb 自启动时行为一致。

5.5 Tomcat 配置处理策略

当前环境配置中存在 server.tomcat.* 参数。针对这些参数，本次采用以下策略：

• 不主动做大规模迁移或参数重写。
• 若 TongWeb Starter 启动时仅忽略这些配置，则保持不动。
• 若个别参数导致启动失败，再针对报错项做最小必要调整。

该策略的目的，是避免在本次需求中扩展出容器参数全面改造。

6. 数据流与运行链路

改造后的启动链路如下：

1. 应用仍从 RuoYiApplication.main 进入。
2. Spring Boot 自动装配 TongWeb Starter。
3. TongWeb 从 classpath 读取 Tongweb_license.dat。
4. 应用在 TongWeb 内嵌容器中完成启动。
5. 现有业务接口继续由 Spring MVC 与现有业务模块处理。

本次不改变业务接口、数据库访问、鉴权、缓存和前端交互逻辑。

7. 错误处理与风险边界

本次重点关注以下风险：

• TongWeb 依赖无法从当前 Maven 仓库解析。
• Tongweb_license.dat 未被正确打包进产物。
• server.tongweb.license.path 与实际资源名不一致导致 license 加载失败。
• 现有 server.tomcat.* 中存在与 TongWeb 冲突的配置项。

对应处理原则如下：

• 先保证依赖可解析、资源可入包、配置可读取。
• 仅在出现明确启动错误时处理 TongWeb 与 Tomcat 参数冲突。
• 不扩展到业务逻辑调整、容器双模切换或外部部署方案。

8. 验证方案

验证范围限定为 TongWeb 适配闭环，不扩展无关测试：

1. 执行 Maven 构建，确认依赖解析正常、项目可打包。
2. 检查 ruoyi-admin 最终构建产物，确认包含 Tongweb_license.dat。
3. 按现有 Spring Boot 自启动方式启动应用。
4. 确认应用能完成启动，且未因 TongWeb license 配置报错中断。

若启动时报出 TongWeb 对 server.tomcat.* 配置不兼容，再做针对性修正并重新验证。

9. 非目标

以下内容不在本次改造范围内：

• 前端页面或前端构建链路调整。
• 外部 TongWeb 服务器 WAR 部署方案。
• Tomcat 与 TongWeb 双容器切换能力。
• 容器参数体系重构。
• 业务接口、数据库结构、权限逻辑变更。

10. 文档产出

本次仅涉及后端，因此实施阶段只需要补充一份后端实施记录，保存在 doc/ 目录下。

11. 审阅说明

根据仓库协作约束，本次不启用 subagent。设计文档将采用手工自检方式完成审阅，待用户确认后再进入实施计划阶段。