feat(门禁): 编号门禁 id-check 落地（36→37 钩子）+ 批 1 编号单词化改名
新增门禁本体 - scripts/check_ids.py：实现 docs/编号规范.md §8 八项校验；默认 warn-only， 唯一硬拦项是「可判定比例跌破基线」（防回退的本体） - scripts/id_registry.json：66 个前缀族，逐项来自 §4 总表 + 全库实测游标， 偏差一律写进 cursor_note，不凭记忆编造 - scripts/id_aliases.json：旧号 → 新号 / 作废标记（照搬 section_aliases.json 范式） - 顺带收编 check_test_traceability.py：正则补齐大写后缀与无模块码形态， 比对范围扩到 test/host 与 7 篇「单元测试说明.md」，另加 --board-only 回退旧口径 批 1 改名（用户授权解禁「不改写存量号」） - 代码规范条款 S1~S19 → CODE-RULE-nn：78 处 / 2 文件 - UI 像素回归状态 S0~S7 → MENU-STATE-nn：61 处 / 3 文件（冻结在 07） - 两族属主登记处 = 脚本自身的规则表 / STATES 表，文档只作引用方 - 新增 scripts/rename_ids.py（§7.3 规划脚本）：映射表驱动、显式 scope、默认干跑、 自动写 scoped 别名，跳过 [示例]/[计划] 行与变更记录表，按原字节读写保 BOM 行尾 - 已应用映射表存档 scripts/rename_maps/batch1.json 作审计轨迹 有牙实测（证明门禁不是空转） - 注入 Z-99 / 裸形 / 悬空 / 越游标 / 未紧邻 / 跨文档重复定义 六例， 分别被校验 1/2/3/5/6/4 点名，--strict 退出码 1；临时档删除后工作树干净 验证与同步 - 可判定比例基线 82.3% → 82.7%（已 --update-baseline 入档）；错误级 1312 → 1291 - ci_local.py 全绿（L0 + L0.5 共 1104 断言）；ui-golden Passed； check_doc_links.py --all 无法判定 0 - 未改任何 C/H 源文件，故本次不需 @build - 文档：AGENTS.md 与 pre-commit使用说明.md 计数 36→37 并新增 §2.25 详解； 编号规范 §4.1 补两行、§8.1 落地记录、§8.2 规范与仓库偏差、§8.3 迁移批次记录
This commit is contained in:
@@ -25,7 +25,7 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|
||||
|
||||
| 步 | 脚本/命令 | 门禁内容 | 预期输出 |
|
||||
|---|---|---|---|
|
||||
| 1 | `simulator/tests/check_menu_rows.py` | 菜单 8 状态：选中行白带 / 非选行黑底白字 / 框体 1px 边框 / 往返像素一致（S3==S1、S6==S1、S7==S2）+ S0 池基线 | `PASS: 8 状态全部断言通过（8 图，池基线 5368 B）` |
|
||||
| 1 | `simulator/tests/check_menu_rows.py` | 菜单 8 状态：选中行白带 / 非选行黑底白字 / 框体 1px 边框 / 往返像素一致（MENU-STATE-03==MENU-STATE-01、MENU-STATE-06==MENU-STATE-01、MENU-STATE-07==MENU-STATE-02）+ MENU-STATE-00 池基线 | `PASS: 8 状态全部断言通过（8 图，池基线 5368 B）` |
|
||||
| 2 | `simulator/tests/check_content_pages.py` | ① 文本级断言（字形模板匹配，50 条，独立于 `ref/`）→ ② 11 页截图与 `ref/` 黄金参考**逐字节**比对 + 开页-关页往返池水位 | `PASS: 11 内容页 + 往返池水位全部通过`（文本断言先于像素比对，失败即中止） |
|
||||
| 3 | `keil-build` skill（`keil_build.py`） | MCU 端编译（UI 源码双端共用，改一端必须过另一端） | 退出码 0 = BUILD_OK |
|
||||
| 4 | `scripts/check_coding_standard.py` | 代码规范 V1.0 机械检查 | PASS |
|
||||
|
||||
+38
-23
@@ -153,30 +153,30 @@ cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法
|
||||
|---|---|
|
||||
| **触发条件** | 自有代码 .c/.h 文件（App/、Drivers/BSP/，第三方与 CubeMX 生成文件除外）违反下列规则 |
|
||||
| **处理方式** | **阻止提交**（必须修复） |
|
||||
| **典型报错** | `L123 [S3 3.4.1] 宏名须全大写+下划线: net_htonl` |
|
||||
| **典型报错** | `L123 [CODE-RULE-03 3.4.1] 宏名须全大写+下划线: net_htonl` |
|
||||
|
||||
**检查项（S 编号与脚本输出一致）**：
|
||||
|
||||
| 编号 | 规范条款 | 规则 |
|
||||
|---|---|---|
|
||||
| S1 | 2.3.1 | .h 文件必须有 `XXX_H` 格式头文件保护宏（禁止 `__` 前缀） |
|
||||
| S2 | 5.2 | 文件开头必须有文件头注释（含 模块名称/作者） |
|
||||
| S3 | 3.4.1 | `#define` 宏名必须全大写+下划线+数字 |
|
||||
| S4 | 3.5.1 | typedef 类型名必须以 `_t` 结尾 |
|
||||
| S5 | 6.3.2 | switch 必须包含 default 分支 |
|
||||
| S6 | 7.5 | 禁用 strcpy/strcat/sprintf/gets/scanf/strtok（改用安全版本） |
|
||||
| S7 | 6.3.3 | 禁止 goto |
|
||||
| S8 | 4.1.1 | 禁止 Tab 缩进（4 空格） |
|
||||
| S9 | 5.3 | 函数定义必须有函数注释（含「函数功能」） |
|
||||
| S10 | 3.3.1 | 函数名必须全小写（HAL_ 厂商 API 回调名豁免） |
|
||||
| S11 | 2.3.5 | 禁止相对/绝对路径 include（2026-10-11 细化判定形态：禁的是"用路径找文件"——引号 include 带 `/`、任意形态带 `..` / `\` / 绝对路径或盘符；`<sys/stat.h>` 这类**尖括号系统头允许带子目录**，由 `-I` 解析。原实现把任何含 `/` 的 include 一律判违规，误伤模拟器侧 2 处；全仓库复核：细化后仅这 2 处项目代码判定发生变化，其余 100 处均在已排除的 `Lib/lvgl/`） |
|
||||
| S12 | 7.6 | 禁止可变参数函数（`...`） |
|
||||
| S13 | 7.7 | 禁止递归函数 |
|
||||
| S15 | 6.1.4 | 文件作用域指针变量必须初始化为 NULL |
|
||||
| S16 | 3.2.2 | 文件作用域非 static 全局变量必须 `g_` 前缀 |
|
||||
| S17 | 2.2 | 非 static 函数必须在配对 .h 中声明（HAL_ 豁免；无配对头则跳过） |
|
||||
| S18 | 6.3.1 | 禁止 Yoda 条件（字面量/常量必须在运算符右侧） |
|
||||
| S19 | 4.4.2 | 函数定义左大括号必须与右括号同行 |
|
||||
| CODE-RULE-01 | 2.3.1 | .h 文件必须有 `XXX_H` 格式头文件保护宏（禁止 `__` 前缀） |
|
||||
| CODE-RULE-02 | 5.2 | 文件开头必须有文件头注释（含 模块名称/作者） |
|
||||
| CODE-RULE-03 | 3.4.1 | `#define` 宏名必须全大写+下划线+数字 |
|
||||
| CODE-RULE-04 | 3.5.1 | typedef 类型名必须以 `_t` 结尾 |
|
||||
| CODE-RULE-05 | 6.3.2 | switch 必须包含 default 分支 |
|
||||
| CODE-RULE-06 | 7.5 | 禁用 strcpy/strcat/sprintf/gets/scanf/strtok（改用安全版本） |
|
||||
| CODE-RULE-07 | 6.3.3 | 禁止 goto |
|
||||
| CODE-RULE-08 | 4.1.1 | 禁止 Tab 缩进（4 空格） |
|
||||
| CODE-RULE-09 | 5.3 | 函数定义必须有函数注释（含「函数功能」） |
|
||||
| CODE-RULE-10 | 3.3.1 | 函数名必须全小写（HAL_ 厂商 API 回调名豁免） |
|
||||
| CODE-RULE-11 | 2.3.5 | 禁止相对/绝对路径 include（2026-10-11 细化判定形态：禁的是"用路径找文件"——引号 include 带 `/`、任意形态带 `..` / `\` / 绝对路径或盘符；`<sys/stat.h>` 这类**尖括号系统头允许带子目录**，由 `-I` 解析。原实现把任何含 `/` 的 include 一律判违规，误伤模拟器侧 2 处；全仓库复核：细化后仅这 2 处项目代码判定发生变化，其余 100 处均在已排除的 `Lib/lvgl/`） |
|
||||
| CODE-RULE-12 | 7.6 | 禁止可变参数函数（`...`） |
|
||||
| CODE-RULE-13 | 7.7 | 禁止递归函数 |
|
||||
| CODE-RULE-15 | 6.1.4 | 文件作用域指针变量必须初始化为 NULL |
|
||||
| CODE-RULE-16 | 3.2.2 | 文件作用域非 static 全局变量必须 `g_` 前缀 |
|
||||
| CODE-RULE-17 | 2.2 | 非 static 函数必须在配对 .h 中声明（HAL_ 豁免；无配对头则跳过） |
|
||||
| CODE-RULE-18 | 6.3.1 | 禁止 Yoda 条件（字面量/常量必须在运算符右侧） |
|
||||
| CODE-RULE-19 | 4.4.2 | 函数定义左大括号必须与右括号同行 |
|
||||
|
||||
**不在检查范围**（语义类规则，无法机械可靠判定）：函数长度/单一职责、参数数量、错误处理、注释掉的代码等，仍需人工评审把关。
|
||||
|
||||
@@ -446,6 +446,21 @@ cppcheck 是开源 C/C++ 静态分析工具，**不运行代码**，通过语法
|
||||
| **首次落地实测（牙齿）** | 注入均打在**临时副本**（`--chars` / `--font` 覆盖，不碰仓库文件）：① txt 删 ▶ → FAIL 点名 `▶(U+25B6)`；② 字体副本删 U+25B6 单码位 cmap 条目 → FAIL 同字；③ 字体副本删 U+538B 的稀疏 `unicode_list` 偏移 → FAIL 点名 `压(U+538B)`；基线 PASS。落地时 txt 内有 **7 个历史冗余字**（上/常/异/片/电/芯/重，源码已不用）→ 仅 WARN 不拦，下次 font-regen 顺带瘦身 |
|
||||
| **运行器** | `scripts/check_font_charset.py`（纯标准库；`--chars` / `--font` 指临时副本做注入测试、`--strict` 升级冗余字；退出码 0=通过 / 1=白框缺口 / 2=环境错误） |
|
||||
|
||||
### 2.25 id-check — 编号门禁（2026-10-20 加，`docs/编号规范.md` §8）
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| **触发条件** | 任意 `.md` / `.c` / `.h` / `.py` / `.yaml` / `.json` / `.txt` 或本配置文件变动（pre-commit 4.x 无 `always: true`，`files:` 按扩展名覆盖全触发面）；**`pass_filenames: false`**——悬空引用 / 孤儿条目 / 重复定义是**跨文件**判定，只喂变更文件必然判错，故每次恒扫全库（实测 536 个文件 1.1 s，够快） |
|
||||
| **处理方式** | **当前 warn-only**（`docs/编号规范.md` §8 上线节奏：先清 backlog → 清零后 `entry` 加 `--strict` 拦提交，与 `doc-links` 章节校验同一条路径）。**唯一例外**：校验 8 的「可判定比例」跌破 `scripts/id_registry.json` 里的基线（82.3%）→ **任何模式都 FAIL**，这根线就是防回退的本体 |
|
||||
| **八项校验**（[示例] 本行引用的是各种非法形态示例，不是真实编号） | ①未登记前缀 ②形态不合规（裸形 `S3` / 空格形 `Trap 07` / 中文形 `陷阱 1` / 补零错 / 档位词带后缀 / 大写后缀 / 缺模块码）③悬空引用 ④重复定义 ⑤冻结前缀越游标 ⑥文档内编号未紧邻文档名 ⑦孤儿条目（告警）⑧可判定比例（只许涨不许跌） |
|
||||
| **配置两份** | `scripts/id_registry.json`：前缀族 → 属主登记处 / 形态正则 / 是否冻结 / 游标，**逐项来自 `docs/编号规范.md` §4 总表**，游标取「规范记载值」与「全库实测最大号」的较大者，偏差写进 `cursor_note`（实测偏差见规范 §8.2）；`scripts/id_aliases.json`：旧号 → 新号 / 作废标记（照搬 `section_aliases.json` 的成功范式） |
|
||||
| **判定口径** | 「定义」= 字面量出现在该族**属主登记处文档**里（不依赖表格行首等易漂移形态）→ §5.5「销项 = 删行 + 清全库引用」只做一半，校验 ③ 立刻报（`N-31`/`N-32` 正是这条）。「重复定义」= 字面量出现在**定义位**（表格首格 / 标题行 / 列表项行首），正文提到不算，否则任何交叉引用都会误判成事故 |
|
||||
| **顺带收编** | `scripts/check_test_traceability.py`（TC 用例双向追溯）由本钩子一并调用：正则补齐 `TC-[A-Z]{1,4}-\d{3,4}[a-z]?` 与大写后缀 / 无模块码形态（旧 `TC-[A-Za-z0-9]+-\d+` **整条漏扫** `TC-AI-01A`），比对范围从「`test/board/*.c` ↔ `*_Test_Guide.md`」扩到 `test/host/` 一侧 + 7 篇「单元测试说明.md」（差异从 33 处涨到 326 处——**原口径漏的正是主机侧单测这一半**），另加 `--board-only` 回退旧口径 |
|
||||
| **首轮实测（2026-10-20）** | 8271 处编号字面量 / 可判定 **82.3%**（6808/8271）；错误级：②416 ③626 ⑥269，告警级：③239 ⑦88。错误集中在 `TC-PS-*`/`TC-PE-*`/`TC-AH-*`/`TC-SOE-*`（**主机侧单测有码无文档**，正是 §7.2 列的"缺文档 = 追溯断链"）与报告自有编号被裸引（`D-x`/`R-x`/`F-x`/`P0-x`，属 §9 阶段 1-③）。逐项数字与口径见 `docs/编号规范.md` §8.1 |
|
||||
| **有牙实测（牙齿）**（[示例] 下列字面量是注入用的假编号） | 注入打在临时档（`git add -N` 进索引，跑完 `git rm --cached` + 删除，`git status` 干净）：`Z-99`→①、裸形 `S3`→②、`TC-NET-9999`→③、第二篇属主文档重复定义 `DP-01`→④、`E-70`→⑤（`E-xx` 冻结于 `E-63`）、裸引 `D-7`→⑥；六项分别被对应校验点名，`--strict` 退出码 1 |
|
||||
| **显式盲区（不是"检查通过"）** | ① 裸形同字母多义（§1.2：`P1` 五义 / `L1` 四义 / `U1` 四义 / `D7` 三义）与元器件位号同形（§4.4）→ 裸形族**只在属主登记处文档内**判越游标，文档外降告警；② 圈号编号（①②③…）与正常列举无法机械区分，不入判定；③ `docs/芯片手册/`、`docs/硬件平台/` 整体排除（位号 `B1`/`C1`/`L1` 与编号同形，是撞形根源）。前两块收口属 §9 阶段 1-②/1-③ 迁移批次，落地后再扩判定范围——盲区登记在 `id_registry.json` 的 `blind_spots` / `unmanaged_bare` |
|
||||
| **运行器** | `scripts/check_ids.py`（纯标准库；`--strict` 拦提交、`--update-baseline` 抬基线（**只许涨**，跌则拒绝写入）、`--only 1,3,5` 跑部分、`--top N` / `--verbose` 出细节、`--no-trace` 跳过 TC 追溯；退出码 0=通过或仅告警 / 1=错误或比例跌破基线 / 2=环境错误） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常工作流
|
||||
@@ -561,9 +576,9 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
|
||||
|
||||
**为什么必须修**：模拟器与固件**共用同一套 UI 源码**，且它是 UI 回归唯一的像素级证据来源——它落在门禁外，等于验证链的地基不受检。
|
||||
|
||||
**纳入后的实测收益（当天）**：`cppcheck` 立刻揪出 `sim_syslog.c` 一处**真实空指针解引用**（`if (p_epoch == NULL || …) { *p_epoch = 0u; … }`——判空分支里紧接着解引用），另有 2 处 `localtime_s` 未初始化告警、1 处 `px` 可加 `const`；`coding-standard` 报出 61 处（44 处函数左大括号 Allman 风格、8 处缺函数注释、3 处缺文件头注释、2 处 `__` 前缀保护宏、2 处 `sprintf`、2 处 S11 误报），已全部处理。
|
||||
**纳入后的实测收益（当天）**：`cppcheck` 立刻揪出 `sim_syslog.c` 一处**真实空指针解引用**（`if (p_epoch == NULL || …) { *p_epoch = 0u; … }`——判空分支里紧接着解引用），另有 2 处 `localtime_s` 未初始化告警、1 处 `px` 可加 `const`；`coding-standard` 报出 61 处（44 处函数左大括号 Allman 风格、8 处缺函数注释、3 处缺文件头注释、2 处 `__` 前缀保护宏、2 处 `sprintf`、2 处 CODE-RULE-11 误报），已全部处理。
|
||||
|
||||
**顺带修掉的规则缺陷**：S11 原实现把**任何含 `/` 的 include** 判违规，误伤 `<sys/stat.h>` 这类系统头；已按 include 形态细化，判定见 §2.8。
|
||||
**顺带修掉的规则缺陷**：CODE-RULE-11 原实现把**任何含 `/` 的 include** 判违规，误伤 `<sys/stat.h>` 这类系统头；已按 include 形态细化，判定见 §2.8。
|
||||
|
||||
**教训**：`exclude` 只写**真正不该进钩子的路径**。已被 `.gitignore` 覆盖的生成物不需要再挡一遍——写上去只会连带豁免同一目录里的自研代码。
|
||||
|
||||
@@ -573,7 +588,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
|
||||
|
||||
| 文件 | 位置 | 说明 |
|
||||
|---|---|---|
|
||||
| `.pre-commit-config.yaml` | 仓库根 | 钩子配置（**36 个钩子**，2026-10-15 清点；本文 §2 详解非单测类——N-19 新增的两个单测钩子见 §2.16/§2.17，N-23 双端注册反向校验（含 U4 补强的 UI 页面描述符表接线 ④）见 §2.18，N-27 RAM 预算门禁见 §2.19，B4 IEC104 协议栈单测见 §2.20，B8 频率测量单测见 §2.21，B9 SOE 动作记录单测见 §2.22，N-21 dhara NAND 移植层单测见 §2.23，U4 残余字符集差集检查见 §2.24，其余主机侧单测见 AGENTS.md 门禁条；主机侧单测共 16 个；UI 门禁另有 `font-charset` 与 `ui-golden`） |
|
||||
| `.pre-commit-config.yaml` | 仓库根 | 钩子配置（**37 个钩子**，2026-10-20 清点；本文 §2 详解非单测类——N-19 新增的两个单测钩子见 §2.16/§2.17，N-23 双端注册反向校验（含 U4 补强的 UI 页面描述符表接线 ④）见 §2.18，N-27 RAM 预算门禁见 §2.19，B4 IEC104 协议栈单测见 §2.20，B8 频率测量单测见 §2.21，B9 SOE 动作记录单测见 §2.22，N-21 dhara NAND 移植层单测见 §2.23，U4 残余字符集差集检查见 §2.24，编号门禁八项校验见 §2.25，其余主机侧单测见 AGENTS.md 门禁条；主机侧单测共 16 个；UI 门禁另有 `font-charset` 与 `ui-golden`） |
|
||||
| `.gitlint` | 仓库根 | gitlint 规则（宽松，兼容中文） |
|
||||
| `.cubemx_survival_baseline.json` | 仓库根 | CubeMX 易失定制基线（哈希；`--write` 重建） |
|
||||
| `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 |
|
||||
@@ -585,7 +600,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env
|
||||
| `scripts/check_lv_conf_sync.py` | scripts/ | 两份 `lv_conf.h` 特性子集一致性（比对生效值 + 无效宏名 + 重复定义） |
|
||||
| `scripts/check_test_suite.py` | scripts/ | 测试套件开关门禁（防测试固件静默提交） |
|
||||
| `scripts/check_font_charset.py` | scripts/ | UI 字符集差集检查（复用 `tools/font_gen/` 提取与 cmap 解析规则，防缺字白框） |
|
||||
| `docs/代码规范/嵌入式C语言代码规范_V1.0.md` | docs/代码规范/ | 代码规范原文（S1~S19 规则来源） |
|
||||
| `docs/代码规范/嵌入式C语言代码规范_V1.0.md` | docs/代码规范/ | 代码规范原文（CODE-RULE-01~CODE-RULE-19 规则来源） |
|
||||
| `docs/代码规范/cppcheck使用说明.md` | docs/代码规范/ | cppcheck 钩子详解（规则/配置/抑制） |
|
||||
| `docs/文档规范.md` | docs/ | 文档体系规范（链接形态/命名/门禁要求） |
|
||||
| `docs/代码规范/pre-commit使用说明.md` | 本文档 | 部署与使用说明 |
|
||||
|
||||
@@ -397,7 +397,7 @@ docs\内存管理\RAM使用分析与优化方案.md:585 [路径引用] docs/内
|
||||
|
||||
| 主题 | 去处 |
|
||||
|---|---|
|
||||
| 提交门禁 35 个钩子 | `docs/代码规范/pre-commit使用说明.md` |
|
||||
| 提交门禁 37 个钩子 | `docs/代码规范/pre-commit使用说明.md` |
|
||||
| 自动化测试与台架流程 | `docs/测试说明/自动化测试流程.md` |
|
||||
| 文档写作规范（编码/链接/登记） | `docs/文档规范.md` |
|
||||
| 工具路径环境变量（换机） | `docs/环境与部署/本地工具路径环境变量方案.md` |
|
||||
|
||||
+75
-15
@@ -2,9 +2,9 @@
|
||||
|
||||
> **适用对象**：本仓库全部 Markdown 文档、C/Python/脚本源码注释、提交信息中出现的**实体编号**（`E-44`、`N-21`、`TC-NET-601`、`FR-STO-1`、`Trap 07` 这类"字母 + 数字"的条目身份标识）。
|
||||
> **不适用**：C 语言标识符（`g_`/`s_`/`PS_*`/`TEST_SUITE_*`）、元器件位号（`U1`/`C12`/`R3`）、章节号（`§3.2`，归 [`docs/文档规范.md`](文档规范.md) §3.5 管）——见下文「划界」一节。
|
||||
> **强制程度**：§2~§5 为**强制**（规划由 `scripts/check_ids.py` 机械校验）；§6~§10 为**约定 + 迁移计划**。
|
||||
> **相关文档**：[`docs/文档规范.md`](文档规范.md)（链接/章节/门禁总规范）、[`docs/任务规划/README.md`](任务规划/README.md) §0（本规范的登记簿摘要）、[`docs/测试说明/测试文档模板规范.md`](测试说明/测试文档模板规范.md) §6（测试侧编号细则）。
|
||||
> **状态**：本文件是**规划稿**——§4 的目标前缀与 §7 的迁移映射在阶段 1 落地前尚未生效，落地进度见 §9。
|
||||
> **强制程度**：§2~§5 为**强制**（由 `scripts/check_ids.py` 机械校验，§8 已落地 warn-only）；§6~§10 为**约定 + 迁移计划**。
|
||||
> **相关文档**：[`docs/文档规范.md`](文档规范.md)（链接/章节/门禁总规范）、[`docs/任务规划/README.md`](任务规划/README.md) §0（本规范的登记簿摘要）、[`docs/测试说明/测试文档模板规范.md`](测试说明/测试文档模板规范.md) §6（测试侧编号细则）、[`docs/代码规范/pre-commit使用说明.md`](代码规范/pre-commit使用说明.md) §2.25（`id-check` 钩子）。
|
||||
> **状态**：**§8 门禁已落地**（warn-only，含 `scripts/id_registry.json` / `scripts/id_aliases.json`，实测基线见 §8.1）；§4 的目标前缀与 §7 的迁移映射在阶段 1 落地前**尚未生效**，落地进度见 §9。
|
||||
|
||||
---
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
| **悬空引用（引用了不存在的号）** | `Trap 19` 从未存在却被 `docs/测试说明/CH395F_Test_Guide.md` 引用；`N-5/N-8/N-19/N-30/N-31/N-32` 销项删行后仍被引用（`N-32` = 监听生命周期模块化，被 `docs/网络/` 三篇与代码注释多处引用） |
|
||||
| **同一事物多种字面** | `Trap 07` / `TRAP-07` / `陷阱 1`；`gen 181` / `gen-288` / `gen68`；`TC-NET-704` / `TC704` / `TC-203` |
|
||||
| **规范自身就不自洽** | `docs/测试说明/测试文档模板规范.md` §6.3 同一行并列 `TC-STO-03`（2 位）与 `TC-RTC-001`（3 位）；`docs/测试说明/测试文档模板规范.md` §6.2 已废止 `PHY` 模块码，而阶段 ID 至今仍是 `TM-PHY-01` |
|
||||
| **机器校验只覆盖一个族** | 31 个 pre-commit 钩子中只有 `TC` 有 `scripts/check_test_traceability.py`，且**未挂钩子、warn-only、正则 `TC-[A-Za-z0-9]+-\d+` 匹配不到 `TC-AI-01A`**；`E/N/S/B/C/D/A/U/O/gen/Trap` 全部裸奔 |
|
||||
| **机器校验只覆盖一个族** | （2026-10-15 现状，2026-10-20 已由 §8.1 收口）当时 31 个 pre-commit 钩子中只有 `TC` 有 `scripts/check_test_traceability.py`，且**未挂钩子、warn-only、正则 `TC-[A-Za-z0-9]+-\d+` 匹配不到大写后缀形态**；`E/N/S/B/C/D/A/U/O/gen/Trap` 全部裸奔 |
|
||||
|
||||
> **可借鉴的先例**：`§N.M` 章节引用当年 1,578 处也全靠自觉，靠「紧邻写法 + 别名表 + 可判定比例 + 钩子」把可判定比例做到 58% 并转为拦提交（[`docs/文档规范.md`](文档规范.md) §3.5）。编号走同一条路径即可收口。
|
||||
|
||||
@@ -53,7 +53,7 @@
|
||||
| **P-2** | **编号不携带语义**：严重度、状态、日期、负责人、波次一律是表格列 | 降级只改列，编号永不变、引用永不断（`P1-x` 的历史教训） |
|
||||
| **P-3** | **一个前缀只有一个属主登记处**；前缀一经分配**永不复用给别类**，号段用尽即扩位（`N-99`→`N-100`），绝不换字母 | 保证"看到前缀就知道去哪张表查" |
|
||||
| **P-4** | **形态唯一**：`<前缀>-<序号>`；前缀 1~3 位大写字母；序号位数按类别固定并左补零；子项只允许一级 `-<小写字母>`。**禁止**裸形（`S3`）、空格形（`Trap 07`）、中文形（`陷阱 1`）、圈号（`①②③④`） | 连字符与补零不得承载语义；字面唯一才能被机器判定 |
|
||||
| **P-5** | **只增不复用**；每个类别有「下一个可用号」游标（`[计划] scripts/id_registry.json`），新增先取游标 | 并行任务与多文档同时新增时防撞号（《项目审查与优化建议报告》与登记簿并轨时 `N-16` 撞过号，就是没有游标——见 `docs/任务规划/README.md` §0） |
|
||||
| **P-5** | **只增不复用**；每个类别有「下一个可用号」游标（`scripts/id_registry.json`，§8.1 已落地），新增先取游标 | 并行任务与多文档同时新增时防撞号（《项目审查与优化建议报告》与登记簿并轨时 `N-16` 撞过号，就是没有游标——见 `docs/任务规划/README.md` §0） |
|
||||
| **P-6** | **引用必须机器可判定**：跨文档引用用行内代码，首次出现紧邻属主文档名；文档内编号**必须**带文档名 | 与 `§N.M` 同一条路：能校验的约定才算存在 |
|
||||
| **P-7** | **编号不语义，引用必语义**：编号本体保持无语义并冻结（同 P-2）；但**正文引用必须带语义括注**——`TRAP-NET-18（异常释放后排空 RX 残渣）`、`docs/网络/网络自愈架构设计.md` §4.6（应用主动拆会话保监听）；**禁止裸 ID 单独承担信息**。语义放括注，事实变了只改括注、编号不变 | 读者不该为看懂一句话去跳三篇文档。可读性由**引用方式**解决，不由**编号命名**解决——命名带语义会重蹈 `P1-x` 覆辙（§1.2）。落地见 §5.6 |
|
||||
| **P-8** | **语义优先**：规划 / 待办类条目**优先用语义标识**（§3.3）——一行短语即标识，不分配字母+数字号；只有**需机器解析**或**作历史证词**的类别才发编号，且引用时强制带语义括注（P-7） | 编号的唯一性维护成本已实测超过收益：`N-31` 销项删行后按"现存最大值 +1"又被取走，与两处历史引用撞号（`docs/任务规划/README.md` §0）。短语自带唯一性（重名一眼可见），且读者不必跳表查号 |
|
||||
@@ -137,10 +137,14 @@
|
||||
|---|---|---|---|
|
||||
| `FR-[A-Z0-9]+-\d{2}` | 功能需求 | `docs/产品需求/产品需求设计文档.md` §5 | 各域独立递增；**新增域写进该文 §1.2 术语与缩写** |
|
||||
| `NFR-[A-Z0-9]+-\d{2}` | 非功能需求（**新建**，现 §7 全是散文无号） | `docs/产品需求/产品需求设计文档.md` §7 | 从 `NFR-<域>-01` 起 |
|
||||
| `N-\d{2}` | **登记簿条目**（技术债 / 长期观察 / 硬件改版项；含义由"网络项"重定义） | `docs/任务规划/登记簿.md` | **曾用**最大 `N-33`（`N-30`~`N-33` 均已销项、登记簿行已删，**现存至 `N-29`**）→ 游标 `N-34`（号不回收）；原 `S-x`/`T-x` 并入本族（§7.1） |
|
||||
| `E-\d{2}` | 错误码/返回值传播审计发现 | 无（原属主 `docs/问题记录/错误码传播审计.md` 已于 2026-10-15 删除） | **冻结**：`E-63` 为最大号，**不再新增**；新发现一律 `DEF`；现存引用仅作历史指称（§4.3） |
|
||||
| `E\d+` | **自愈实验编号**（N34 台架实验，**无连字符**） | `docs/网络/网络自愈架构设计.md` §5.2 | **已封闭**：`E0`~`E15`，**不再新增**；原始实验记录已归档（该文档 §12）。⚠ 与上一行靠**连字符**区分：带连字符 = 审计发现 |
|
||||
| `TC-[A-Z]{1,4}-\d{3,4}` | 测试用例 | 各测试文档 | 3 位起；分阶段套件序号 = 阶段号×100 + 项号（阶段 ≥10 自然进位 4 位，`TC-NET-1001` 合规）；后缀只允许 `-<小写字母>` |
|
||||
| `N-\d{1,3}[a-z]?` | **登记簿条目**（技术债 / 长期观察 / 硬件改版项；含义由"网络项"重定义） | `docs/任务规划/登记簿.md` | **曾用**最大 `N-33`（`N-30`~`N-33` 均已销项、登记簿行已删，**现存至 `N-29`**）→ 游标 `N-34`（号不回收）；原 `S-x`/`T-x` 并入本族（§7.1）。⚠ 实测另有报告侧补零带子项后缀的 `N-03a`/`N-03c` 与 §5.5 的扩位示例 `N-100` → 位数收到 3、允许小写子项后缀 |
|
||||
| `E-\d{1,2}` | 错误码/返回值传播审计发现 | 无（原属主 `docs/问题记录/错误码传播审计.md` 已于 2026-10-15 删除） | **冻结**：`E-63` 为最大号，**不再新增**；新发现一律 `DEF`；现存引用仅作历史指称（§4.3）。⚠ 属主已删 → 该族**无法判定义存在与否**，门禁只拦越游标（§8.1） |
|
||||
| `E\d+` | **自愈实验编号**（N34 台架实验，**无连字符**） | `docs/网络/网络自愈架构设计.md` §5.2 | ⚠ 规范原记「已封闭 `E0`~`E15`」，**实测该表已到 `E19`**（E16~E19 是其后追加）→ 游标按实测 `E19` 收录，封闭线待订。⚠ 与上一行靠**连字符**区分：带连字符 = 审计发现 |
|
||||
| `TC-[A-Z][A-Z0-9]{0,4}-\d{1,4}[a-z]?` | 测试用例 | 各测试文档 | 3 位起；分阶段套件序号 = 阶段号×100 + 项号（阶段 ≥10 自然进位 4 位，`TC-NET-1001` 合规）；后缀只允许 `-<小写字母>`。⚠ 模块码 `GD5F`/`I104` **含数字**，规范原写的 `[A-Z]{1,4}` 会整族漏掉 GD5F（实测 285 处）→ 已按实测放宽 |
|
||||
| `F-<MOD>-<nn>` | **net / 驱动侧功能与改进项**（`F-NET-2~17`、`F-DRV-*`、`F-MS-*`） | `docs/网络/网络自愈架构设计.md` | 2026-10-20 补行：本族**早就在被代码注释大量引用**（实测 60+ 处）而总表里没有——正是 §5.1 第 1 步"表里没有的类别先改本规范"的适用对象；`id-check` 落地时按实测收编 |
|
||||
| `P-<n>` | **本规范的设计原则条目**（`P-1`~`P-8`） | 本文档 §2 | 2026-10-20 补行；⚠ 与档位词 `P0~P3`（§4.4）、审计条目 `P0-x`（§4.3）靠**连字符**区分，三者形态互斥 |
|
||||
| `CODE-RULE-<nn>` | **嵌入式 C 代码规范条款号**（配原文章节号，如 `CODE-RULE-03 (3.4.1)`） | `scripts/check_coding_standard.py`（规则表 = 单一事实源） | 2026-10-20 批 1 新建：原名是裸形 `S1`~`S19`，与登记簿 `S-x`、UI 像素状态、2026-10-02 复审专项条目**四义撞形**（§1.2）→ 单词化改名，旧号进 `id_aliases.json` 的 **scoped** 条目。⚠ `S14` 历史上不存在，空洞不复用 → 游标 19 |
|
||||
| `MENU-STATE-<nn>` | **UI 菜单像素回归状态号**（按键序列状态，共 8 态） | `simulator/tests/check_menu_rows.py` 的 `STATES` 表 | 2026-10-20 批 1 新建：原名裸形 `S0`~`S7`（同上撞形）；**冻结在 07**，加状态须先改本族游标 |
|
||||
| `TM-[A-Z]{1,4}-\d{2}` | 测试阶段 | 各测试文档 | 模块码取 §6 统一表（`TM-PHY-01` → `TM-NET-01`） |
|
||||
| `DP-[A-Z]{1,4}-\d{2}` | 设计原则 | 各测试文档 | **加模块码**（现 `DP-01` 跨文档会撞） |
|
||||
| `L\d` / `L\d-\d{1,2}` | 采集与保护分层、层内条目 | `docs/算法/继电保护功能复现规划.md` §3 | 保留（代码侧 141 处引用，是全项目最规范的一族，作样板）；`L` 前缀**专属**此族 |
|
||||
@@ -222,7 +226,7 @@
|
||||
0. **先问"能不能不加号"**：能用 § 小节引用、表格列、语义标题表达清楚的，就不要分配编号——
|
||||
编号是"确需跨文档长期引用"时才付的成本（P-1 / P-3 / P-7）。确需新增才往下走。
|
||||
1. 查 §4 总表确定类别与属主登记处；**表里没有的类别 → 先改本规范，不得自造前缀**。
|
||||
2. 到属主登记处取游标号（`[计划] scripts/id_registry.json` 记录每类下一个可用号），登记处新增一行。
|
||||
2. 到属主登记处取游标号（`scripts/id_registry.json` 记每类的游标与冻结状态），登记处新增一行。
|
||||
3. 严重度 / 状态 / 波次 / 出处写进表格列，**不进编号**。
|
||||
|
||||
### 5.2 引用写法
|
||||
@@ -273,9 +277,11 @@
|
||||
短语**不复用**——重名即视为同一条目，与"号不回收"同理（撞名风险高于撞号，故由门禁兜底）。
|
||||
- **代码注释**：语义短语可进代码注释（中文注释允许），但必须带属主文档名（同 §5.3）；
|
||||
现状 `App/algo/` 下 `N-18` 等 6+ 处**裸编号引用违反 P-7**，迁移时一并补语义。
|
||||
- **门禁**（待落地）：① 同一登记处内短语去重；② 引用了登记处不存在的短语 = 悬空，报错；
|
||||
③ 打印「语义标识可判定比例」，只许涨不许跌。校验脚本 `[计划] scripts/check_ids.py`
|
||||
尚未落地（§8），落地前由人工 + `grep` 执行上述三条。
|
||||
- **门禁**（`scripts/check_ids.py`，§8，2026-10-20 已落地 warn-only）：① 同一登记处内短语去重；
|
||||
② 引用了登记处不存在的短语 = 悬空，报错；③ 打印「语义标识可判定比例」，只许涨不许跌。
|
||||
⚠ **当前落的是"编号"侧的 ②③**（编号族的悬空与可判定比例已机械化）；**语义短语**侧的
|
||||
同表去重与短语悬空仍由人工 + `grep` 执行——短语是自由文本，机械去重要先解决同义异写判定
|
||||
（`日志静默` vs `49s 日志静默`），那是另一个问题，别把它记成"已由门禁兜住"。
|
||||
|
||||
---
|
||||
|
||||
@@ -359,7 +365,7 @@ git grep -n '<旧字面量>' # 零残留
|
||||
|
||||
## 8. 门禁：`check_ids.py` 与 `id-check` 钩子
|
||||
|
||||
配置两份：`[计划] scripts/id_registry.json`（前缀 → 属主文档 / 形态正则 / 是否冻结 / 游标）、`[计划] scripts/id_aliases.json`（旧号 → 新号，照搬 `scripts/section_aliases.json` 的成功范式）。
|
||||
配置两份：`scripts/id_registry.json`（前缀 → 属主文档 / 形态正则 / 是否冻结 / 游标）、`scripts/id_aliases.json`（旧号 → 新号，照搬 `scripts/section_aliases.json` 的成功范式）。
|
||||
|
||||
| # | 校验 | 级别 |
|
||||
|---|---|---|
|
||||
@@ -376,6 +382,58 @@ git grep -n '<旧字面量>' # 零残留
|
||||
- 上线节奏：**先 warn-only 清 backlog → 清零后加 `--strict` 拦提交**（与 `doc-links` 章节校验完全同一条路径）。
|
||||
- 顺带收编 `scripts/check_test_traceability.py`：正则补 `TC-[A-Z]{1,4}-\d{3,4}[a-z]?`，覆盖 7 篇「单元测试说明.md」，一并挂进 `id-check`（现为 warn-only 且未挂钩子）。
|
||||
|
||||
### 8.1 落地记录（2026-10-20）
|
||||
|
||||
**已落地并挂上 `id-check` 钩子（warn-only）**。三项机械判据先定死，否则八项校验全是空话：
|
||||
|
||||
| 判据 | 口径 |
|
||||
|---|---|
|
||||
| 「定义」存在 | 字面量出现在该族的**属主登记处文档**里（registry 的 `owner_docs` / `owner_docs_glob`）——不依赖表格行首等易漂移形态 |
|
||||
| 「重复定义」 | 字面量出现在**定义位**（表格首格 / 标题行 / 列表项行首）；正文里"提到过"不算定义，否则任何交叉引用都会被误判 |
|
||||
| 「可判定」 | 字面量落进已登记前缀族**且该族属主登记处已存在**；未登记前缀、属主还是 `[计划]` 的都算不可判定 |
|
||||
|
||||
**首轮基线（本仓库实测，`--update-baseline` 写进 `id_registry.json`，只许涨不许跌）**：
|
||||
|
||||
| 项 | 数值 |
|
||||
|---|---|
|
||||
| 扫描文件 | 536 个（`git ls-files` 减去 §8 排除清单） |
|
||||
| 编号字面量出现 | 8271 处 |
|
||||
| **可判定比例基线** | **82.6%**（6840 / 8271 = 82.70%，批 1 改名后重打，存进 `id_registry.json` 时**下取整到 0.1pp**——用 `round()` 会让 82.34 进位成 82.3 再反过来把自己判死，实测踩过；比较容差 0.1pp） |
|
||||
| 校验 1 未登记前缀 | 0 处 |
|
||||
| 校验 2 形态不合规 | 396 处（**批 1 已从 417 降到 396**：裸形 `S`/`T` 类 71 → 50。剩余大头：真无模块码 `TC-nnn` 181 处 / 5 文件、数字模块码 `TC-104-nnn` 23 处（§6 表里模块码是 `I104`，非数字）、`DP-0n` 22 处、`Task #nn` 33 处、`Trap 空格形`+`陷阱 中文形` 43 处、`gen/round` 36 处、大写后缀 31 处） |
|
||||
| 校验 3 悬空引用 | 错误 626 / 告警 223（scoped 别名收编旧号后 −16）（错误集中在 `TC-PS-*`/`TC-PE-*`/`TC-AH-*`/`TC-FR-*`/`TC-SOE-*`——**主机侧单测有码无文档**，正是 §7.2 列的"缺文档 = 追溯断链"） |
|
||||
| 校验 4 重复定义 | 0 处（`§4.3` 已声明的同号不同义族对 443 个字面量走 `collides_with` 白名单，不计事故） |
|
||||
| 校验 5 冻结越游标 | 0 处 |
|
||||
| 校验 6 未紧邻文档名 | 269 处（报告自有编号 `D-x`/`R-x`/`F-x`/`P0-x` 被裸引，属 §9 阶段 1-③ 待办） |
|
||||
| 校验 7 孤儿条目 | 88 处（告警） |
|
||||
| 附带 TC 双向追溯 | 代码侧 556 / 文档侧 290 / 交集 260（差异 326，收编后含主机侧单测一侧，比原板级口径的 33 大一个量级——**原口径漏的正是 7 篇单测说明**） |
|
||||
|
||||
**有牙实测**（[示例] 下列字面量是注入用的假编号，不是真实引用）：临时注入 `Z-99` / 裸形 `S3` / `TC-NET-9999`（悬空）/ `E-70`（越 `E-63` 游标）/ 裸引 `D-7` / 在第二篇属主文档重复定义 `DP-01` → 六项分别被校验 1/2/3/5/6/4 点名，`--strict` 退出码 1；临时档删除后 `git status` 干净。
|
||||
|
||||
**显式盲区（不是"检查通过"，是记在案上的判定边界）**：裸形同字母多义（§1.2 的 P1 五义 / L1 四义 / U1 四义 / D7 三义）与元器件位号同形（§4.4）→ 裸形族**只在属主登记处文档内**判越游标，文档外降为告警；圈号编号与正常列举无法机械区分，不入判定。这两块的收口属 §9 阶段 1-②/1-③ 的迁移批次，收口后再扩判定范围。
|
||||
|
||||
### 8.2 落地时发现的规范 ↔ 仓库偏差（registry 按实测收录，规范行待订正）
|
||||
|
||||
| 规范原文 | 实测 | 处置 |
|
||||
|---|---|---|
|
||||
| §4.1 `E\d+`「已封闭 `E0`~`E15`」 | `docs/网络/网络自愈架构设计.md` §5.2 实验表已到 **E19** | 游标按实测 E19 收录；封闭线待修订 |
|
||||
| §4.1 `FR-[A-Z0-9]+-\d{2}` | 现存 `FR-STO-1` 等全是**未补零**的 1 位序号 | 正则放宽到 `\d{1,2}`，补零归 §9 阶段 1 |
|
||||
| §4.1 `TC-[A-Z]{1,4}-\d{3,4}` | 模块码 `GD5F`/`I104` **含数字**，按原文正则会漏掉 GD5F 全族（实测 285 处） | 放宽为 `[A-Z][A-Z0-9]{0,4}`；序号暂收 2 位（`TC-STO-06` 属 §7.2 孤儿） |
|
||||
| §4.1/§4.2 总表无 `F-<MOD>-<nn>` | `F-NET-2~17`/`F-DRV-*`/`F-MS-*` 定义在 `docs/网络/网络自愈架构设计.md` 且被大量代码注释引用 | 先按实测收编成族（§5.1 第 1 步：表里没有的类别先改本规范） |
|
||||
| §4.1 `N-\d{2}` | 报告用 `N-03a`/`N-03c` 子项后缀；§5.5 扩位示例 `N-100` | 放宽到 `\d{1,3}[a-z]?` |
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 8.3 迁移批次记录（改名走 `scripts/rename_ids.py`）
|
||||
|
||||
| 批 | 日期 | 族 | 旧 → 新 | 处数 / 文件 | 别名 |
|
||||
|---|---|---|---|---|---|
|
||||
| **批 1** | 2026-10-20 | 代码规范条款 | `S1`~`S19` → `CODE-RULE-01`~`19` | 78 处 / 2 文件 | 18 条（scoped：`scripts/check_coding_standard.py`、`docs/代码规范/pre-commit使用说明.md`） |
|
||||
| **批 1** | 2026-10-20 | UI 像素回归状态 | `S0`~`S7` → `MENU-STATE-00`~`07` | 61 处 / 3 文件 | 8 条（scoped：`simulator/tests/check_menu_rows.py`、`docs/UI设计/UI_自动化测试流程.md`、`simulator/README.md`） |
|
||||
|
||||
⚠ **别名必须带 scope**：同一裸形字面量可同时是多族的旧号（实测 `S3` 三义）。全局别名会把另一族的真悬空洗成「已解析」——等于用工具复制 §1.2 的 `N-31`/`N-32` 撞号事故。
|
||||
|
||||
---
|
||||
|
||||
## 9. 落地阶段与验收
|
||||
@@ -387,7 +445,7 @@ git grep -n '<旧字面量>' # 零残留
|
||||
| **1-① 小族** | `RC`/`PAT`/`GEN`/`RUN`/`MS`/`GAP`/`SC`/`OQ`/`RSK`/`DR`/`TRAP`/`ST`/`UL`/`LAT`/`CS` + Mermaid 节点 id + 孤儿处置 | 每批：dry-run 通读 → 落盘 → `git grep` 零残留 → `check_doc_links --all` → `@build` 0/0 → `ci_local.py` | 中 |
|
||||
| **1-② 大族** | `N` 补零 + `S`/`T` 并入；`WI` ← `B`/`C`/`D`/`W1-0`/`S1x`/`A-x`/`R-x`/`F-x`/`U-x`；测试分层 `L0~L3` → `T0~T3`（**最大机械批次**，`L0.5` 一词全库百余处） | 同上，逐族一个 commit | **高** |
|
||||
| **1-③ 缺陷族** | `DEF` ← `P0-x`~`P3-x` 在册项；报告历史编号补齐紧邻文档名；档位词规则落地；别名表与游标定稿 | 同上 | 中 |
|
||||
| **2 门禁** | `check_ids.py` + `id-check` 钩子（warn → strict）；`check_test_traceability.py` 收编 | 全库告警清零后转 strict；可判定比例基线入档 | 中（首轮会暴露大量真悬空引用） |
|
||||
| **2 门禁** | ✅ **已落地（2026-10-20，warn-only）**：`scripts/check_ids.py` + `id-check` 钩子 + `scripts/id_registry.json` / `scripts/id_aliases.json`；`check_test_traceability.py` 已收编（正则补齐 + 纳入 7 篇「单元测试说明.md」与 `test/host/` 一侧） | 全库告警清零后 entry 加 `--strict` 转拦提交；可判定比例基线 **82.6%** 已入档（批 1 改名后由 82.3% 抬升）（§8.1，写在 `id_registry.json` 里，跌破即失败） | 中（首轮确实暴露出 626 处真悬空 + 416 处形态违规 + 269 处未紧邻文档名，见 §8.1） |
|
||||
|
||||
每阶段结束停下等指令再提交（`AGENTS.md` 边界：commit/push 须明确指示）。
|
||||
|
||||
@@ -412,4 +470,6 @@ git grep -n '<旧字面量>' # 零残留
|
||||
|---|---|---|
|
||||
| 2026-10-14 | 新增 P-7 与引用可读性规则 | §2 加 **P-7「编号不语义，引用必语义」**（编号本体保持无语义并冻结，但正文引用必须带语义括注、禁裸 ID 独担信息）→ 六条原则变**七条**；§5.1 加前置步"先问能不能不加号"；新增 **§5.6「编号密集文档的对照节（强制）」**（≥3 个编号族必须加「导读：编号与术语」）；§4.1 补登记 **`E\d+`**（N34 自愈实验编号族，已封闭）并把 `N-\d{2}` 的在册范围订正为「曾用最大 `N-33`，现存至 `N-29`」；§1.2 悬空引用示例补 `N-32`；§7.1 同步订正。起因：`docs/网络/网络自愈架构设计.md` 合并与导读节实践暴露"裸编号引用不可读"，用户裁定以后尽量用语义标识 |
|
||||
| （规划稿） | 建立本文档 | 全库扫描 1,385 个不同编号 / 19,306 处出现后定稿的两层编号体系（全局编号 + 文档内编号）、六条原则、目标前缀总表、三批迁移映射与 `check_ids.py` 门禁设计；用户决策：`E-xx` 冻结保留、严重度档位词 `P0~P3` 不变、文档落 `docs/编号规范.md`、阶段 1 三批全做 |
|
||||
| 2026-10-20 | **编号改名开禁（用户授权）+ 批 1 落地** | 新增 `scripts/rename_ids.py`（§7.3 规划脚本：映射表驱动、显式 scope、干跑/落盘两态、自动写 `id_aliases.json` 的 scoped 条目、跳过 `[示例]`/`[计划]` 行与变更记录表、按原字节读写保 BOM 与行尾）。**批 1**：代码规范条款 `S1~S19` → `CODE-RULE-nn`（78 处/2 文件）、UI 像素回归状态 `S0~S7` → `MENU-STATE-nn`（61 处/3 文件）；`check_ids.py` 支持 **scoped 别名** 并登记两族（66 族）；可判定比例 82.3% → **82.7%**、裸形判错 71 → 50、错误级 1312 → 1291。§4.1 补两行、新增 §8.3 迁移批次记录 |
|
||||
| 2026-10-20 | **§8 门禁落地（warn-only）** | 新增 `scripts/check_ids.py`（八项校验 + 可判定比例基线）、`scripts/id_registry.json`（逐项来自 §4 总表 + 实测游标）、`scripts/id_aliases.json`；挂上 `id-check` 钩子（36→37）；顺带收编 `check_test_traceability.py`（正则补齐大写后缀/无模块码形态，比对范围扩到 7 篇「单元测试说明.md」+ `test/host/` 一侧，另加 `--board-only` 回退原口径）。**新增 §8.1 落地记录**（基线 82.3%、backlog 分布、有牙实测、显式盲区）与 **§8.2 规范↔仓库偏差表**（`E19`、`FR` 未补零、`TC` 模块码含数字、`F-<MOD>-<nn>` 总表缺行、`N` 子项后缀/扩位）；§4.1 相应行按实测订正并补 `F-<MOD>` / `P-<n>` 两行 |
|
||||
| 2026-10-15 | 新增 P-8 与语义标识规范（§3.3 / §5.7） | §2 加 **P-8「语义优先」**（规划 / 待办类条目优先用语义标识，不发字母+数字号）→ 七条原则变**八条**；§3 主轴由"两层编号"扩为**编号 / 语义标识 / 章节引用**三种；新增 **§3.3「语义标识（新条目默认形态）」**（形态规则、适用分界、引用写法）与 **§5.7「语义标识的登记、冻结与别名」**；§4.2 加修订说明（规划类前缀改语义标识，`TC`/`TRAP`/`FR`/`NFR`/`RC` 等保留编号）；§9 加「0.5 语义标识」阶段。起因：用户裁定去除字母数字编号（难理解），先定规范本体 |
|
||||
|
||||
Reference in New Issue
Block a user