his/docs/UPGRADE_PLAN_v2.0.md

OpenHIS 二次开发版本 — 组件升级计划

编制日期: 2026-06-03 对比基线: Gitee tntlinking-opensource/openhis-itai-pro 2.0 分支 目标: 在不破坏现有业务的前提下，逐步引入高价值组件升级

---

升级原则

1. 独立可验证 — 每个 Phase 完成后必须独立通过编译 + 冒烟测试
2. 不破坏业务 — 一次只升级一个组件，出问题可快速回滚
3. 先补丁后重构 — 小版本升级直接改版本号，大版本升级单独评估
4. 文档同步 — 每次升级后更新 UPGRADE_LOG.md

---

Phase 0: 安全修复（预估 0.5 天）

🔴 最高优先级 — 安全漏洞，必须立即处理

0.1 BouncyCastle 1.69 → 1.80

项目	详情
文件	openhis-server-new/pom.xml
变更	<bcprov-jdk15on.version>1.69</bcprov-jdk15on.version> → 删除，改用 jdk18on
新依赖	org.bouncycastle:bcprov-jdk18on:1.80 + org.bouncycastle:bcpkix-jdk18on:1.80
原因	1.69 有已知安全漏洞；1.80 支持国密 SM2/SM3 算法
影响面	rg "bouncycastle|bcprov|bcpkix" --type java 搜索所有引用
验证	mvn compile + 启动后检查加解密功能（登录、token 签发）

0.2 vue-router 4.3 → 4.5

项目	详情
文件	openhis-ui-vue3/package.json
变更	"vue-router": "^4.3.0" → "^4.5.1"
风险	低 — 4.x 小版本，API 兼容
验证	前端 npm run dev → 测试所有页面路由跳转、返回、权限拦截

---

Phase 1: 核心组件升级（预估 1-2 天）

🟡 高价值 — 改动可控，收益明显

1.1 echarts 5.4 → 6.0

项目	详情
文件	openhis-ui-vue3/package.json
变更	"echarts": "^5.4.3" → "^6.0.0"
影响面	rg "echarts" --type vue --type js 搜索所有图表组件
Breaking Changes	ECharts 6 主要变更：Tree-shaking 更彻底、部分 API 重命名
验证清单	首页统计图表、门诊量趋势、药品销售报表、住院床位占用图
回滚方案	改回 "^5.4.3" 即可

1.2 lodash-es → es-toolkit

项目	详情
文件	openhis-ui-vue3/package.json + 所有引用文件
变更	"lodash-es": "^4.17.21" → 删除，添加 "es-toolkit": "^1.41.0"
迁移映射	_.cloneDeep → cloneDeep、_.debounce → debounce、_.isEqual → isEqual、_.get → get
影响面	rg "from 'lodash-es'" --type vue --type js 逐个替换
风险	中 — 需逐个替换 import，但 API 基本一致
验证	全站功能冒烟测试

1.3 引入 MapStruct（后端）

项目	详情
文件	openhis-server-new/pom.xml (parent) + openhis-application/pom.xml
新增依赖	org.mapstruct:mapstruct:1.5.5.Final + mapstruct-processor + lombok-mapstruct-binding
使用方式	新增 @Mapper(componentModel = "spring") 接口替代 BeanUtils.copyProperties
策略	渐进式 — 不改造现有代码，仅新功能使用 MapStruct
验证	mvn compile 确认注解处理器工作

---

Phase 2: 富文本 + 数据库迁移（预估 3-5 天）

🟢 中等工作量 — 需要一定的改造

2.1 tiptap 富文本编辑器（替代 vue-quill）

项目	详情
新增依赖	@tiptap/vue-3、@tiptap/starter-kit、@tiptap/extension-* 系列
替换目标	@vueup/vue-quill（当前用于病历编辑、处方备注等）
影响面	rg "vue-quill|Quill" --type vue 搜索所有引用
新增能力	表格编辑、图片内嵌、协作编辑、自定义节点
策略	新页面用 tiptap，旧页面逐步迁移
验证	病历编辑器、处方备注、各种富文本输入场景

2.2 引入 Flyway 数据库迁移

项目	详情
新增依赖	org.flywaydb:flyway-core + flyway-database-postgresql
配置	application-dev.yml 添加 Flyway 配置
目录	src/main/resources/db/migration/
迁移文件命名	V1__init.sql、V2__add_xxx.sql
策略	不对现有表做迁移，仅新功能的 DDL 用 Flyway 管理
风险	中 — 需确保现有数据库与 Flyway 基线一致
验证	启动时 Flyway 自动执行 → 检查 flyway_schema_history 表

---

Phase 3: UI 框架评估（预估 5-10 天，可选）

⚪ 长期规划 — 工作量大，收益高但风险也高

3.1 Tailwind CSS 引入

项目	详情
新增依赖	tailwindcss、autoprefixer、postcss
策略	渐进式 — Tailwind 与现有 SCSS 共存，新页面用 Tailwind
影响面	全局样式可能冲突，需仔细测试
建议	先在 help-center 或独立页面试水

3.2 Vben Admin 组件库评估

项目	详情
可引入的包	@vben/access（权限）、@vben/request（请求封装）、@vben/preferences（偏好设置）
风险	高 — Vben 组件与我们现有架构耦合度未知
策略	仅评估，不做实施。等 Phase 0-2 完成后再决定

---

升级路线图

Week 1:  Phase 0 (BouncyCastle + vue-router)     ← 立即执行
Week 1:  Phase 1.1 (echarts 6)                    ← 紧随其后
Week 2:  Phase 1.2 (es-toolkit) + 1.3 (MapStruct)
Week 3:  Phase 2.1 (tiptap)                       ← 可并行
Week 3:  Phase 2.2 (Flyway)                       ← 可并行
Week 4+: Phase 3 (Tailwind + Vben 评估)           ← 按需

---

升级日志模板

## [日期] 升级记录

### 组件: XXX Y.Y → Z.Z
- **Phase**: 0/1/2/3
- **变更文件**: list...
- **验证结果**: ✅ 编译通过 / ✅ 冒烟测试通过
- **回滚方案**: 改回旧版本号
- **备注**: ...

---

风险矩阵

风险	概率	影响	缓解措施
echarts 6 API 不兼容	中	高	先在测试环境验证所有图表
es-toolkit 行为差异	低	中	逐个替换，每个改完跑测试
Flyway 与现有 SQL 冲突	中	高	设置 baseline，不管理已有表
tiptap 与现有编辑器冲突	低	低	新旧共存，逐步迁移
Tailwind 样式覆盖	高	中	使用 CSS Module 隔离