docs(编号规范): 新增 P-8 语义优先与语义标识规范（§3.3 / §5.7）
规划 / 待办类条目改以一行短语作标识，不再分配字母+数字号： - §2 加 P-8「语义优先」，七条原则变八条 - §3 主轴由"两层编号"扩为 编号 / 语义标识 / 章节引用 三种形态 - 新增 §3.3 形态规则与适用分界：TC / TRAP / FR / NFR 等需机器 解析或作历史证词的仍保留编号，并强制带语义括注（P-7） - 新增 §5.7 登记、冻结与别名规则：短语即标识，改措辞等于换 ID； 销项 = 删行 + 清全库引用，短语不复用 - §4.2 加修订说明，§9 加「0.5 语义标识」迁移阶段 起因：N-31 销项删行后按"现存最大值 +1"又被取走，与两处历史引用 撞号（见 docs/任务规划/README.md §0）。 注：本文件不是 R-9 会话所改，按"全部提交"一并入库。
This commit is contained in:
+71
-2
@@ -45,7 +45,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 七条设计原则（强制）
|
||||
## 2. 八条设计原则（强制）
|
||||
|
||||
| # | 原则 | 理由 |
|
||||
|---|---|---|
|
||||
@@ -56,19 +56,24 @@
|
||||
| **P-5** | **只增不复用**；每个类别有「下一个可用号」游标（`[计划] scripts/id_registry.json`），新增先取游标 | 并行任务与多文档同时新增时防撞号（《项目审查与优化建议报告》与登记簿并轨时 `N-16` 撞过号，就是没有游标——见 `docs/任务规划/README.md` §0） |
|
||||
| **P-6** | **引用必须机器可判定**：跨文档引用用行内代码，首次出现紧邻属主文档名；文档内编号**必须**带文档名 | 与 `§N.M` 同一条路：能校验的约定才算存在 |
|
||||
| **P-7** | **编号不语义，引用必语义**：编号本体保持无语义并冻结（同 P-2）；但**正文引用必须带语义括注**——`TRAP-NET-18（异常释放后排空 RX 残渣）`、`docs/网络/网络自愈架构设计.md` §4.6（应用主动拆会话保监听）；**禁止裸 ID 单独承担信息**。语义放括注，事实变了只改括注、编号不变 | 读者不该为看懂一句话去跳三篇文档。可读性由**引用方式**解决，不由**编号命名**解决——命名带语义会重蹈 `P1-x` 覆辙（§1.2）。落地见 §5.6 |
|
||||
| **P-8** | **语义优先**：规划 / 待办类条目**优先用语义标识**（§3.3）——一行短语即标识，不分配字母+数字号；只有**需机器解析**或**作历史证词**的类别才发编号，且引用时强制带语义括注（P-7） | 编号的唯一性维护成本已实测超过收益：`N-31` 销项删行后按"现存最大值 +1"又被取走，与两处历史引用撞号（`docs/任务规划/README.md` §0）。短语自带唯一性（重名一眼可见），且读者不必跳表查号 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 主轴：两层编号
|
||||
## 3. 主轴：编号 / 语义标识 / 章节引用
|
||||
|
||||
| 层 | 适用事物 | 形态 | 引用规则 | 门禁校验 |
|
||||
|---|---|---|---|---|
|
||||
| **全局编号** | 会跨文档流转：需求、缺陷、待办、决策、风险、测试用例、陷阱记录 | 全局唯一前缀 + 全局序号 + **唯一属主登记处** | 行内代码；跨文档首次出现紧邻属主名 | 全库唯一；必须能在属主表查到定义行 |
|
||||
| **文档内编号** | 只在定义它的那篇文档内有意义：状态机组合、方案档位、专项风险、专项阶段 | 允许存在，前缀带类别码，**号段文档内独立** | **必须紧邻文档名**（同 `§N.M` 紧邻规则） | 校验"该文档内确有此编号" |
|
||||
| **语义标识**（§3.3，**规划 / 待办类默认**） | 登记簿条目、任务卡、待确认、风险、决策、缺陷、工作项、差距、验证场景 | **一行短语即标识**，不分配字母+数字号；≤20 汉字 | 同文档内写短语；跨文档紧邻属主文档名 | 同表内去重（同义异写算撞名）；引用查不到 = 悬空 |
|
||||
|
||||
### 3.1 判定口诀
|
||||
|
||||
> **会不会在别的文档里被引用？会 → 全局编号；不会 → 文档内编号，且引用必须带文档名。**
|
||||
>
|
||||
> **前置一步（P-8）**：规划 / 待办类条目先问"能不能用一行短语说清是什么事"——
|
||||
> **能 → 用语义标识（§3.3），不发编号**；只有需机器解析（`TC`）或作历史证词（`TRAP`）才进上面的判定。
|
||||
|
||||
现状的病根正是把该全局的（发现、待办）做成了文档内编号（各文档自造 `O1~O4`、`A1~A6`），又把该文档内的（设计决策 `D1~D7`、状态机 `U1~U15`）做成了裸形全局编号。
|
||||
|
||||
@@ -81,6 +86,47 @@
|
||||
|
||||
各设计文档的"本期不做 / 遗留可选项"清单（现状 `O1~O4` 四篇文档四义）**默认不造编号**，改用 §小节引用；确需逐条引用时才启用文档内编号 `OOS-<nn>`。
|
||||
|
||||
### 3.3 语义标识（新条目默认形态）
|
||||
|
||||
> **立场**：编号是"确需跨文档长期引用"才付的成本（§5.1 第 0 步）。规划与待办类条目
|
||||
> 生命周期短、销项即删行，编号带来的唯一性维护成本已实测超过收益——`N-31` 销项删行后
|
||||
> 按"现存最大值 +1"又被取走，与两处历史引用撞号（详见 `docs/任务规划/README.md` §0）。
|
||||
> **这类条目改用语义标识：一行短语本身就是标识，不再分配字母+数字号。**（原则见 P-8）
|
||||
|
||||
**形态规则**（强制）：
|
||||
|
||||
| 项 | 规则 |
|
||||
|---|---|
|
||||
| 构成 | 主语 + 症状/动作，直接说清是什么事：`49s 日志静默`、`USART1 TX-only 根治`、`dhara is_free/copy 判据` |
|
||||
| 长度 | **≤20 个汉字**（或 ≤40 个 ASCII 字符），一行写完 |
|
||||
| 禁用 | 不含 `\|`（表格安全）、不换行、不以 `-` 结尾、不带序号后缀（`日志静默-1` 非法） |
|
||||
| 不含易变属性 | 严重度、状态、日期、负责人、波次一律写进表格列，不进标识（同 P-2） |
|
||||
| 唯一性 | 同一属主登记处内唯一；**同义异写视为撞名**（`日志静默` 与 `49s 日志静默` 只能留一条） |
|
||||
| 冻结 | 措辞一经登记即**冻结**；确需改写在原行加"别名"列，旧措辞保留可查（§5.7） |
|
||||
|
||||
**适用分界**（强制）：
|
||||
|
||||
| 域 | 条目 | 标识形态 |
|
||||
|---|---|---|
|
||||
| **规划 / 待办**（转语义） | 登记簿条目（原 `N-x` / `S-x` / `T-x`）、排期任务卡（原 `B` / `C` / `D`）、待确认（`OQ`）、风险（`RSK`）、决策（`DR`）、缺陷（`DEF`）、工作项（`WI`）、模拟器差距（`GAP`）、验证场景（`SC`） | **语义标识** |
|
||||
| **机器解析 / 历史证词**（保留编号） | `TC-*`、`TRAP-*`、`FR-*` / `NFR-*`、`RC-*` | **编号 + 强制语义括注**（P-7） |
|
||||
| **历史冻结族**（§4.3） | `E-xx`、报告自有编号、`S1~S14`、`A-1~A-7`、`P0-x`~`P3-x` | 不回改，走别名表 |
|
||||
|
||||
> ⚠ **为什么 `TC-*` 不能转语义**（硬约束，勿试）：`scripts/check_test_traceability.py`
|
||||
> 用 `TC-[A-Z]{1,4}-\d{3,4}` 做可追溯性比对；`test/host/ch395f_socket_test.py` 把
|
||||
> `TC-NET-602` 打进运行日志；板级 `test/board/ch395f_test_task.c` 直接把它编进 C 宏名
|
||||
> `PHASE2_TC203_TIMEOUT_MS`。语义短语进不了宏名，也做不了正则排序。
|
||||
> `TRAP-*` 同理不转：196 处文档 + 122 处代码引用，是历史证词的高频锚点。
|
||||
|
||||
**引用写法**：
|
||||
|
||||
| 场景 | 写法 |
|
||||
|---|---|
|
||||
| 登记处表内 | `` `49s 日志静默` ``（`#` 列填短语本身，不再填号） |
|
||||
| 跨文档 | `` `docs/任务规划/登记簿.md` 的 `49s 日志静默` ``（紧邻文档名，同 §N.M 规则） |
|
||||
| 代码注释 | 允许，但**必须带属主文档名**（同 §5.3），如：（登记簿 `8 路电气量分属两片转换器`） |
|
||||
| 销项 | 删行 + 清全库引用；短语**不复用**（同"号不回收"，见 §5.7） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 编号空间总表
|
||||
@@ -102,6 +148,11 @@
|
||||
|
||||
### 4.2 目标前缀（阶段 1 改名后启用）
|
||||
|
||||
> **2026-10-15 修订（依 P-8 / §3.3）**：本表中**规划 / 待办类**前缀在阶段 1 落地时改为
|
||||
> **语义标识**形态（不再分配序号）——`DEF` / `WI` / `OQ` / `RSK` / `DR` / `MS` / `GAP` / `SC`；
|
||||
> **需机器解析或作历史证词**的保留编号——`TC` / `TM` / `DP` / `TRAP` / `FR` / `NFR` /
|
||||
> `RC` / `GEN` / `RUN`，引用时强制带语义括注（P-7）。下表的"游标"列对转语义的前缀不再适用。
|
||||
|
||||
| 新前缀 | 类别 | 收编的旧编号 | 新属主登记处 | 游标 |
|
||||
|---|---|---|---|---|
|
||||
| `DEF-<nnn>` | 缺陷 / 问题发现 | `P0-x`~`P3-x`（在册项）、新发现 | `[计划] docs/问题记录/缺陷登记簿.md` | `DEF-001` |
|
||||
@@ -210,6 +261,22 @@
|
||||
此时该文档即其**唯一可查处**。
|
||||
- 与 P-7 配套：**正文引用带语义括注**（局部可读）+ **对照节给编号族总览**（全局可查），两者合起来才算看得懂。
|
||||
|
||||
### 5.7 语义标识的登记、冻结与别名
|
||||
|
||||
- **登记**：在属主登记处新增一行，`#` 列填短语本身；落笔前先 `grep` 确认同表内无同名 /
|
||||
同义条目（同义异写 = 撞名，见 §3.3 形态规则）。
|
||||
- **冻结**：短语即标识，**改措辞等于换 ID**。确需改写时在原行加「别名」列，新旧措辞并存，
|
||||
引用侧同步替换完成后再删旧名——**禁止原地改写且不留下别名**。
|
||||
- **历史编号迁移**：编号转语义标识时，原号进别名表（例：`N-18` → `8 路电气量分属两片转换器`）；
|
||||
历史文档中的裸号**不回改**（§5.5 同款处置）。
|
||||
- **销项**：删行 + 清全库引用（沿用 `docs/任务规划/README.md` §3 与 `AGENTS.md` 既有规则）；
|
||||
短语**不复用**——重名即视为同一条目，与"号不回收"同理（撞名风险高于撞号，故由门禁兜底）。
|
||||
- **代码注释**：语义短语可进代码注释（中文注释允许），但必须带属主文档名（同 §5.3）；
|
||||
现状 `App/algo/` 下 `N-18` 等 6+ 处**裸编号引用违反 P-7**，迁移时一并补语义。
|
||||
- **门禁**（待落地）：① 同一登记处内短语去重；② 引用了登记处不存在的短语 = 悬空，报错；
|
||||
③ 打印「语义标识可判定比例」，只许涨不许跌。校验脚本 `[计划] scripts/check_ids.py`
|
||||
尚未落地（§8），落地前由人工 + `grep` 执行上述三条。
|
||||
|
||||
---
|
||||
|
||||
## 6. 模块码表（`TC` / `TM` / `DP` / `TRAP` 共用）
|
||||
@@ -316,6 +383,7 @@ git grep -n '<旧字面量>' # 零残留
|
||||
| 阶段 | 内容 | 验收判据 | 风险 |
|
||||
|---|---|---|---|
|
||||
| **0 规范** | 本文件；`docs/任务规划/README.md` §0 改为指向本规范的摘要；`docs/README.md`、`AGENTS.md`、`docs/文档规范.md` §6 登记；两份 `id_*.json` 初版 | `check_doc_links --all` 通过、`@build` 0/0 | 零（纯新增 + 指针） |
|
||||
| **0.5 语义标识** | §3.3 / §5.7 规范落地：登记簿、排期、波次的**存量条目转语义短语**（原号进别名表，`N-x`/`S-x`/`T-x`/`B`/`C`/`D`）；代码注释裸编号（如 `N-18`）补语义；`DEF`/`WI`/`OQ`/`RSK`/`DR`/`GAP`/`SC` 按语义形态启用 | 每批：dry-run 通读 → 落盘 → `git grep` 零残留 → `check_doc_links --all` → `@build` 0/0 | 中（撞名与措辞漂移是主要风险） |
|
||||
| **1-① 小族** | `RC`/`PAT`/`GEN`/`RUN`/`MS`/`GAP`/`SC`/`OQ`/`RSK`/`DR`/`TRAP`/`ST`/`UL`/`LAT`/`CS` + Mermaid 节点 id + 孤儿处置 | 每批：dry-run 通读 → 落盘 → `git grep` 零残留 → `check_doc_links --all` → `@build` 0/0 → `ci_local.py` | 中 |
|
||||
| **1-② 大族** | `N` 补零 + `S`/`T` 并入；`WI` ← `B`/`C`/`D`/`W1-0`/`S1x`/`A-x`/`R-x`/`F-x`/`U-x`；测试分层 `L0~L3` → `T0~T3`（**最大机械批次**，`L0.5` 一词全库百余处） | 同上，逐族一个 commit | **高** |
|
||||
| **1-③ 缺陷族** | `DEF` ← `P0-x`~`P3-x` 在册项；报告历史编号补齐紧邻文档名；档位词规则落地；别名表与游标定稿 | 同上 | 中 |
|
||||
@@ -344,3 +412,4 @@ git grep -n '<旧字面量>' # 零残留
|
||||
|---|---|---|
|
||||
| 2026-10-14 | 新增 P-7 与引用可读性规则 | §2 加 **P-7「编号不语义，引用必语义」**（编号本体保持无语义并冻结，但正文引用必须带语义括注、禁裸 ID 独担信息）→ 六条原则变**七条**；§5.1 加前置步"先问能不能不加号"；新增 **§5.6「编号密集文档的对照节（强制）」**（≥3 个编号族必须加「导读：编号与术语」）；§4.1 补登记 **`E\d+`**（N34 自愈实验编号族，已封闭）并把 `N-\d{2}` 的在册范围订正为「曾用最大 `N-33`，现存至 `N-29`」；§1.2 悬空引用示例补 `N-32`；§7.1 同步订正。起因：`docs/网络/网络自愈架构设计.md` 合并与导读节实践暴露"裸编号引用不可读"，用户裁定以后尽量用语义标识 |
|
||||
| （规划稿） | 建立本文档 | 全库扫描 1,385 个不同编号 / 19,306 处出现后定稿的两层编号体系（全局编号 + 文档内编号）、六条原则、目标前缀总表、三批迁移映射与 `check_ids.py` 门禁设计；用户决策：`E-xx` 冻结保留、严重度档位词 `P0~P3` 不变、文档落 `docs/编号规范.md`、阶段 1 三批全做 |
|
||||
| 2026-10-15 | 新增 P-8 与语义标识规范（§3.3 / §5.7） | §2 加 **P-8「语义优先」**（规划 / 待办类条目优先用语义标识，不发字母+数字号）→ 七条原则变**八条**；§3 主轴由"两层编号"扩为**编号 / 语义标识 / 章节引用**三种；新增 **§3.3「语义标识（新条目默认形态）」**（形态规则、适用分界、引用写法）与 **§5.7「语义标识的登记、冻结与别名」**；§4.2 加修订说明（规划类前缀改语义标识，`TC`/`TRAP`/`FR`/`NFR`/`RC` 等保留编号）；§9 加「0.5 语义标识」阶段。起因：用户裁定去除字母数字编号（难理解），先定规范本体 |
|
||||
|
||||
Reference in New Issue
Block a user