Integrate TongWeb into backend

docs/plans/backend/2026-04-17-tongweb-integration-implementation.md

@@ -0,0 +1,79 @@
+# 2026-04-17 TongWeb 接入实施记录
+
+## 1. 改动目标
+
+- 按 TongWeb 接入指南将后端默认内嵌容器从 Tomcat 切换为 TongWeb
+- 保持当前 Spring Boot 3.5.8 工程结构不变，按 Jakarta 体系接入 TongWeb 3.x Starter
+- 将 TongWeb license 随 `ruoyi-admin` 产物一起打包，并补齐可回归测试
+
+## 2. 实施内容
+
+### 2.1 Maven 依赖与仓库配置
+
+涉及文件：
+
+- `pom.xml`
+- `ruoyi-admin/pom.xml`
+
+实施内容：
+
+- 在根 `pom.xml` 增加 `tongweb.version=7.0.E.7`
+- 在根 `pom.xml` 增加 TongWeb Maven 仓库 `https://mvn.elitescloud.com/nexus/repository/maven-releases/`
+- 在根 `pom.xml` 的 `dependencyManagement` 中声明 `com.tongweb.springboot:tongweb-spring-boot-starter-3.x`
+- 在 `ruoyi-admin/pom.xml` 中对 `ruoyi-framework` 传递进来的 `spring-boot-starter-tomcat` 做排除
+- 在 `ruoyi-admin/pom.xml` 中引入 `tongweb-spring-boot-starter-3.x`
+- 在 `ruoyi-admin/pom.xml` 中显式保留 `src/main/resources` 资源打包规则，确保 `.dat` 文件进入产物
+
+说明：
+
+- 指南中的 `tongweb-spring-boot-starter-2.x` 仅适用于 Spring Boot 2.x
+- 当前仓库为 Spring Boot 3.5.8，因此本次按 TongWeb 3.x Starter 接入，避免 Jakarta/Servlet 版本不兼容
+
+### 2.2 TongWeb 基础配置与 license 资源
+
+涉及文件：
+
+- `ruoyi-admin/src/main/resources/application.yml`
+- `ruoyi-admin/src/main/resources/Tongweb_license.dat`
+
+实施内容：
+
+- 在基础配置 `application.yml` 中新增 `server.tongweb.license.path=classpath:Tongweb_license.dat`
+- 将 TongWeb license 以 `Tongweb_license.dat` 固定名称放入 `ruoyi-admin/src/main/resources/`
+- 保留现有环境文件中的 `server.tomcat.*` 配置，先不做额外收缩，后续仅在 TongWeb 启动日志明确报冲突时再按最小范围调整
+
+### 2.3 回归测试补齐
+
+涉及文件：
+
+- `ruoyi-admin/src/test/java/com/ruoyi/config/TongWebIntegrationConfigurationTest.java`
+
+实施内容：
+
+- 新增 classpath 资源测试，校验 `Tongweb_license.dat` 能从测试类路径读取
+- 新增基础配置测试，校验 `application.yml` 中存在 `server.tongweb.license.path`
+- 测试目标是防止后续重构时误删 TongWeb 配置或 license 资源
+
+## 3. 验证项
+
+建议执行以下命令：
+
+```bash
+mvn -pl ruoyi-admin -am test -Dtest=TongWebIntegrationConfigurationTest,LogbackConfigurationTest
+mvn -pl ruoyi-admin -am package -DskipTests
+mvn -pl ruoyi-admin -am dependency:tree "-Dincludes=com.tongweb.springboot:*,com.tongweb:*,org.apache.tomcat.embed:*"
+jar tf ruoyi-admin/target/ruoyi-admin.jar | rg 'Tongweb_license.dat|tongweb'
+```
+
+验证重点：
+
+- TongWeb 依赖能够正常解析
+- `spring-boot-starter-tomcat` 不再作为 `ruoyi-admin` 主依赖链出现
+- `Tongweb_license.dat` 已进入打包产物
+- TongWeb 相关 jar 已进入 `BOOT-INF/lib/`
+
+## 4. 结论
+
+- 本次接入保持现有工程结构与启动入口不变，仅替换内嵌 Servlet 容器实现
+- 接入链路已经覆盖依赖、配置、资源与自动化校验四个层面
+- 后续若要做运行态验证，可继续基于本次改造执行 `spring-boot:run` 或打包后启动，并在验证完成后关闭测试进程