wandering1
dc44c1e54e
用户诉求原话："现在门禁都在干什么，我一概不知。" 原有文档回答"有哪些钩子、怎么配"，回答不了 "这一条到底在拦什么、什么时候会骗我"。本目录按**每种门禁一篇**补齐 23 篇（39 个 hook id 全覆盖： 16 个主机单测是同机制 16 实例合一篇；cppcheck 与 test-cppcheck 是同工具两套范围合一篇）， 文件名用 hook id，与提交输出里的名字一致、可 grep。 八段固定结构：查什么 / 为什么要它（拦下过什么真事）/ 触发面 / 报错怎么读 / 好处 / **限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。最后一节是这批文档存在的理由—— 只看"拦了什么"的文档会让人以为绿就是对的；本仓三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、 id-check 台账 640 处）的绿灯含义只是"没比上次更差"。README 另立"三种拦截姿态"一节：改写型 / 硬拦截 / 增量拦截，分清才知道报错时该改代码还是该还基线。 有实证的地方全部带数字，没实证的地方直接写"预防性、未记录到实际拦截案例"（不编故事）： · cppcheck：把 simulator/ 纳入受检后立刻揪出 sim_syslog.c 真实空指针；test/ 曾有 s_rx_buf 使用先于声明；**并记入两条实测负结果**——它对 14 处丢弃 HAL_SPI_* 返回值与"未初始化局部量 进 P_FAIL 判定"一条不报（这正是 consume-result 的由来）。 · lv-conf-sync：漂移导致 64,576 B 死代码入库（旧镜像的 23.5%），且 golden 跑的是模拟器那份配置。 · cubemx-survival：2026-09-29 一次重生成覆盖 4 处定制（P0×1+P1×2+P2×1），且不报编译错。 · registration-check：rs485_task.c、lftpd_log.c 两处都没注册 = 从不参与编译的死代码；第四类 "页面描述了但没接进 s_defs[] 表"编译链接全过，前三类完全照不出。 · test-suite-switch：实测已提交的 HEAD 里 TEST_SUITE_CH395F 就是开着的，.map 含 34 处 test 代码。 · task-table：2026-09 两张表都比源码落后一大截（写 2048/4096/…/16384，实际 1024…512）。 · mem-numbers：2026-09-26 复核，文档写 82,048 B / 62.6%，实际 87,040 B / 66.4%；Flash 写 249,432 / 23.8%，实际 261,932 / 25.0%。 · ui-golden：注入 .top_y +3 像素 → golden FAIL 点名"1366 px 差异"、退出码 1；并把"有基线 ≠ 有门禁"与"逼人 --no-verify 的门禁等于没有门禁"两条选型依据写进去。 · check-yaml：本仓已移除的 always 键只告警 Unexpected key(s) 然后忽略——配置"看起来生效其实没 生效"而本门全绿，所以验收方式是实跑看目标钩子是 Passed 还是 Skipped。 · no-mojibake：types: [c] 只管 C/H，**文档侧乱码无人管**——覆盖面与需求错配定性写进限制一节。 盲区写法示例（每篇都要求写真实限度，不留空）：layer-deps 只查直接 include、按 basename 匹配、 不查是否真的用到；font-charset 管不到运行期拼出来的字符串与配置文件里的字；host-unit-tests 用宿主 编译器、桩是第二份真相、include_dirs 手写、没有对应钩子的模块等于零回归；mem-budget 的 92% 是管理 阈值不是安全余量、.map 缺失即"通过式跳过"；registration-check 不看条件编译与注册指向是否正确； coding-standard 的 CODE-RULE-17 在无配对头时跳过、规则编号 14 作废不回收。 写文档过程自己被自家门禁拦了两轮，都按规矩改而不是绕过： ① doc-links 拦下我自己——我在解释"写 §数字 而没紧邻文档名会被判成本文自引用"这段话里，正好 就犯了这个写法（两处），另有一处示例输出未标记；改成正例写法 + [示例] 标记。 ② id-check 拦下 7 类新账：示例报错行里的号、档号引用未紧邻文档名、说明"裸形不合规"时自己写了 裸形。全部改成平实描述或补文档名、给样例加 [示例]，没有一条是往台账里塞 reason 解决的。 这两次本身已写进相关篇目的"限制/变更记录"，是这套文档最实在的注脚。 同步：手册 pre-commit使用说明.md 的 §2 顶部加指针（逐项详解已迁往本目录；两处收敛为"通用机制 + 总览 + 指针"排在 docs/门禁说明/README.md §4 的下一步，并注明收敛要按内容重指既有引用——只核编号 存在与否不够）；README 索引 23 行状态全部置为已写、文档列改为可达链接。 验证：纯文档，不动代码与构建产物；check_doc_links --all --sections-strict **171 篇 0 问题** （新目录 24 个文件的内部链接与跨文档引用都纳入判定）；id-check --strict 增量拦截通过；本次受影响 文件 pre-commit run **RC=0**；24 个文件字节卫生 0 异常（无 BOM、无 CR、无 U+FFFD、均有尾换行）。
7.0 KiB
7.0 KiB
id-check — 编号门禁（实体编号的八项校验）
一句话：它管**"号"这个东西不许野生**——每个编号必须属于一个已登记的族、形态合法、 有定义处、有人引用、引用它的时候说清是哪篇文档的号。 规范正文 =
docs/编号规范.md（§4 前缀总表、§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/N-x/TC-*/E-xx/TRAP-*/D10/U12等几十族编号，历史上出过 真事故：登记簿销项删行后号被复用（撞号）、引用指向已被删的号（悬空）、同一字面量两个 属主（重复定义）。规范 §1 把成因写得很直白：连字符与补零偷偷承载语义。 - 本次实测拦下过我自己两次：一次是"字母加数字"自造号（校验 1），一次是引用某个跨文档 编号时没紧邻文档名（校验 6）——两次都是提交前门直接报，说明它在真起作用。
- 校验 8 是唯一的"趋势"闸门：它不要求号变少，只要求解释能力不许退化（新增不可判定的字面量会让比例下跌 → 失败）。
3. 触发面
- 扫描面以 git 清单为准。当前一次实跑：551 个文件、编号字面量 8868 处。
- 排除：
Lib/、Middlewares/、HAL/CMSIS、docs/芯片手册/、docs/硬件平台/。 最后一个是关键：硬件文档里的元器件位号U1/C12/R3/L5/D7与我们的编号字面 同形，不整体排除就会大量误报（脚本里另有一套位号识别，但仍没有解除这两个目录的语料排除）。 - 已声明的"同号不同义"族对（
docs/编号规范.md§4.3）：实跑 583 个字面量走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（按指纹豁免，实跑 640 处在册）。
5. 好处
- 把"编号卫生"从人脑记忆变成机器判定：销项只做一半、引用写错文档、自造号，都会在提交时被点名。
- 台账机制让存量不阻塞日常工作，同时"无台账外新账"这句话是可验证的承诺。
6. 限制与盲区（这一节请当正文读）
- 绿灯不等于编号都合法：门禁是【增量拦截】——存量 640 处按台账豁免。它保证的是 "没变差"，不是"干净"。
collides_with白名单挡事故、不挡可读性。已声明同号不同义的族对不再报——于是 "新造一个和已有裸形撞车的代号"可以一路绿灯。这正是本门禁今天照不出来的东西： 我自己造的四个字母数字代号在被改名前，没有任何一条校验会响（同形多义已被声明为已知事实）。 结论：编号可读性要人管，docs/门禁说明/bsp-err.md§6 那条就是这个教训的落点。- 实跑有 867 处"裸形盲区"：形态太像普通词/数字组合的字面量识别不出来，等于不在管辖内。
- 校验 7（孤儿）只告警不拦提交：定义完一直没人引用的号会长期存在而门禁不响。
- "定义"的判据是"出现在属主登记处文档里"，不校验语义：写进错的属主文档、或写成一句 否定（"该号从未存在"）也算定义——批量改名工具最阴的失效模式就是"字面改对、意思改错"。
- 登记表类文件不得当引用语料（
id_registry.json、id_aliases.json、id_known_backlog.json、scripts/rename_maps/里必然写着旧的非法形态），否则第一次提交就被自家审计表当"新账"拦下。 - 校验 8 只许涨不许跌：好处是防退化，代价是顺手写一个未登记族的号就会红，哪怕与本次改动无关。
- 它不懂"这个号该不该存在"。新增一族编号是否合理，仍是
docs/编号规范.md的人工判断。
7. 豁免与台账口径
- 存量：
scripts/id_known_backlog.json（指纹级）；只减不增，收紧用--prune-backlog。 - 别名：
scripts/id_aliases.json（旧字面量 → 现行字面量）——号改名走scripts/rename_ids.py， 它会显式写别名条目，绝不全局查找替换。 - 比例基线：
id_registry.json的decidable_ratio_baseline（实跑当前 82.85%，基线 82.6%、容差 0.1pp）。
8. 改这个门禁本身
- 改族定义 = 改
scripts/id_registry.json，改完必须看编号字面量总数有没有变小： 历史上两次批量改名后，识别正则的上界没跟着放宽，整批号不再被匹配（等于静默放行）。 - 不要为了绿而往台账加 reason；确实该欠的债要写清楚原因（默认禁止顺手加）。
- 台账文件自身不是语料（见 §6 第 6 条），改动它之后要单跑一次确认没有自循环新账。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-23 | 首篇逐项文档（数据为当日实跑：551 文件 / 8868 字面量 / 台账 640 处 / 可判定 82.85%） |