研发开发规范 · 文档目录规范

本篇学习指南

读完你能

拿到一篇新文档，按五级判定确定它放哪
说清分支创建、合入、发版、删除各节点对应的文档动作
记住三个固定名文件与 doc/README.md 的更新时机

阅读时长

约 6 分钟 · 建议与 06 对照着读（同构）

前置知识

先读 01·03·06

读完

规范全部读完！回总览页查漏补缺

打个比方：doc/ 是「档案馆 + 图书馆」双系统

doc/branch/ 是档案馆：按事件立卷——一次变更一卷，只增不毁，哪怕分支删了、事件结束了，卷宗也永久留存。主题目录（指南 / 设计 / 规则）是图书馆：按主题上架，长期检索，旧版可被新版替换。doc/README.md 则是两套系统共用的总索引卡——不知道该去哪个书架时，先查它。

文档目录规范

规范定位与目标

本篇与 06·SQL 版本化的 SQL 目录规则同构——目录镜像分支树、生命周期与分支联动、唯一索引入口，但只管「文档放哪、怎么命名、何时产生与保留」；分支规则本体见 01/03，SQL 规则本体见 06。

三条目标（对齐 SQL 侧的「SQL 可回溯」）：

文档可追溯：任何文档能从路径直接判断它绑定哪条分支、或属于哪个主题。
生命周期联动：分支的每个节点（创建、合入、发版、删除）都有明确的文档动作。
唯一入口：doc/README.md 是 doc/ 的总索引，地位对应 sql/CHANGELOG.md。

为什么目录也要立规范？一篇文档放错地方，等于同时丢了两次：按分支路径找的人找不到它，按主题目录找的人也找不到它。SQL 侧早已用「目录镜像分支树 + CHANGELOG 唯一入口」解决了「放哪、在哪找」（06·SQL 版本化）；本篇把同样的思想在文档侧补齐。

文档放哪：五级判定（顺序自上而下，命中即停）

判定五连问 · 命中即停

客户定制？

doc/定制/<客户>/

驱动参考？

驱动设计文档/

变更记录？

doc/branch/…

长期参考？

指南 / 设计 / 规则

模块专区？

doc/<模块>/

顺序即优先级：先定制、再驱动、再变更、再主题、最后模块——命中任何一级立即停止，不再往下判定

顺序	判定	去向
1	是某客户定制的文档 / SQL	`doc/定制/<客户>/`（永不入 `doc/branch/` 与 `sql/`，见 03·定制隔离）
2	是某驱动的长期参考（功能设计、开发指南）	`doc/驱动设计文档/<驱动>/`
3	是某次变更的方案 / 分析 / 修复 / 验证记录	`doc/branch/<分支路径>/`（映射表）
4	是跨版本长期参考	操作 / 配置类 → `doc/指南/`；设计 / 架构类 → `doc/设计/`；工程规则类 → `doc/规则/`
5	属于某模块专区（授权、智问、websocket 等）	`doc/<模块>/`

判定核心：内容是「一次变更的记录」，还是「跨版本长期有效的参考」？前者随分支走，后者按主题走。

晋升机制：分支文档中的长期价值内容（如驱动的属性设计说明），在合入 release 时晋升到主题目录，分支目录保留原文或留指针。禁止把长期参考只留在分支目录里——分支删了照样找得到，但没人知道去哪找。

目录结构总览（与 sql/ 同构）

tree

doc/
├── README.md                     # 总索引（唯一导航入口）
├── branch/                       # ── 分支绑定大区：镜像分支树 ──
│   ├── feature/<版本>/<语义>/     # feature 方案 / 设计 / 验证记录
│   ├── hotfix/<版本>/<语义>/      # 修复方案 / 分析 / 验证记录（门禁产物）
│   └── tag/<版本>/                # 发版说明.md（随发版一次性产出）
├── 定制/<客户>/                   # 按客户组织，不镜像分支
├── 指南/  设计/  规则/            # 跨版本主题目录
├── 驱动设计文档/<驱动>/            # 驱动参考库（纯文档，不含执行用 SQL）
└── 授权/  智问/  websocket/ …     # 模块专区

目录即归属：ls doc/branch/hotfix/2.1.0/ 即知该版本所有现场修复记录，与 git branch -a 的分支树可逐层对照——这与 sql/ 的设计思想完全一致（06·目录即归属）。

发版产物只新增说明、不复制：SQL 侧发版要把脚本全量复制冻结为 sql/tag/<版本>/，文档侧 tag 目录只新增一篇 发版说明.md——SQL 复制是为了「同版本号 = 同一套脚本」，文档没有这个等值需求。

分支 ↔ 文档目录映射表

分支 / 节点	文档目录	定位
`release/<版本>`	无常设目录	版本汇总视图由 `sql/CHANGELOG.md` + `doc/README.md` 承担；发版产物落 tag 目录
`feature/<版本>/<语义>`	`doc/branch/feature/<版本>/<语义>/`	开发期方案、设计、验证记录；合入后原地保留，长期内容晋升
`hotfix/<版本>/<语义>`	`doc/branch/hotfix/<版本>/<语义>/`	修复方案、分析报告、`验证记录.md`（回流门禁，03·规则二）；分支删除后保留
tag `vX.Y.Z`	`doc/branch/tag/<版本>/`	`发版说明.md`（变更清单、升级步骤、已知问题），发版当天产出
维护性微版本 `release/<X.Y.Z>.<N>`	`doc/branch/tag/<X.Y.Z>.<N>/`	同 tag：发版说明 + 随附修复记录（无常设分支目录）
`custom/<版本>/<语义>`	`doc/定制/<客户>/`	不入 `doc/branch/`（按客户组织，03·定制隔离）
`line/` 产品线四段式	`doc/branch/<前缀>/<产品>/<版本>/<语义>/`	插产品代号段、用自身版本号（01·产品线分支），如 `doc/branch/feature/eos/1.1.0/<语义>/`
`dev/<人名>`	❌ 不入 `doc/`	个人临时实验（≤3 天），不留档

生命周期：分支每个节点的文档动作

创建：目录随首个文档创建，不预建空壳。与 sql/feature/ 的 README 占位锚定不同——SQL 需提前锚定序号归属防并行冲突，文档无此需求。
门禁产物：验证记录.md 是固定文件名，从模板复制填写；无该记录不得回流（03·规则二，记录模板见 09·现场验证记录）。
合入：文档不汇总、原地保留——与 SQL 相反（SQL 按主题并入序号文件后清空草稿目录）。合入时执行晋升动作：长期内容移入主题目录，分支目录留指针，同步更新 doc/README.md。
发版：按发版检查单阶段三完成 doc/branch/tag/<版本>/发版说明.md；阶段四更新 doc/README.md 索引（检查单见 09·发版检查单）。
删除：分支合并删除后，其文档目录保留（SQL 清空壳、文档留全档）。确属废弃的错误文档才删除，并在 doc/README.md 摘除条目。
新增 SQL 一律进 sql/：doc/ 下不再新增执行用 SQL（定制 SQL 除外，按 03 放 doc/定制/）。存量遗留 SQL 的汇总归档见历史问题与迁移任务。

为什么 SQL 要汇总、文档不汇总？SQL 是「要执行的资产」——多一份副本，现场就多一个可能被执行的真相源，必须并成一份；文档是「历史的证词」——每篇都是当时的记录，合并反而毁灭信息。所以 SQL 合入后清空草稿目录，文档合入后原地全留。

与 SQL 生命周期对照（关键差异一表看清）

维度	SQL（06）	文档（本篇）
feature 期落位	`sql/feature/<版本>/<语义>/` 草稿	`doc/branch/feature/<版本>/<语义>/` 生长
合入 release	按主题汇总进序号文件，清空草稿目录	原地保留；长期内容晋升主题目录
发版	复制冻结为 `sql/tag/<版本>/`	只新增 `doc/branch/tag/<版本>/发版说明.md`，不复制
分支删除	清理空壳	目录保留（历史即价值）
唯一权威	`sql/CHANGELOG.md`（登记：顺序、现场执行）	`doc/README.md`（导航：目录、去向）

命名规则与固定名三件套

目录命名：分支绑定目录目录名 = 分支语义段（中文短语或英文小写连字符，禁空格，见 01·分支命名），保证 doc/branch/ 树与分支树逐层对照；主题 / 模块目录沿用现有命名，新增主题目录须同步登记进 doc/README.md。

固定名三件套（不可改名，工具与流程按名检索）：

固定文件名	位置	作用	强制性
`验证记录.md`	`doc/branch/<分支路径>/`	回流门禁产物（03·规则二）	feature / hotfix 回流必填
`发版说明.md`	`doc/branch/tag/<版本>/`	发版交付物（变更清单、升级步骤、已知问题）	打 tag 必填
`README.md`	`doc/branch/<分支路径>/`	该分支多文档时的导读	可选

一般文档：<主题>.md，可中文，建议含主题关键词（如 knx隧道假死优化修复.md、Rcp内存泄漏分析报告.md）。每个新建 .md 首行下方统一信息块：

markdown

# <标题>
> 作者：xxx　日期：YYYY-MM-DD　版本：v1.0　关联分支：feature/2.1.1/<语义>（分支文档必填）

为什么固定名不可改？门禁与流程按文件名检索：回流审查查的就是「验证记录.md」这个名字，发版核查查的就是「发版说明.md」。文件一改名，检查瞬间「看不见」它——记录还在，门禁却失效了。

总索引 doc/README.md

地位对应 sql/CHANGELOG.md，但角色是导航而非登记——文档没有执行顺序与现场状态需要记录，要维护的只有「有哪些目录、各自去向是什么」。

更新时机（三选一命中即更新）：

doc/ 一级目录或 branch/ 下的版本 / 语义目录新增或删除；
发生晋升（分支文档移入主题目录）；
发版归档（新增 doc/branch/tag/<版本>/）。

新手常见问题

「这文档放哪」是日常最高频的困惑，提前看

写了一篇新文档，怎么最快决定放哪？

五级判定按顺序问，命中即停：① 客户定制？→ doc/定制/<客户>/；② 某驱动的长期参考？→ doc/驱动设计文档/<驱动>/；③ 某次变更的记录？→ doc/branch/<分支路径>/；④ 跨版本长期参考？→ 指南 / 设计 / 规则按内容性质分；⑤ 某模块专区？→ doc/<模块>/。拿不准时回到判定核心：「一次变更的记录」还是「跨版本参考」；仍拿不准就查 doc/README.md，看同类文档放在哪。

分支都删了，它的文档目录为什么还留着？

文档是历史记录——尤其 hotfix 的现场修复记录，是日后排查同类问题的第一手线索。SQL 侧合入后清空草稿目录，是因为真相已经汇总进序号文件；文档没有「汇总」这个动作，目录本身就是档案，删了信息就没了。确属写错的废弃文档才删除，并同步在 doc/README.md 摘除条目。

什么叫「晋升」？什么时候做？

分支文档里长期有效的内容（比如驱动的属性设计说明），在分支合入 release 时移入主题目录，分支目录保留原文或留指针，并更新 doc/README.md。判定标准：半年后还有人要查的内容，就该晋升。不做晋升的后果是「分支删了照样找得到，但没人知道去哪找」——文档实际等于丢了。