wangyizhe/his
1
3
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
55785252f673add13c3e9220b8b88b3faf694d92
his/MD/DOCUMENTATION_STANDARD.md
华佗 d8427f788e 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
2026-06-06 09:06:21 +08:00

6.9 KiB
Raw Blame History

HealthLink HIS 文档管理规范

文档类型: 技术规范 适用范围: 项目所有文档(Markdown格式) 版本: v1.0 编制日期: 2026-06-06 最后更新: 2026-06-06

一、目录结构规范

MD/
├── DOCUMENTATION_STANDARD.md    # 本文档(规范)
├── architecture/                # 架构设计
├── development/                 # 开发计划与记录
├── standards/                   # 国家/行业标准
├── specs/                       # 技术规范与流程
├── bugs/                        # Bug分析与修复记录
├── guides/                      # 使用指南
└── upgrade/                     # 升级记录

1.1 目录说明

目录 用途 示例文件
architecture/ 系统架构、模块设计、数据库设计 GRADE3A_DETAILED_DESIGN.md
development/ 开发计划、进度记录、功能分析 DEVELOPMENT_PLAN_V2.md
standards/ 国家/行业标准规范、政策文件 GRADE3A_HIS_STANDARD.md
specs/ 技术规范、流程定义、检查清单 BACKEND_CHECKLIST.md
bugs/ Bug分析、修复记录、问题追踪 BUG_632_ANALYSIS.md
guides/ 使用指南、操作手册 FLYWAY_USAGE_GUIDE.md
upgrade/ 升级计划、升级日志 SPRINGBOOT_UPGRADE_LOG.md

二、文件命名规范

2.1 命名规则

<类别>_<子类别>_<简短描述>.md

2.2 命名格式

类别 格式 示例
架构设计 ARCH_<模块>_<描述> ARCH_DATABASE_DESIGN.md
开发计划 PLAN_<类型>_<版本> PLAN_DEVELOPMENT_V2.md
国家标准 STD_<标准名称> STD_GRADE3A_HIS.md
技术规范 SPEC_<类型>_<描述> SPEC_BACKEND_CHECKLIST.md
Bug修复 BUG_<编号>_<描述> BUG_632_ANALYSIS.md
使用指南 GUIDE_<主题> GUIDE_FLYWAY.md
升级记录 UPGRADE_<组件>_<类型> UPGRADE_SPRINGBOOT_LOG.md

2.3 命名规则详解

  1. 全部大写 — 文件名使用大写字母和下划线
  2. 英文命名 — 所有文件名使用英文(描述内容可用中文)
  3. 下划线分隔 — 单词之间用下划线连接
  4. 版本号 — 在文件名末尾标注版本(如 _V2)
  5. 日期标注 — 不在文件名中使用日期(使用文件内元数据)

2.4 禁止事项

  • ❌ 使用中文作为文件名
  • ❌ 使用空格分隔单词
  • ❌ 使用特殊字符(!@#$%^&*)
  • ❌ 文件名超过50个字符
  • ❌ 使用大驼峰命名(MyDocument.md)

三、文档格式规范

3.1 文档头部元数据

每个文档必须包含以下元数据:

# 文档标题

> **文档类型**: [架构设计|开发计划|技术规范|Bug修复|使用指南|升级记录]
> **适用范围**: [描述适用的模块或场景]
> **版本**: v1.0
> **编制日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD
> **编制人**: [姓名/角色]

3.2 文档结构模板

# 文档标题

> 元数据块

---

## 一、概述
<!-- 简要描述文档目的和内容 -->

## 二、详细内容
<!-- 主体内容 -->

## 三、实施计划
<!-- 如果适用 -->

## 四、注意事项
<!-- 关键约束和注意事项 -->

---

> **文档版本**: v1.0
> **最后更新**: YYYY-MM-DD

3.3 格式要求

要求 说明
标题层级 使用 # ## ###，不超过4级
表格 使用标准Markdown表格格式
代码块 使用 ``` 包裹，标注语言类型
列表 使用 - 或 1. 统一格式
链接 使用相对路径引用其他文档
图片 使用相对路径，存储在 assets/ 目录

四、文件分类映射表

4.1 现有文件映射

原文件路径 新文件路径 说明
docs/三甲医院HIS系统标准规范汇编.md MD/standards/GRADE3A_HIS_STANDARD.md 三甲标准规范
docs/GRADE3A_DETAILED_DESIGN.md MD/architecture/GRADE3A_DETAILED_DESIGN.md 三甲详细设计
docs/GRADE3A_DEVELOPMENT_PLAN.md MD/development/GRADE3A_DEVELOPMENT_PLAN.md 三甲开发计划
docs/GRADE3A_HIS_DESIGN.md MD/architecture/GRADE3A_HIS_DESIGN.md 三甲HIS设计
docs/DEVELOPMENT_PLAN_V2.md MD/development/DEVELOPMENT_PLAN_V2.md 开发计划V2
docs/BACKEND_UPGRADE_PLAN.md MD/upgrade/BACKEND_UPGRADE_PLAN.md 后端升级计划
docs/UPGRADE_PLAN_v2.0.md MD/upgrade/UPGRADE_PLAN_V2.md 升级计划V2
docs/UPGRADE_LOG.md MD/upgrade/UPGRADE_LOG.md 升级日志
docs/MYBATIS_PLUS_UPGRADE_PLAN.md MD/upgrade/MYBATIS_PLUS_UPGRADE.md MyBatis升级
docs/RUOYI_392_UPGRADE_CHECKLIST.md MD/upgrade/RUOYI_UPGRADE_CHECKLIST.md 若依升级清单
docs/FLYWAY_USAGE_GUIDE.md MD/guides/FLYWAY_USAGE_GUIDE.md Flyway使用指南
docs/MENU_FUNCTION_ANALYSIS.md MD/development/MENU_FUNCTION_ANALYSIS.md 菜单功能分析
docs/HIS项目Bug修复记录-v1.0.md MD/bugs/BUG_FIX_RECORD.md Bug修复记录
docs/bug439_analysis.md MD/bugs/BUG_439_ANALYSIS.md Bug 439分析
docs/bug462_analysis.md MD/bugs/BUG_462_ANALYSIS.md Bug 462分析
docs/bug494_analysis.md MD/bugs/BUG_494_ANALYSIS.md Bug 494分析
docs/bug498_analysis.md MD/bugs/BUG_498_ANALYSIS.md Bug 498分析
docs/bug-fixes/bug-632.md MD/bugs/BUG_632_ANALYSIS.md Bug 632分析
docs/bug-fixes/bug-634.md MD/bugs/BUG_634_ANALYSIS.md Bug 634分析
docs/bug-fixes/bug-644.md MD/bugs/BUG_644_ANALYSIS.md Bug 644分析
docs/specs/backend-checklist.md MD/specs/BACKEND_CHECKLIST.md 后端检查清单
docs/specs/frontend-checklist.md MD/specs/FRONTEND_CHECKLIST.md 前端检查清单
docs/specs/cicd-gatekeeper.md MD/specs/CICD_GATEKEEPER.md CI/CD门禁
docs/specs/commit-template.md MD/specs/COMMIT_TEMPLATE.md 提交模板
docs/specs/his-release-checklist-v1.0.md MD/specs/RELEASE_CHECKLIST.md 发布清单
docs/specs/playwright-e2e-testing-plan.md MD/specs/PLAYWRIGHT_TESTING_PLAN.md E2E测试计划

五、铁律

  1. 文档统一存储 — 所有文档必须存储在 MD/ 目录中
  2. 命名规范 — 所有文件名必须遵循命名规范
  3. 格式规范 — 所有文档必须包含元数据块
  4. 版本管理 — 重大修改必须更新版本号
  5. 及时更新 — 代码变更后必须同步更新相关文档

六、检查清单

  • 文件名是否使用大写英文+下划线？
  • 文件是否存储在正确的子目录中？
  • 文档头部是否包含元数据块？
  • 文档结构是否符合模板？
  • 代码块是否标注语言类型？
  • 表格是否使用标准格式？
  • 链接是否使用相对路径？

文档版本: v1.0 最后更新: 2026-06-06