STM32F4-Base/docs/编号规范.md

编号规范

适用对象：本仓库全部 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 §3.5 管）——见下文「划界」一节。 强制程度：§2~§5 为强制（规划由 scripts/check_ids.py 机械校验）；§6~§10 为约定 + 迁移计划。 相关文档：docs/文档规范.md（链接/章节/门禁总规范）、docs/任务规划/README.md §0（本规范的登记簿摘要）、docs/测试说明/测试文档模板规范.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<n>、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/N-32 销项删行后仍被引用（N-32 = 监听生命周期模块化，被 docs/网络/ 三篇与代码注释多处引用）
同一事物多种字面	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 §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），新增先取游标	并行任务与多文档同时新增时防撞号（《项目审查与优化建议报告》与登记簿并轨时 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. 主轴：编号 / 语义标识 / 章节引用

层	适用事物	形态	引用规则	门禁校验
全局编号	会跨文档流转：需求、缺陷、待办、决策、风险、测试用例、陷阱记录	全局唯一前缀 + 全局序号 + 唯一属主登记处	行内代码；跨文档首次出现紧邻属主名	全库唯一；必须能在属主表查到定义行
文档内编号	只在定义它的那篇文档内有意义：状态机组合、方案档位、专项风险、专项阶段	允许存在，前缀带类别码，号段文档内独立	必须紧邻文档名（同 §N.M 紧邻规则）	校验"该文档内确有此编号"
语义标识（§3.3，规划 / 待办类默认）	登记簿条目、任务卡、待确认、风险、决策、缺陷、工作项、差距、验证场景	一行短语即标识，不分配字母+数字号；≤20 汉字	同文档内写短语；跨文档紧邻属主文档名	同表内去重（同义异写算撞名）；引用查不到 = 悬空

3.1 判定口诀

会不会在别的文档里被引用？会 → 全局编号；不会 → 文档内编号，且引用必须带文档名。

前置一步（P-8）：规划 / 待办类条目先问"能不能用一行短语说清是什么事"—— 能 → 用语义标识（§3.3），不发编号；只有需机器解析（TC）或作历史证词（TRAP）才进上面的判定。

现状的病根正是把该全局的（发现、待办）做成了文档内编号（各文档自造 O1~O4、A1~A6），又把该文档内的（设计决策 D1~D7、状态机 U1~U15）做成了裸形全局编号。

3.2 编号 vs 章节引用

条目特征	用什么
会增删、会重排、只是"读第几条"	章节引用 `docs/xxx.md` §N.M（不造编号）
需要稳定身份（要销项、要被代码引用、要跨文档追溯）	编号

各设计文档的"本期不做 / 遗留可选项"清单（现状 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. 编号空间总表

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-30~N-33 均已销项、登记簿行已删，现存至 N-29）→ 游标 N-34（号不回收）；原 S-x/T-x 并入本族（§7.1）
E-\d{2}	错误码/返回值传播审计发现	无（原属主 docs/问题记录/错误码传播审计.md 已于 2026-10-15 删除）	冻结：E-63 为最大号，不再新增；新发现一律 DEF；现存引用仅作历史指称（§4.3）
E\d+	自愈实验编号（N34 台架实验，无连字符）	docs/网络/网络自愈架构设计.md §5.2	已封闭：E0~E15，不再新增；原始实验记录已归档（该文档 §12）。⚠ 与上一行靠连字符区分：带连字符 = 审计发现
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 改名后启用）

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
WI-<nnn>	工作项 / 任务卡	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-<nnn>	决策记录	docs/网络/网络自愈架构设计.md 的 D1~D7	[计划] docs/架构设计/决策记录登记簿.md	DR-001
OQ-<nnn>	待确认 / 开放问题	B0-a/b/c、待确认-N	docs/任务规划/基线与待确认.md	OQ-001
RSK-<nn>	风险（文档内编号）	保护规划 R1~R8、看门狗 R1~R7	各文档风险表（引用必须带文档名）	各文档自 RSK-01
TRAP-<MOD>-<nn>	陷阱记录	Trap 07、TRAP-07、陷阱 1	docs/问题记录/<模块>_Trap_Records.md	保留原号（TRAP-NET-01~21——NET 域 2026-10-13 全库迁移并重排连续，沿革见该文档、TRAP-GD5F-01~06、TRAP-RTC-01~）
GAP-<nn>	模拟器差距	H-1~H-7、L-1~L-4、差距清单 N-1~N-6	docs/测试说明/模拟器差距清单.md	GAP-01
SC-<nn>	实机验证场景	实机预检 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-<nnn>	台架日志代次	gen 181、gen-288、gen68	docs/测试说明/串口助手设计说明.md	数字不变，仅改字面
RUN-<yyyymmdd>-<n>	台架轮次	round 1~9	docs/测试说明/实机测试实施指南.md	日期制
MS-<nn>	里程碑	M1~M3	波次文件	MS-01
RC-<nn>	net 周期对账类型	①②③④⑤（唯一被代码逻辑引用的圈号链）	docs/网络/网络自愈架构设计.md	RC-01~RC-05
PAT-<nn>	缺陷模式（九类）	原 docs/问题记录/错误码传播审计.md §1.1 的 P1~P9（该文档已删除，定义迁至本文档 §4.2.1）	本文档 §4.2.1	PAT-01~PAT-09
ST-<n>	专项内部实施阶段（文档内编号）	保护规划 §7.1 的 P0~P5、方案阶段 P0~P3	各专项文档	各文档自 ST-0
UL-<n>	UI 标准化四层（文档内编号）	报告 UI 四层 L0~L3	docs/UI设计/UI_设计架构.md	UL-0
LAT-<nn>	链路延迟分段（文档内编号）	docs/测试说明/链路延迟测试说明.md 的 L1~L11	同文	LAT-01
CS-<n>	CubeMX 定制存活三层	AGENTS.md 的 L1 写进 .ioc → L2 USER CODE → L3 审计	docs/子系统设计/看门狗设计说明.md §10	CS-1~CS-3

4.2.1 缺陷模式定义（PAT-01~PAT-09）

2026-10-15 由已删除的 docs/问题记录/错误码传播审计.md §1.1 迁入（原编号 P1~P9，与发现编号 E-xx 区分）。 新发现归入 DEF-<nnn> 时，"缺陷模式"列仍按本表取值：

模式	名字	一句话	典型症状
PAT-01	值拷贝队列陷阱	消息体按值拷进队列，netTask 修改的是副本，调用方看不到	回传字段恒为初始值
PAT-02	共享全局错误变量竞态	全局 errno 被多任务交错覆写	报出别人的错误码
PAT-03	返回值与错误码混同	"0 = 成功"其实是"命令已发出"；成功路径不清 errno	失败被当成功
PAT-04	返回值未检查	HAL_* / 库函数返回被丢弃	失败静默继续
PAT-05	事件标志语义	状态位被当作命令位消费掉	等待者永不唤醒
PAT-06	通知值宽度与符号	32 位通知值装不下 / 符号位被当成数据	大长度变负数
PAT-07	ISR 与跨上下文共享状态	ISR 写、任务读，无同步	读到半包 / 撕裂
PAT-08	外设 / 库特定约定	该外设 / 该移植版特有的规则	照抄上游示例即错
PAT-09	超时与错误混同	超时用同一个码表达，调用方无法区分	无法复位 / 无法重试

4.3 冻结前缀（历史快照，正文不回改）

冻结对象	处置
E-<nn>	冻结于 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 新增编号

0. 先问"能不能不加号"：能用 § 小节引用、表格列、语义标题表达清楚的，就不要分配编号—— 编号是"确需跨文档长期引用"时才付的成本（P-1 / P-3 / P-7）。确需新增才往下走。
1. 查 §4 总表确定类别与属主登记处；表里没有的类别 → 先改本规范，不得自造前缀。
2. 到属主登记处取游标号（[计划] scripts/id_registry.json 记录每类下一个可用号），登记处新增一行。
3. 严重度 / 状态 / 波次 / 出处写进表格列，不进编号。

5.2 引用写法

场景	写法
全局编号，跨文档首次出现	`docs/任务规划/登记簿.md` N-21（紧邻，同 §N.M 规则）
全局编号，同段后续	`N-21`
文档内编号	必须 `docs/网络/网络自愈架构设计.md` DR-003
尚未创建的条目文件	加 [计划] 前缀（docs/文档规范.md §3.3）
引用报错样例/历史字面	该行加 [示例] 标记

5.3 代码注释引用

• 允许引用（长期有效）：FR-*、NFR-*、DEF-*、E-*（冻结存量）、N-*、TRAP-*、DR-*、TC-*、L<n>-<nn>。
• 禁止引用（易变）：WI-*、W<n>、MS-*、OQ-*、ST-*——代码是长期资产，波次与任务卡会变。
• 首次出现带属主文档名（现状 90% 裸引，靠"全库唯一"这一未成文假设）。

5.4 提交信息

标题带主编号：fix(net): N-32 监听重建阻塞导致心跳缺口。一次提交只挂一个主编号，其余进正文。

5.5 销项与归档

• 销项 = 删登记行 + 清全库引用（沿用 docs/任务规划/README.md §3 与 AGENTS.md 既有规则）+ 游标不回退。
• 号段用尽 → 扩位（N-99→N-100），不换字母。
• 历史文档（审计报告、评审报告、已闭环陷阱）不回改，走别名表。

5.6 编号密集文档的对照节（强制）

一篇文档若引用 ≥3 个编号族（如 I* + E* + F-* + M* + U* + TRAP-*），必须在正文之前 加一节「导读：本文用到的编号与术语」——每个记号一行，给出「是什么 + 在哪查」，让读者不必跳出本文拼语义。

• 首次实践：docs/网络/网络自愈架构设计.md 的 ## 导读：本文用到的编号与术语。
• 对已封闭 / 已归档的编号族尤其必要：属主登记表可能已删行（N-30N-33 销项、E0E15 随审计归档）， 此时该文档即其唯一可查处。
• 与 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 共用）

现状是板端 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-30~N-33 已销项，现存至 N-29）	N-02…N-33	仅补零，数字不变；号不回收，游标仍 N-34
登记簿 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-<MOD>-<nn>	数字不变，补模块码
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-<日期>-<n>	无日期的历史轮次留别名表
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）	就地展开成事实描述（原属主《网络Socket监听生命周期设计说明》已并入 docs/网络/网络自愈架构设计.md §9.3，不再补编号定义行）
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 改写操作规程（每批必走）

# 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	零（纯新增 + 指针）
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 在册项；报告历史编号补齐紧邻文档名；档位词规则落地；别名表与游标定稿	同上	中
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 按原样补回

---

变更记录

日期	变更	说明
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 语义标识」阶段。起因：用户裁定去除字母数字编号（难理解），先定规范本体