# 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 文档头部元数据

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

```markdown
# 文档标题

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

### 3.2 文档结构模板

```markdown
# 文档标题

> 元数据块

---

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

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

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

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

---

> **文档版本**: 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