From 74bf338328c4840c502d7fd7e62eddc530a26589 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Mon, 12 Oct 2026 18:10:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BC=96=E5=8F=B7=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E8=A7=84=E5=88=92=E7=A8=BF=EF=BC=88=E5=AE=9E=E4=BD=93=E7=BC=96?= =?UTF-8?q?=E5=8F=B7=E4=BD=93=E7=B3=BB=E9=87=8D=E5=86=99=EF=BC=8Ccheck=5Fi?= =?UTF-8?q?ds.py=20=E8=A7=84=E5=88=92=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 划界：实体编号 vs C 标识符/位号/章节号；§2~§5 强制（规划机械校验）， §6~§10 约定 + 迁移计划；状态 = 规划稿（阶段 1 落地前未生效） - 本提交为 Lead 代提交（用户批准）：文件由并行会话 17:56 写完静置， 阻塞 task-worktree done 的主工作树干净前置检查 --- docs/编号规范.md | 314 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 docs/编号规范.md diff --git a/docs/编号规范.md b/docs/编号规范.md new file mode 100644 index 00000000..70b19cd3 --- /dev/null +++ b/docs/编号规范.md @@ -0,0 +1,314 @@ +# 编号规范 + +> **适用对象**：本仓库全部 Markdown 文档、C/Python/脚本源码注释、提交信息中出现的**实体编号**（`E-44`、`N-21`、`TC-NET-601`、`FR-STO-1`、`Trap 07` 这类"字母 + 数字"的条目身份标识）。 +> **不适用**：C 语言标识符（`g_`/`s_`/`PS_*`/`TEST_SUITE_*`）、元器件位号（`U1`/`C12`/`R3`）、章节号（`§3.2`，归 [`docs/文档规范.md`](文档规范.md) §3.5 管）——见下文「划界」一节。 +> **强制程度**：§2~§5 为**强制**（规划由 `scripts/check_ids.py` 机械校验）；§6~§10 为**约定 + 迁移计划**。 +> **相关文档**：[`docs/文档规范.md`](文档规范.md)（链接/章节/门禁总规范）、[`docs/任务规划/README.md`](任务规划/README.md) §0（本规范的登记簿摘要）、[`docs/测试说明/测试文档模板规范.md`](测试说明/测试文档模板规范.md) §6（测试侧编号细则）。 +> **状态**：本文件是**规划稿**——§4 的目标前缀与 §7 的迁移映射在阶段 1 落地前尚未生效，落地进度见 §9。 + +--- + +## 1. 为什么要重写编号体系 + +### 1.1 病根：前缀按"来源"分配，不按"事物类别"分配 + +每来一次审计/复审/专项，就自造一套前缀，字母很快瓜分殆尽： + +| 来源 | 自造的前缀 | +|---|---| +| 2026-09-21 错误码传播审计 | `E-xx`、缺陷模式 `P1~P9`、严重度 `P0~P2` | +| 2026-09-15/09-21 代码审计 | `P0-x` ~ `P3-x`（严重度直接进编号） | +| 2026-09 项目审查与优化建议报告 | `N-xx`、`D-x`、`S-x`、`R-x`、`F-x`、`U1~U5` | +| 台架与长期观察 | `N-x`、`S-x`、`T-x`、`gen`、`round`、`V2/V4/V5` | +| 2026-10-02 复审 | `S1~S14`、`A-1~A-7` | +| 任务规划 | `W`、`B\d`、`C\d`、`D\d`、`M\d` | +| 各模块陷阱/设计文档 | `Trap NN`、`陷阱 N`、`D1~D10`、`O1~O6`、`U1~U15`、`①~④` | + +**后果**：同一字母被 3~5 个来源共用，编号本身不再能定位事物。 + +### 1.2 已确证的事故（全部有仓内证据，非假想） + +| 类型 | 实锤 | +|---|---| +| **同字母多义** | `P1` 五义（缺陷模式 / 严重度 / 审计条目 `P1-8` / 用例优先级 / `ch395f_test_task.c` 的 Phase1 测试项 `P1-01`）；`L1` 四义（算法层 / 测试分层 / UI 四层 / CubeMX 三层）；`U1` 四义；`O4` 四篇文档四义 | +| **同一文件内双义** | `实机测试实施指南.md` 的 `A2/A3/A4` 既是环境预检项（§2）又是已完成事项（§10） | +| **连字符/补零偷偷承载语义** | `R1`=风险、`R-2`=内存优化项；`D7`=验证窗口、`D-7`=文档门禁、`D1~D7`=设计决策；`N-2`（登记簿）与 `N-02`（报告）同号不同义 | +| **跨文档同号不同义** | `Trap 02` 在 CH395F 是"缓冲区重叠"、在 GD5F 是"测试缓冲越界"；`B10` 在规划是"送检窗口"、在陷阱审计是"孤儿监听" | +| **语义进编号 → 事实一变编号就撒谎** | `P1-x` 把严重度写进号里，而审计中大量条目事后降级（`E-59` P0→P1、dhara `is_free` P1→P2）：改号则引用全断，不改则号实不符 | +| **孤儿编号（代码有、文档无）** | `I-1`/`I-2`、`Task #32` 会话号、`P1-01~P1-09`、`TC-GD5F-1100/1101/1102`、`TC-STO-06`、`TC-AH-*`、`TC-PE-*`（前两项项目已在 `docs/测试说明/实机测试实施指南.md` 自行承认） | +| **悬空引用（引用了不存在的号）** | `Trap 19` 从未存在却被 `docs/测试说明/CH395F_Test_Guide.md` 引用；`N-5/N-8/N-19/N-30/N-31` 销项删行后仍被引用 | +| **同一事物多种字面** | `Trap 07` / `TRAP-07` / `陷阱 1`；`gen 181` / `gen-288` / `gen68`；`TC-NET-704` / `TC704` / `TC-203` | +| **规范自身就不自洽** | `docs/测试说明/测试文档模板规范.md` §6.3 同一行并列 `TC-STO-03`（2 位）与 `TC-RTC-001`（3 位）；`docs/测试说明/测试文档模板规范.md` §6.2 已废止 `PHY` 模块码，而阶段 ID 至今仍是 `TM-PHY-01` | +| **机器校验只覆盖一个族** | 31 个 pre-commit 钩子中只有 `TC` 有 `scripts/check_test_traceability.py`，且**未挂钩子、warn-only、正则 `TC-[A-Za-z0-9]+-\d+` 匹配不到 `TC-AI-01A`**；`E/N/S/B/C/D/A/U/O/gen/Trap` 全部裸奔 | + +> **可借鉴的先例**：`§N.M` 章节引用当年 1,578 处也全靠自觉，靠「紧邻写法 + 别名表 + 可判定比例 + 钩子」把可判定比例做到 58% 并转为拦提交（[`docs/文档规范.md`](文档规范.md) §3.5）。编号走同一条路径即可收口。 + +--- + +## 2. 六条设计原则（强制） + +| # | 原则 | 理由 | +|---|---|---| +| **P-1** | **前缀 = 事物类别，不是来源文档/审计轮次**。来源是登记簿的「出处」列，不进编号 | 否则每轮审计都造一套新字母，必然瓜分殆尽 | +| **P-2** | **编号不携带语义**：严重度、状态、日期、负责人、波次一律是表格列 | 降级只改列，编号永不变、引用永不断（`P1-x` 的历史教训） | +| **P-3** | **一个前缀只有一个属主登记处**；前缀一经分配**永不复用给别类**，号段用尽即扩位（`N-99`→`N-100`），绝不换字母 | 保证"看到前缀就知道去哪张表查" | +| **P-4** | **形态唯一**：`<前缀>-<序号>`；前缀 1~3 位大写字母；序号位数按类别固定并左补零；子项只允许一级 `-<小写字母>`。**禁止**裸形（`S3`）、空格形（`Trap 07`）、中文形（`陷阱 1`）、圈号（`①②③④`） | 连字符与补零不得承载语义；字面唯一才能被机器判定 | +| **P-5** | **只增不复用**；每个类别有「下一个可用号」游标（`[计划] scripts/id_registry.json`），新增先取游标 | 并行任务与多文档同时新增时防撞号（`docs/问题记录/项目审查与优化建议报告.md` 变更记录自述"并轨时未做全局唯一性检查"就是没有游标） | +| **P-6** | **引用必须机器可判定**：跨文档引用用行内代码，首次出现紧邻属主文档名；文档内编号**必须**带文档名 | 与 `§N.M` 同一条路：能校验的约定才算存在 | + +--- + +## 3. 主轴：两层编号 + +| 层 | 适用事物 | 形态 | 引用规则 | 门禁校验 | +|---|---|---|---|---| +| **全局编号** | 会跨文档流转：需求、缺陷、待办、决策、风险、测试用例、陷阱记录 | 全局唯一前缀 + 全局序号 + **唯一属主登记处** | 行内代码；跨文档首次出现紧邻属主名 | 全库唯一；必须能在属主表查到定义行 | +| **文档内编号** | 只在定义它的那篇文档内有意义：状态机组合、方案档位、专项风险、专项阶段 | 允许存在，前缀带类别码，**号段文档内独立** | **必须紧邻文档名**（同 `§N.M` 紧邻规则） | 校验"该文档内确有此编号" | + +### 3.1 判定口诀 + +> **会不会在别的文档里被引用？会 → 全局编号；不会 → 文档内编号，且引用必须带文档名。** + +现状的病根正是把该全局的（发现、待办）做成了文档内编号（各文档自造 `O1~O4`、`A1~A6`），又把该文档内的（设计决策 `D1~D7`、状态机 `U1~U15`）做成了裸形全局编号。 + +### 3.2 编号 vs 章节引用 + +| 条目特征 | 用什么 | +|---|---| +| 会增删、会重排、只是"读第几条" | **章节引用** `` `docs/xxx.md` §N.M ``（不造编号） | +| 需要稳定身份（要销项、要被代码引用、要跨文档追溯） | **编号** | + +各设计文档的"本期不做 / 遗留可选项"清单（现状 `O1~O4` 四篇文档四义）**默认不造编号**，改用 §小节引用；确需逐条引用时才启用文档内编号 `OOS-`。 + +--- + +## 4. 编号空间总表 + +### 4.1 在册保留（零改写，仅补规则） + +| 前缀（正则） | 类别 | 属主登记处 | 游标/规则 | +|---|---|---|---| +| `FR-[A-Z0-9]+-\d{2}` | 功能需求 | `docs/产品需求/产品需求设计文档.md` §5 | 各域独立递增；**新增域写进该文 §1.2 术语与缩写** | +| `NFR-[A-Z0-9]+-\d{2}` | 非功能需求（**新建**，现 §7 全是散文无号） | `docs/产品需求/产品需求设计文档.md` §7 | 从 `NFR-<域>-01` 起 | +| `N-\d{2}` | **登记簿条目**（技术债 / 长期观察 / 硬件改版项；含义由"网络项"重定义） | `docs/任务规划/登记簿.md` | 在册最大 `N-33` → 游标 `N-34`；原 `S-x`/`T-x` 并入本族（§7.1） | +| `E-\d{2}` | 错误码/返回值传播审计发现 | `docs/问题记录/错误码传播审计.md` | **冻结**：`E-63` 为最大号，**不再新增**；新发现一律 `DEF` | +| `TC-[A-Z]{1,4}-\d{3,4}` | 测试用例 | 各测试文档 | 3 位起；分阶段套件序号 = 阶段号×100 + 项号（阶段 ≥10 自然进位 4 位，`TC-NET-1001` 合规）；后缀只允许 `-<小写字母>` | +| `TM-[A-Z]{1,4}-\d{2}` | 测试阶段 | 各测试文档 | 模块码取 §6 统一表（`TM-PHY-01` → `TM-NET-01`） | +| `DP-[A-Z]{1,4}-\d{2}` | 设计原则 | 各测试文档 | **加模块码**（现 `DP-01` 跨文档会撞） | +| `L\d` / `L\d-\d{1,2}` | 采集与保护分层、层内条目 | `docs/算法/继电保护功能复现规划.md` §3 | 保留（代码侧 141 处引用，是全项目最规范的一族，作样板）；`L` 前缀**专属**此族 | +| `W\d+` | 波次 | `docs/任务规划/README.md` §2.0 | 保留；游标 `W8`；子任务卡不再用 `W1-0` 形态（并入 `WI`） | + +### 4.2 目标前缀（阶段 1 改名后启用） + +| 新前缀 | 类别 | 收编的旧编号 | 新属主登记处 | 游标 | +|---|---|---|---|---| +| `DEF-` | 缺陷 / 问题发现 | `P0-x`~`P3-x`（在册项）、新发现 | `[计划] docs/问题记录/缺陷登记簿.md` | `DEF-001` | +| `WI-` | 工作项 / 任务卡 | `B\d`(功能主线)、`C\d`(结构债)、`D\d`(验证窗口)、`W1-0`、`S1~S14`、`A-1~A-7`、`P1-10`、报告 `R-x`(内存优化)、`F-x`、`U1~U5` 的未闭环项 | `docs/任务规划/` 波次与排期文件（类别做列） | `WI-001` | +| `DR-` | 决策记录 | `docs/子系统设计/网络Socket监听生命周期设计说明.md` 的 `D1~D10` | `[计划] docs/架构设计/决策记录登记簿.md` | `DR-001` | +| `OQ-` | 待确认 / 开放问题 | `B0-a/b/c`、`待确认-N` | `docs/任务规划/基线与待确认.md` | `OQ-001` | +| `RSK-` | 风险（**文档内编号**） | 保护规划 `R1~R8`、看门狗 `R1~R7` | 各文档风险表（引用必须带文档名） | 各文档自 `RSK-01` | +| `TRAP--` | 陷阱记录 | `Trap 07`、`TRAP-07`、`陷阱 1` | `docs/问题记录/<模块>_Trap_Records.md` | 保留原号（`TRAP-NET-01~25`、`TRAP-GD5F-01~06`、`TRAP-RTC-01~`） | +| `GAP-` | 模拟器差距 | `H-1~H-7`、`L-1~L-4`、差距清单 `N-1~N-6` | `docs/测试说明/模拟器差距清单.md` | `GAP-01` | +| `SC-` | 实机验证场景 | 实机预检 `A1~A8`、看门狗验证用例 `V2/V4/V5` | `docs/测试说明/实机测试实施指南.md` | `SC-01` | +| `T0/T0.5/T1/T2/T3` | **测试分层**（原 `L0/L0.5/L1/L2/L3`） | 测试分层五档 | `docs/测试说明/测试开发标准流程.md` §1 | 固定五档 | +| `G0/G0.5/G1/G2/G3` | **门禁**（必跑清单，与测试分层是两套，不合并） | 现门禁决策表 `G0~G3` | `docs/测试说明/测试开发标准流程.md` §1.1 | 固定 | +| `GEN-` | 台架日志代次 | `gen 181`、`gen-288`、`gen68` | `docs/测试说明/串口助手设计说明.md` | 数字不变，仅改字面 | +| `RUN--` | 台架轮次 | `round 1~9` | `docs/测试说明/实机测试实施指南.md` | 日期制 | +| `MS-` | 里程碑 | `M1~M3` | 波次文件 | `MS-01` | +| `RC-` | net 周期对账类型 | `①②③④`（唯一被代码逻辑引用的圈号链） | `docs/子系统设计/网络Socket监听生命周期设计说明.md` | `RC-01`~`RC-04` | +| `PAT-` | 缺陷模式（九类） | `docs/问题记录/错误码传播审计.md` §1.1 的 `P1~P9` | 同文 | `PAT-01`~`PAT-09` | +| `ST-` | 专项内部实施阶段（**文档内编号**） | 保护规划 §7.1 的 `P0~P5`、方案阶段 `P0~P3` | 各专项文档 | 各文档自 `ST-0` | +| `UL-` | UI 标准化四层（**文档内编号**） | 报告 UI 四层 `L0~L3` | `docs/UI设计/UI_设计架构.md` | `UL-0` | +| `LAT-` | 链路延迟分段（**文档内编号**） | `docs/测试说明/链路延迟测试说明.md` 的 `L1~L11` | 同文 | `LAT-01` | +| `CS-` | CubeMX 定制存活三层 | `AGENTS.md` 的 `L1 写进 .ioc → L2 USER CODE → L3 审计` | `docs/子系统设计/看门狗设计说明.md` §10 | `CS-1`~`CS-3` | + +### 4.3 冻结前缀（历史快照，正文不回改） + +| 冻结对象 | 处置 | +|---|---| +| `E-` | 冻结于 `E-63`；引用照旧，**禁止新增**；门禁拒绝游标之外的新 E 号 | +| `docs/问题记录/项目审查与优化建议报告.md` 自造的 `N-xx`/`D-x`/`S-x`/`R-x`/`F-x`/`U1~U5` | 报告是历史基线，**不回改**；引用一律紧邻文档名；未闭环项已并轨进 `N-19~N-29`，出处列保留报告编号 | +| `docs/问题记录/CH395F_Trap_Records.md` 2026-10-11 审计的 `A1~A6`/`B1~B10` | 该表是审计快照（条目已修复或推翻），**冻结**；新发现进 `DEF`；引用紧邻文档名 | +| `P0-x`~`P3-x` | 在册项迁 `DEF`；已闭环项留在历史文档，走别名表 | +| `Task #32` 等会话临时号 | **禁止入册**；现存引用（`Src/main.c`、`Drivers/BSP/UI/ui_net_sink.c` 的 `I-1/I-2`）改写为可解析形式或就地展开成事实描述 | + +### 4.4 划界：这些不是编号，不受本规范管 + +| 对象 | 例子 | 归属 | +|---|---|---| +| C 标识符 | `PS_OC1_EN`、`TEST_SUITE_STORAGE`、`ENABLE_PHASE14_TESTS`、`SYS_EVT_NET_READY`、`TASK_WD_ADC` | `docs/代码规范/嵌入式C语言代码规范_V1.0.md` | +| 元器件位号 | `U1`、`C12`、`R3`、`L5`、`D7`（`docs/硬件平台/`、`docs/芯片手册/`） | **门禁与改写脚本一律排除**，这是最大误伤风险源 | +| 章节号 | `§3.2` | `docs/文档规范.md` §3.5 | +| **档位词** | `P0`/`P1`/`P2`/`P3`（严重度、用例优先级） | 允许继续使用，但**永不带 `-<数字>` 后缀**——`P1-8` 这类形态一律非法 | +| 图元 id | `README.md` 架构图 Mermaid 节点 `A1`/`B1`/`C1`/`D2` | 改描述性 id（`net`/`sto`/`ui`），避免与条目字面撞名 | +| 运行时计数 | 网络代次号 `net_get_generation()` | 代码概念；与台架 `GEN` 是两回事，文档里须写全"网络代次号" | + +--- + +## 5. 分配、引用、销项规则（强制） + +### 5.1 新增编号 + +1. 查 §4 总表确定类别与属主登记处；**表里没有的类别 → 先改本规范，不得自造前缀**。 +2. 到属主登记处取游标号（`[计划] scripts/id_registry.json` 记录每类下一个可用号），登记处新增一行。 +3. 严重度 / 状态 / 波次 / 出处写进表格列，**不进编号**。 + +### 5.2 引用写法 + +| 场景 | 写法 | +|---|---| +| 全局编号，跨文档首次出现 | `` `docs/任务规划/登记簿.md` N-21 ``（紧邻，同 `§N.M` 规则） | +| 全局编号，同段后续 | `` `N-21` `` | +| 文档内编号 | **必须** `` `docs/子系统设计/网络Socket监听生命周期设计说明.md` DR-003 `` | +| 尚未创建的条目文件 | 加 `[计划] ` 前缀（`docs/文档规范.md` §3.3） | +| 引用报错样例/历史字面 | 该行加 `[示例]` 标记 | + +### 5.3 代码注释引用 + +- **允许引用**（长期有效）：`FR-*`、`NFR-*`、`DEF-*`、`E-*`（冻结存量）、`N-*`、`TRAP-*`、`DR-*`、`TC-*`、`L-`。 +- **禁止引用**（易变）：`WI-*`、`W`、`MS-*`、`OQ-*`、`ST-*`——代码是长期资产，波次与任务卡会变。 +- 首次出现带属主文档名（现状 90% 裸引，靠"全库唯一"这一未成文假设）。 + +### 5.4 提交信息 + +标题带主编号：`fix(net): N-32 监听重建阻塞导致心跳缺口`。一次提交只挂一个主编号，其余进正文。 + +### 5.5 销项与归档 + +- 销项 = 删登记行 + **清全库引用**（沿用 `docs/任务规划/README.md` §3 与 `AGENTS.md` 既有规则）+ 游标**不回退**。 +- 号段用尽 → 扩位（`N-99`→`N-100`），**不换字母**。 +- 历史文档（审计报告、评审报告、已闭环陷阱）不回改，走别名表。 + +--- + +## 6. 模块码表（`TC` / `TM` / `DP` / `TRAP` 共用） + +现状是**板端 6 个码 + 主机侧 10 个码两套并存**，且 `docs/测试说明/ADC输入层单元测试说明.md` 明文豁免主机侧"与板端缩写表互不影响"。本规范合并为一张表，**现有码全部沿用（零改写）**，只规定新模块必须先登记： + +| 码 | 模块（源文件/目录） | 码 | 模块 | +|---|---|---|---| +| `NET` | `Drivers/BSP/CH395F` + `Drivers/BSP/NET` | `AI` | `App/algo/adc_input` | +| `GD5F` | `Drivers/BSP/GD5F2GQ5UE` | `AH` | `App/algo/adc_health` | +| `STO` | 存储栈（FTL + FatFs + `App/fs`） | `PH` | `App/algo/phasor` + `sample_ring` | +| `RTC` | `Drivers/BSP/SD2506` | `PS` | `App/algo/prot_set` | +| `ADC` | 采集节拍与通道映射（`Src/adc.c`、TIM3） | `PE` | `App/algo/prot_elm` | +| `RS485` | `Drivers/BSP/RS485` | `VL` | `App/fs/vol_lock` | +| `UI` | `Drivers/BSP/UI` | `TS` | `App/sync/time_sync` | +| `LOG` | `App/log` | `CLK` | `App/util/sys_clock` | +| `CFG` | `App/cfg` + `Drivers/BSP/NETCFG` | `WD` | `App/util/task_watchdog` | +| `SH` | `App/util/sha256` | `FA` | `Drivers/BSP/NET/lftpd` 鉴权 | +| `I104` | `App/protocol/iec104` | `TOOL` | PC 端工具（串口助手等） | + +> 废止码：`PHY`（→ `NET`）、`NAND`（→ `GD5F`）。历史文档不回改，新文档按本表。 + +--- + +## 7. 迁移映射（legacy → 新号） + +### 7.1 映射规则 + +| 旧族 | 新族 | 规则 | +|---|---|---| +| 登记簿 `N-2`…`N-33` | `N-02`…`N-33` | 仅补零，数字不变 | +| 登记簿 `S-3/S-4/S-5`、`T-7` | `N-34`… | 续号并入，别名表保留旧号 | +| 主线 `B0~B10`、结构债 `C1~C6`、验证窗口 `D2~D7`、`W1-0` | `WI-001`… | 按波次顺序连续重编，映射表逐条列出并落别名表 | +| 复审 `S1~S14`、`A-1~A-7`、报告 `R-x`/`F-x`/`U1~U5` 未闭环项 | `WI-*` | 同上；已闭环项留历史文档 | +| `P0-x`~`P3-x` 在册项 | `DEF-*` | 严重度转列 | +| 设计说明 `D1~D10` | `DR-001`~`DR-010` | 数字对齐 | +| `B0-a/b/c`、`待确认-N` | `OQ-001`… | — | +| `Trap NN` / `陷阱 N` | `TRAP--` | 数字不变，补模块码 | +| `H-1~H-7`、`L-1~L-4`、差距 `N-1~N-6` | `GAP-01`~`GAP-17` | 按文档内出现顺序 | +| 实机 `A1~A8`、看门狗 `V2/V4/V5` | `SC-01`… | — | +| 测试分层 `L0/L0.5/L1/L2/L3` | `T0/T0.5/T1/T2/T3` | 门禁 `G0~G3` 不动（两套不同尺度，不合并） | +| `gen 181`/`gen-288`/`gen68` | `GEN-181`/`GEN-288`/`GEN-068` | 数字不变 | +| `round 1~9` | `RUN-<日期>-` | 无日期的历史轮次留别名表 | +| `M1~M3` | `MS-01`~`MS-03` | — | +| 对账 `①~④` | `RC-01`~`RC-04` | 代码注释同步 | +| 审计模式 `P1~P9` | `PAT-01`~`PAT-09` | 正文冻结，新文档用新号 | +| 保护 `R1~R8`、看门狗 `R1~R7` | 各文档 `RSK-01`… | 文档内编号 + 引用带文档名 | +| 保护阶段 `P0~P5`、方案 `P0~P3` | 各文档 `ST-0`… | 与档位词 `P0` 解耦 | +| `TC-STO-01~06` | `TC-STO-001~006` | 补零 | +| `TC-AI-01A`/`02A`/`02B`/`02C`、`TC-VL-008b` | `TC-AI-001a`… / `TC-VL-008b` | 后缀统一小写字母，基号补零 | +| `TM-PHY-01~11` | `TM-NET-01~11` | 模块码 | +| `DP-01~04` | `DP-NET-01~04` | 加模块码 | + +### 7.2 孤儿编号处置（阶段 1 一并清） + +| 孤儿 | 处置 | +|---|---| +| `I-1`/`I-2`（`ui_net_sink.c`） | 在 `docs/子系统设计/网络Socket监听生命周期设计说明.md` 补定义行，或就地展开成事实描述 | +| `Task #32` 会话号及其小节引用 | 会话号，改写为可解析引用（结论已沉淀进 `docs/子系统设计/看门狗设计说明.md` §11） | +| `P1-01~P1-09`（`ch395f_test_task.c`） | 改指 `TC-NET-101`…，或补文档条目 | +| `TC-GD5F-1100/1101/1102`、`TC-STO-06` | 补进 `docs/测试说明/GD5F2GQ5UE_Test_Guide.md` | +| `TC-AH-*`、`TC-PE-*`、iec104 `TC-014/015/024` | 补单测说明文档（缺文档 = 追溯断链） | +| `Trap 19` | 悬空引用，删除或改指实际条目 | + +### 7.3 改写操作规程（每批必走） + +```powershell +# 1) 预览：映射表驱动的 dry-run，人工通读 diff（重点看 docs/硬件平台/ 是否被误伤） +& '.venv\Scripts\python.exe' [计划] scripts/rename_ids.py --map [计划] scripts/id_aliases.json --dry-run + +# 2) 落盘后三重复核 +git grep -n '<旧字面量>' # 零残留 +& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all +& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 0 错误 0 警告 +``` + +**硬约束**：`docs/硬件平台/`、`docs/芯片手册/` 全程排除（元器件位号 `U1/C12/R3/L5/D7` 与编号字面同形）；带 BOM 的文件（`Drivers/BSP/UI/*`、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h`）改写后必须核对 BOM 未丢；**禁止**用 `Get-Content`/`Set-Content` 重写含中文文件。 + +--- + +## 8. 门禁：`check_ids.py` 与 `id-check` 钩子 + +配置两份：`[计划] scripts/id_registry.json`（前缀 → 属主文档 / 形态正则 / 是否冻结 / 游标）、`[计划] scripts/id_aliases.json`（旧号 → 新号，照搬 `scripts/section_aliases.json` 的成功范式）。 + +| # | 校验 | 级别 | +|---|---|---| +| 1 | 出现未登记前缀（自造编号） | 错误 | +| 2 | 形态不合规：裸形 `S3`、空格形 `Trap 07`、中文形 `陷阱 1`、补零错、`P1-8` 这类档位词带后缀 | 错误 | +| 3 | 引用查无定义且不在别名表（悬空引用） | 错误 | +| 4 | 同一字面量被两个属主重复定义（`N-16` 类事故） | 错误 | +| 5 | 冻结前缀出现游标之外的新号 | 错误 | +| 6 | 文档内编号引用未紧邻文档名 | 错误 | +| 7 | 定义了但全库无引用（孤儿条目） | 告警 | +| 8 | 打印**「编号引用可判定比例」** | 每次运行，只许涨不许跌 | + +- 排除：`Lib/`、`Middlewares/`、HAL/CMSIS、`docs/芯片手册/`、`docs/硬件平台/`（位号）、构建产物。 +- 上线节奏：**先 warn-only 清 backlog → 清零后加 `--strict` 拦提交**（与 `doc-links` 章节校验完全同一条路径）。 +- 顺带收编 `scripts/check_test_traceability.py`：正则补 `TC-[A-Z]{1,4}-\d{3,4}[a-z]?`，覆盖 7 篇「单元测试说明.md」，一并挂进 `id-check`（现为 warn-only 且未挂钩子）。 + +--- + +## 9. 落地阶段与验收 + +| 阶段 | 内容 | 验收判据 | 风险 | +|---|---|---|---| +| **0 规范** | 本文件；`docs/任务规划/README.md` §0 改为指向本规范的摘要；`docs/README.md`、`AGENTS.md`、`docs/文档规范.md` §6 登记；两份 `id_*.json` 初版 | `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` 在册项；报告历史编号补齐紧邻文档名；档位词规则落地；别名表与游标定稿 | 同上 | 中 | +| **2 门禁** | `check_ids.py` + `id-check` 钩子（warn → strict）；`check_test_traceability.py` 收编 | 全库告警清零后转 strict；可判定比例基线入档 | 中（首轮会暴露大量真悬空引用） | + +每阶段结束停下等指令再提交（`AGENTS.md` 边界：commit/push 须明确指示）。 + +--- + +## 10. 常见错误速查 + +| 现象 | 原因 | 修复 | +|---|---|---| +| `id-check` 报"未登记前缀" | 自造了一套编号 | 查 §4 总表归到既有类别；确属新类别先改本规范 | +| 同一编号在两篇文档各指一物 | 用了文档内编号却裸引 | 改全局编号，或引用补文档名（紧邻） | +| 引用的编号查不到定义 | 孤儿/悬空 | 补定义行，或删引用 | +| 降级后编号与事实不符 | 语义进了编号 | 违反 P-2；严重度改列，编号不动 | +| 硬件文档里 `U1`/`C12` 被改 | 改写脚本没排除位号目录 | 回滚该批，按 §7.3 排除清单重跑 | +| 改完中文变乱码 | 用了整文件重写 | 见 `AGENTS.md` 铁律：只用精确子串替换，BOM 按原样补回 | + +--- + +## 变更记录 + +| 日期 | 变更 | 说明 | +|---|---|---| +| （规划稿） | 建立本文档 | 全库扫描 1,385 个不同编号 / 19,306 处出现后定稿的两层编号体系（全局编号 + 文档内编号）、六条原则、目标前缀总表、三批迁移映射与 `check_ids.py` 门禁设计；用户决策：`E-xx` 冻结保留、严重度档位词 `P0~P3` 不变、文档落 `docs/编号规范.md`、阶段 1 三批全做 |