wangyizhe/his
1
3
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
9cef0ac4a70d38654e70f1c6b131da6d7fa5d0ba
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

193 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
Reference in New Issue View Git Blame Copy Permalink