STM32F4-Base/docs/门禁说明/id-check.md

id-check — 编号门禁（实体编号的八项校验）——已退役（2026-10-28）

⚠ 本文是退役留档，不要照着它去改门禁。 2026-10-28 用户裁定：编号体系本身不再产生价值，全库语料审计的维护成本高过收益 → 钩子摘除（52 → 51），脚本与两份语料整体移入 scripts/archive/id_gate/； 接班件 id-check-new 也已于 2026-10-29 退役（只查新增行那道，用户裁定）→ docs/门禁说明/id-check-new.md。 两道编号门禁自此全部退场：编号形态没有机器面，判据回到 docs/编号规范.md §1 三句自问 + §4.1 族总表 + 人工评审；归档脚本 scripts/archive/id_gate/check_ids_new.py 可随时手工普查形态。 退役路线与判据替换 → docs/编号规范.md §8.5。下面保留退役前的原样描述与实测基线， 只在手工复查「存量编号现状」时还用得上。

一句话：它管**"号"这个东西不许野生**——每个编号必须属于一个已登记的族、形态合法、 有定义处、有人引用、引用它的时候说清是哪篇文档的号。 规范正文 = docs/编号规范.md（§1 默认答案（一律停发）、§4.1 存量族〔穷举〕、§8 门禁与实测基线），本门禁是那八项的机械执行。

• 配置：entry: python scripts/archive/id_gate/check_ids.py --strict，pass_filenames: false， files: 覆盖 .md/.c/.h/.py/.yaml/.json/.txt 与配置文件本身。
• 两份数据源（不是脚本里写死的）：scripts/archive/id_gate/id_registry.json（族 → 形态正则 / 属主登记处 / 是否冻结 / 游标 / 作用域 / 级别）、scripts/archive/id_gate/id_aliases.json（旧字面量 → 现行字面量）。

1. 它在查什么

校验	内容	级别
1	出现未登记前缀（自造编号）	错误
2	形态不合规：缺连字符的裸形（模块字母直接跟数字）、族名与数字之间空一格的空格形、中文形、补零位数不对、档位词带后缀、缺模块码	错误
3	悬空引用：引用了查无定义且不在别名表的号	错误
4	重复定义：同一字面量被两个属主各定义一次	错误
5	冻结族越游标：已冻结的族里出现游标之外的新号	错误
6	引用未紧邻文档名：文档内编号（各文档自己的风险表等）裸引	错误
7	孤儿条目：定义了但全库无人引用	告警（不拦）
8	打印编号引用可判定比例与不可判定引用绝对数；记录基线 / 上限在 id_registry.json	只报告（2026-10-28 起不再失败，见 §7.6）

"定义"的机械判据是：该字面量出现在它所属族的"属主登记处"文档里。不依赖表格行首之类 容易漂移的形态。副作用要知道：把号写进属主文档的任何位置都算定义。

2. 为什么要它

• 本仓曾同时存在几十族编号（N-xx/TC-*/E-xx/TRAP-*/D10/U12…），历史上出过 真事故：登记簿销项删行后号被复用（撞号）、引用指向已被删的号（悬空）、同一字面量两个 属主（重复定义）。规范 §1 把成因写得很直白：连字符与补零偷偷承载语义。
• 本次实测拦下过我自己两次：一次是"字母加数字"自造号（校验 1），一次是引用某个跨文档 编号时没紧邻文档名（校验 6）——两次都是提交前门直接报，说明它在真起作用。
• 校验 8 是唯一的"趋势"闸门：它不要求号变少，只要求解释能力不许退化（新增不可判定的字面量会让比例下跌 → 失败）。
• owner_docs ≠ 定义集（2026-10-25 起）：族可以"有登记处"却"没有定义位"。判可判定只看 owner_docs 是否解析出真实文件；而悬空（校验 3）/ 撞号（校验 4）/ 裸形（校验 2）/ 紧邻（校验 6） 一律只看 _def_owners。两者仅在一种情形下不同：snapshot_only 族的登记处挂在规范正文 （docs/编号规范.md §4.3 说的冻结前缀：登记处只剩冻结存档，甚至只存在于规范正文）。规范正文里混着大量写法示例， 若拿它当定义集会立刻误伤——实测裸形 S1 被判成 S-1 漏连字符 238 条、表里 S-3 与登记簿 S-3 被判重复定义。所以这类族的 _def_owners 为空，等价于"属主已删、只有存档"。 代价要认清：这类族的号不会再被校验 3 兜住，新增引用只能靠别名表或人工核。

3. 触发面

• 扫描面以 git 清单为准。最近一次实跑（2026-10-26 编号迁移批次后）：754 个文件、编号字面量 8,230 处（方案 A 之前 10,956 → 方案 A 之后 8,946 → 方案 B 之后 8,503 → 编号迁移批次后 8,230）。
• 排除：Lib/、Middlewares/、HAL/CMSIS、docs/芯片手册/、docs/硬件平台/。 最后一个是关键：硬件文档里的元器件位号 U1/C12/R3/L5/D7 与我们的编号字面 同形，不整体排除就会大量误报（脚本里另有一套位号识别，但仍没有解除这两个目录的语料排除）。
• 已声明的"同号不同义"族对（docs/编号规范.md §4.3）：实跑 876 个字面量走 collides_with 白名单，不计入校验 4。

4. 报错怎么读

[FAIL] 编号门禁·增量拦截：N 类台账之外的错误级问题（新引入的债）
    +2  [校验1] <文件>  <字面量>
    → 改引用/补登记处；确属该欠的债要在台账写 reason（默认禁止顺手加）

• 单独跑：& '.venv\Scripts\python.exe' scripts/archive/id_gate/check_ids.py --strict --verbose（--verbose 带修法，--top 30 多打，--only 1,3,5 只跑指定校验）。
• 常用旗标：--strict（钩子用的档位）、--verbose、--write-backlog / --prune-backlog （重建 / 收紧台账）、--update-baseline（把当前可判定比例写回 id_registry.json，只许涨）、--no-trace。
• 存量在 scripts/archive/id_gate/id_known_backlog.json（按指纹豁免，实跑 0 处 / 0 类指纹在册；HEAD 台账 303 条指纹 / 651 处）。

5. 好处

• 拦下过真事（2026-10-25 追加）：一份专项文档（原 docs/任务规划/测试与架构专项.md，已删除 2026-10-28）的一条返工提交被 校验 6 拦下 4 处——C 注释里裸写该文档的条目编号、未紧邻属主文档名；补齐文档名即过。 实证紧邻写法在代码注释里同样是硬约束，不是只约束 Markdown。

• 把"编号卫生"从人脑记忆变成机器判定：销项只做一半、引用写错文档、自造号，都会在提交时被点名。

• 台账机制让存量不阻塞日常工作，同时"无台账外新账"这句话是可验证的承诺。

6. 限制与盲区（这一节请当正文读）

1. 绿灯不等于编号都合法：门禁是【增量拦截】——存量 0 处按台账豁免。它保证的是 "没变差"，不是"干净"。
2. collides_with 白名单挡事故、不挡可读性。已声明同号不同义的族对不再报——于是 "新造一个和已有裸形撞车的代号"可以一路绿灯。这正是本门禁今天照不出来的东西： 我自己造的四个字母数字代号在被改名前，没有任何一条校验会响（同形多义已被声明为已知事实）。 结论：编号可读性要人管，docs/门禁说明/bsp-err.md §6 那条就是这个教训的落点。
3. 实跑有 827 处"裸形盲区"：形态太像普通词/数字组合的字面量识别不出来，等于不在管辖内。
4. 校验 7（孤儿）只告警不拦提交：定义完一直没人引用的号会长期存在而门禁不响。
5. "定义"的判据是"出现在属主登记处文档里"，不校验语义：写进错的属主文档、或写成一句 否定（"该号从未存在"）也算定义——批量改名工具最阴的失效模式就是"字面改对、意思改错"。
6. 登记表类文件不得当引用语料（id_registry.json、id_aliases.json、id_known_backlog.json、 scripts/rename_maps/ 里必然写着旧的非法形态），否则第一次提交就被自家审计表当"新账"拦下。
7. 校验 8 的两根护栏自 2026-10-28 起只报告、不拦提交：此前"只许涨不许跌"好处是防退化，代价是 顺手写一个未登记族的号就会红，哪怕与本次改动无关——代价最终由每一笔提交付，故转报告制（§7.6 末）。
8. 它不懂"这个号该不该存在"。新增一族编号是否合理，仍是 docs/编号规范.md 的人工判断。
9. 变更记录行豁免（2026-10-26 加）：首格是日期的表格行不参与判定——政策禁止回改历史， 拦它等于逼人改历史或 --no-verify。代价：新写进变更记录行的旧形态编号照不出来。
10. 未跟踪文件不在扫描面（2026-10-28 实测）：文件清单来自 git ls-files， 新文件在 git add 之前扫不到。提交时跑不受影响（要提交的文件必已进索引）， 但手工在暂存前跑会得到假绿——别拿这种手工结果当门禁结论。
11. 二进制工件整体跳过（2026-10-25 task-22 补）：gz 串口存档 / png 等字节流没有编号语义， 按文本 errors=replace 解码后随机字节会拼出「字母-数字」形态的伪编号，把无关存量顶成 校验 1 的"台账外新账"（boot_log_data 落 f3rounds gz 时实测拦下提交——本节文字引用这类 噪声形态时同样会被扫，措辞必须只描述形态不举例）。判据 = gzip 魔数或头 2KB 含 NUL → 计入 binary_skipped，口径与 noise_literals/裸形盲区一致。反向盲区也在案：真编号若只存在于 二进制工件里，本门禁看不见——需要它可判定时就该以文本形态入库。

• 裸形多义是显式承认的盲区（docs/编号规范.md §1 与 §4.4）：同一个裸形字母在本仓可能同时是风险号、 档位、层号、元器件位号。所以裸形族只在属主登记处文档内判"越游标"，文档外降级处理。本目录 bsp-err.md §6 记的那件事正是这个洞的产物。
• 本钩子顺带收编 scripts/check_test_traceability.py（TC 用例双向追溯），它不是独立钩子； 改 TC 相关正则时两个脚本要一起看（历史上批量改名后就出现过正则上界没跟上、整批号不再被匹配）。
• 有牙实测的做法：把假编号注入临时档（git add -N 进索引，跑完 git rm --cached 并删除， 保证 git status 干净），看它是否被点名。
• --update-baseline 只许涨：可判定比例下跌时拒绝写入——防止用抬基线掩盖退化。

7. 豁免与台账口径

• 存量：scripts/archive/id_gate/id_known_backlog.json（指纹级）；只减不增，收紧用 --prune-backlog。
• 别名：scripts/archive/id_gate/id_aliases.json（旧字面量 → 现行字面量）——号改名走 scripts/rename_ids.py， 它会显式写别名条目，绝不全局查找替换。
• 比例基线：id_registry.json 的 decidable_ratio_baseline（实跑当前 86.01%，基线 86.0%、容差 0.1pp）。

7.5 2026-10-26 清号批次对门禁的影响

• 删的是引用，不是登记：E-xx、P0-xP3-x、报告六族（D/R/F/N/U）、复审残号（S 族 114 / A 族 / B 族）、 会话临时号、TM-* / DP-*、模拟器差距 H-x/L-x 等族仍留在 id_registry.json（frozen / snapshot_only）， 为的是历史行与 [示例] 不报错；但活文档与代码注释里已不再引用它们，新增引用会被校验 3 / 5 当场拦下。
• 可判定比例为什么上涨：这些族的属主登记处已删 → 字面量原本进分母、不进分子。删掉这类"判不了" 的引用，分母缩小，比例自然上升。⚠ 这不等于"编号卫生变好了"——真证据是编号字面量绝对数下降 （清理前 10,956 → 现在 8,230）且校验 2/3/6 的存量同时下降。只报比例不报绝对数，就是自欺。
• 族不是越多越好：docs/编号规范.md §4.1 现在只列「有属主登记处、且全仓真有引用」的族；原 scripts/archive/id_gate/编号治理历史.md §4.2 那 15 个 「改名后才启用」的目标前缀已作废——空族会骗人：读者看到 DR-001 就会去找一张根本不存在的登记表。
• 要加一族：先改 docs/编号规范.md §4.1，再改 id_registry.json，两处同一批提交（docs/编号规范.md §5.1 第 1 步）。
• 本批顺带补了「变更记录行」豁免（CHANGELOG_ROW：表格首格是日期、或「（规划稿）」）： rename_ids.py / doc-links / 追溯器早就是这条口径，唯独本门禁缺——于是把 docs/编号规范.md §5.5「历史不回改」 锁死的行当活账拦提交，实测 36 处错误级 + 20 处告警全来自历史行。豁免后这些行的编号 不再被判定（新增时也判不到，这是这条豁免的代价，写进 §6 盲区）；被跳过的字面量数打印在 扫描首行（变更记录行 N 处），不让它变成看不见的面分母缩水。

7.6 方案 B（同日）：登记簿系编号退休为语义短语，与新增的第二根护栏

用户裁定「B 方案」：把规划 / 待办类在册编号也停发——登记簿 N-x/S-x/T-x、专项 A-x、已删报告的 UI 簇 U1~U5， 共 20 个号；引用侧同批改写约 418 处、字面量净减 443（8,946 → 8,503）——构成：在册活号 237 处 + 指向已销项号的死引用 196 处（FTP 鉴权 / 监听生命周期模块化 / 探针窗口心跳缺口 / 日志读写放大那批已销项号）+ UI 簇非位号约 45 处。 对门禁的三件事：

1. 族保留登记、只停发（游标冻结不前进）。不为"看着干净"而删族：删族后历史行与别名表里的旧号会立刻 报「未登记前缀」，等于把清理变成制造新账（与 scripts/archive/id_gate/编号治理历史.md §8.3 记的「快照族先补定义位」同一方向的教训）。

2. 旧号进 id_aliases.json 标 status: retired-to-phrase（不是 void）——区别在于条目还活着， 只是不再用号指它。门禁两者都只当"可解析"，都不许再被活文档引用。 ⚠ 反过来，那批故意不进别名表的死号（FTP 鉴权那个旧号）：进了就等于把残留引用永久洗白； 让校验 3 继续报它们，才是"引用清干净了"的机器证据。本批实测：转换掉定义位后， 那 12 处 Drivers/BSP/** 残留立刻从"静默"变成 12 条错误——这正是想要的效果。

3. 新增第二根护栏：不可判定引用绝对数上限（id_registry.json → undecidable_total_ceiling，只减不增， --update-baseline 同时下调用它，且拒绝上调）。为什么必须加：

   清号批次把「本可判定的引用」换成散文，分子分母同时缩小——比例这类比值指标反而下跌。 实测本批 86.4% vs 批次前 86.7%，而不可判定引用绝对数一处没涨（清号前 1,192 → 清号后仍 ≤ 该值）。 也就是说比例的下跌 100% 是稀释，不是卫生退化；只拿比值当护栏，等于惩罚清号本身。

   所以同批把 decidable_ratio_baseline 下调到本批实测值（工具按设计拒绝下调，需人工改 registry—— 这是有意的摩擦：下调基线必须留下书面理由，理由就写在本节）。此后判断"编号有没有变坏"看两条： 不可判定绝对数（会不会新增没登记的号）+ 字面量总数（号有没有变多），比值只作趋势参考。

顺带修的口径：CHANGELOG_ROW 原先只认「首格是日期」的变更记录行，首格是版本号、次格是日期 （| v1.6 | 2026-10-25 | …）那类表漏豁免——同一份冻结历史被两种表头拆成两种待遇，属工具缺陷， 现已补齐（要求版本号与日期两格连排，单独的版本号不算，避免普通表格被误免）。

7.6.1 2026-10-28：两根护栏转「报告制」（本节口径的最新状态）

用户裁定：编号门禁每次浪费很多时间，而语义标识已是默认形态 → 先摘掉语料审计的强制面。

• 变的是强制力：护栏 1 / 护栏 2 越线只打 [报告] 两行，退出码不再受影响； 上面 §7.6 描述的"下调基线要留书面理由"这套摩擦随之退役（--update-baseline 仍在，用来记当前值）。
• 不变的是牙：校验 1~6 的台账外新账照旧拦提交（--strict），这是本次减负的边界。
• 减负依据（实测）：单次运行仅 1.8 s，但近 80 笔提交里 61 笔改了语料 / 门禁 / 规范； 语料共 99 族（78 族已冻结、8 族快照、21 族未冻结），registry 87.6 KB + 别名表 187 KB。
• 后续路线（替换语料审计 → 退役语料）见 docs/编号规范.md §8.5。

7.7 「不可判定绝对数」到底是什么：构成实测 + 每批自证没吃余量的做法（2026-10-27）

先给一条与直觉相反的结论，它是这一节存在的理由：给带属主登记处的族加引用，完全不吃这根护栏 （那些引用算「可判定」）。这根护栏只统计门禁主动豁免掉的字面量与真·硬不可判定。

实测拆解（.venv 解释器，import check_ids 后取 Checker.stats；口径同 §7.6 的第二根护栏）：

项	数	是什么
refs_total	8,744	候选字面量总数（硬件位号在进分母之前就 continue，不计入，见 §6）
decidable	7,582	落进已登记前缀族且该族属主登记处存在
两者之差 = 护栏口径	1,162	等于下面三项之和（逐项相加精确闭合，无第四类）
└ skip_bare_unmanaged	834	裸形盲区：同字母多义的裸号出现在属主登记处文档之外，按 §6 明令不判
└ noise_allowed	326	命中 id_registry.json 的 noise_literals 白名单（不是编号，但形态像）
└ undecidable	2	真·硬不可判定：族仍登记着、但属主登记处已空（cleared_2026_10_26 那批遗留）

三条读法：

1. 这 1,162 里约 99.8% 是设计上的豁免，不是「没登记的野号」。把它当债务余额来读会得出错误结论。 它与本文件打印的「校验 1 未登记前缀：0 处」不矛盾——校验 1 报的是新增错误级，护栏统计的是分母差； 两者一个是行为、一个是水位，别互相替换。
2. 真正会推高这个绝对数的只有两类动作：在属主登记处之外新增裸形引用，或新增命中噪声表的连字符形态。 要指代就写全号并紧邻属主文档名（写法口径见 docs/文档规范.md §3.5，判它的是校验 6）。
3. ⚠ 反向错误更贵：为了「少占余量」而把编号改写成语义短语/散文——那正是 §7.6 与这根护栏的动机要防的 稀释（比值会被清号动作稀释，绝对数不会）。2026-10-27 凌晨 Lead 给三条道下过这样一条错指令，已撤回； 当时的口径是：按 docs/编号规范.md §1 先问三句，属允许族就用号（该判据 2026-10-29 作废，全族一律停发），需要新母号时由 Lead 改 id_registry.json 游标。

每批自证没吃余量（可复制的做法，五项式）：

1. 改之前先跑一次 ./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py，记下三个数：字面量总数、可判定、 不可判定绝对数。⚠ --strict 只回答「有没有新错误级」，不回答可判定占比动了没有——别拿它当替身。
2. 改完再跑一次，逐数比对。
3. 若绝对数涨了，先确认是不是本批吃的账。不要用 git stash / git checkout 去回退（那会把别人在飞的 改动一起收走，本仓同日刚为此踩过）：用 git show HEAD:<路径> 把名下文件取成临时副本，或开一棵 git worktree，只回退自己名下那几个文件，再跑同一扫描器——差值就是本批的净影响。
4. 交报告时把差值写全，形如 refs +0 / dec +0 / und +0 / 比值 +0.00pp / 错误 +0；别只写「跑过没问题」。 2026-10-26 的清号批次与同日三篇文档改写都是按这句式交的，读者能自己复算。
5. 确实还掉一块之后，用 --update-baseline 把 undecidable_total_ceiling 同步下调（脚本自己拒绝上调）。 手工把上限调高等于自废这道闸，任何时候都不许做。

8. 改这个门禁本身

• 改族定义 = 改 scripts/archive/id_gate/id_registry.json，改完必须看编号字面量总数有没有变小： 历史上两次批量改名后，识别正则的上界没跟着放宽，整批号不再被匹配（等于静默放行）。
• 不要为了绿而往台账加 reason；确实该欠的债要写清楚原因（默认禁止顺手加）。
• 台账文件自身不是语料（见 §6 第 6 条），改动它之后要单跑一次确认没有自循环新账。

6.10 「删裸形」不等于按出现次数还债（道G task-45 实测，2026-10-27）

本仓第一次真正还第二根护栏的债（绝对数 1,162 → 1,156），还掉的格数远少于删掉的裸形数，机制值得写死：

1. 只有落不进任何已登记族的裸形才计不可判定。撞进已登记族的那些本来就记在可判定一侧，删它们分子 分母同缩、可判定比例反而会上升（实测 86.74% → 86.77%）。「清了一大片、绝对数只降几格」不是算错。
2. 要真腾余量得挑无族可归的裸形态下手；撞族的删了只是稀释分母——与 §7.6 那根护栏防的稀释同源、方向相反。
3. 更省事的正解是写注释与文档时一开始就别用裸形：改用语义短语，或写全号 + 紧邻属主文档名。同日还有一 次反向教训：为「省余量」把在册族的号改成散文，那才是真把护栏当敌人（见 §7.7）。
4. 附带收益常比余量值钱：这次顺带消掉一个同形两义的撞号源（同一裸形既像自造状态号又撞已登记族）。