design.md 7.7 KB

Context

当前系统版本号链路(已上线):

根目录 VERSION.md  →(vite.config.ts 用 Node readFileSync 读取)→ define __APP_VERSION_FILE__
                  →(src/utils/version.ts 解析标记区)→ APP_VERSION / VERSION_LOGS
                  →(src/App.tsx 左侧导航底部 + 顶部 Header)→ 界面显示

VERSION.md 有两个标记区:<!-- CURRENT_VERSION_START --> ~ <!-- CURRENT_VERSION_END -->(当前版本三行)与 <!-- CHANGELOG_START --> ~ <!-- CHANGELOG_END -->(历史版本段落,最新在最上)。

痛点:维护者必须手工记住版本规则与标记区位置,易写错格式或漏改「当前版本信息」区,造成导航栏版本号与更新内容不一致。

约束:

  • VERSION.md 在构建期由 Node 注入,浏览器运行期无法写回磁盘;
  • 前端为 React 18 + Ant Design v6(Option 已废弃需用 options、Divider 用 titlePlacement、日期组件需中文本地化);
  • 菜单三处一致性要求:keyToPath / menuTitleMap / MENU_RENDERERS 必须齐全,否则 dev 启动时 validateMenuRoutes() 告警。

Goals / Non-Goals

Goals:

  1. 在系统内可视化查看当前版本与全部历史版本的「新增/优化/修复」内容;
  2. 通过表单录入新版本,自动按规则生成版本号,生成符合规范的 Markdown;
  3. 一键「复制全文 / 下载 VERSION.md / 下载新增片段」,维护者覆盖根目录文件后重新打包即生效;
  4. 与导航栏共用同一份解析逻辑(utils/version.ts),保证界面显示与维护内容同源。

Non-Goals:

  • 不新增后端接口与数据表(避免文件与数据库两份版本数据);
  • 不在浏览器端直接写盘/调用文件系统(安全与部署限制);
  • 不改版号规则与标记区命名(向后兼容已写内容);
  • 不做版本发布审批流、不做版本对比/回滚。

Decisions

决策 1:纯前端方案(生成 + 复制/下载),不引入后端存储

  • 选择:页面基于已注入的 VERSION.md 原文做解析与重新拼接,产出新文件文本供复制/下载。
  • 备选 A(后端表 + 接口):需新增 BS_DRGVersionRecord 表与查询/保存/删除接口,页面可真正增删改查;但会出现"文件与库两份版本数据",且导航栏仍读文件,二者易不一致。
  • 备选 B(写本地文件服务):需额外引入 Node 写文件服务,生产部署形态(nginx 静态托管)不支持。
  • 理由:版本内容是低频、单人维护的构建期资产,纯前端生成最轻量、零后端改造、与"文件是唯一来源"的既定约定一致。

决策 2:新增版本号自动推算,允许人工覆盖

  • 规则:v + YYYY.MM.DD + 当日序列号(2 位)。
  • 推算:取历史版本中"发布日期 == 今天"的最大序列号 + 1;若今天无记录则从 01 开始;若历史为空则 v<今天>.01。
  • 版本号输入框可编辑(DatePicker 改变日期时自动重算为 v<所选日期>.01 或当日 +1)。

决策 3:全文生成采用"标记区替换 + 顶部插入",不整体重写文件

在 utils/version.ts 增加 buildVersionFile({ version, date, desc, groups }):

  1. 用新三行替换 CURRENT_VERSION_START/END 之间的内容(保留标记行本身);
  2. 在 <!-- CHANGELOG_START --> 之后插入新版本段落(## vX(date) + ### 分类 + - 条目);
  3. 其余原文原样保留(维护说明、历史记录不动)。
  4. 理由:保留人工维护说明与注释,diff 最小,误操作风险低。

决策 4:更新内容录入用 Form.List 动态条目

三类(新增/优化/修复)各自一组可增删的输入项;提交时过滤空行与"无"。日期控件统一使用中文(import 'dayjs/locale/zh-cn'; dayjs.locale('zh-cn') + locale={zhCN},格式 YYYY年MM月DD日),与项目既有规范一致。

决策 5:新增「发布人」「影响模块」两个字段,写进版本段落

  • 表示形式:写在每个版本段落标题下、### 分类 之前,形如两行列表项,便于解析与人工阅读: ```markdown

    v2026.09.14.02(2026-09-14)

    • 发布人:张三
    • 影响模块:DRG分组、系统管理

### 新增

  • xxx

    - 「发布人」默认取当前登录用户(`localStorage.userInfo.userName`),可手工修改;
    - 「影响模块」用 `Select mode="tags"`:预置常用模块(DRG分组 / DIP付费 / 医保控费预警 / 盈亏分析 / 基础数据 / HIS数据 / 特例单议 / 系统管理 / 接口服务 / 其它),同时允许自由输入新模块名;存储为顿号分隔的字符串,解析时按 `、/,/,` 切分;
    - 两个字段均可选:为空时不写入 Markdown,页面也不展示空字段。
    
    ### 决策 6:页面只读展示历史,不支持在线改历史
    
    历史版本列表为只读,如需修正历史内容请在 `VERSION.md` 手工编辑——保证"生成逻辑"单一方向(只追加),避免解析/重写历史导致结构损坏。
    
    ## 页面与数据流
    
    

VersionMaintenance.tsx ├─ 当前版本卡片 ← utils/version.ts: APP_VERSION / APP_VERSION_DATE / APP_VERSION_DESC ├─ 历史版本时间轴 ← VERSION_LOGS(倒序,展开显示 新增/优化/修复) └─ 「新增版本」Modal(Form)

  ├─ 版本号(自动推算,可编辑)
  ├─ 更新日期(DatePicker 中文)
  ├─ 版本说明(Input)
  ├─ 发布人(默认当前登录用户,可改)
  ├─ 影响模块(Select tags,预置 + 自由输入)
  └─ 新增/优化/修复(Form.List 动态条目)
       → 提交 → buildVersionFile() 生成全文
       → 结果展示:只读预览 + [复制全文] [下载 VERSION.md] [下载新增片段]

```

关键实现点

文件 变更
frontend/src/utils/version.ts 新增 VERSION_FILE_RAW、buildVersionFile()、suggestNextVersion();保留既有导出
frontend/src/pages/System/VersionMaintenance.tsx 新增页面(函数组件 + Hooks)
frontend/src/routes/menuRouteRegistry.tsx 导入页面;MENU_RENDERERS 新增 'system-version'
frontend/src/routes/menuRoutes.ts keyToPath['system-version'] = '/system/version';menuTitleMap['system-version'] = '版本更新维护'
BS_DrgSystemMenu(菜单配置页面) 新增菜单记录(详见 tasks)

Risks / Trade-offs

  • [需人工落盘] 生成的内容需人工覆盖 VERSION.md 并重新打包 → 页面明确提示"下载后替换项目根目录 VERSION.md,并执行 npm run build";提供一键复制降低操作成本。
  • [格式被手写破坏] 若人工把标记行改名/删除,buildVersionFile 会失败 → 函数内做标记存在性校验,缺失时给出明确中文提示并回退为"仅生成新增片段"。
  • [版本号重复] 人工可改版本号导致重复 → 提交前校验版本号是否已存在,重复则拦截提示。
  • [大文件预览] VERSION.md 增大后预览区较长 → 预览区固定高度 + 滚动,默认展示新增段落。

Migration Plan

  1. 前端新增页面与路由注册,本地 npm run dev 验证菜单可打开;
  2. 在「菜单配置」页新增 system-version 菜单并授权给对应角色;
  3. npm run build 打包,部署 dist 到生产(E:\DRG\dist);
  4. 回滚:菜单下线或删除该菜单记录即可,无数据变更、无后端依赖,零风险。

Open Questions

  1. 是否需要"编辑/删除历史版本"能力(当前为只读追加)?
  2. 版本生效是否需要在页面内展示"当前线上版本"(构建时间)以便核对是否重新打包?——建议后续在版本卡片补充"打包时间"(构建期注入 new Date().toISOString())。