东方通

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

@@ -0,0 +1,193 @@
+# 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` 节点下，形式为：
+
+```yml
+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。设计文档将采用手工自检方式完成审阅，待用户确认后再进入实施计划阶段。