# 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 评估)           ← 按需
```

---

## 升级日志模板

```markdown
## [日期] 升级记录

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

---

## 风险矩阵

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