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

编号规范：默认不用编号

一句话：语义标识是唯一默认形态，编号是例外。 例外只留给有脚本按字面量匹配的那几种 （§4.1 的「允许继续发号」一栏）；同一张表里还有一栏是已停发、存量待清的族（编号治理历史.md §9.1 给清点与批次）。 除此之外一律写语义短语（§3.3）。

这条不是洁癖，是用户 2026-10-27 的明确要求：「不要用字母加数字的编号，简直太难以理解了，语义标识是最好的」。 依据也很硬：规划 / 待办 / 审计 / 差距 / 阶段这些给人看的东西，历史上全发过号，也全都变成了没人认得的代号。 2026-10-26 起两批清理把编号字面量从 10,956 压到 8,230 处，2026-10-27 复测为 7,828 处（编号治理历史.md §8.1 有口径说明）； 而清掉的号里绝大多数从来没被任何脚本读过一次。沿革与教训留在 编号治理历史.md §8.3 与 git log，正文不复述。

机器面才是事实源：现行门禁 scripts/check_ids_new.py 的两张前缀级白名单（KNOWN_DASH / KNOWN_BARE） 是 §4.1 的机器投影；本文与白名单冲突时以白名单为准，回来改本文（详解 docs/门禁说明/id-check-new.md）。 旧的族注册表 / 别名表 / 八项校验脚本已随全库审计退役进 scripts/archive/id_gate/，只在手工复查存量时用。

---

本文范围：这里只留现在还生效的口径。跳号的节（编号治理历史.md §2 八条原则 / 编号治理历史.md §4.2 / 编号治理历史.md §4.5 / 编号治理历史.md §6 模块码表 / 编号治理历史.md §7 改号与迁移 / 编号治理历史.md §8.1 基线 / 编号治理历史.md §8.3 批次 / 编号治理历史.md §8.4 台账 / 编号治理历史.md §9 存量清点与换算表）是编号治理的过程记录， 2026-10-28 已整体移入 scripts/archive/id_gate/编号治理历史.md——要查历史判据、批次流水、 「数据可信」任务卡号换算表，去那里；改现在的做法只看本文。 节号沿用旧编号，故意不重排：外部文档与脚本引的是 §4.1 / §8.5 这些号，重排等于制造一批假链接。

1. 决定要不要发号之前，先问三句

问自己	答"否"的结论
有脚本 / CI / 回归测试要按这个字面量做匹配吗？	不发号，写语义短语（§3.3）
现有文档或登记表里已经能指代这件事吗？	引用它，别再发第二个号指同一件事
一年后别人还能在属主登记表查到它的定义吗？	查不到就别发——"先记着，以后再说"是编号失控的唯一来源

三条硬规矩（对确实要发的号）：

• 号不承载语义：严重度、优先级、模块名、轮次都不写进号里。事实一变，号就开始撒谎。
• 号不回收、不复用：销项 = 删登记行 + 清掉所有引用 + 别名表标 void（§5.5）。历史上"销掉的号被 重新取走"撞过两次。
• 引用必须带语义：号旁边要有人话，裸号不许独担信息（读者不该被迫查表才看懂一句话）。

3. 三种指代方式，按这个顺序挑

优先	方式	用在
① 最好	语义短语	规划 / 待办 / 缺陷 / 风险 / 决策 / 差距 / 文档内步骤与阶段——默认形态
② 其次	文档名 + 章节号	指某篇文档的某节（docs/网络/网络自愈架构设计.md §4.10，紧邻写法）
③ 最后	编号	只有 §4.1「允许继续发号」那一栏，且必须能反查到定义

3.1 判定口诀

机器读 → 发号；人读 → 写短语。 拿不准就写短语：短语看不懂还能靠上下文猜，号看不懂只能去查表。

3.2 编号 vs 章节引用

章节引用不是编号，但同样要紧邻文档名——只写「§ + 小节号」而不写文档名，会被 doc-links 当成本文自引用而静默放过， 这是它的已知盲区，别踩。

3.3 语义标识（默认形态，怎么写）

• 一行短语就是标识：≤20 汉字、说清"是什么事"、同一登记表内不撞名（同义异写算撞名）。
• 好的例子：双转换器无共同采样触发、FTP 鉴权、写回缓存空闲 flush、队列往返基线待重验。 坏的例子：优化项 3、遗留问题、重要缺陷——换个上下文就指代不明，等于又造了个号。
• 登记处就是那张表：表首格写短语，不要再配一个字母号；跨文档引用写成 `docs/任务规划/登记簿.md` 「双转换器无共同采样触发」，同篇后续直接用短语。
• 文档内的实施步骤 / 测试阶段 / 设计原则条目写中文：「步骤 3」「阶段 7」「DMA 边界安全」， 不写 S3 / TM-… / DP-… 这种号。

---

4. 编号空间

4.1 允许用号的族（穷举——这张表以外一律不许发号）

允许继续发号——恰好下面 5 行，判据 = 有脚本按字面量匹配它（现状实测 2026-10-27 见 编号治理历史.md §9.1）。 TC-* 不在本表：它的发号已按用户裁定 2026-10-27 停掉（别把那句裁定读成「暂缓」——防误读的三条对照在 本节末的框里，清点的来龙去脉在 编号治理历史.md §9.1 批次三）。

族	形态	属主登记处	用途
TRAP-*	TRAP-<域>-<nn>	docs/问题记录/*_Trap_Records.md	踩坑证词的永久锚点，代码注释反查
FR-*	需求	docs/产品需求/产品需求设计文档.md §5	需求↔测试追溯
CODE-RULE-<nn>	代码规范条款	scripts/check_coding_standard.py	门禁按条款号报错并统计存量
MENU-STATE-<nn>	UI 状态机键	simulator/tests/check_menu_rows.py	像素回归脚本按它取状态行
P-<n>	本文的设计原则	本文 编号治理历史.md §2	就是本文自己的条目

⚠ 「批次三不做了」只有一层意思：不去清这个族，同时把它的发号口关死。 它不是「TC 族维持原状、 新用例照旧配号」——维持原状的是存量号，关掉的是发号口。三条对照，防止往任何一边读过头：

• ❌「不做 = 维持原状 = 还能发」——错。新用例一律用语义化测试函数名 + 文档用例表的行名（§3.3）， 不再配 TC 号；指认既有用例仍可引用现存号（旧号只读，不是许可新配）。
• ❌「停发 = 这族要废了，顺手清掉、把号腾出来复用」——也错。现存号与它在 scripts/archive/id_gate/id_registry.json 里的登记，是 check_test_traceability.py 与 41 套 run_unit_test.py 按字面量读的追溯把手， 清它等于换机制（编号治理历史.md §9.1）；号不回收、不复用是 §1 的硬规矩。
• ❌「registry 里 TC 族还带着活游标，所以门禁允许我发」——不成立：这条缺口已于 2026-10-27 同日关掉。 37 个 TC 类族现在全部 frozen: true，其中 34 个 TC-HOST-* 子族的 cursor 冻结在裁定日该套件存量 最高号（5 个游标低于存量的已抬到水位：TC-PROTELEM-013→015、TC-SYSLOG-108→137、TC-ADCHEALTH-011→023、 TC-ADCCAL-017→023、TC-I104SRV-041→053；游标必须是字符串形态，整型比较会静默不生效）→ 在套件 登记处写一个比游标更高的 TC 号就是 §8 第 5 项「冻结族越游标」错误级，而 id_known_backlog.json 台账 0 条指纹 → 增量拦截等于全量拦提交。探针实测（check_ids 的 Checker _check_frozen）：在 TC-PROTSET- 段存量最高号之上再加一号 → 命中 1 条校验 5；写存量最高号本身 → 零误伤。 还剩一处空白，别把这条机械化读成无死角：主族 TC（没有专属子族的模块码，如 TC-ADCIN-*）的 cursor 仍为 null——一个游标表达不了每个模块码的水位，写全族最高号反而放行低号，所以按空白登记（探针实测： 给无专属子族的模块码（如 TC-ADCIN- 段）写一个新号，门禁不响）。这一面由三条兜：① §8 校验 3——新号没进属主登记处 = 悬空引用（错误级）； ② 编号治理历史.md §9.1 末段的冻结水位（只减不增，涨了就要问「这号是谁在停发之后发的」）；③ 评审。所以给这些模块 补号，即使在文档表格里一并补了定义行，一样违反本裁定。 要把这面也钉死（按模块码克隆子族，或给族级加 字面量上限）与「真要清退」同属追溯机制改造，按 编号治理历史.md §7.3 单独开卡，别夹在本批里顺手做。
• 唯一的重启入口：先由用户裁定 → 再回到本节把族放回上面那 7 行、并指出按它做字面量匹配的脚本 → 才谈得上发号。顺序倒过来就是 编号治理历史.md §1.2 那四类事故的由来。

已停发、存量待清（一律不得再新增引用；下表除 TC-* 外，登记未删只是为了让历史行不报「未登记前缀」， 清点见 编号治理历史.md §9.1。TC-* 是这一栏的特例：登记与现存号都要留着，它是机器把手而不是待清对象，见 编号治理历史.md §9.1 批次三）：

族	状态	依据
TC-*	保留现存号、即日停发（机器已冻结）：34 个 TC-HOST-* 子族 frozen: true、游标钉在 2026-10-27 存量水位，越游标即 §8 校验 5 错误级；现存号只减不增，新用例改用语义化测试函数名 + 文档表格行名（主族 TC 的空白面见上方框）	用户裁定 2026-10-27「批次三，不坐」；本族是 §4.1 判据唯一真被脚本按字面量读的族，清它等于换追溯机制，详见 编号治理历史.md §9.1 批次三

族	形态	存量	为什么该清
L<n>-<nn>	保护功能号	批次二已整族转功能名，即日停发：活引用 0，只剩一处原始串口日志（冻结证据、永久保留）与本文/技能文档的形态举例；属主文档表首格写功能名，不再配号	用户 2026-10-27 定调「语义标识是最好的」+ 本轮指令「把能清的族清掉一批」；探针（Checker _check_dangling）：写一个新号（字母 L + 段号 + 连字符 + 两位数、从未定义过的形态）→ §8 校验 3 悬空引用错误级 → 发号口已机器关闭。不冻结数值游标：L1/L2/…各段最高号不同，单一数字游标反而放行低号
F-<MOD>-<nn>	网络设计条目	批次一已转「编号治理历史.md §7 条目名」，即日停发：代码与测试侧 0 处；属主文档 编号治理历史.md §7 编号列 13 条仅作历史对照（定义行不算引用）	同上；探针：写一个新号（F 前缀 + 模块码 + 从未出现过的序号）→ 校验 3 错误级；引用旧号命中小写别名表 retired-to-phrase = 只读，不构成发号许可
N-*	登记簿 N-<nn>	4 处 / 3 个字面量	登记簿已于 2026-10-26 全面改语义短语，残留的是漏网的旧引用
TM-*	阶段/里程碑 TM-<code>-<nn>	1 处	阶段号本就属 §3.3 明令不许写号的那类
T-TEST	台架阶段 裸形（字母 T 紧跟一位数字）	活引用 0（批次一清零；余下是本文自述与技能文档的形态举例）	裸形最危险（同字母多义），且改「台架阶段一」即可
F-*	网络设计条目 F-<MOD>-<nn>	动手前 38 处 / 12 个 → 2026-10-27 批次一收口：正文 9 处（含一个从来没有定义行的 DRV 段孤儿号，删号）+ 主机侧单测注释 1 处改「条目名」，仅属主文档 编号治理历史.md §7 历史对照表留 12 条编号	代码注释按号回指设计条目，但没有任何脚本匹配它

• 新增族的唯一正当条件：有脚本要按字面量匹配它。顺序固定：先改 id_registry.json（含属主登记处） → 再写属主文档 → 最后才允许在别处引用。反过来做必然造出悬空号。
• 模块码是既定缩写，事实源 = registry 的族 pattern 与属主文档标题行，别自创（编号治理历史.md §6）。

4.1.1 已停发的族（别再指，更别再"复用"这些号）

停发族	现在怎么写	旧号去哪查
登记簿 N-x / S-x / T-x、专项 A-x、已删报告的 UI 簇 U1~U5（2026-10-26 方案 B）	语义短语——登记簿表首格本身就是短语，如「双转换器无共同采样触发」「CI 远端闭环未验证」	scripts/archive/id_gate/id_aliases.json 标 retired-to-phrase
网络设计条目 F-NET/F-DRV/F-MS-<nn>（12 个，2026-10-27 批次一）	「编号治理历史.md §7 + 条目名」短语，如 （编号治理历史.md §7「全局读即清搁浅事件」）；条目名的权威清单 = docs/网络/网络自愈架构设计.md 编号治理历史.md §7「条目名」列；那个 DRV 段孤儿号按本节末句删号留事实、未补定义	scripts/archive/id_gate/id_aliases.json 标 retired-to-phrase（13 条）＋属主文档 编号治理历史.md §7 编号列仅作历史对照
「数据可信」任务卡号（中文前缀「卡」+ 数字，形态见 编号治理历史.md §9.3；2026-10-27 批次五）	§5 表的标识列直接写任务名（「端子/子板变比确认」「两点标定与精度验收」），代码注释与文档写语义短语（「标定折算落地」「未标定闭锁」「遥测快照发布」…）；逐号换算表见本文 编号治理历史.md §9.3	⚠ 机器面空白：中文前缀不进 scripts/archive/id_gate/check_ids.py 语料（族 pattern 全是拉丁形态）→ 门禁咬不到，今天只有本表 + 编号治理历史.md §9.3 + 评审三条兜；id_aliases.json 刻意不登记（登记了机器也看不见，只多一张没人核的表）
测试验证层级号（L0、L0.5、L1~L3 这一族，注意与 UI 设计令牌层 L0、硬件位号 L1~L3、采集链旧层名等同形族无关；2026-10-28 批次六）	文档与 CI 步骤名写语义名（静态门禁 / 主机侧纯逻辑单测 / 板端测试套件 / 主机侧回归 / 人工目检）；ASCII 短码（static / preflight / commitmsg / size / host-unit / coverage）只进日志标签、命令行旗标、CI job id、日志文件名	⚠ 同形族警示：逐号换算表与判族表见 scripts/archive/id_gate/编号治理历史.md §10 与 §10.1（撞族六个，动手前先判族）；本族虽是拉丁形态但门禁咬不到——id-check 同日退役、现行 id-check-new 只看新增行里的「字母+数字」形态，停发只靠本表 + 归档换算表 + 评审
E-xx 审计发现、P0-x~P3-x 审计条目、报告六族 D/R/F/N/U/S、复审残号 S1~S14/A-x/B1~B10/T-x、模拟器差距 H-x/L-x、TM-* 阶段号、DP-*、gen/round/会话临时号	写条目本身（"原子快照取数"、"队头阻塞"、"台架日志代次 288"、"第 3 轮台架"）	别名表标 void；部分死号故意不进别名表，好让门禁继续咬残留引用
规范曾规划却从未启用的前缀族（DEF/WI/DR/OQ/RSK/GAP/SC/GEN/MS/UL/LAT/CS 等）	同上，写事实	无定义，本就不该存在

想知道某个号还活着吗：跑 scripts/archive/id_gate/check_ids.py --top 0，或直接查 id_aliases.json——命中 void / retired-to-phrase 就是死号。看到查不到的号，正确动作是删号留事实，不是补一个定义。

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

族还在注册表里、但属主登记处已删的：只为让冻结历史行不报"未登记前缀"而保留登记，游标一律冻结， 不得新增、不得复用。

4.4 这些不是编号——别顺手清，也别当门禁漏洞

元器件位号 U1/C12/R3/L5/D7（硬件语料按目录整体排除）、数学与协议记号（N-1、测频的正序与 负序分量 S1/S2、SHA-256、RS-485、ADC1_IN14、手册页码）、活表代号 E0~E19（网络自愈 §5.2， 无连字符，与死号 E-nn 只差一个连字符）、Socket 状态组合 U1~U15（网络自愈 §1.1）、档位词 P0~P3。 判据只有一条：带连字符、且能在属主登记表查到定义才叫编号；查不到的就是普通文本，不是「漏登记的号」。

2026-10-27 补两条实测口径：① 元器件位号目录整体排除——tools/netlist_semantics/ 是硬件知识库 （字母 T 紧跟数字在那里是网络变压器位号），已进 id_registry.json 的 excluded_paths，与 docs/硬件平台/ 同口径； ② 唯一已知误判：docs/算法/傅氏算法详解.md 里的数学记号 N-1（「一个周波 N 个点」的求和上界）会被 N-x 族命中，属可判定引用、不影响两根护栏，不清——清了反而破坏公式。

5. 分配、引用、销项

5.1 新增编号

先过 §1 三问。确实要发号：① 在 id_registry.json 确认族与游标 ② 在属主登记处写定义行 ③ 才允许在 别处引用。没有属主登记处的号不许存在——门禁的校验 3 就是照这句实现的。 族不在 §4.1 那 5 行之内的，第 ① 步就该走不通（TC-* 已停发：即使在 registry 里查得到它、游标还是活的， 也不构成"能发号"的理由，见 §4.1 末框）。

5.3 代码注释

优先写短语（FTP 鉴权、监听生命周期模块化），别写字母号；确需引用活号时必须带属主文档名。 规划 / 待办类编号禁止出现在代码里——代码的寿命比任何一张待办表都长，待办表改了行，注释就成了 永久的假引用（本仓实测：196 处这样的死引用，全是这么攒出来的）。

5.5 销项与归档

删登记行 + 同步清掉全仓引用（清引用是销项的一部分，不是"以后再说"）+ 别名表标 void。 冻结的历史（变更记录行、[示例] / [计划] 行）不回改，门禁对它们已豁免。现状补充：2026-10-28 起新文档一律不再设「变更记录」节（docs/文档规范.md §5.1），所以这条冻结规则只对仍保留变更记录表的 5 篇（同一份清单）与 scripts/archive/id_gate/ 下的归档文档生效——不是「以后还能往变更记录里写」的理由。唯一例外（用户裁定 2026-10-28）：这类行里已停发 / 作废族的示例编号可改成形态描述（写成「字母紧跟数字」这类说法）——改的是示例的写法，不是历史事实；保留现存号族的游标数字与硬件位号举例不在例外内，形态化等于毁证据。

5.7 语义标识的登记与别名

短语就是登记处的行名，不需要别名表；**只有"号转短语"**时才在别名表留一条 retired-to-phrase， note 写清短语，方便把残留引用找干净。

---

8. 门禁（2026-10-28 起：只有一道）

现行门禁 = id-check-new（钩子同名）：只查 git diff 的新增行里有没有未登记形态的 「字母+数字」标识；零语料、零维护。判据、白名单与盲区 → docs/门禁说明/id-check-new.md。

本节以下（编号治理历史.md §8.1~编号治理历史.md §8.4）是已退役的全库语料审计（id-check，八项校验）的留档： 脚本与两份语料已整体移入 scripts/archive/id_gate/，不再进提交门禁， 只在你手工复查「存量编号现状」时才跑。退役理由与判据替换见 §8.5； 八项校验一句话版（历史口径）：① 未登记前缀 ② 形态不合规 ③ 悬空引用 ④ 重复定义 ⑤ 冻结族越游标 ⑥ 编号未紧邻文档名 ⑦ 孤儿条目（告警）⑧ 可判定比例 + 两根护栏。

8.5 门禁退役路线（2026-10-28 裁定）

目标不是"关掉检查"，而是把成本从养 99 族语料降到禁止新编号。三步，每步可独立回滚：

步	内容	状态
①	两根护栏（比例基线 / 不可判定绝对数上限）转报告制：照打数字，不再影响退出码	已完成 2026-10-28
②	用 diff 级新号拦截替换语料审计：只看新增行里命中"字母+数字"形态、且不在白名单里的字面量，FAIL 并提示改成语义短语；白名单 = 前缀级两张表（活族 11 + 器件/协议/点号约 90），基本不增长	已完成 2026-10-28（scripts/check_ids_new.py + 钩子 id-check-new，与 id-check 双跑观察期；详解 docs/门禁说明/id-check-new.md）
③	退役语料：99 族语料＋脚本整体移入 scripts/archive/id_gate/（保留可复现性，不再进提交门禁）；check_ids.py 降为手工报告工具，钩子摘除（口径 52 → 51）	已完成 2026-10-28（用户裁定跳过观察期直接做；docs/门禁说明/id-check-new.md 是唯一现役编号门禁）

在 ② 落地之前，校验 1~6 仍是唯一的机械牙：别因为"两根线不拦了"就顺手写号—— 新增的未登记前缀照样当场 FAIL（实测：在一个新文件里写一个自造前缀 + 数字，校验 1 与增量拦截双拦）。

---

10. 速查

• 看到一个不认识的号 → 先查 id_aliases.json 与属主登记表；查不到就删号留事实，不要补定义。
• 想给待办 / 缺陷 / 差距 / 风险发号 → 不许，写短语（§3.3）。
• 想知道「还有多少号可清」→ 看 编号治理历史.md §9 的存量表与三批计划。
• 想给文档内步骤或测试阶段发号 → 不许，写「步骤 3」「阶段 7」（§3.3）。
• 想新增前缀族 → 先回答"哪个脚本要按字面量匹配它"（§4.1）；答不出就别建。
• 要改号 → scripts/rename_ids.py + 编号治理历史.md §7.3 五步。
• 门禁报错读不懂 → docs/门禁说明/id-check.md。

---

变更记录

（本文件不再记流水账：改了什么是正文说了算，改动过程查 git log。）