迁移项目到 RuoYi-Vue springboot2 基线

doc/2026-04-13-local-tomcat-remote-tongweb-design.md

@@ -0,0 +1,147 @@
+# 本地 Tomcat 运行与 TongWeb 打包并存设计
+
+## 背景
+
+当前项目已经被调整为统一的 TongWeb `war` 交付模式，这会导致本地开发时也必须围绕 TongWeb 组织启动流程，不符合当前开发诉求。
+
+本次目标是同时保留两条链路：
+
+- 本地开发运行继续使用内嵌 Tomcat
+- 打包交付继续支持服务器上的 TongWeb
+
+并且要求一次 `mvn package` 同时产出本地运行所需的 `jar` 和服务器部署所需的 `war`。
+
+## 目标
+
+- 保留 `IDEA`、`mvn spring-boot:run`、本地脚本直启后端的开发体验
+- 保留面向 TongWeb 的 `war` 交付方式
+- `mvn package` 后同时得到 `ruoyi-admin.jar` 与 `ruoyi-admin.war`
+- 本地不强依赖安装 TongWeb
+- 服务器部署脚本继续只消费 `war`
+
+## 非目标
+
+- 不新增第二个后端启动模块
+- 不拆分额外的部署工程
+- 不修改前端构建方式
+- 不引入“兼容模式”“降级模式”之类额外分支逻辑
+
+## 设计方案
+
+### 1. 构建产物设计
+
+`ruoyi-admin` 恢复为以 `jar` 为主产物的 Spring Boot 应用，用于本地开发运行。
+
+在同一个 Maven 模块中补充 `war` 打包步骤，使一次 `mvn package` 后同时得到：
+
+- `ruoyi-admin/target/ruoyi-admin.jar`
+- `ruoyi-admin/target/ruoyi-admin.war`
+
+这样本地和服务器都从同一套源码构建，但消费不同产物：
+
+- 本地消费 `jar`
+- 服务器消费 `war`
+
+### 2. 依赖设计
+
+为了保证本地可继续走内嵌 Tomcat：
+
+- 恢复 Web 模块中的内嵌 Tomcat 依赖链
+- 保持 `spring-boot:run` 与 `java -jar` 均可正常工作
+
+为了保证 TongWeb 外部容器部署：
+
+- 打出的 `war` 不能把容器自身实现错误打包成部署冲突形式
+- `Servlet API` 继续按外部容器提供的思路处理
+
+本质上，本地运行和 TongWeb 部署共享同一套业务代码，但运行容器不同。
+
+### 3. 启动脚本设计
+
+#### 本地脚本
+
+`bin/restart_java_backend.sh` 恢复为本地开发脚本：
+
+- 执行 Maven 打包
+- 使用 `ruoyi-admin.jar`
+- 通过 `java -jar` 管理本地后端进程
+
+这条链路不再依赖 `TONGWEB_HOME`。
+
+#### 生产脚本
+
+以下脚本保持 TongWeb 交付模型：
+
+- `bin/prod/restart_java.sh`
+- `bin/prod/deploy_from_package.sh`
+- `bin/prod/deploy_release.sh`
+
+它们继续只处理 `ruoyi-admin.war`，不回退到 `jar`。
+
+### 4. 本地与服务器联调设计
+
+本地开发时不要求本机安装 TongWeb。
+
+如果需要验证 TongWeb 运行环境，只通过两种方式完成：
+
+- 打包后部署到服务器 TongWeb 验证
+- 本地系统直接调用服务器上已部署的 TongWeb 地址联调
+
+这意味着：
+
+- 本地开发链路只围绕 `jar + Tomcat`
+- 服务器部署链路只围绕 `war + TongWeb`
+
+## 验证方案
+
+### 构建验证
+
+执行：
+
+```sh
+mvn -pl ruoyi-admin -am package -DskipTests
+```
+
+确认同时存在：
+
+- `ruoyi-admin/target/ruoyi-admin.jar`
+- `ruoyi-admin/target/ruoyi-admin.war`
+
+### 本地运行验证
+
+执行：
+
+```sh
+sh bin/restart_java_backend.sh restart
+```
+
+确认本地以 `java -jar` 正常运行。
+
+### TongWeb 脚本验证
+
+执行：
+
+```sh
+sh bin/prod/restart_java_test.sh
+sh bin/prod/deploy_from_package_test.sh
+```
+
+确认 TongWeb 侧仍围绕 `war` 工作。
+
+## 影响范围
+
+- `ruoyi-admin` Maven 打包配置
+- Web 相关模块的容器依赖声明
+- 本地后端脚本
+- 生产 TongWeb 脚本
+- 运行文档与实施记录
+
+## 结论
+
+本方案采用最短路径实现“双产物、双运行链路并存”：
+
+- 本地运行继续走内嵌 Tomcat
+- 服务器部署继续走 TongWeb
+- 一次打包同时产出 `jar` 与 `war`
+
+在不新增模块、不扩散复杂度的前提下，满足开发与部署两端的实际需要。