insar-management-system-v2/docs/DOCUMENTATION_GOVERNANCE.md

文档治理约定

最后更新：2026-05-28

1. 目标

本文件用于定义本仓库的文档治理规则，解决以下问题：

• 哪些文档是当前事实来源
• 哪些文档只是设计过程记录
• 哪些文档应归档而不是继续留在主导航里
• 新文档应如何命名、放置和维护

本文件是长期有效的治理约定，不是一次性的状态快照。

2. 事实来源优先级

当多个文档描述同一主题且内容不一致时，按以下优先级判断：

1. README.md 项目总览、当前架构收口、启动入口。

2. docs/INDEX.md 当前有效文档与历史参考文档的总入口。

3. 当前状态 / 部署 / 审计类文档 例如：

   • CURRENT_STATUS_*
   • DEPLOYMENT.md
   • *_AUDIT_*

4. 当前执行中的设计 / 规格文档 例如：

   • *_DESIGN_*
   • *_SPEC_*

5. 计划 / TODO / 实验 / 过程记录 例如：

   • *_PLAN_*
   • *_TODO_*
   • *_EXPERIMENT_*
   • 临时工作笔记

6. 已删除历史材料 旧 archive、实验记录和阶段计划已从当前文档树移除；需要追溯时使用 Git 历史。

3. 文档分类

3.1 长期有效文档

适合长期保留在 docs/ 根目录并放入 docs/INDEX.md 的文档：

• 总览：项目总览、部署说明、运行约束
• 状态：当前状态快照、健康检查摘要
• 审计：数据库、自维护、安全、代码库清理等审计结论
• 设计：当前仍在执行中的架构设计
• 规格：仍然有效的接口、产物、目录或包结构规范

3.2 过程型文档

通常不应作为主事实来源，除非 docs/INDEX.md 显式列入“当前有效”：

• 实施计划
• TODO 清单
• 阶段性实验记录
• 迁移草案
• 工作过程笔记

3.3 历史文档

满足以下任一条件时，应优先考虑删除；确需保留时才放入专门的历史目录：

• 已被更新文档明确取代
• 描述的是已结束阶段
• 只保留历史讨论价值，不再指导当前开发或部署

4. 放置规则

4.1 仓库根目录

根目录只保留高频入口或必须靠近项目根的文件：

• README.md
• .env.example
• 启动脚本
• 极少数确实需要放在根目录的说明文件

不应在根目录长期堆积阶段性分析、实验记录、临时修复说明。

4.2 docs/

docs/ 根目录用于放当前仍有导航价值的正式文档。

4.3 历史材料

默认不再长期堆积 docs/archive/。被当前实现取代的设计、计划、TODO 和实验记录应删除，让 Git 历史承担追溯职责。只有外部审计、交付或合规确实要求保留的历史材料，才单独建立历史目录并维护索引。

5. 命名规则

建议优先使用以下命名模式：

• CURRENT_STATUS_YYYYMMDD.md 当前状态快照

• *_AUDIT_YYYYMMDD.md 审计结论

• *_DESIGN_YYYYMMDD.md 当前设计

• *_SPEC.md 稳定规格

• *_PLAN_YYYYMMDD.md 计划文档

• *_TODO_YYYYMMDD.md 或 *_TODO.md 待办事项

• *_EXPERIMENT_YYYYMMDD.md 实验记录

规则：

• 有日期的文档应表达“状态时间点”或“阶段结论”。
• 没有日期的文档应尽量只用于长期有效的稳定说明。
• 如果文档已经明显是阶段性材料，不要再继续使用无日期命名。

6. 索引维护规则

每次新增或退役正式文档时，至少同步更新以下其中之一：

• README.md
• docs/INDEX.md

推荐规则：

• 新的正式文档进入 docs/ 根目录时，必须决定是否加入 docs/INDEX.md
• 文档失效时，必须从“当前有效”区移除
• 被取代文档默认删除；确需保留时必须说明保留原因并同步索引

7. 语言与编码规则

7.1 文档语言

当前项目以中文工程文档为主，这没有问题。

但为了降低终端编码、跨环境协作和代码审阅成本，建议：

• 代码注释与 docstring：默认使用 English
• 用户界面文案：可继续使用中文
• 面向本地团队的正式说明文档：可使用中文
• 如同一主题同时涉及代码约束与面向用户的描述，优先让代码侧说明保持 English

7.2 编码

文本文件建议统一使用：

• UTF-8
• 尽量无 BOM

如果 PowerShell 中看到乱码，不应立即判断源码损坏。应先：

1. 在编辑器中确认文件实际编码
2. 再决定是否需要修复源文件

8. INIT.md 的定位

INIT.md 视为“开发/运维工作笔记”，不是系统架构、部署或运行事实的最高依据。

使用原则：

• 可以记录当前机器、本轮修复、局部操作注意事项
• 不应替代 README.md 和 docs/INDEX.md
• 如果其中内容已经成为长期规则，应迁移到正式文档中

9. 当前建议的下一步整理方向

后续文档清理建议按以下顺序推进：

1. 保持 README.md 与 docs/INDEX.md 为主导航入口
2. 删除明确失效的阶段性文档
3. 收紧 docs/ 根目录，只保留当前仍需导航的文档
4. 逐步减少无明确角色的过程型文件