docs: 统一文档管理规范，合并docs/到MD/目录
- 创建MD/目录结构(architecture/development/standards/specs/bugs/guides/upgrade) - 制定文档命名规范(大写英文+下划线) - 制定文档格式规范(元数据块、结构模板) - 合并27个文档到MD/目录，按类别分类 - 删除旧的docs/目录 - 更新AGENTS.md铁律#5: 文档统一管理 命名规范: - 架构设计: ARCH_<模块>_<描述>.md - 开发计划: PLAN_<类型>_<版本>.md - 国家标准: STD_<标准名称>.md - 技术规范: SPEC_<类型>_<描述>.md - Bug修复: BUG_<编号>_<描述>.md - 使用指南: GUIDE_<主题>.md - 升级记录: UPGRADE_<组件>_<类型>.md
This commit is contained in:
171
MD/upgrade/UPGRADE_PLAN_V2.md
Normal file
171
MD/upgrade/UPGRADE_PLAN_V2.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# HealthLink-HIS 二次开发版本 — 组件升级计划
|
||||
|
||||
> **编制日期**: 2026-06-03
|
||||
> **对比基线**: Gitee `tntlinking-opensource/healthlink-his` 2.0 分支
|
||||
> **目标**: 在不破坏现有业务的前提下，逐步引入高价值组件升级
|
||||
|
||||
---
|
||||
|
||||
## 升级原则
|
||||
|
||||
1. **独立可验证** — 每个 Phase 完成后必须独立通过编译 + 冒烟测试
|
||||
2. **不破坏业务** — 一次只升级一个组件，出问题可快速回滚
|
||||
3. **先补丁后重构** — 小版本升级直接改版本号，大版本升级单独评估
|
||||
4. **文档同步** — 每次升级后更新 `UPGRADE_LOG.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: 安全修复（预估 0.5 天）
|
||||
|
||||
> 🔴 **最高优先级** — 安全漏洞，必须立即处理
|
||||
|
||||
### 0.1 BouncyCastle 1.69 → 1.80
|
||||
|
||||
| 项目 | 详情 |
|
||||
|---|---|
|
||||
| **文件** | `healthlink-his-server/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
|
||||
|
||||
| 项目 | 详情 |
|
||||
|---|---|
|
||||
| **文件** | `healthlink-his-ui/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
|
||||
|
||||
| 项目 | 详情 |
|
||||
|---|---|
|
||||
| **文件** | `healthlink-his-ui/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
|
||||
|
||||
| 项目 | 详情 |
|
||||
|---|---|
|
||||
| **文件** | `healthlink-his-ui/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（后端）
|
||||
|
||||
| 项目 | 详情 |
|
||||
|---|---|
|
||||
| **文件** | `healthlink-his-server/pom.xml` (parent) + `healthlink-his-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 隔离 |
|
||||
|
||||
Reference in New Issue
Block a user