docs(编号): 批次三裁定「不做」入档——TC 族保留现状但即日停发
用户裁定原文:「**批次三,不坐**」(即不做)。本笔把裁定连同**理由与后续硬口径**一起写进 `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` 与 不可判定绝对数不受影响。
This commit is contained in:
+25
-9
@@ -82,7 +82,8 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
### 4.1 允许用号的族(**穷举**——这张表以外一律不许发号)
|
||||
|
||||
**允许继续发号**(有脚本按字面量匹配,现状实测 2026-10-27 见 §9.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` | 踩坑证词的永久锚点,代码注释反查 |
|
||||
@@ -95,6 +96,10 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
**已停发、存量待清**(登记未删只是为了让历史行不报「未登记前缀」,**不得再新增引用**;清点见 §9.1):
|
||||
|
||||
| 族 | 状态 | 依据 |
|
||||
|---|---|---|
|
||||
| `TC-*` | **保留现存号、即日停发**:游标冻结、只减不增,新用例改用语义化测试函数名 + 文档表格行名 | 用户裁定 2026-10-27「批次三,不坐」;本族是 §4.1 判据唯一真被脚本按字面量读的族,清它等于换追溯机制,详见 §9.1 批次三 |
|
||||
|
||||
| 族 | 形态 | 存量 | 为什么该清 |
|
||||
|---|---|---|---|
|
||||
| `N-*` | 登记簿 `N-<nn>` | 4 处 / 3 个字面量 | 登记簿已于 2026-10-26 全面改语义短语,残留的是漏网的旧引用 |
|
||||
@@ -233,7 +238,7 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
| 一 | 登记簿旧号 / 阶段号 / 台架阶段裸形 / 网络条目号 | 活文档清零;顺带清 3 处裸形;位号目录整目录排除 |
|
||||
| 二 | 保护功能号 28 个 | 代码与测试 215 处 + 文档 194 处 + 配置注释 3 处 + 入口文档 2 处;活文档只剩
|
||||
**冻结的变更记录行 40 处**与**一处原始串口日志**(真机抓包证据,改它等于篡改现场,永久保留) |
|
||||
| 三 | 测试用例族 561 站点 | **仍未动**,等用户裁定(清它等于换追溯机制) |
|
||||
| 三 | 测试用例族 561 站点 | **用户裁定不做**:该族保留,但**即日停发**(游标冻结,新用例不再配号) |
|
||||
|
||||
编号字面量 **8,787 → 7,828**;不可判定绝对数 **1,161 → 982**(上限 1,166,余量从 5 格宽到 184 格)。
|
||||
比值 86.79% → 87.46% 属**纯稀释**(删的都是可判定引用,分子分母同缩),**基线不下调**,见本节末裁定。
|
||||
@@ -244,7 +249,7 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
| 族 | 引用站点 | 字面量 | 文件 | 集中处 | 处置 |
|
||||
|---|---:|---:|---:|---|---|
|
||||
| `TC-*`(含各模块子族) | **561** | 472 | 77 | 测试用例与断言标签、`test/host/**` | **需要先裁定**(见下) |
|
||||
| `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` | 批次一:转语义 |
|
||||
@@ -268,12 +273,22 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
规划表首格写功能名、不再配号。要点:必须**按功能逐个改**,不能全局替换(同一号在不同文档指同一功能,
|
||||
但句子结构不同);改完用追溯器复核代码侧没有残留号引用。
|
||||
|
||||
**批次三 · 需要你裁定:`TC-*`(561 个站点 / 472 个字面量 / 77 个文件)**。这是唯一**代码里也大量存在**的族
|
||||
(C 断言标签 + 测试函数名 + 文档用例表),并且 `check_test_traceability.py` 正是靠它做「代码↔文档」双向核对。
|
||||
清它的代价不是改文本,而是**换掉追溯机制**:候选方案是「用例名即标识」(`test_xxx_yyy()` 名字 ↔ 文档表格行名,
|
||||
脚本按名字比对),并把断言标签改成短语。**收益**:全仓字母号一次减掉一半以上;**代价**:追溯门禁要重写并
|
||||
重打基线,且当天所有在飞分支都要跟着改。⇒ 我建议**单独开一张卡**做,不与其他批次混;我这一轮只把批次一的
|
||||
范围与做法写清(§9.2),批次二排在其后,批次三等你一句话。
|
||||
**批次三 · 用户裁定 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 别再做什么
|
||||
「编号说明」这件事本身应该继续变薄:每多一个族,就多一处需要有人记得它的地方;每多发一个号,就多一个
|
||||
@@ -294,5 +309,6 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
| 日期 | 变更 | 说明 |
|
||||
|---|---|---|
|
||||
| 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对其他文档「冻结历史不回改」的约束。 |
|
||||
|
||||
Reference in New Issue
Block a user