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

id-check — 编号门禁（实体编号的八项校验）

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

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

1. 它在查什么

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

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

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/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/id_known_backlog.json（按指纹豁免，实跑 0 处 / 0 类指纹在册；HEAD 台账 303 条指纹 / 651 处）。

5. 好处

• 拦下过真事（2026-10-25 追加）：docs/任务规划/测试与架构专项.md 一条返工提交被 校验 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 只许涨不许跌：好处是防退化，代价是顺手写一个未登记族的号就会红，哪怕与本次改动无关。
8. 它不懂"这个号该不该存在"。新增一族编号是否合理，仍是 docs/编号规范.md 的人工判断。
9. 变更记录行豁免（2026-10-26 加）：首格是日期的表格行不参与判定——政策禁止回改历史， 拦它等于逼人改历史或 --no-verify。代价：新写进变更记录行的旧形态编号照不出来。
10. 二进制工件整体跳过（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/id_known_backlog.json（指纹级）；只减不增，收紧用 --prune-backlog。
• 别名：scripts/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 现在只列「有属主登记处、且全仓真有引用」的族；原 docs/编号规范.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. 族保留登记、只停发（游标冻结不前进）。不为"看着干净"而删族：删族后历史行与别名表里的旧号会立刻 报「未登记前缀」，等于把清理变成制造新账（与 docs/编号规范.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 | …）那类表漏豁免——同一份冻结历史被两种表头拆成两种待遇，属工具缺陷， 现已补齐（要求版本号与日期两格连排，单独的版本号不算，避免普通表格被误免）。

8. 改这个门禁本身

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

9. 变更记录

日期	变更
2026-10-26	方案 B（同日续批）：登记簿系 N-x/S-x/T-x/A-x 与 UI 簇 U1~U5 共 20 个号停发、约 418 处引用转语义短语（字面量净减 443：8,946 → 8,503）；新增第二根护栏「不可判定引用绝对数上限」（undecidable_total_ceiling，只减不增），并把比例基线下调——理由与实测（比例跌、绝对数不涨）见 §7.6；CHANGELOG_ROW 补「版本号 + 日期」表头的变更记录行
2026-10-26	清号批次（用户裁定：字母+数字编号太多、没人认得）：全仓删除「属主已死 / 从未启用」的编号约 1,100 处，规范 §4.1 收成全活族 + §4.1.1 列已清除族，§4.2/§4.5/§7.1/§9 作废压缩。门禁口径不变（族仍登记，只拦新增引用）；扫描面 / 字面量总数 / 台账 / 比例基线按本批实跑重打（见 §3、§7）。新增 §7.5 讲清"比例上升 ≠ 卫生变好"的读法
2026-10-25	二进制工件跳过（§6 第 9 条）：iter_files 按 gzip 魔数/头 2KB NUL 嗅探排除 gz/png 等，防乱码伪编号顶出校验 1 假新账（f3rounds gz 入库实测触发）；602 处存量台账口径不变
2026-10-25	补「owner_docs ≠ 定义集」口径（§2 末条）：snapshot_only 族的登记处挂在规范正文时，_def_owners 为空 → 只恢复可判定、不参与悬空/撞号/裸形/紧邻。基线 82.6% → 84.0%（删《项目审查与优化建议报告》+ 补登 11 条已死号别名后重打，实测 84.02%、696 文件 / 10410 字面量）
2026-10-23	首篇逐项文档（数据为当日实跑：551 文件 / 8868 字面量 / 台账 640 处 / 可判定 82.85%）