用户裁定原文:「**批次三,不坐**」(即不做)。本笔把裁定连同**理由与后续硬口径**一起写进 `docs/编号规范.md`, 而不是只把那一行划掉——因为「不做」最容易被误读成「那就可以继续发 TC 号」,必须把它关死。 **为什么留着 TC 族与今天的定调不矛盾**:§4.1 那条判据是「有脚本按字面量匹配它」,而 `TC-*` 是**唯一真正 满足这条判据的族**——追溯门禁与 40 套主机单测按字面量读它,C 断言标签、测试函数名、文档用例表三处同 一号,是「代码 ↔ 文档」双向核对的机器把手。清它的代价不是改文本,而是**换掉追溯机制**(候选方案「用 例名即标识」要把追溯门禁重写并重打基线),期间测试与文档的对应关系会处于**断裂态**,而测试本身就是提 交门禁(跑全部 40 套并守覆盖率基线回退)——拿它做不可逆试验不值。**结论写进文档**:机器面自解释的族 可以保留;字母号的痛在「人读」侧,解法是**别再造给人读的号**,而不是把机器面的把手也拆掉。 「不做」之后跟着两条硬口径(这才是本笔的实际效力): ① **本族即日停发**:游标冻结、现存号只减不增,**新用例一律用语义化测试函数名 + 文档表格行名,不再配 `TC-` 号**——已作为一行加进 §4.1 的『已停发』栏,并在『允许继续发号』栏开头写明「该族虽仍被脚本读, 但发号已停,其余 7 族不受影响」,免得两栏看起来互相打脸; ② 将来真要清,走 `scripts/rename_ids.py` + §7.3 五步**单独开卡**,前提是先让追溯器**同时认新旧两种形态**、 并行核对通过再谈切换;**不许先改文档再改代码**(凭空造出悬空号,校验 3 会当场拦)。 三处口径同步:§9.1 批次三正文(裁定 + 理由 + 两条口径)、§9 存量表该行的处置列(「需要先裁定」→「保留、 即日停发」)、§9 顶部执行结果表的批次三行。复核:全文再无「等你裁定 / 需要你裁定」这类悬空表述(唯一 命中的是 `UI补齐.md` 里**运行时长口径**那条,是另一件仍未决的事,没动)。 自查:`check_doc_links --all` exit 0(198 篇)、本篇 `--sections-strict` 通过(新加的「§ 8 校验 3」是紧邻本文 自引用,符合紧邻写法)、noBOM / LF / U+FFFD=0 / 结尾换行齐;本笔零代码、零编号增删,`id-check --strict` 与 不可判定绝对数不受影响。
26 KiB
编号规范:默认不用编号
一句话:语义标识是唯一默认形态,编号是例外。 例外只留给有脚本按字面量匹配的那几种 (§4.1 的「允许继续发号」一栏);同一张表里还有一栏是已停发、存量待清的族(§9.1 给清点与批次)。 除此之外一律写语义短语(§3.3)。
这条不是洁癖,是用户 2026-10-27 的明确要求:「不要用字母加数字的编号,简直太难以理解了,语义标识是最好的」。 依据也很硬:规划 / 待办 / 审计 / 差距 / 阶段这些给人看的东西,历史上全发过号,也全都变成了没人认得的代号。 2026-10-26 起两批清理把编号字面量从 10,956 压到 8,230 处,2026-10-27 复测为 7,828 处(§8.1 有口径说明); 而清掉的号里绝大多数从来没被任何脚本读过一次。沿革与教训留在 §8.3 与 git log,正文不复述。
机器面才是事实源:族注册表
scripts/id_registry.json、旧号别名scripts/id_aliases.json、 门禁scripts/check_ids.py(八项校验,详解docs/门禁说明/id-check.md)。本文与机器面冲突时 以机器面为准,并回来改本文。
1. 决定要不要发号之前,先问三句
| 问自己 | 答"否"的结论 |
|---|---|
| 有脚本 / CI / 回归测试要按这个字面量做匹配吗? | 不发号,写语义短语(§3.3) |
| 现有文档或登记表里已经能指代这件事吗? | 引用它,别再发第二个号指同一件事 |
| 一年后别人还能在属主登记表查到它的定义吗? | 查不到就别发——"先记着,以后再说"是编号失控的唯一来源 |
三条硬规矩(对确实要发的号):
- 号不承载语义:严重度、优先级、模块名、轮次都不写进号里。事实一变,号就开始撒谎。
- 号不回收、不复用:销项 = 删登记行 + 清掉所有引用 + 别名表标
void(§5.5)。历史上"销掉的号被 重新取走"撞过两次。 - 引用必须带语义:号旁边要有人话,裸号不许独担信息(读者不该被迫查表才看懂一句话)。
1.2 这四类事故就是上面三条的由来
- 同一字母多义:
P1五义、L1四义、U1四义、D7与元器件位号同形 → 前缀必须按事物类别 分配(§2)。 - 属主文档一删,号全体成孤儿:审计报告删除后,全仓几百处引用再也查不到定义 → 号越少,这种 "集体失效"的爆炸半径越小(§4.5)。
- 语义塞进号里:条目事后降级,改号则引用全断、不改则号实不符 → 号不承载语义(P-2)。
- 销项号被复用:登记簿删行后仓库里毫无痕迹,下一个条目顺手取走同号 → 不回收、不复用, 改用语义标识(短语自带唯一性)。
2. 八条设计原则(一句话版)
P-8 语义优先压过其余七条:给人看的条目一律不发号。其余七条只在"确实要发号"时生效—— P-1 前缀 = 事物类别(不是来源文档 / 审计轮次)· P-2 号不承载语义 · P-3 一个事实一个号 · P-4 规范形态唯一(连字符与补零不承载语义,写法只许一种)· P-5 只增不复用,新增先取游标 · P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语义、引用必语义。
3. 三种指代方式,按这个顺序挑
| 优先 | 方式 | 用在 |
|---|---|---|
| ① 最好 | 语义短语 | 规划 / 待办 / 缺陷 / 风险 / 决策 / 差距 / 文档内步骤与阶段——默认形态 |
| ② 其次 | 文档名 + 章节号 | 指某篇文档的某节(docs/网络/网络自愈架构设计.md §4.10,紧邻写法) |
| ③ 最后 | 编号 | 只有 §4.1「允许继续发号」那一栏,且必须能反查到定义 |
3.1 判定口诀
机器读 → 发号;人读 → 写短语。 拿不准就写短语:短语看不懂还能靠上下文猜,号看不懂只能去查表。
3.2 编号 vs 章节引用
章节引用不是编号,但同样要紧邻文档名——只写「§ + 小节号」而不写文档名,会被 doc-links 当成本文自引用而静默放过,
这是它的已知盲区,别踩。
3.3 语义标识(默认形态,怎么写)
- 一行短语就是标识:≤20 汉字、说清"是什么事"、同一登记表内不撞名(同义异写算撞名)。
- 好的例子:
双转换器无共同采样触发、FTP 鉴权、写回缓存空闲 flush、L5 队列往返基线待重验。 坏的例子:优化项 3、遗留问题、重要缺陷——换个上下文就指代不明,等于又造了个号。 - 登记处就是那张表:表首格写短语,不要再配一个字母号;跨文档引用写成
`docs/任务规划/登记簿.md` 「双转换器无共同采样触发」,同篇后续直接用短语。 - 文档内的实施步骤 / 测试阶段 / 设计原则条目写中文:「步骤 3」「阶段 7」「DMA 边界安全」,
不写
S3/TM-…/DP-…这种号。
4. 编号空间
4.1 允许用号的族(穷举——这张表以外一律不许发号)
允许继续发号(有脚本按字面量匹配,现状实测 2026-10-27 见 §9.1)——注意 TC-* 虽仍被脚本读,但
| 其发号已按用户裁定 2026-10-27 停掉(游标冻结),下表其余 7 族不受该裁定影响: | |||
|---|---|---|---|
TC-* |
TC-<模块码>-<序号> |
docs/测试说明/*_Test_Guide.md、test/host/<模块>/*(代码即登记处) |
用例↔断言双向追溯,要进 C 断言标签 |
TRAP-* |
TRAP-<域>-<nn> |
docs/问题记录/*_Trap_Records.md |
踩坑证词的永久锚点,代码注释反查 |
L<n>-<nn> |
保护功能号 | docs/算法/继电保护功能复现规划.md |
全库唯一"定义与引用都齐"的样板族 |
F-<MOD>-<nn> |
功能项 | docs/网络/网络自愈架构设计.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> |
本文的设计原则 | 本文 §2 | 就是本文自己的条目 |
已停发、存量待清(登记未删只是为了让历史行不报「未登记前缀」,不得再新增引用;清点见 §9.1):
| 族 | 状态 | 依据 |
|---|---|---|
TC-* |
保留现存号、即日停发:游标冻结、只减不增,新用例改用语义化测试函数名 + 文档表格行名 | 用户裁定 2026-10-27「批次三,不坐」;本族是 §4.1 判据唯一真被脚本按字面量读的族,清它等于换追溯机制,详见 §9.1 批次三 |
| 族 | 形态 | 存量 | 为什么该清 |
|---|---|---|---|
N-* |
登记簿 N-<nn> |
4 处 / 3 个字面量 | 登记簿已于 2026-10-26 全面改语义短语,残留的是漏网的旧引用 |
TM-* |
阶段/里程碑 TM-<code>-<nn> |
1 处 | 阶段号本就属 §3.3 明令不许写号的那类 |
T-TEST |
台架阶段 裸形 T0~T3 |
19 处 / 4 个 | 裸形最危险(同字母多义),且改「台架阶段一」即可 |
F-* |
网络设计条目 F-<MOD>-<nn> |
38 处 / 12 个 | 代码注释按号回指设计条目,但没有任何脚本匹配它 |
- 新增族的唯一正当条件:有脚本要按字面量匹配它。顺序固定:先改
id_registry.json(含属主登记处) → 再写属主文档 → 最后才允许在别处引用。反过来做必然造出悬空号。 - 模块码是既定缩写,事实源 = registry 的族 pattern 与属主文档标题行,别自创(§6)。
4.1.1 已停发的族(别再指,更别再"复用"这些号)
| 停发族 | 现在怎么写 | 旧号去哪查 |
|---|---|---|
登记簿 N-x / S-x / T-x、专项 A-x、已删报告的 UI 簇 U1~U5(2026-10-26 方案 B) |
语义短语——登记簿表首格本身就是短语,如「双转换器无共同采样触发」「CI 远端闭环未验证」 | scripts/id_aliases.json 标 retired-to-phrase |
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/check_ids.py --top 0,或直接查id_aliases.json——命中void/retired-to-phrase就是死号。看到查不到的号,正确动作是删号留事实,不是补一个定义。
4.2 目标前缀(作废)
2026-10-26 删除:那批"改名后才启用"的前缀族从未有属主登记处,留着只会把读者带到一张不存在的登记表前。
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/是硬件知识库 (T1在那里是网络变压器位号),已进id_registry.json的excluded_paths,与docs/硬件平台/同口径; ② 唯一已知误判:docs/算法/傅氏算法详解.md里的数学记号N-1(「一个周波 N 个点」的求和上界)会被N-x族命中,属可判定引用、不影响两根护栏,不清——清了反而破坏公式。
4.5 已删报告的自有族
《项目审查与优化建议报告》2026-10-25 已删除,它自造的六族随之失去定义,且与登记簿同字母不同义。 看到「报告 + 登记簿旧号」这类写法一律按死号处理:删号留事实——各条目原本指向的设计文档就是现在的出处。
5. 分配、引用、销项
5.1 新增编号
先过 §1 三问。确实要发号:① 在 id_registry.json 确认族与游标 ② 在属主登记处写定义行 ③ 才允许在
别处引用。没有属主登记处的号不许存在——门禁的校验 3 就是照这句实现的。
5.3 代码注释
优先写短语(FTP 鉴权、监听生命周期模块化),别写字母号;确需引用活号时必须带属主文档名。
规划 / 待办类编号禁止出现在代码里——代码的寿命比任何一张待办表都长,待办表改了行,注释就成了
永久的假引用(本仓实测:196 处这样的死引用,全是这么攒出来的)。
5.5 销项与归档
删登记行 + 同步清掉全仓引用(清引用是销项的一部分,不是"以后再说")+ 别名表标 void。
冻结的历史(变更记录行、[示例] / [计划] 行)不回改,门禁对它们已豁免。
5.7 语义标识的登记与别名
短语就是登记处的行名,不需要别名表;**只有"号转短语"**时才在别名表留一条 retired-to-phrase,
note 写清短语,方便把残留引用找干净。
6. 模块码表
TC 与 TRAP 共用模块码。唯一事实源是 scripts/id_registry.json 的族 pattern 与属主文档标题行;
本文故意不再抄一份——抄一份就多一处会过期的地方(历史上这张表就长期与代码不同步)。
要加模块码:先改 registry,再在属主文档出现,最后才在别处引用。
7. 改号与迁移
7.1 映射规则(作废)
"按审计报告把某族整体迁到另一族"那套映射已作废。2026-10-26 的实测结论是:绝大多数号该删不该迁。
7.2 孤儿编号处置(已完成)
代码有号、文档无号那批已按同一口径处理完:能对上属主表的补模块码,对不上的删号留事实; 绝不为了少报孤儿而凭空补定义行(那等于把账做平、把问题藏起来)。
7.3 改号操作规程(要动号就照这个走,一步都别省)
- 走
scripts/rename_ids.py:映射表驱动、显式 scope、默认干跑、自动写别名条目; 绝不全局查找替换——同一裸形字面量可能同属多个族(实测S3三义),全局替换等于造新撞号。 - 改完复核所有识别面:
check_ids.py与check_test_traceability.py的候选正则上界都要还能匹配新 形态;判据是"编号字面量总数有没有真的变小"(曾经因为正则上界太窄,改完号静默隐形 339 个)。 - 逐号做语义复核,不能只看 dry-run 命中数:最阴的失效是"字面改对、意思改错"。
- 登记表 / 映射表类文件不得当引用语料,否则自家审计表里的旧形态会被判成新账。
- 收尾重打台账
--prune-backlog(只减不增),并确认新错误级为 0。
8. 门禁:id-check(八项校验)
查什么、报错怎么读、盲区在哪——全在 docs/门禁说明/id-check.md,本文只留口径与基线。
八项校验一句话版:① 未登记前缀 ② 形态不合规(裸形 / 空格 / 中文 / 补零)③ 悬空引用 ④ 重复定义
⑤ 冻结族越游标 ⑥ 编号未紧邻文档名 ⑦ 孤儿条目(告警)⑧ 可判定比例 + 两根护栏。
8.1 当前基线(2026-10-26 编号迁移批次后重打)
| 项 | 数值 |
|---|---|
| 扫描文件 / 编号字面量 | 784 个 / 7,828 处(2026-10-27 复测;两批清理前 10,956 → 8,230,此后新代码与新文档回涨 553 处,其中测试用例族占大头,见 §9.1) |
护栏 1:可判定比例下限 decidable_ratio_baseline |
86.0%(实测 86.01%;容差 0.1pp,只许涨) |
护栏 2:不可判定引用绝对数上限 undecidable_total_ceiling |
1,166 处,只减不增(2026-10-27 实跑 1,161 处,余量 5;构成拆解见 docs/门禁说明/id-check.md §7.7) |
| 校验 1/2/3/4/5/6 错误级 | 0;债务台账 0 条指纹 → --strict 实为全量拦截 |
| 告警 | 悬空 2(App/algo/freq.c 的正序 / 负序记号,属 §4.4 误判面)+ 孤儿 50(陷阱条目这类本就允许无人引用) |
⚠ 读这些数字的口径:跨批次不可直接相减。方案 B 把"本可判定的引用"换成散文,分子分母同缩, 比例反而从 86.7% 掉到 85.98%,而不可判定绝对数一处没涨——所以同批加了护栏 2,并把比例基线 人工下调一次(工具按设计拒绝下调,必须留书面理由,见
docs/门禁说明/id-check.md§7.6);本规范瘦身后比例回到 86.0%, 护栏 2 也顺手从 1,192 收紧到 1,166。 以后判断"编号有没有变坏"看绝对数,不看比值:号只许越清越少,新增没登记的号一定被护栏 2 拦住。
8.3 改号与清号批次(只留要点)
2026-10-21 五批统一改名(陷阱号归范、主机侧单测认代码为属主登记处、追溯器三档口径对齐);
2026-10-26 两批清号(A:删死号约 1,557 处文本实删;B:登记簿系 20 个号转语义短语约 418 处)。
逐批动机与影响只在 git log 与 scripts/rename_maps/,本文不维护流水账。要记住的只有两条教训:
门禁曾经把"政策上禁止回改的变更记录行"当活账拦提交;也曾经用比值当唯一护栏而惩罚清号动作本身
——两处都在 2026-10-26 修掉了,别再往回改。
8.4 台账与 --strict
错误级问题按「文件 + 校验项 + 字面量 + 次数」记指纹进 scripts/id_known_backlog.json,--strict 只拦
台账之外的新账,台账只减不增。本批台账已还清到 0 条——从现在起任何一条新错误级问题都会当场
拦提交,别指望还有豁免面可钻。
9. 还剩什么:存量清点与批次(2026-10-27 实测)
批次一与批次二已于 2026-10-27 执行完毕,下表保留的是动手前的清点基线(用来解释为什么这么分批), 不是当前存量。当前状态:
| 批次 | 范围 | 结果 |
|---|---|---|
| 一 | 登记簿旧号 / 阶段号 / 台架阶段裸形 / 网络条目号 | 活文档清零;顺带清 3 处裸形;位号目录整目录排除 |
| 二 | 保护功能号 28 个 | 代码与测试 215 处 + 文档 194 处 + 配置注释 3 处 + 入口文档 2 处;活文档只剩 |
| 冻结的变更记录行 40 处与一处原始串口日志(真机抓包证据,改它等于篡改现场,永久保留) | ||
| 三 | 测试用例族 561 站点 | 用户裁定不做:该族保留,但即日停发(游标冻结,新用例不再配号) |
编号字面量 8,787 → 7,828;不可判定绝对数 1,161 → 982(上限 1,166,余量从 5 格宽到 184 格)。 比值 86.79% → 87.46% 属纯稀释(删的都是可判定引用,分子分母同缩),基线不下调,见本节末裁定。
先回答「还有多少号可以清」。下面是用门禁自己的接口跑出来的存量(check_ids.py 的 Checker,按族统计
「活引用站点 / 不同字面量 / 涉及文件数」;只统计非冻结族、且排除属主登记处的定义位):
| 族 | 引用站点 | 字面量 | 文件 | 集中处 | 处置 |
|---|---|---|---|---|---|
TC-*(含各模块子族) |
561 | 472 | 77 | 测试用例与断言标签、test/host/** |
保留、即日停发(用户裁定 2026-10-27,见 §9.1 批次三) |
L-PROT(保护功能号) |
184 | 28 | 58 | 保护规划与各模块说明 | 批次二:转语义 |
TRAP-* |
134 | 25 | 51 | 踩坑记录与驱动注释 | 保留(可检索锚点,用户已裁定) |
F-*(网络设计条目) |
38 | 12 | 20 | ch395f.h、net_events.c |
批次一:转语义 |
CODE-RULE-* |
35 | 20 | 13 | 代码规范门禁 | 保留(门禁按号报错) |
MENU-STATE-* |
少量 | — | — | 像素回归脚本 | 保留(脚本按它取状态行) |
T-TEST(台架阶段裸形) |
19 | 4 | 12 | 串口/台架脚本与测试流程 | 批次一:转语义 |
N-*(登记簿旧号残留) |
4 | 3 | 3 | 规范自身与两处脚本注释 | 批次一:清 |
TM-* |
1 | 1 | 1 | 规范自身 | 批次一:清 |
合计:26 个族仍有引用、565 个不同字面量、1,108 个引用站点(其余 73 个登记族已零引用或冻结)。
9.1 三批计划(按「值不值得动门禁」排序)
批次一 · 现在就能清(约 62 个站点 / 20 个字面量,不碰任何门禁):N-*、TM-*、T-TEST、F-*。
这四族没有任何脚本按字面量匹配,纯人读,正是「语义标识最好」的适用面;T-TEST 还是裸形(T0~T3),
最容易与别的字母撞义。改法:号 → 短语(「台架阶段一」「网络自愈:监听生命周期」),残留引用同步清,
别名表标 void,台账 --prune-backlog。
批次二 · 文档为主、量大(约 184 个站点 / 28 个字面量):L-PROT 保护功能号。它曾有明确价值
(功能复现规划逐条对齐),但用户已裁定字母号难认 ⇒ 改成功能名本身(「过流Ⅰ段」「零序过流」),
规划表首格写功能名、不再配号。要点:必须按功能逐个改,不能全局替换(同一号在不同文档指同一功能,
但句子结构不同);改完用追溯器复核代码侧没有残留号引用。
批次三 · 用户裁定 2026-10-27「不做」:TC-*(561 个站点 / 472 个字面量 / 77 个文件)保留现状。
裁定记录(原话:「批次三,不坐」,即批次三不做)。留着的理由与今天的定调并不矛盾,而是它的前提:
TC-* 是本规范 §4.1 那条判据唯一真正满足它的族——check_test_traceability.py 与 40 套 run_unit_test.py
按字面量读它,C 断言标签、测试函数名、文档用例表三处同一号,是「代码 ↔ 文档」双向核对的机器把手。
清它的代价不是改文本,而是换掉追溯机制:候选方案「用例名即标识」(test_xxx_yyy() ↔ 文档表格行名,
脚本按名字比对)要把追溯门禁重写并重打基线,收益是字母号一次少掉一半以上,代价是期间测试与文档的
对应关系处于断裂态——本仓测试是提交门禁(test-coverage 跑全部 40 套并守覆盖率基线回退),拿它做
不可逆试验不值。结论:机器面自解释的族可以保留;字母号的痛在「人读」侧,解法是别再造给人读的号,
而不是把机器面的把手也拆掉。
「不做」之后跟着两条硬口径(否则裁定会被当成默许继续扩族):
① 本族即日停发:游标冻结,现存号只减不增,新用例一律用语义化测试函数名 + 文档表格行名,不再配
TC- 号(§4.1 的『已停发』栏已加一行);
② 若将来真要清,按 scripts/rename_ids.py + §7.3 五步单独开卡,前提是先让追溯器同时认两种形态
(新旧并行核对通过,再谈切换),不许先改文档再改代码(会凭空造出悬空号,§8 校验 3 会当场拦)。
9.2 别再做什么
「编号说明」这件事本身应该继续变薄:每多一个族,就多一处需要有人记得它的地方;每多发一个号,就多一个 将来没人敢删的字符串。要新增族之前,请把 §4.1 的「允许继续发号」那 8 行当作反对你的第一手证据。
10. 速查
- 看到一个不认识的号 → 先查
id_aliases.json与属主登记表;查不到就删号留事实,不要补定义。 - 想给待办 / 缺陷 / 差距 / 风险发号 → 不许,写短语(§3.3)。
- 想知道「还有多少号可清」→ 看 §9 的存量表与三批计划。
- 想给文档内步骤或测试阶段发号 → 不许,写「步骤 3」「阶段 7」(§3.3)。
- 想新增前缀族 → 先回答"哪个脚本要按字面量匹配它"(§4.1);答不出就别建。
- 要改号 →
scripts/rename_ids.py+ §7.3 五步。 - 门禁报错读不懂 →
docs/门禁说明/id-check.md。
变更记录
| 日期 | 变更 | 说明 |
|---|---|---|
| 2026-10-27 | 批次三裁定「不做」:TC-* 保留现状但即日停发 |
用户原话「批次三,不坐」(即不做)。裁定写进 §9.1 批次三(含理由与两条硬口径)、§4.1『已停发』栏加一行、§9 结果表同步。停发的硬口径:游标冻结、现存号只减不增、新用例一律用语义化测试函数名 + 文档表格行名,不再配 TC- 号;真要清则先让追溯器同时认新旧两种形态、核对通过后单独开卡,不许先改文档再改代码(会造悬空号)。留着的判据依据:TC-* 是 §4.1 那条判据(有脚本按字面量匹配)唯一真满足的族,字母号的痛在「人读」侧,解法是不再造给人读的号,而不是拆掉机器面的把手。 |
| 2026-10-27 | 语义标识定为唯一默认形态;编号收窄为「机器按字面量匹配」的例外,并首次给出现量清点与三批计划 | 用户原话:「不要用字母加数字的编号,简直太难以理解了,语义标识是最好的」。本笔:① 标题下的一句话从「允许用号的族只有 8 个」改成「语义标识是唯一默认、编号是例外」,并把 §4.1 拆成『允许继续发号』8 族与『已停发、存量待清』4 族(N-* / TM-* / 台架阶段裸形 / F-*)——原表自称穷举,实际漏登记了这三类在用族,属真缺陷。② 新增 §9 存量清点(用门禁自身接口实测:26 族仍有引用、565 个字面量、1,108 个引用站点)与三批计划:批次一 62 站点不碰门禁即可清、批次二保护功能号 184 站点转功能名、批次三 TC-* 561 站点需先换追溯机制(等用户裁定)。③ §8.1 基线按 2026-10-27 复测重打:784 文件 / 7,828 字面量、护栏 2 实跑 1,161 / 上限 1,166。 |
| 2026-10-26 | 编号治理收口:清死号 → 停发活号 → 本文重写为短版(用户三次裁定) | 全仓字母+数字编号 10,956 → 8,230 处。① 清死号:属主登记处已删或从未启用的号一律就地删号留事实、禁补号(文本实删约 1,557 处)。② 停发活号:登记簿 N-x/S-x/T-x、专项 A-x、已删报告的 UI 簇 U1~U5 共 20 个号转成语义短语(约 418 处)——登记簿表首格就是短语,旧号进 scripts/id_aliases.json 标 retired-to-phrase;已销项的死号故意不进别名表,让门禁继续咬残留引用。③ 本文瘦身:619 行 → 229 行,删掉八原则长表、迁移映射表、模块码表与门禁细节(那些各有事实源:registry / 别名表 / docs/门禁说明/id-check.md),改成「先问三句再决定要不要发号」+ §4.1 允许用号的族穷举 = 8 个。④ 门禁配套:check_ids.py 加变更记录行豁免与第二根护栏 undecidable_total_ceiling(比值会被清号动作稀释,绝对数不会),债务台账还清到 0 条 → --strict 实为全量拦截,比例基线重打为 86.0%。本表按用户 2026-10-26 的明确指示只保留最近一条,更早沿革看 git log 与 docs/门禁说明/id-check.md §7.5(含其后的方案 B 一节);这是本文档的例外,不改变 §5.5对其他文档「冻结历史不回改」的约束。 |