Files

T

wandering1 925058a5ae fix(NET)+docs: lftpd 对端地址修复、E6 裁决收口、陷阱编号迁移重排 TRAP-NET-01~21

- lftpd：net_inet_ntoa 段序改 MSB 首 + 新增 net_getpeername，FTP 日志打印
  真实对端地址（真机实证 192.168.1.2:55524，登记 TRAP-NET-21）
- E6：NET_U15_PROBE 命中=0（含压测）→ 阶段 3 项 4 不立项，U15 登记观察项；
  插桩留仓（宏=0 零成本），soak 驱动 test/host/e6_soak.py 入库
- 编号：全库 Trap NN → TRAP-NET-<nn> 迁移并重排连续 01~21（单调映射，
  沿革见 CH395F_Trap_Records.md 头注）；死号 12/13/19/21 引用全部清除；
  GD5F 域引用补正为 TRAP-GD5F-NN
- 陷阱文档全新化：索引 21 行行行真陷阱；删误判存档/发现时间/git 考古/
  FTP 附录；台架纪律教训沉淀第六章方法论
- RAM：Code 211348→211456（+108 lftpd 修复），RW+ZI 净增 +4B；
  优化方案/台账受管区/tsv 同笔同步
- ftp_abort_probe.py 挪 test/host/；引用关系图重生成
- 回归：@build 0/0；@test PASS；ftp_abort 10/10；relisten :7003 20/20；
  ci_local L0+L0.5 全绿；E6 窗口零复位，7 条 WD stall 登记压测假象备查

2026-10-13 20:54:31 +08:00

24 KiB

Raw Blame History

编号规范

适用对象：本仓库全部 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 §3.5 管）——见下文「划界」一节。 强制程度：§2~§5 为强制（规划由 scripts/check_ids.py 机械校验）；§6~§10 为约定 + 迁移计划。 相关文档：docs/文档规范.md（链接/章节/门禁总规范）、docs/任务规划/README.md §0（本规范的登记簿摘要）、docs/测试说明/测试文档模板规范.md §6（测试侧编号细则）。状态：本文件是规划稿——§4 的目标前缀与 §7 的迁移映射在阶段 1 落地前尚未生效，落地进度见 §9。

1. 为什么要重写编号体系

1.1 病根：前缀按"来源"分配，不按"事物类别"分配

每来一次审计/复审/专项，就自造一套前缀，字母很快瓜分殆尽：

来源	自造的前缀
2026-09-21 错误码传播审计	`E-xx`、缺陷模式 `P1~P9`、严重度 `P0~P2`
2026-09-15/09-21 代码审计	`P0-x` ~ `P3-x`（严重度直接进编号）
2026-09 项目审查与优化建议报告	`N-xx`、`D-x`、`S-x`、`R-x`、`F-x`、`U1~U5`
台架与长期观察	`N-x`、`S-x`、`T-x`、`gen`、`round`、`V2/V4/V5`
2026-10-02 复审	`S1~S14`、`A-1~A-7`
任务规划	`W<n>`、`B\d`、`C\d`、`D\d`、`M\d`
各模块陷阱/设计文档	`Trap NN`、`陷阱 N`、`D1~D10`、`O1~O6`、`U1~U15`、`①~④`

后果：同一字母被 3~5 个来源共用，编号本身不再能定位事物。

1.2 已确证的事故（全部有仓内证据，非假想）

类型	实锤
同字母多义	`P1` 五义（缺陷模式 / 严重度 / 审计条目 `P1-8` / 用例优先级 / `ch395f_test_task.c` 的 Phase1 测试项 `P1-01`）；`L1` 四义（算法层 / 测试分层 / UI 四层 / CubeMX 三层）；`U1` 四义；`O4` 四篇文档四义
同一文件内双义	`实机测试实施指南.md` 的 `A2/A3/A4` 既是环境预检项（§2）又是已完成事项（§10）
连字符/补零偷偷承载语义	`R1`=风险、`R-2`=内存优化项；`D7`=验证窗口、`D-7`=文档门禁、`D1~D7`=设计决策；`N-2`（登记簿）与 `N-02`（报告）同号不同义
跨文档同号不同义	`Trap 02` 在 CH395F 是"缓冲区重叠"、在 GD5F 是"测试缓冲越界"；`B10` 在规划是"送检窗口"、在陷阱审计是"孤儿监听"
语义进编号 → 事实一变编号就撒谎	`P1-x` 把严重度写进号里，而审计中大量条目事后降级（`E-59` P0→P1、dhara `is_free` P1→P2）：改号则引用全断，不改则号实不符
孤儿编号（代码有、文档无）	`I-1`/`I-2`、`Task #32` 会话号、`P1-01~P1-09`、`TC-GD5F-1100/1101/1102`、`TC-STO-06`、`TC-AH-`、`TC-PE-`（前两项项目已在 `docs/测试说明/实机测试实施指南.md` 自行承认）
悬空引用（引用了不存在的号）	`Trap 19` 从未存在却被 `docs/测试说明/CH395F_Test_Guide.md` 引用；`N-5/N-8/N-19/N-30/N-31` 销项删行后仍被引用
同一事物多种字面	`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` 全部裸奔

可借鉴的先例：§N.M 章节引用当年 1,578 处也全靠自觉，靠「紧邻写法 + 别名表 + 可判定比例 + 钩子」把可判定比例做到 58% 并转为拦提交（docs/文档规范.md §3.5）。编号走同一条路径即可收口。

2. 六条设计原则（强制）

#	原则	理由
P-1	前缀 = 事物类别，不是来源文档/审计轮次。来源是登记簿的「出处」列，不进编号	否则每轮审计都造一套新字母，必然瓜分殆尽
P-2	编号不携带语义：严重度、状态、日期、负责人、波次一律是表格列	降级只改列，编号永不变、引用永不断（`P1-x` 的历史教训）
P-3	一个前缀只有一个属主登记处；前缀一经分配永不复用给别类，号段用尽即扩位（`N-99`→`N-100`），绝不换字母	保证"看到前缀就知道去哪张表查"
P-4	形态唯一：`<前缀>-<序号>`；前缀 1~3 位大写字母；序号位数按类别固定并左补零；子项只允许一级 `-<小写字母>`。禁止裸形（`S3`）、空格形（`Trap 07`）、中文形（`陷阱 1`）、圈号（`①②③④`）	连字符与补零不得承载语义；字面唯一才能被机器判定
P-5	只增不复用；每个类别有「下一个可用号」游标（`[计划] scripts/id_registry.json`），新增先取游标	并行任务与多文档同时新增时防撞号（`docs/问题记录/项目审查与优化建议报告.md` 变更记录自述"并轨时未做全局唯一性检查"就是没有游标）
P-6	引用必须机器可判定：跨文档引用用行内代码，首次出现紧邻属主文档名；文档内编号必须带文档名	与 `§N.M` 同一条路：能校验的约定才算存在

3. 主轴：两层编号

层	适用事物	形态	引用规则	门禁校验
全局编号	会跨文档流转：需求、缺陷、待办、决策、风险、测试用例、陷阱记录	全局唯一前缀 + 全局序号 + 唯一属主登记处	行内代码；跨文档首次出现紧邻属主名	全库唯一；必须能在属主表查到定义行
文档内编号	只在定义它的那篇文档内有意义：状态机组合、方案档位、专项风险、专项阶段	允许存在，前缀带类别码，号段文档内独立	必须紧邻文档名（同 `§N.M` 紧邻规则）	校验"该文档内确有此编号"

3.1 判定口诀

会不会在别的文档里被引用？会 → 全局编号；不会 → 文档内编号，且引用必须带文档名。

现状的病根正是把该全局的（发现、待办）做成了文档内编号（各文档自造 O1~O4、A1~A6），又把该文档内的（设计决策 D1~D7、状态机 U1~U15）做成了裸形全局编号。

3.2 编号 vs 章节引用

条目特征	用什么
会增删、会重排、只是"读第几条"	章节引用 `docs/xxx.md` §N.M（不造编号）
需要稳定身份（要销项、要被代码引用、要跨文档追溯）	编号

各设计文档的"本期不做 / 遗留可选项"清单（现状 O1~O4 四篇文档四义）默认不造编号，改用 §小节引用；确需逐条引用时才启用文档内编号 OOS-<nn>。

4. 编号空间总表

4.1 在册保留（零改写，仅补规则）

前缀（正则）	类别	属主登记处	游标/规则
`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-34`；原 `S-x`/`T-x` 并入本族（§7.1）
`E-\d{2}`	错误码/返回值传播审计发现	`docs/问题记录/错误码传播审计.md`	冻结：`E-63` 为最大号，不再新增；新发现一律 `DEF`
`TC-[A-Z]{1,4}-\d{3,4}`	测试用例	各测试文档	3 位起；分阶段套件序号 = 阶段号×100 + 项号（阶段 ≥10 自然进位 4 位，`TC-NET-1001` 合规）；后缀只允许 `-<小写字母>`
`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` 前缀专属此族
`W\d+`	波次	`docs/任务规划/README.md` §2.0	保留；游标 `W8`；子任务卡不再用 `W1-0` 形态（并入 `WI`）

4.2 目标前缀（阶段 1 改名后启用）

新前缀	类别	收编的旧编号	新属主登记处	游标
`DEF-<nnn>`	缺陷 / 问题发现	`P0-x`~`P3-x`（在册项）、新发现	`[计划] docs/问题记录/缺陷登记簿.md`	`DEF-001`
`WI-<nnn>`	工作项 / 任务卡	`B\d`(功能主线)、`C\d`(结构债)、`D\d`(验证窗口)、`W1-0`、`S1~S14`、`A-1~A-7`、`P1-10`、报告 `R-x`(内存优化)、`F-x`、`U1~U5` 的未闭环项	`docs/任务规划/` 波次与排期文件（类别做列）	`WI-001`
`DR-<nnn>`	决策记录	`docs/子系统设计/网络Socket监听生命周期设计说明.md` 的 `D1~D10`	`[计划] docs/架构设计/决策记录登记簿.md`	`DR-001`
`OQ-<nnn>`	待确认 / 开放问题	`B0-a/b/c`、`待确认-N`	`docs/任务规划/基线与待确认.md`	`OQ-001`
`RSK-<nn>`	风险（文档内编号）	保护规划 `R1~R8`、看门狗 `R1~R7`	各文档风险表（引用必须带文档名）	各文档自 `RSK-01`
`TRAP-<MOD>-<nn>`	陷阱记录	`Trap 07`、`TRAP-07`、`陷阱 1`	`docs/问题记录/<模块>_Trap_Records.md`	保留原号（`TRAP-NET-01~21`——NET 域 2026-10-13 全库迁移并重排连续，沿革见该文档、`TRAP-GD5F-01~06`、`TRAP-RTC-01~`）
`GAP-<nn>`	模拟器差距	`H-1~H-7`、`L-1~L-4`、差距清单 `N-1~N-6`	`docs/测试说明/模拟器差距清单.md`	`GAP-01`
`SC-<nn>`	实机验证场景	实机预检 `A1~A8`、看门狗验证用例 `V2/V4/V5`	`docs/测试说明/实机测试实施指南.md`	`SC-01`
`T0/T0.5/T1/T2/T3`	测试分层（原 `L0/L0.5/L1/L2/L3`）	测试分层五档	`docs/测试说明/测试开发标准流程.md` §1	固定五档
`G0/G0.5/G1/G2/G3`	门禁（必跑清单，与测试分层是两套，不合并）	现门禁决策表 `G0~G3`	`docs/测试说明/测试开发标准流程.md` §1.1	固定
`GEN-<nnn>`	台架日志代次	`gen 181`、`gen-288`、`gen68`	`docs/测试说明/串口助手设计说明.md`	数字不变，仅改字面
`RUN-<yyyymmdd>-<n>`	台架轮次	`round 1~9`	`docs/测试说明/实机测试实施指南.md`	日期制
`MS-<nn>`	里程碑	`M1~M3`	波次文件	`MS-01`
`RC-<nn>`	net 周期对账类型	`①②③④`（唯一被代码逻辑引用的圈号链）	`docs/子系统设计/网络Socket监听生命周期设计说明.md`	`RC-01`~`RC-04`
`PAT-<nn>`	缺陷模式（九类）	`docs/问题记录/错误码传播审计.md` §1.1 的 `P1~P9`	同文	`PAT-01`~`PAT-09`
`ST-<n>`	专项内部实施阶段（文档内编号）	保护规划 §7.1 的 `P0~P5`、方案阶段 `P0~P3`	各专项文档	各文档自 `ST-0`
`UL-<n>`	UI 标准化四层（文档内编号）	报告 UI 四层 `L0~L3`	`docs/UI设计/UI_设计架构.md`	`UL-0`
`LAT-<nn>`	链路延迟分段（文档内编号）	`docs/测试说明/链路延迟测试说明.md` 的 `L1~L11`	同文	`LAT-01`
`CS-<n>`	CubeMX 定制存活三层	`AGENTS.md` 的 `L1 写进 .ioc → L2 USER CODE → L3 审计`	`docs/子系统设计/看门狗设计说明.md` §10	`CS-1`~`CS-3`

4.3 冻结前缀（历史快照，正文不回改）

冻结对象	处置
`E-<nn>`	冻结于 `E-63`；引用照旧，禁止新增；门禁拒绝游标之外的新 E 号
`docs/问题记录/项目审查与优化建议报告.md` 自造的 `N-xx`/`D-x`/`S-x`/`R-x`/`F-x`/`U1~U5`	报告是历史基线，不回改；引用一律紧邻文档名；未闭环项已并轨进 `N-19~N-29`，出处列保留报告编号
`docs/问题记录/CH395F_Trap_Records.md` 2026-10-11 审计的 `A1~A6`/`B1~B10`	该表是审计快照（条目已修复或推翻），冻结；新发现进 `DEF`；引用紧邻文档名
`P0-x`~`P3-x`	在册项迁 `DEF`；已闭环项留在历史文档，走别名表
`Task #32` 等会话临时号	禁止入册；现存引用（`Src/main.c`、`Drivers/BSP/UI/ui_net_sink.c` 的 `I-1/I-2`）改写为可解析形式或就地展开成事实描述

4.4 划界：这些不是编号，不受本规范管

对象	例子	归属
C 标识符	`PS_OC1_EN`、`TEST_SUITE_STORAGE`、`ENABLE_PHASE14_TESTS`、`SYS_EVT_NET_READY`、`TASK_WD_ADC`	`docs/代码规范/嵌入式C语言代码规范_V1.0.md`
元器件位号	`U1`、`C12`、`R3`、`L5`、`D7`（`docs/硬件平台/`、`docs/芯片手册/`）	门禁与改写脚本一律排除，这是最大误伤风险源
章节号	`§3.2`	`docs/文档规范.md` §3.5
档位词	`P0`/`P1`/`P2`/`P3`（严重度、用例优先级）	允许继续使用，但永不带 `-<数字>` 后缀——`P1-8` 这类形态一律非法
图元 id	`README.md` 架构图 Mermaid 节点 `A1`/`B1`/`C1`/`D2`	改描述性 id（`net`/`sto`/`ui`），避免与条目字面撞名
运行时计数	网络代次号 `net_get_generation()`	代码概念；与台架 `GEN` 是两回事，文档里须写全"网络代次号"

5. 分配、引用、销项规则（强制）

5.1 新增编号

查 §4 总表确定类别与属主登记处；表里没有的类别 → 先改本规范，不得自造前缀。
到属主登记处取游标号（[计划] scripts/id_registry.json 记录每类下一个可用号），登记处新增一行。
严重度 / 状态 / 波次 / 出处写进表格列，不进编号。

5.2 引用写法

场景	写法
全局编号，跨文档首次出现	`docs/任务规划/登记簿.md` N-21（紧邻，同 `§N.M` 规则）
全局编号，同段后续	`N-21`
文档内编号	必须 `docs/子系统设计/网络Socket监听生命周期设计说明.md` DR-003
尚未创建的条目文件	加 `[计划]` 前缀（`docs/文档规范.md` §3.3）
引用报错样例/历史字面	该行加 `[示例]` 标记

5.3 代码注释引用

允许引用（长期有效）：FR-*、NFR-*、DEF-*、E-*（冻结存量）、N-*、TRAP-*、DR-*、TC-*、L<n>-<nn>。
禁止引用（易变）：WI-*、W<n>、MS-*、OQ-*、ST-*——代码是长期资产，波次与任务卡会变。
首次出现带属主文档名（现状 90% 裸引，靠"全库唯一"这一未成文假设）。

5.4 提交信息

标题带主编号：fix(net): N-32 监听重建阻塞导致心跳缺口。一次提交只挂一个主编号，其余进正文。

5.5 销项与归档

销项 = 删登记行 + 清全库引用（沿用 docs/任务规划/README.md §3 与 AGENTS.md 既有规则）+ 游标不回退。
号段用尽 → 扩位（N-99→N-100），不换字母。
历史文档（审计报告、评审报告、已闭环陷阱）不回改，走别名表。

6. 模块码表（`TC` / `TM` / `DP` / `TRAP` 共用）

现状是板端 6 个码 + 主机侧 10 个码两套并存，且 docs/测试说明/ADC输入层单元测试说明.md 明文豁免主机侧"与板端缩写表互不影响"。本规范合并为一张表，现有码全部沿用（零改写），只规定新模块必须先登记：

码	模块（源文件/目录）	码	模块
`NET`	`Drivers/BSP/CH395F` + `Drivers/BSP/NET`	`AI`	`App/algo/adc_input`
`GD5F`	`Drivers/BSP/GD5F2GQ5UE`	`AH`	`App/algo/adc_health`
`STO`	存储栈（FTL + FatFs + `App/fs`）	`PH`	`App/algo/phasor` + `sample_ring`
`RTC`	`Drivers/BSP/SD2506`	`PS`	`App/algo/prot_set`
`ADC`	采集节拍与通道映射（`Src/adc.c`、TIM3）	`PE`	`App/algo/prot_elm`
`RS485`	`Drivers/BSP/RS485`	`VL`	`App/fs/vol_lock`
`UI`	`Drivers/BSP/UI`	`TS`	`App/sync/time_sync`
`LOG`	`App/log`	`CLK`	`App/util/sys_clock`
`CFG`	`App/cfg` + `Drivers/BSP/NETCFG`	`WD`	`App/util/task_watchdog`
`SH`	`App/util/sha256`	`FA`	`Drivers/BSP/NET/lftpd` 鉴权
`I104`	`App/protocol/iec104`	`TOOL`	PC 端工具（串口助手等）

废止码：PHY（→ NET）、NAND（→ GD5F）。历史文档不回改，新文档按本表。

7. 迁移映射（legacy → 新号）

7.1 映射规则

旧族	新族	规则
登记簿 `N-2`…`N-33`	`N-02`…`N-33`	仅补零，数字不变
登记簿 `S-3/S-4/S-5`、`T-7`	`N-34`…	续号并入，别名表保留旧号
主线 `B0~B10`、结构债 `C1~C6`、验证窗口 `D2~D7`、`W1-0`	`WI-001`…	按波次顺序连续重编，映射表逐条列出并落别名表
复审 `S1~S14`、`A-1~A-7`、报告 `R-x`/`F-x`/`U1~U5` 未闭环项	`WI-*`	同上；已闭环项留历史文档
`P0-x`~`P3-x` 在册项	`DEF-*`	严重度转列
设计说明 `D1~D10`	`DR-001`~`DR-010`	数字对齐
`B0-a/b/c`、`待确认-N`	`OQ-001`…	—
`Trap NN` / `陷阱 N`	`TRAP-<MOD>-<nn>`	数字不变，补模块码
`H-1~H-7`、`L-1~L-4`、差距 `N-1~N-6`	`GAP-01`~`GAP-17`	按文档内出现顺序
实机 `A1~A8`、看门狗 `V2/V4/V5`	`SC-01`…	—
测试分层 `L0/L0.5/L1/L2/L3`	`T0/T0.5/T1/T2/T3`	门禁 `G0~G3` 不动（两套不同尺度，不合并）
`gen 181`/`gen-288`/`gen68`	`GEN-181`/`GEN-288`/`GEN-068`	数字不变
`round 1~9`	`RUN-<日期>-<n>`	无日期的历史轮次留别名表
`M1~M3`	`MS-01`~`MS-03`	—
对账 `①~④`	`RC-01`~`RC-04`	代码注释同步
审计模式 `P1~P9`	`PAT-01`~`PAT-09`	正文冻结，新文档用新号
保护 `R1~R8`、看门狗 `R1~R7`	各文档 `RSK-01`…	文档内编号 + 引用带文档名
保护阶段 `P0~P5`、方案 `P0~P3`	各文档 `ST-0`…	与档位词 `P0` 解耦
`TC-STO-01~06`	`TC-STO-001~006`	补零
`TC-AI-01A`/`02A`/`02B`/`02C`、`TC-VL-008b`	`TC-AI-001a`… / `TC-VL-008b`	后缀统一小写字母，基号补零
`TM-PHY-01~11`	`TM-NET-01~11`	模块码
`DP-01~04`	`DP-NET-01~04`	加模块码

7.2 孤儿编号处置（阶段 1 一并清）

孤儿	处置
`I-1`/`I-2`（`ui_net_sink.c`）	在 `docs/子系统设计/网络Socket监听生命周期设计说明.md` 补定义行，或就地展开成事实描述
`Task #32` 会话号及其小节引用	会话号，改写为可解析引用（结论已沉淀进 `docs/子系统设计/看门狗设计说明.md` §11）
`P1-01~P1-09`（`ch395f_test_task.c`）	改指 `TC-NET-101`…，或补文档条目
`TC-GD5F-1100/1101/1102`、`TC-STO-06`	补进 `docs/测试说明/GD5F2GQ5UE_Test_Guide.md`
`TC-AH-`、`TC-PE-`、iec104 `TC-014/015/024`	补单测说明文档（缺文档 = 追溯断链）
`Trap 19`	悬空引用，删除或改指实际条目

7.3 改写操作规程（每批必走）

# 1) 预览：映射表驱动的 dry-run，人工通读 diff（重点看 docs/硬件平台/ 是否被误伤）
& '.venv\Scripts\python.exe' [计划] scripts/rename_ids.py --map [计划] scripts/id_aliases.json --dry-run

# 2) 落盘后三重复核
git grep -n '<旧字面量>'                       # 零残留
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # 0 错误 0 警告

硬约束：docs/硬件平台/、docs/芯片手册/ 全程排除（元器件位号 U1/C12/R3/L5/D7 与编号字面同形）；带 BOM 的文件（Drivers/BSP/UI/*、App/task/ui_task.c、App/cfg/cfg_file.c、Lib/lv_conf.h）改写后必须核对 BOM 未丢；禁止用 Get-Content/Set-Content 重写含中文文件。

8. 门禁：`check_ids.py` 与 `id-check` 钩子

配置两份：[计划] scripts/id_registry.json（前缀 → 属主文档 / 形态正则 / 是否冻结 / 游标）、[计划] scripts/id_aliases.json（旧号 → 新号，照搬 scripts/section_aliases.json 的成功范式）。

#	校验	级别
1	出现未登记前缀（自造编号）	错误
2	形态不合规：裸形 `S3`、空格形 `Trap 07`、中文形 `陷阱 1`、补零错、`P1-8` 这类档位词带后缀	错误
3	引用查无定义且不在别名表（悬空引用）	错误
4	同一字面量被两个属主重复定义（`N-16` 类事故）	错误
5	冻结前缀出现游标之外的新号	错误
6	文档内编号引用未紧邻文档名	错误
7	定义了但全库无引用（孤儿条目）	告警
8	打印「编号引用可判定比例」	每次运行，只许涨不许跌

排除：Lib/、Middlewares/、HAL/CMSIS、docs/芯片手册/、docs/硬件平台/（位号）、构建产物。
上线节奏：先 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 且未挂钩子）。

9. 落地阶段与验收

阶段	内容	验收判据	风险
0 规范	本文件；`docs/任务规划/README.md` §0 改为指向本规范的摘要；`docs/README.md`、`AGENTS.md`、`docs/文档规范.md` §6 登记；两份 `id_*.json` 初版	`check_doc_links --all` 通过、`@build` 0/0	零（纯新增 + 指针）
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；可判定比例基线入档	中（首轮会暴露大量真悬空引用）

每阶段结束停下等指令再提交（AGENTS.md 边界：commit/push 须明确指示）。

10. 常见错误速查

现象	原因	修复
`id-check` 报"未登记前缀"	自造了一套编号	查 §4 总表归到既有类别；确属新类别先改本规范
同一编号在两篇文档各指一物	用了文档内编号却裸引	改全局编号，或引用补文档名（紧邻）
引用的编号查不到定义	孤儿/悬空	补定义行，或删引用
降级后编号与事实不符	语义进了编号	违反 P-2；严重度改列，编号不动
硬件文档里 `U1`/`C12` 被改	改写脚本没排除位号目录	回滚该批，按 §7.3 排除清单重跑
改完中文变乱码	用了整文件重写	见 `AGENTS.md` 铁律：只用精确子串替换，BOM 按原样补回

变更记录

日期	变更	说明
（规划稿）	建立本文档	全库扫描 1,385 个不同编号 / 19,306 处出现后定稿的两层编号体系（全局编号 + 文档内编号）、六条原则、目标前缀总表、三批迁移映射与 `check_ids.py` 门禁设计；用户决策：`E-xx` 冻结保留、严重度档位词 `P0~P3` 不变、文档落 `docs/编号规范.md`、阶段 1 三批全做

24 KiB Raw Blame History Unescape Escape