67 lines
4.8 KiB
Markdown
67 lines
4.8 KiB
Markdown
|
# 文档库命名规范提案（2026-09-23）
|
|||
|
|
|
|||
|
|
> **触发**：用户问「`04-` 是什么意思？文件夹命名规则不一致，里面文件命名五花八门」
|
|||
|
|
> **性质**：**诊断 ＋ 规范提案**。⛔ 本轮**未重命名 / 未移动任何档案**（147 个重命名属批量红线 ⇒ 先出方案再动手）。
|
|||
|
|
> **取证**：现读 `dsh-server-docs/04-调整方案/` 147 个文件 ＋ `README.md` / `INDEX.md` 的既有编号说明。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §一 `04-` 是什么（**文档库自己早有明文，不是命名失误**）
|
|||
|
|
|
|||
|
|
`README.md` 原文：
|
|||
|
|
|
|||
|
|
> **两套编号互不相同**：根级 `01/02/03/06` 是**长期文档**（架构、运维、路线图、UI 规范）；`04-调整方案/NN-` 是**一次性改造档案**。说「档案 NN」时**默认指后者**。
|
|||
|
|
|
|||
|
|
⇒ `04` = **文档库早期划分的第 4 个「分区」**（主题位，不是顺序位）；`05` **不存在**（历史跳号）。所以：
|
|||
|
|
- **`01/02/03/06/07/08/09-`＝常驻文档**（每类一份，编号固定）；
|
|||
|
|
- **`04-调整方案/NN-`＝一次性改造档案**（编号是**分区内流水号**，与根级编号是两套体系）。
|
|||
|
|
|
|||
|
|
## §二 现状诊断（147 个 `.md`，现读统计）
|
|||
|
|
|
|||
|
|
| 维度 | 分布 | 判定 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 扩展名 | `.md` **147/147** | ✅ 本来就统一（没"五花八门"到格式层面） |
|
|||
|
|
| 编号位数 | **两位 95 个**（`01-`…`99-`）＋ **三位 47 个**（`100-`…`149-`）＋ **无编号 5 个** | 🔴 **这是"乱"的真正来源** |
|
|||
|
|
| 排序 | 字符串序 ≠ 编号序 | 🔴 **`100-` 会排在 `10-` 与 `11-` 之间** ⇒ 目录列表看起来错乱 |
|
|||
|
|
| 编号连续 | 1..149 **缺 48 / 63 / 130 / 131 / 132**（5 个） | ⚠️ 断层（历史删除或改号留下） |
|
|||
|
|
| 分隔符 | 含 `-` 146/147；含 `_` 仅 1 处 | ✅ 基本一致（`-` 为主） |
|
|||
|
|
| 语言 | 含中文 146/147 | ℹ️ 中文命名是既有约定（可读性优先），非缺陷 |
|
|||
|
|
| 无编号件 | 5 个（含目录说明 `README.md`） | ⚠️ 需逐一看是什么，多半是说明/索引件 |
|
|||
|
|
|
|||
|
|
**一句话**：格式其实统一（全 `.md`、全 `-` 分隔、中文名），**真正的问题是「两位/三位混排 ⇒ 排序错乱」＋「5 个断层号」＋「5 个无编号件」**。
|
|||
|
|
|
|||
|
|
## §三 目标规范（提案）
|
|||
|
|
|
|||
|
|
1. **编号 = 三位零填充**：`NNN-<主题>.md`（`001-`…）⇒ 排序永远等于编号序。⚠️ 与"是否全量重排"绑定，见 §五 B。
|
|||
|
|
2. **主题写法**：`<动词或名词短语>-<限定词>`，内部一律 `-` 连接；⛔ 不用空格、⛔ 不用 `_`、⛔ 不用书名号与括号（搜索友好）。
|
|||
|
|
3. **编号只增不复用**：缺号**不补**（补号会让"档案 N"指代漂移）。
|
|||
|
|
4. **目录说明件**固定名 `README.md`（已满足）。
|
|||
|
|
5. **新档一律照本规范**；存量是否重排 = §五 拍板项。
|
|||
|
|
|
|||
|
|
## §四 迁移影响面（现读，供拍板用）
|
|||
|
|
|
|||
|
|
- 整仓对 `dsh-server-docs/04-调整方案` 的**路径引用 10 处**；`INDEX.md` / `README.md` / 各档案之间另有互引。
|
|||
|
|
- 🔑 **关键事实**：既有引用习惯用的是**短号**（`04-16` / `04-31` / `04-57` / `04-71`…），不是完整文件名 ⇒
|
|||
|
|
- **只改文件名的主题部分 ⇒ 短号引用不断**（风险低）；
|
|||
|
|
- **改编号体系（两位→三位 或 全量重排）⇒ 所有短号引用与人的记忆同时作废**（需逐个改，风险高）。
|
|||
|
|
- 另有生成物 `docs-manifest.json` 需重生成（⛔ 本轮未跑生成器）。
|
|||
|
|
|
|||
|
|
## §五 三个候选（真取舍 · 竖排）
|
|||
|
|
|
|||
|
|
**A 只约束新增（我倾向的第一半）**
|
|||
|
|
优点：零风险、旧档一动不动、`04-NN` 短号习惯与 10 处引用全部保住；乱象**不再恶化**。
|
|||
|
|
缺点：混排与断层**继续存在**，`100-` 依旧插在 `10-` 后。
|
|||
|
|
|
|||
|
|
**B 全量补零重排（`001-`…`149-`）**
|
|||
|
|
优点：排序彻底正确、观感统一，一步到位。
|
|||
|
|
缺点：**所有短号引用与人的记忆全废**（10＋处路径引用 ＋ INDEX 里的 `04-NN` 指代都要改）＋ 147 文件重命名属批量动作（红线）＋ 历史文档里"见 04-NN"的自述性表述无法机械替换 ⇒ 收益是观感，代价是全局。
|
|||
|
|
|
|||
|
|
**C 不重排、只加主题索引页（我倾向的第二半）**
|
|||
|
|
优点：**零改名零风险**，直接解决"找不到" —— 在 `04-调整方案/README.md` 生成一张按主题分组的索引表（插件投放 / 覆盖网络 / IM / UI / 部署 … ＋ 编号 ＋ 一句话用途）。
|
|||
|
|
缺点：物理顺序仍错乱（只解决可发现性，不解决排序观感）。
|
|||
|
|
|
|||
|
|
**倾向 = A ＋ C**：新档照规范（顺带把新档编号直接写成三位，`150-` 起天然有序），存量靠索引页导航；**B 留给"某天专门做一次文档库重排"的独立专项**。
|
|||
|
|
|
|||
|
|
## §六 本轮边界
|
|||
|
|
|
|||
|
|
⛔ 未改任何文件名、未移动任何档案、未跑 `docs-manifest.py`；本件仅诊断与提案。执行时按「一批 ≤10 个 ＋ 每批复核 ＋ 引用同步」进行。
|