框架项目和业务项目双线演进管理方案

当前有两个长期演进方向：

• 框架项目：D:\WorkSpace\MySpace\yin-yang
• 业务项目：D:\WorkSpace\Electric\cloud-web\03.Code\Taichi

框架项目负责沉淀通用能力，业务项目负责交付具体业务。两边同时开发时，最大风险是重复复制、手工合并、业务逻辑被框架升级覆盖。

一、推荐定位

把框架项目当成 upstream，把业务项目当成 downstream。

框架项目输出：

1. 通用后端模块。
2. 通用前端组件、指令、路由和权限能力。
3. 标准工程结构。
4. 升级说明和迁移脚本。

业务项目保留：

1. 业务 Controller、Service、Entity、Mapper。
2. 业务前端页面。
3. 业务数据库表。
4. 客户现场配置和部署脚本。

二、不要长期靠复制文件

短期可以从框架复制代码，但长期应逐步变成版本化依赖。

推荐顺序：

1. 先把业务项目纳入 Git。
2. 把框架能力拆成 Maven/npm 可发布模块。
3. 业务项目通过版本号升级框架能力。
4. 只有真正业务相关的代码留在业务项目。

后端可以演进为：

business-admin -> business-module -> framework-system -> framework-common
business-admin -> framework-mqtt

前端可以演进为：

business-app -> framework-ui
business-app -> framework-permission

三、分支模型

框架项目

• main：稳定版本。
• dev：日常开发。
• release/x.y.z：发布候选。

每次框架发布必须包含：

1. 版本号。
2. 变更日志。
3. 迁移说明。
4. 数据库变更脚本。
5. 兼容性说明。

业务项目

• main：生产稳定版本。
• dev：业务开发。
• framework-sync/x.y.z：框架升级集成分支。

框架升级必须先进入 framework-sync/* 分支，验证通过后再合并进业务 dev。

四、升级流程

1. 框架项目发布 vX.Y.Z。
2. 业务项目新建 framework-sync/vX.Y.Z。
3. 阅读框架变更日志和迁移说明。
4. 升级 Maven/npm 版本或同步必要文件。
5. 执行数据库迁移。
6. 跑后端编译、单测和前端构建。
7. 做权限、登录、菜单、业务核心流程回归。
8. 合并回业务开发分支。

五、边界规则

框架可以改

• 权限模型
• 用户、角色、菜单通用能力
• 请求封装
• 动态路由
• 通用异常处理
• 通用工具类
• 通用组件

框架不能直接改

• 设备业务规则
• 固件升级业务流程
• MQTT 业务 Handler 的具体含义
• 业务数据库表字段语义
• 客户定制页面

六、兼容性约定

每个框架版本都要说明以下内容：

1. Java 版本。
2. Spring Boot 版本。
3. 前端 Vue/Vite/Element Plus 版本。
4. 数据库兼容范围。
5. 是否需要重新登录或清理 localStorage。
6. 是否修改权限标识。
7. 是否修改接口响应结构。

权限标识尤其要稳定。比如 sys:config:query 一旦被业务项目使用，就不要随意改成 system:config:query。

七、自动化检查

每次框架升级业务项目至少要跑：

./mvnw.cmd -pl yin-admin -am test -DskipTests
pnpm run build
pnpm run build-tsc

如果项目已有历史类型债，可以先把 pnpm run build 作为硬门槛，把 build-tsc 作为质量债清单逐步治理。

八、文档管理

每次升级应在博客或项目文档里记录：

1. 升级前版本。
2. 升级后版本。
3. 涉及模块。
4. 改动原因。
5. 代码改动点。
6. 数据库变更。
7. 验证命令和结果。
8. 已知风险。

这样下一次升级可以复用经验，不需要重新从 diff 里猜意图。

九、推荐落地步骤

1. 先给业务项目初始化 Git 仓库或接入现有远程仓库。
2. 建立 framework-sync/* 集成分支规范。
3. 把可复用能力逐步抽成模块依赖。
4. 把业务私有逻辑从框架代码里剥离。
5. 给每次框架发布写迁移文档。
6. 建立最小自动化验证命令。

这套方式的核心是：框架输出稳定能力，业务项目只消费稳定版本；业务逻辑不反向写进框架，框架升级也不直接覆盖业务逻辑。