From d8427f788eee7eb4a45c5aaa5bdc7c679e8f27a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=8E=E4=BD=97?= Date: Sat, 6 Jun 2026 09:06:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E8=A7=84=E8=8C=83=EF=BC=8C=E5=90=88=E5=B9=B6?= =?UTF-8?q?docs/=E5=88=B0MD/=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建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 --- MD/DOCUMENTATION_STANDARD.md | 192 ++++++++++++++++++ .../architecture}/GRADE3A_DETAILED_DESIGN.md | 0 .../architecture}/GRADE3A_HIS_DESIGN.md | 0 .../bugs/BUG_439_ANALYSIS.md | 0 .../bugs/BUG_462_ANALYSIS.md | 0 .../bugs/BUG_494_ANALYSIS.md | 0 .../bugs/BUG_498_ANALYSIS.md | 0 .../bug-632.md => MD/bugs/BUG_632_ANALYSIS.md | 0 .../bug-634.md => MD/bugs/BUG_634_ANALYSIS.md | 0 .../bug-644.md => MD/bugs/BUG_644_ANALYSIS.md | 0 .../bugs/BUG_FIX_RECORD.md | 0 .../development}/DEVELOPMENT_PLAN_V2.md | 0 .../development}/GRADE3A_DEVELOPMENT_PLAN.md | 0 .../development}/MENU_FUNCTION_ANALYSIS.md | 0 {docs => MD/guides}/FLYWAY_USAGE_GUIDE.md | 0 .../specs/BACKEND_CHECKLIST.md | 0 .../specs/CICD_GATEKEEPER.md | 0 .../specs/COMMIT_TEMPLATE.md | 0 .../specs/FRONTEND_CHECKLIST.md | 0 .../specs/PLAYWRIGHT_TESTING_PLAN.md | 0 .../specs/RELEASE_CHECKLIST.md | 0 .../standards/GRADE3A_HIS_STANDARD.md | 0 {docs => MD/upgrade}/BACKEND_UPGRADE_PLAN.md | 0 .../upgrade/MYBATIS_PLUS_UPGRADE.md | 0 .../upgrade/RUOYI_UPGRADE_CHECKLIST.md | 0 {docs => MD/upgrade}/UPGRADE_LOG.md | 0 .../upgrade/UPGRADE_PLAN_V2.md | 0 healthlink-his-server/AGENTS.md | 32 +++ 28 files changed, 224 insertions(+) create mode 100644 MD/DOCUMENTATION_STANDARD.md rename {docs => MD/architecture}/GRADE3A_DETAILED_DESIGN.md (100%) rename {docs => MD/architecture}/GRADE3A_HIS_DESIGN.md (100%) rename docs/bug439_analysis.md => MD/bugs/BUG_439_ANALYSIS.md (100%) rename docs/bug462_analysis.md => MD/bugs/BUG_462_ANALYSIS.md (100%) rename docs/bug494_analysis.md => MD/bugs/BUG_494_ANALYSIS.md (100%) rename docs/bug498_analysis.md => MD/bugs/BUG_498_ANALYSIS.md (100%) rename docs/bug-fixes/bug-632.md => MD/bugs/BUG_632_ANALYSIS.md (100%) rename docs/bug-fixes/bug-634.md => MD/bugs/BUG_634_ANALYSIS.md (100%) rename docs/bug-fixes/bug-644.md => MD/bugs/BUG_644_ANALYSIS.md (100%) rename docs/HIS项目Bug修复记录-v1.0.md => MD/bugs/BUG_FIX_RECORD.md (100%) rename {docs => MD/development}/DEVELOPMENT_PLAN_V2.md (100%) rename {docs => MD/development}/GRADE3A_DEVELOPMENT_PLAN.md (100%) rename {docs => MD/development}/MENU_FUNCTION_ANALYSIS.md (100%) rename {docs => MD/guides}/FLYWAY_USAGE_GUIDE.md (100%) rename docs/specs/backend-checklist.md => MD/specs/BACKEND_CHECKLIST.md (100%) rename docs/specs/cicd-gatekeeper.md => MD/specs/CICD_GATEKEEPER.md (100%) rename docs/specs/commit-template.md => MD/specs/COMMIT_TEMPLATE.md (100%) rename docs/specs/frontend-checklist.md => MD/specs/FRONTEND_CHECKLIST.md (100%) rename docs/specs/playwright-e2e-testing-plan.md => MD/specs/PLAYWRIGHT_TESTING_PLAN.md (100%) rename docs/specs/his-release-checklist-v1.0.md => MD/specs/RELEASE_CHECKLIST.md (100%) rename docs/三甲医院HIS系统标准规范汇编.md => MD/standards/GRADE3A_HIS_STANDARD.md (100%) rename {docs => MD/upgrade}/BACKEND_UPGRADE_PLAN.md (100%) rename docs/MYBATIS_PLUS_UPGRADE_PLAN.md => MD/upgrade/MYBATIS_PLUS_UPGRADE.md (100%) rename docs/RUOYI_392_UPGRADE_CHECKLIST.md => MD/upgrade/RUOYI_UPGRADE_CHECKLIST.md (100%) rename {docs => MD/upgrade}/UPGRADE_LOG.md (100%) rename docs/UPGRADE_PLAN_v2.0.md => MD/upgrade/UPGRADE_PLAN_V2.md (100%) diff --git a/MD/DOCUMENTATION_STANDARD.md b/MD/DOCUMENTATION_STANDARD.md new file mode 100644 index 000000000..0234270fb --- /dev/null +++ b/MD/DOCUMENTATION_STANDARD.md @@ -0,0 +1,192 @@ +# 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 diff --git a/docs/GRADE3A_DETAILED_DESIGN.md b/MD/architecture/GRADE3A_DETAILED_DESIGN.md similarity index 100% rename from docs/GRADE3A_DETAILED_DESIGN.md rename to MD/architecture/GRADE3A_DETAILED_DESIGN.md diff --git a/docs/GRADE3A_HIS_DESIGN.md b/MD/architecture/GRADE3A_HIS_DESIGN.md similarity index 100% rename from docs/GRADE3A_HIS_DESIGN.md rename to MD/architecture/GRADE3A_HIS_DESIGN.md diff --git a/docs/bug439_analysis.md b/MD/bugs/BUG_439_ANALYSIS.md similarity index 100% rename from docs/bug439_analysis.md rename to MD/bugs/BUG_439_ANALYSIS.md diff --git a/docs/bug462_analysis.md b/MD/bugs/BUG_462_ANALYSIS.md similarity index 100% rename from docs/bug462_analysis.md rename to MD/bugs/BUG_462_ANALYSIS.md diff --git a/docs/bug494_analysis.md b/MD/bugs/BUG_494_ANALYSIS.md similarity index 100% rename from docs/bug494_analysis.md rename to MD/bugs/BUG_494_ANALYSIS.md diff --git a/docs/bug498_analysis.md b/MD/bugs/BUG_498_ANALYSIS.md similarity index 100% rename from docs/bug498_analysis.md rename to MD/bugs/BUG_498_ANALYSIS.md diff --git a/docs/bug-fixes/bug-632.md b/MD/bugs/BUG_632_ANALYSIS.md similarity index 100% rename from docs/bug-fixes/bug-632.md rename to MD/bugs/BUG_632_ANALYSIS.md diff --git a/docs/bug-fixes/bug-634.md b/MD/bugs/BUG_634_ANALYSIS.md similarity index 100% rename from docs/bug-fixes/bug-634.md rename to MD/bugs/BUG_634_ANALYSIS.md diff --git a/docs/bug-fixes/bug-644.md b/MD/bugs/BUG_644_ANALYSIS.md similarity index 100% rename from docs/bug-fixes/bug-644.md rename to MD/bugs/BUG_644_ANALYSIS.md diff --git a/docs/HIS项目Bug修复记录-v1.0.md b/MD/bugs/BUG_FIX_RECORD.md similarity index 100% rename from docs/HIS项目Bug修复记录-v1.0.md rename to MD/bugs/BUG_FIX_RECORD.md diff --git a/docs/DEVELOPMENT_PLAN_V2.md b/MD/development/DEVELOPMENT_PLAN_V2.md similarity index 100% rename from docs/DEVELOPMENT_PLAN_V2.md rename to MD/development/DEVELOPMENT_PLAN_V2.md diff --git a/docs/GRADE3A_DEVELOPMENT_PLAN.md b/MD/development/GRADE3A_DEVELOPMENT_PLAN.md similarity index 100% rename from docs/GRADE3A_DEVELOPMENT_PLAN.md rename to MD/development/GRADE3A_DEVELOPMENT_PLAN.md diff --git a/docs/MENU_FUNCTION_ANALYSIS.md b/MD/development/MENU_FUNCTION_ANALYSIS.md similarity index 100% rename from docs/MENU_FUNCTION_ANALYSIS.md rename to MD/development/MENU_FUNCTION_ANALYSIS.md diff --git a/docs/FLYWAY_USAGE_GUIDE.md b/MD/guides/FLYWAY_USAGE_GUIDE.md similarity index 100% rename from docs/FLYWAY_USAGE_GUIDE.md rename to MD/guides/FLYWAY_USAGE_GUIDE.md diff --git a/docs/specs/backend-checklist.md b/MD/specs/BACKEND_CHECKLIST.md similarity index 100% rename from docs/specs/backend-checklist.md rename to MD/specs/BACKEND_CHECKLIST.md diff --git a/docs/specs/cicd-gatekeeper.md b/MD/specs/CICD_GATEKEEPER.md similarity index 100% rename from docs/specs/cicd-gatekeeper.md rename to MD/specs/CICD_GATEKEEPER.md diff --git a/docs/specs/commit-template.md b/MD/specs/COMMIT_TEMPLATE.md similarity index 100% rename from docs/specs/commit-template.md rename to MD/specs/COMMIT_TEMPLATE.md diff --git a/docs/specs/frontend-checklist.md b/MD/specs/FRONTEND_CHECKLIST.md similarity index 100% rename from docs/specs/frontend-checklist.md rename to MD/specs/FRONTEND_CHECKLIST.md diff --git a/docs/specs/playwright-e2e-testing-plan.md b/MD/specs/PLAYWRIGHT_TESTING_PLAN.md similarity index 100% rename from docs/specs/playwright-e2e-testing-plan.md rename to MD/specs/PLAYWRIGHT_TESTING_PLAN.md diff --git a/docs/specs/his-release-checklist-v1.0.md b/MD/specs/RELEASE_CHECKLIST.md similarity index 100% rename from docs/specs/his-release-checklist-v1.0.md rename to MD/specs/RELEASE_CHECKLIST.md diff --git a/docs/三甲医院HIS系统标准规范汇编.md b/MD/standards/GRADE3A_HIS_STANDARD.md similarity index 100% rename from docs/三甲医院HIS系统标准规范汇编.md rename to MD/standards/GRADE3A_HIS_STANDARD.md diff --git a/docs/BACKEND_UPGRADE_PLAN.md b/MD/upgrade/BACKEND_UPGRADE_PLAN.md similarity index 100% rename from docs/BACKEND_UPGRADE_PLAN.md rename to MD/upgrade/BACKEND_UPGRADE_PLAN.md diff --git a/docs/MYBATIS_PLUS_UPGRADE_PLAN.md b/MD/upgrade/MYBATIS_PLUS_UPGRADE.md similarity index 100% rename from docs/MYBATIS_PLUS_UPGRADE_PLAN.md rename to MD/upgrade/MYBATIS_PLUS_UPGRADE.md diff --git a/docs/RUOYI_392_UPGRADE_CHECKLIST.md b/MD/upgrade/RUOYI_UPGRADE_CHECKLIST.md similarity index 100% rename from docs/RUOYI_392_UPGRADE_CHECKLIST.md rename to MD/upgrade/RUOYI_UPGRADE_CHECKLIST.md diff --git a/docs/UPGRADE_LOG.md b/MD/upgrade/UPGRADE_LOG.md similarity index 100% rename from docs/UPGRADE_LOG.md rename to MD/upgrade/UPGRADE_LOG.md diff --git a/docs/UPGRADE_PLAN_v2.0.md b/MD/upgrade/UPGRADE_PLAN_V2.md similarity index 100% rename from docs/UPGRADE_PLAN_v2.0.md rename to MD/upgrade/UPGRADE_PLAN_V2.md diff --git a/healthlink-his-server/AGENTS.md b/healthlink-his-server/AGENTS.md index 4d564ce30..f7337378c 100644 --- a/healthlink-his-server/AGENTS.md +++ b/healthlink-his-server/AGENTS.md @@ -25,3 +25,35 @@ ## 铁律 #4: 验证后信 每次修改后必须验证编译通过，不信记忆。 + +## 铁律 #5: 文档统一管理 +**所有文档必须存储在 `MD/` 目录中，遵循以下规范：** + +### 目录结构 +``` +MD/ +├── architecture/ # 架构设计 +├── development/ # 开发计划与记录 +├── standards/ # 国家/行业标准 +├── specs/ # 技术规范与流程 +├── bugs/ # Bug分析与修复记录 +├── guides/ # 使用指南 +└── upgrade/ # 升级记录 +``` + +### 命名规范 +- 文件名使用**大写英文+下划线**（如 `GRADE3A_DETAILED_DESIGN.md`） +- 不使用中文作文件名 +- 不使用空格分隔单词 +- 版本号标注在文件名末尾（如 `_V2`） + +### 格式要求 +- 文档头部必须包含元数据块（文档类型、版本、日期） +- 代码块必须标注语言类型 +- 表格使用标准Markdown格式 + +### 详细规范 +参见 `MD/DOCUMENTATION_STANDARD.md` + +## 铁律 #6: 测试通过后才提交 +**代码修改必须通过完整测试后才能提交到远程仓库。**