wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
696 Commits 3 Branches 0 Tags
a275539c1775d8278af3013402d9aa7289698be2
Commit Graph

41 Commits

Author SHA1 Message Date
wandering1 563737f39c docs(规范): 立两条协作纪律——归因必须带可复核证据、注释必须陈述事实而非意图 
§2.4 讲的是「抢跑之前自己该跑哪些等价门禁」，那一节管形态；这一节管另一类钩子拦不住的东西：
**归因与陈述的正确性**。今天一天里，这类错误造成的代价不比任何一个编译错误小，所以四条规则
每条都配着当天真实发生过的一次返工：

1. 数字必须钉产物身份（路径 + 构建/运行时刻）；**重跑同一个报告脚本不算新测量**——产物没变、
   数字必然不变，写成「我复验过」就是假凭证。附带本仓实测坑：stack_report.py 的 REPO_ROOT 跟着
   __file__ 走，cd 进别的 worktree 跑主仓脚本量的还是主仓产物（今天就栽过一次，据此错怪了一笔
   清白的提交，公开更正了两次）。
2. hash 不是稳定身份，tree + 父提交才是；出回执前先核 reflog，**先请人按 hash 复算、自己再重写
   hash** 是顺序错误（今天真发生过，让队友的回执一出生就过期）。
3. 归因前先确认数字来自哪棵树、哪一次运行——并发时序不是谁的错。当天把「文件 mtime 晚于构建」
   误判成某个道「删实现后注册」，实际只是两条道同时在写、构建读到中间态；更正时两个道都点到名。
4. 「我核过」不等于机器核过：「6 个文件 BOM 逐个核过」被 bom-guard 证伪；自写扫描脚本报「0 处
   嵌套注释」是脚本自身 bug 的假绿。结论必须附可复跑的命令与退出码。

同族第二条是「**注释与文档必须陈述事实，而不是意图**」：ui_data_maint_ready() 的头注释写着「页面用
它决定这页能不能操作」，而页面从没用过它（全仓零消费者）。它解释了为什么假接口能活过一整轮评审：
**评审读意图陈述，门禁读可达路径，两者都不反驳「意图未实现」**。写法要求与机器兜底的分界也写清了：
死代码有 bsp-err 的 consume-result 与覆盖率总闸兜，**意图陈述没有任何钩子能证伪**，只能靠写的人，
所以才必须落在文档里。

自查：check_doc_links.py --all exit 0（186 个文档）、本篇 --sections-strict exit 0（新增引用全部写成
可校验形式）；check_ids.py --strict exit 0，不可判定绝对数 1162 **未变**（本笔没吃余量、没新增编号）；
字节卫生 bom=false / CRLF=0 / U+FFFD=0 / 结尾换行齐，新增行最长 79 字符。

看板：本笔收口 task-35。其余任务仍在五条道手上，我只暂存本篇。
 2026-10-27 02:06:14 +08:00
wandering1 41c277a8ae docs(门禁): 抢跑等价门禁自查表落地——把「谁漏跑一次，这道检查这次就不存在」写死 
今天三次 --no-verify 共放过三类真问题：5 条 CODE-RULE-17（.c/.h 配对）、2 个缺尾换行加
1 个漏提文件（HEAD 一度是「代码已整行独占、旁边 runner 文档串还写着无锁直发」）、
以及共享尾段 +80 B 把 iec104Task 压到 1,024 B ISR 底线之下。根因不是「不该抢跑」，
而是**抢跑时只跑了部分等价门禁**——doc-links、id-check、字节卫生都跑了，唯独漏了
stack_report，而它恰恰是数字与安全边界那一类。

§2.4 三组清单（任何人可用，不是 Lead 特权说明）：A 抢跑前必跑（stack_report、
ram_report、ram_baseline --gate 含「跳过不等于有余量」、coding-standard、bom-drift
含「别用有 BOM 就是错的外行判据」、mojibake、受影响模块单测、test-coverage、id-check、
doc-links、generated-fresh 必须 .venv、ci_local 并注明它**不含** stack_report 与
ram_baseline 所以不能当替身）；B 手跑代替不了真提交的三类（改写型钩子、要靠 stash
才能正确归因的、只有真提交才碰到的 gitlint 与正文每行 80 列）；C 抢跑之后：
git show --stat 对交付清单 + git status 里不该再出现声明过的文件（含 ??，漏提 runner
就是这么发现的），并强制在正文点名「哪些没跑、为什么、谁在飞」。

一条结构性说明：stack_report 与 ram_baseline **不在钩子清单里**，所以「人漏跑一次 =
这道检查这次不存在」；要机械化得先解决「磁盘 .htm/.map 属于最后一次构建的那个人」
——与 stash 覆盖面那条同源，不是加一根钩子就完事。另写明 --all-files **也不 stash**，
会让改写型钩子当场改全库，只能在静默窗口跑、跑完复核。

文档里的命令必须能直接跑：只读等价那条一行式刻意纯 ASCII——Windows PowerShell 5.1 按
ANSI 读无 BOM 的 .ps1，带中文标签的版本会碎成 SyntaxError（作者踩过并复现），改完后
从文档里抽出来重跑验证：checked 40 files (incl untracked)，problems 0。

同篇顺手核掉的同源不同源（可单独回滚）：§6 钩子数 40 → 50（口径 = YAML 解析条目；
直接 grep 声明行会多算一条被注释掉的候选 = 51）、主机侧单测「16 个合一篇」→ 22 根
专属钩子 + 18 套走 test-coverage 总闸；两处跨行断行的表格行修好，全文 8 个表格块
列数一致（脚本核过）。generated-fresh.md §4 补上解释器解析口径与 [ENV] 输出。
 2026-10-26 23:42:41 +08:00
wandering1 0f7b5a87fb chore(编号): 存量编号全量转语义短语，门禁识别面与语料同批重打 
登记簿、文档与代码注释里的存量字母加数字编号（N-x / S-x / T-x / E-x / A-x / 卡号）
一律改写为语义短语，净删 2,028 处引用；删除基线与待确认、并行分道方案、排期详述、
采集保护收尾 4 篇（内容已并入 docs/任务规划/README 与登记簿）。

门禁机器与三张账同批重打：check_ids.py 新增变更记录行豁免与第二根护栏
undecidable_total_ceiling；check_test_traceability.py 只加 stdout/stderr UTF-8
reconfigure（TC_RE 未动）；check_cubemx_survival.py 的 --write 固定 newline=LF；
id_registry / id_aliases（+19 条 retired-to-phrase）/ id_known_backlog 重打。

test/ 56 个文件同步 TC 标签语义化，其中 18 个 TU 改了 CHECK / printf 里的标签文字，
是本批唯一改变构建产物的文件集合。

为什么合成一笔、不拆四笔（实测撞闸，非偏好）：pre-commit 跑钩子前会 stash 未 staged
部分，拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、
不可判定 1,453 > 上限 1,166，编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。

实跑基线（工作区全量）：754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01%
（基线 86.0%，容差 0.1pp）/ 不可判定绝对数 1,151（上限 1,166）/ 校验 1-6 错误级 0 /
告警 = 悬空 2（App/algo/freq.c 的 S2，属 §4.4 同号不同义）+ 孤儿 50。

基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6：本批真删了 2,028 处
引用，可判定面随真实内容上升，不是把分母做小。同批新增排除 docs/硬件平台/ 语料，使
识别面少 264 处——芯片手册位号与网表料号不属编号空间（registry 有 excluded_paths_note）。

⚠ 余量只剩 0.11pp（约 10 处）与绝对数 15 处：把「可判定的引用」改成散文会立刻撞第二
根护栏。另遗留一项：id_aliases 里 retired 的 N / S / T / A 别名没有 scope（U1~U5 有），
今后有人新写一个 A-4，校验 3 不会响，只能靠人，建议下批补 scope。

固件不变证据：115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等，残留代码差异 0；
App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告；40/40 主机套件、2,889
断言全通过；覆盖率 line 89.2% / func 92.6%；pre-commit 48 钩子 --all-files 全绿；
check_doc_links --all 通过（176 文档，章节引用无法判定 0）；逐字节卫生核过：14 个带
BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD，字符串字面量纯 ASCII。

.cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法：
Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写，代码未变。

同批带上体积同码凭证与 RAM 台账行（@build 之后盖戳）：RW_IRAM1 79,008 B / 60.3%，
RW_CCM 57,376 B / 87.9%，阈值 92%。
 2026-10-26 12:28:14 +08:00
wandering1 4ac869058d ci(gates): 自触发已生效；纠正我自己误读提交输出得到的两条假结论 
先说结论：**触发面含门禁自身是生效的**。只改 .pre-commit-config.yaml 的两个提交
（e327636、c4ca292）里 test-coverage 都实跑并 Passed（约 45 s、28 套），bsp-err 同样
实跑。上一提交写下的"改 files: 那次由旧配置管辖"是**我误读输出得到的假结论**，
已按事实改写；那条猜测当时被当成"实测语义"写进配置注释，正是本仓反复防的问题，
所以这一批先降级为"待证"、再判定、再落事实。

误读的机制（值得留档，因为它会让人系统性看错门禁状态）：钩子没声明 stages: 就
默认属于**所有阶段**，于是同一次提交的输出里每根钩子出现两次——pre-commit 阶段
那一遍才可能实跑；commit-msg 阶段那一遍拿到的"文件"是提交信息文件，跟这些钩子的
files: 都不匹配，几乎必然 (no files to check)Skipped。我前几次都只 tail 了输出结尾，
看到的就是第二遍，于是连着误判了两次（第一次判成"自触发没生效"，第二次为了自洽
又编出"旧配置管辖"这条规则）。同一批里 bsp-err 的表现也是同一成因。

判据写成一句话：**看某根钩子跑没跑，认它第一次出现的那行**，别读尾巴。已同时补到
pre-commit使用说明 §2.2 的通用机制表里（新增一行），配置注释里也留了实跑证据的提交号。

自查：本提交只改配置与一份机制文档（无代码改动，未跑 @build）；提交自身会触发
test-coverage 实跑一遍作为回归；doc-links 与 id-check 见下条。未 push。
 2026-10-24 08:18:45 +08:00
wandering1 744a1cb086 ci(gates): 接线 test-coverage 覆盖率总闸（FAIL 语义），并修三处已成假话的门禁文档 
用户裁定 2026-10-24：缺 mscoverage 组件时**失败**，不做 skip。于是 P1 之后那个
"钩子只挂 16/28 套"的缺口关闭了。

为什么挂这一根而不是补 12 根 per-module 钩子：本闸跑**全部 28 套**，并且守
"已覆盖行只增不减"的基线台账。这是 per-module 钩子结构性做不到的——删掉一套
测试，它那根钩子只会因为"没有文件要检查"而静默跳过（Skipped 不等于失败）。
实测接线代价：45 s（28 套，含 28 次 MSVC 编译与插桩运行）。

FAIL 语义已按本仓"合成自证"的纪律验证（不是只测绿的那一半）：把
DTU_MS_COVERAGE 指到一个不存在的文件 → 钩子 Failed、脚本退出码 2、并打印可
执行的 [ENV] 提示（说明该 exe 装在哪、怎么覆盖）。脚本对显式环境变量刻意
"不做自动探测回退"，所以指错会被点名，而不是悄悄换一份工具跑出另一本账。

顺手修掉三条**现在已经不成立**的文档说法（门禁文档最贵的就是骗人）：
- 口径 §7 第 8 条：原写"只有 BuildTools 且没勾代码覆盖率工具的机器会退出码 2"。
  实测本机 Community 18.10 与 BuildTools 18.9 **两份安装都自带**该 exe（mtime
  2026-09-15 02:30 / 2026-09-05 16:17，都是各自安装当日，不是后来补勾）→ VS 18
  的 BuildTools 默认就带它。真实风险面只剩：裸 MSVC 无 VS 的机器、环境变量指错、
  以及靠 PATH 兜底的环境。
- 门禁说明 host-unit-tests.md 盲区第 4 条：原写"没有对应钩子的模块 = 零回归"——
  如今 12 套新模块由总闸兜住，这句话已经不成立，改成两种口径并写清触发面。
- 同篇第 6 条：原写"无覆盖率统计"。行/函数覆盖**已有**度量（本闸出 Cobertura 并
  守基线），仍无的只是分支覆盖——那是用户裁定 2026-10-23 记下的**已接受缺口**，
  不是待办，改口时把这个区分写清楚。

钩子计数同步（新增 1 根 → 声明 40 根 / pre-commit 阶段 39 根 + commit-msg 的
gitlint，已用脚本核对，不是手数）：AGENTS.md（总数、枚举、索引表）、
pre-commit使用说明.md（66 / 91 / 234 三处，含清点日期）、门禁说明 README
（正文与索引标题，另加一行索引指向口径文档——23 篇不变，同一事实不在两处维护）、
门禁说明 gitlint.md（--no-verify 跳过的"其它 38 个"→39）、并行任务工作树方案。

自查：end-of-file-fixer 与 trailing-whitespace 复跑 Passed（首轮 --all-files 只
因末行空行红过一次，已按钩子自身规范化）；doc-links --all --sections-strict 通过
（178 个文档）；id-check --strict 零台账外新账；8 个改动文件 U+FFFD = 0、无 CRLF。
零代码改动，故未跑 @build。未 push。
 2026-10-24 07:50:53 +08:00
wandering1 6505cef9df feat(门禁): coding-standard 加 CODE-RULE-20 禁 C 库堆分配（销 §4.8 空白 ②） 
规则：在**掩码后**的文本上匹配 malloc/calloc/realloc/strdup/strndup/
free/aligned_alloc 调用。三条判据都是踩过坑之后定的——
- 大小写敏感：pvPortMalloc / vPortFree（唯一允许的配对）不会误报；
- 词边界 \b：dhara_nand_is_free(、buf_alloc( 这类同形后缀不误报；
- 用掩码：注释与字符串字面量里写 malloc 不报（规范示例就踩过这种）。
覆盖名比 AGENTS 列的五枚多带上 strndup / aligned_alloc——同族同类，
漏一个就等于留后门。

出处不在规范 V1.0，在平台约束：MicroLIB 的 C 堆由 startup_stm32f407xx.s
的 Heap_Size EQU 0x200 只有 512 B，KB 级分配必返 NULL，而模拟器（宿主
CRT 堆）完全正常、**照不出来**——配置引擎 2026-09-18 那次堆分配纠偏与
lftpd 的 malloc 隐患都是**先上线才发现**的那类，靠评审等于没管。

落地前按 门禁说明/coding-standard.md §8 的纪律先全库普查：钩子范围内
C/H 共 151 个文件，命中**只有** simulator/sim/cfg_file_store_sim.c 两行，
即 cfg_store_alloc/cfg_store_free = **平台分配后端的宿主侧实现**（设计依据
写在 docs/子系统设计/配置文件设计说明.md 的"MCU 端 = pvPortMalloc、
模拟器端 = 宿主 CRT"）。所以零基线、直接硬拦截；豁免用脚本里的
HEAP_ALLOC_ALLOWLIST（**文件路径 + 函数名**双条件），刻意不做目录级豁免：
下次谁要碰 C 堆就得往这张表加一行，评审看得见。

自证：临时样例文件里 malloc/calloc/free 各报一处，pvPortMalloc/vPortFree/
buf_alloc(、注释、字符串五种陷阱形态全部不误报；
pre-commit run coding-standard --all-files → **Passed**（= 全库零存量）。

顺带修三处口径不一致：
- 规范 V1.0 §6.1 的示例自己写着 malloc/free（通用 C 模板遗留）→ 已在示例
  下加"本仓例外，别照抄"批注，事实源指向 AGENTS.md 平台约束；
- docs/门禁说明/mem-budget.md 里"这条纪律只靠 AGENTS 铁律与评审"已过期 →
  更正为由 CODE-RULE-20 机器拦截；
- AGENTS.md 平台约束条加"已机器拦截 + 唯一豁免"一句；scripts/README.md
  补登 check_test_coverage.py（上一个提交漏登记）。

另：本次一并修好上一处编辑事故——报告 §4.8 曾被我的脚本调用截成半句
（只落第一行、丢掉 malloc 那半句），已重写为"两处空白均已闭合"。

自查：pre-commit run --files（9 个改动文件）适用项全 Passed；
check_doc_links.py --all = 35 处，与主干同数（本分支贡献 0）；
check_ids.py --strict 通过（裸编号 P0-1 改平实说法，避免记成新账）；
9 个文件 BOM/CR/U+FFFD/行尾与 HEAD 逐项一致。本轮零 .c/.h 改动，未跑
@build、未占 build/bench 锁；分支已 rebase 到 v2-on-ui，覆盖率脚本全量
回归仍 16/16、line=2552/2893 不变。
 2026-10-23 23:44:46 +08:00
wandering1 6822726b2c docs(门禁说明): 手册 §2 收敛为通用机制与查号表，逐项详解归一到 23 篇 
用户一句"现在门禁都在干什么，我一概不知"引出的收尾。原手册 §2 有 27 个逐钩子小节，只回答
"拦了什么、怎么配"，回答不了"什么时候会骗我"；docs/门禁说明/ 已把逐项详解（含"限制与盲区"
一节）建好，本笔做收敛：同一事实只留一处（docs/文档规范.md 的要求）。

**先搬后删**（否则收敛等于丢事实）：旧 §2 里独有条目逐篇折回，共 18 处插入、15 篇受益。折回的
东西包括：六套主机单测的来历与用例规模（13/36/82/46/32/149 断言，含 nand-port 的"与旧算法
对照"）与"改动公共骨架 unit_test_harness.py 会同时触发 16 个钩子"；UI 页面**两层注册**（构建
注册 vs 框架注册：枚举 + s_defs[] 描述符表）与"豁免不整目录一刀切"；lv-conf-sync 首次落地清掉
26 个 LVGL 9.3 不存在的选项、3 处重复定义、10 项隐式开关显式化，以及 ALLOW_DIFF 端专属白名单
与必须穿过 lv_conf_internal.h 里那层 KCONFIG 包裹；cubemx-survival 的 16 项清单、断言前先剥
C 注释（本仓注释刻意引用历史代码，不剥就恒定误报）、旧手册"自造标记区"建议与看门狗文档实测
教训之间的优先级；id-check 顺带收编 check_test_traceability.py、裸形同字母多义属**显式承认的
盲区**、--update-baseline 只许涨；layer-deps 的注入自证与报错时三条修法（注入回调 / 上层递数据
/ 才谈 ALLOW）；coding-standard **nand_ftl.* 也在排除清单**（我先前那篇漏了）；test-suite-switch
的剥注释判定与派生宏白名单；mem-budget 两类软提醒不拦、退出码 2 是解析失败不是通过；doc-links
的排除目录与状态词 ±40 字符距离；task-table 改栈三步；gitlint 报错样例；no-mojibake 的修复路径。

**顺带抓到旧文档两处错**（记进文档，不悄悄改）：一是 check-added-large-files 的阈值旧手册写
"单个文件 > 1MB"，按本机安装的钩子源码实测是 --maxkb 默认 **500**（500 KB）——已更正，并把
"本目录任何默认值都以实测或安装的钩子源码为准"写进 end-of-file-fixer 当反面教材；二是
**ui-golden 在旧手册里连小节都没有**，只活在配置注释里：除了"有基线不等于有门禁"，这是另一种
失踪——有钩子、没文档。

手册 §2 改写为三节：迁移说明 / **旧编号 → 新文档 查号表**（历史引用靠它读，旧号按"冻结历史不
回改"保留）/ **跨钩子通用机制**：两阶段与换机必须重装 hooks 才带 commit-msg、stash 陷阱、
always: true 已废、改写型与只读型豁免不对称、增量拦截三段式且刻意没有 --write、没有 .map 是
"跳过"不是"通过"、改配置的验收是看目标钩子出现在输出里且不是 Skipped、新增门禁三步必须做
注入自证且"限制与盲区"不许留空，另有快速自查入口。手册 707 行 → 273 行。

引用**按内容**重指（只核编号存在与否不够，同号小节会被当本文自引用静默放过）：编号规范、
scripts/README（顺带更正那里过时的 warn-only 说法，早已关闸为增量拦截）、RAM 使用分析与优化
方案、测试开发标准流程、lvgl-simulator skill、AGENTS 文档表（拆成"每门禁一篇详解"与"通用
机制"两行）、.pre-commit-config.yaml 头注释、docs/README.md 描述、手册自身 §5.5 与 §6 的两处
内部引用。另：表格里的裸节号会被 doc-links 判成本文自引用，查号表统一写成不带 § 的形态。

写说明过程又被自家门禁拦一次：gitlint 篇里引用报错样例时写了两个规则号字面量，被判形态不合规
→ 改成中文描述，没有往台账里塞 reason 解决。

验证：纯文档与注释改动，不动代码，Program Size 不变，故不跑 @build/@test；
check_doc_links --all --sections-strict **171 篇 0 问题**；id-check 增量拦截通过；
pre-commit run **RC=0 / 13 项 Passed**；28 个改动文件字节卫生 **0 异常**（无 BOM、无 CR、
无 U+FFFD、均 LF、无行尾空白）。
 2026-10-23 11:44:21 +08:00
wandering1 dc44c1e54e docs(门禁说明): 补齐 23 篇逐项门禁文档，每种门禁一篇含限制与盲区 
用户诉求原话："现在门禁都在干什么，我一概不知。" 原有文档回答"有哪些钩子、怎么配"，回答不了
"这一条到底在拦什么、什么时候会骗我"。本目录按**每种门禁一篇**补齐 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、均有尾换行）。
 2026-10-23 10:54:33 +08:00
wandering1 2575177e81 refactor(gate): bsp-err 四项检查改用自描述标签，废掉 R1~R4 这组撞车代号 
纯改名，检查行为一个字没动：规则逻辑、阈值、豁免形状全部原样。

改名原因（用户一句「R4 到底是什么」问出来的）：R1~R4 是我在 check_bsp_err.py 注释里
自造的序号，而这个裸形在本仓另有含义——R1~R8 已在 scripts/id_registry.json 登记为
"专项风险"的文档内编号（保护规划与看门狗的风险表都在用），带连字符的那一族又是审查
报告的可靠性 / 内存优化项编号（编号规范 §1 的"连字符承载语义"一行正是这么写的）。
**同一个裸形四种意思**。最刺人的一点：编号门禁**不会报**这种撞法，因为编号规范 §4.3
已把这些裸形声明为"同号不同义"、走 collides_with 白名单，校验 4 不计事故——同一天里
我起的另一组自造号被当场拦下、这组代号却一路绿灯，差别不在我做对了什么，而在白名单
挡的是"事故"、不是"可读性"。

新名同时是基线键的第二字段（格式 文件|标签|名字）：
· err-type        错误通道不外泄（对外接口不拿 HAL_StatusTypeDef / bool 当成败）
· timeout-name    超时宏不取负值
· return-doc      公开函数必须写「返回值：」
· consume-result  返回值不得裸丢弃（须接住或显式 (void)）
老名对照：R1=err-type、R2=timeout-name、R3=return-doc、R4=consume-result。

同步面：脚本里的规则码与 38 条基线键的字段**一起换**（中途不跑 --prune，否则改名会被
读成"38 条全还清 + 38 条新账"），换完 --emit-baseline 复核仍是 38/38/0、RC=0。现状类
文本全部换新名：AGENTS.md、pre-commit使用说明.md §2.27（新增"检查项叫什么"一行含老新
对照与撞号说明）、bsp_err.h 边界纪律、报告 §0.4 / §9 / 附录 A，以及代码注释里的 5 处
（gd5f2gq5ue.c/.h、nand_ftl.h、ui_menu_tab.h）。已提交的变更记录行里的老名按"冻结历史
不回改"处理，以 §2.27 对照行为准。ui_menu_tab.h 带 BOM，Edit 又剥掉、已按原样补回。

写说明文字时又被编号门禁拦了一次：我为了举例"老名撞车"，在那段话里写了两个编号字面，
被判"未紧邻文档名 / 未登记前缀"共 3 类新账——连批评自造编号的段落本身都在自造编号。
改法是不写号、只描述形态并指向权威条目。

验证：@build **0 错 0 警告**，Program Size 与上一笔**逐字段相同**（Code 213,676、RO
18,860、RW 1,188、ZI 131,500）→ 证明确为注释与文案，故不跑 @test（无指令变化）；
pre-commit run 全绿 **17 项 Passed**；check_doc_links --all --sections-strict 147
  篇 0
问题（中途我自己写的 §4.3 没紧邻文档名，被判成本文自引用，已补全路径）；9 个文件字节
卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、均有尾换行）。
 2026-10-23 09:36:01 +08:00
wandering1 d9b887c0af feat(S-5 R4): 返回值不得裸丢弃成为机械检查，并修掉照出的第一处 ECC 静默降级 
B 的第一步（加规则）与第二步（修最小最值的那处）。用户裁定"B 按你说的进行"。

**为什么只能项目侧自己做**（两条实测负结果，已写进 §2.27 与 bsp_err.h 边界纪律 4）：
· ARMCC v5 对 __attribute__((warn_unused_result)) 不生效（凌晨在 rs485_transmit 上实测：属性
  在位、调用点裸调不接返回值，构建仍 0 错 0 警告）；
· cppcheck 也照不出来——按本仓自己的 --enable=warning,style,performance,portability 跑
  gd5f2gq5ue.c，对 14 处丢弃 HAL_SPI_* 返回值、以及"未初始化局部量直接进 P_FAIL 判定"
  **一条不报**（它假定 gd5f_read_status(&status) 会写出参，而失败路径根本不写）。
结论：**丢弃底层传输的返回值，今天没有任何工具会响**。

**R4 上线即照出 37 条存量丢弃**：gd5f2gq5ue.c 29（14 处 HAL + 15 处自家原语）、net_socket.c 8、
ui_net_sink.c 4（net_close）、rs485.c 2、nand_ftl.c 1。按增量拦截老规矩入基线、只减不增——
这是覆盖面扩大新暴露的历史债，不是新增违规；基线 19 → 1 → **38**。

**R4 自己被修三次（逐条记下，都是"规则比我想的更脆"）**：
① 首版漏判"裸调用行尾带注释"这种写法（正则的 \s*$ 卡死），而那恰是最常见的"带说明的丢弃"
   → 补可选注释分支，并做 6 条正/反例自检；
② 把 net_set_errno 八处误判成丢弃（它是 setter，返回 int 是状态回声不是调用成败）→ **按真实
   反例把规则收窄**（谓词 + setter 两类豁免），而不是塞进基线洗掉假阳性；
③ must-use 名单只从**头文件**取，gd5f_set_feature 这类 static 原语整个在视野外——而下面那处
   真窟窿恰恰是 static、靠人工才发现 → 名单扩到 .c 内 static 定义（同一套启发式），补完立刻
   又照出 gd5f_bbt_save#1：**运行时标坏后 BBT 落盘结果被丢弃 = 坏块记账可能没持久化**，已入
   基线记为待还，本步不动行为。
另修一处自己的排版误判：R3 原本要求注释块出现字面"返回值"，规范 V1.0 允许列对齐写法
「返 回 值：」→ 改为忽略空格匹配（门禁不该规定排版）。

**修掉的第一处真窟窿**：bbt_rebuild 的注释写着"无论扫描成败都须恢复 ECC，否则后续 I/O 在无
ECC 下运行"，而它下面 gd5f_set_feature(0xB0,…) + gd5f_wait_busy(100) **返回值全丢**：SPI 一抖
ECC 就保持关闭，且 gd5f_check_ecc() 在 ECC 关闭时恒读"无 ECC 错"——整条链再没有任何信号。
补法复用 init 路径的 E-10（写完回读 B0h 验 ECC_EN 位真生效，"写了但没生效"与写失败同罪），
并把"关 ECC 失败"改成**立即中止**（此时 ECC 仍开着，是安全侧；带着 ECC 去扫 spare 反而会把
厂标好块误判成坏块，"重建 BBT"变成制造坏块）。恢复失败时按 (void)gd5f_bbt_load() 回读盘上
副本，避免 RAM 留着"比盘上更新"的表而下次上电又退回旧表。

**一条定位纠正（差点把修复记大）**：查链接映射发现 Removing gd5f2gq5ue.o
(i.gd5f2gq5ue_bbt_rebuild), (604 bytes)——该函数在产品镜像里**根本没被链接**（产品构建无调用
者），只由 ENABLE_STORAGE_RECOVERY_TESTS 的恢复构建经 testTask 调用。所以本次修的是**恢复流程
自身的安全**（跑恢复时若 ECC 没恢复，设备会带着"已恢复"的结论在无保护状态下继续跑），不是
现场日常路径；相应地镜像 Code 的 +28 B 也不是它带来的（未逐字节追，线索是
gd5f_private_get_feature 由单调用点变多调用点、内联决策可能变化）。验证因此不能只跑产品构建：
临时打开 TEST_SUITE_STORAGE + ENABLE_STORAGE_RECOVERY_TESTS 编一次（0 错 0 警告且该函数不再
出现在 Removing 列表），随即还原两处开关并重编产品构建核对（test/board 无残留差异）。

**编号门禁把我自己的自造编号拦下了**：我起初用 B-1/B2/B3/B4 标记这批缺陷，id-check 报"未登记
前缀"13 处（且 B2/B3/B4 会与真实里程碑号撞号）→ 全部改写成平实语言。这是那条"注释与文档里
不许用没人检索得到的内部阶段编号"的规则第一次在提交前拦住我，规则是对的。

验证：@build 0 错 0 警告，Code 213,648 → **213,676**、RO 18,860、ER_IROM1 **232,536 B
  / 22.2%**
（ROM 合计 233,724 B；RAM 逐字段不变）；ram_report 重生成 + ram_baseline.py --update + 配图常量
同步（mem-numbers Passed）；@test **PASS**（到 net init: OK 682 ms、[ERR] 0）；R4 两处**探针
实证**（临时加一条裸调用 → 立刻成为新增并 RC=1；还原 → 38/38/0）；--prune 点名本次还掉的 2 条
已删；pre-commit run 全绿 15 Passed；check_doc_links --all --sections-strict 147 篇
  0 问题；
id-check --strict 增量拦截通过。

文档：AGENTS.md 与 .pre-commit-config.yaml 的 bsp-err 口径（四条规则、基线 38）；
pre-commit使用说明.md §2.27（R4 全量口径 + 两条负结果 + 名单来源与豁免形状 + 单行限度）；
bsp_err.h 边界纪律 4；报告 §0.4 / §5.1 / §9 / 附录 A + 变更记录；存储维护与容量恢复.md 新增
§4.3（运维判据：出现 ECC restore FAILED / ECC not enabled 即本次恢复**不算完成**，须断电重启
重走 init，不许接着 nand_ftl_format() 当作已修好；并记明该函数产品镜像不链接）——顺带修该文
结构缺陷：原 ## 5. 变更记录 误插在 §4.1 与 §4.2 之间，会让 §4.2 变成 §5 的子节。
 2026-10-23 09:15:41 +08:00
wandering1 cc2966319a docs(S-5): 补齐 16 条返回值约定，bsp-err 基线 19 → 1，并修门禁自身误判 
A（还债）先行，B（GD5F 的 SPI 失败被吞成成功）另波处理。本笔不改行为：@build 的
Program Size 与上一笔逐字段相同（Code 213,648、RO 18,860、RW 1,188、ZI 131,500）。

**补齐 16 条「返回值：」约定，bsp-err 存量基线 19 → 1**：
· gd5f2gq5ue.h 九个 SPI 原语（wait_busy / write_enable / read_status / page_read /
  read_from_cache / program_load / program_exec / block_erase / check_ecc）
  写全规范五要素，
  并把**每个函数能返回哪些码**写死：哪一个是"可重试"的 GD5F_WAIT_EXPIRED、哪一个才是
  器件自认坏块的 P_FAIL/E_FAIL、失败时出参为什么不可信（E-42 同族）。
· nand_ftl.h 从零散三行补成带模块头，并明写 **nand_ftl_init() 的 −1 抹掉了失败类**：
  分类目前只在失败点进日志，要按类分支需要 C4 快照（现无消费者故未做）；同时警告"不得
  把 −1 解读成卷坏了可以重格式化"（E-31 的教训正在这条上）。
· ui_menu_tab.h 五个表查询 API 由行尾短注释升级为完整块（含"越界返回 false 是保守取
  只读"、"宁可按一张错表导航失败也不要按错表导航成功"这类判断依据）。

**修掉门禁自己的一条误判口径**（本笔最该记的）：R3 原本要求紧邻注释块里出现字面"返回值"，
而规范 V1.0 允许列对齐写法「返 回 值：」。后果有两层：① 合规写法被判违规；② 反向更糟——
gd5f_write_enable / gd5f_read_status 两条**早就"通过"了**，原因竟是它们的**函数说明**里顺口
写了"返回值"三个字，而不是真有一行返回值说明。**一条会因为散文里出现关键词而放行的规则，
等于在奖励运气**。修法是在块内忽略空格后再匹配关键词（排版选择不是违规），并在注释里写明
为什么不许把"必须写成不空格的形式"写进规则。

剩余 1 条刻意保留：bool ui_content_page_open()。它与"补注释"不是一档事——要改签名、要处理
3 个调用点（ui_menu.c:138/192/196 **今天三处全部丢弃返回值**，即"按 ENTER 开页失败是静默的"
这件事现在没人知道）、且 UI 源码双端编译（模拟器同一份），验证面是"重建模拟器 + 像素回归 +
真机逐页进菜单"。这不是还债，是独立一波改动，留档待决策。UI 三个文件带 BOM，Edit 会静默
剥掉 → 已按原样补回 3 字节（AGENTS 铁律：丢 BOM 后 ARMCC 按 CP936 解码，中文报 #870-D）。

**更正我自己写进文档的一条错话**：S-5 各条里我把 GD5F_SPI_TIMEOUT 100 记成"自旋圈数（改
分频时长会变）"。这次逐行核它 12 处用法，**全部是 HAL_* 超时参数或 HAL_GetTick() 差值 →
它也是毫秒**。真问题降级为"单位没写进名字（缺 _MS 后缀），读代码必须回实现里查单位"。
osWaitForever 与 HAL_MAX_DELAY 同为 0xFFFFFFFFU、以及 *_BUSY_TIMEOUT = -2 其实是返回码这两条
仍然成立（后者已改）。现状类条目（报告 §0.4、bsp_err.h、pre-commit使用说明.md §2.27、脚本
文件头）已全部改准；**已提交的变更记录行仍写着旧说法——按 §8.1 冻结历史不回改，以本笔新增
的更正行为准**。

验证：@build 0 错 0 警告（尺寸同上，故**不跑 @test**——无指令变化，跑它没有新信息）；受影响
文件的 17 个钩子全 Passed（含 ui-golden 像素回归、cppcheck、编码规范、bsp-err 1/1/0 且
--prune 干净）；check_doc_links --all --sections-strict 147 篇 0 问题；id-check
  --strict 通过；
9 个文件字节卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、无行尾空格、均有尾换行）。
口径同步：AGENTS.md、.pre-commit-config.yaml、pre-commit使用说明.md §2.27 的基线计数 19 → 1；
报告 §0.4 / §9 / 附录 A 与变更记录两条（还债一条、更正一条）。
 2026-10-23 08:25:58 +08:00
wandering1 78248a1cdf feat(S-5): 收编 SD2506/TPAFE 并给 dhara 失败分类，门禁基线 19→17 
前一笔立契约与门禁（`Drivers/BSP/bsp_err.h` + `bsp-err` 钩子 + RS485 试点）；这一笔按用户
指定顺序 C3 → C1 → C2 把三个模块真正收编，并让存储失败第一次变得可读、可分类。

**C3 · SD2506 整模块（11 个公共 API + 6 个内部 helper）**：三枚私有宏 `SD2506_OK`/
`SD2506_ERROR`/`SD2506_I2C_ERROR` **删除而不是留别名**——留别名等于新代码还能用旧形状，
把迁移洗掉；编译器替我们找全所有调用点。新增 `sd2506_err_from_hal()`，**把 I2C 超时从
"和没人应答共用一个 −2"里拆出来归成 `BSP_ERR_TIMEOUT`（可重试）**——SD2506 是启动链第一站、
I2C1 上电时序敏感，这是本波唯一真正的语义改善，不是改名。`sd2506_init` 的 charge 寄存器
**回读校验不符**原返参数类错误，改归 `BSP_ERR_IO`（那不是调用方的错）。

**C1 · 同形两义**：`GD5F_BUSY_TIMEOUT` → `GD5F_WAIT_EXPIRED`（**值 −2 不变**，纯消"名字叫
TIMEOUT 其实是返回码"）。**GD5F 私有码集整体收编刻意没做**：169 处引用里 48 处在板级套件、
还要动 Trap 记录用词，属另一波带真机+套件回归的工作，不夹带。TPAFE5160 收编 23 处：
`BUSY_TIMEOUT → BSP_ERR_TIMEOUT`、`ERROR → BSP_ERR_PARAM`（**同值 −1，行为零变化**）、
`FRSTDATA_ERR → BSP_ERR_NO_DEVICE`（E-44 的本义就是"芯片没驱动 DB 总线"，归到器件无响应比
私有 −3 有用，且避开与 `BSP_ERR_TIMEOUT` 撞值）。实测 `tpafe5160.o`/`gd5f2gq5ue.o` 的 Code
增量为 **0**——改名不产生一条指令。

⚠ **`tpafe5160_snapshot()` 刻意不套成败码**：它是 1=有新帧 / 0=无新帧 / −1=参数错 的三态
**状态**返回，0 不是错误而是"这一拍没有新数据"，强行收编会把慢消费者的正常路径变成失败。
顺带订正我上一版在 `bsp_err.h` 的断言——"本层只有 `net_*` 把数量与错误挤同一返回值"是错的，
`snapshot`/`adc_input_poll` 就是第二族；两族现都已写明并各注保留理由。

**C2 · FTL 坍缩点分类**：`ftl_flush_cache`/`ftl_read_page` 不再把 dhara 失败压成
  `GD5F_ERROR`，
按**处置差异**分三类，并在最早同时知道 LPN 与原始码的位置就地打印：`ECC`/`TOO_BAD` →
`BSP_ERR_CRC`（页级，重试或换页，不代表卷坏）；`JOURNAL_FULL`/`MAP_FULL` →
`BSP_ERR_NO_SPACE`（介质健康但块池/日志见底，此时重格式化只是把问题推回去）；
`BAD_BLOCK`/`RECOVER`/`CORRUPT_MAP`/越界 → `BSP_ERR_IO`（完整性故障，保卷 + 上报，不许自愈
重格式化）。这与 **E-31** 是同一条纪律的两端。可读名用自建短表：**本仓 dhara 没有编
`error.c`，用 `dhara_strerror()` 会直接链接失败**。`disk_read`/`disk_write` 仍回
  `RES_ERROR`
（FatFs 契约）；要让 defaultTask 卷健康探针按类分支还差跨调用存活的快照 → C4 待还。

**两次靠核实拦住的自我错误**：① 我一度认定 `DBG_ERROR("... err=%d", err)` 是把结构体塞进
varargs 的格式 bug——核 `Lib/dhara/error.h` 后确认 `dhara_error_t` 是 `enum`（标量），那行日志
本来合法，改了反而是引入错误；② `bsp-err` 一次 `replace_all` 越界把 8 处 **GD5F 码空间**的
判据改成 `!= BSP_OK`（数值同为 0、无行为变化），但那正是"把两个码空间混起来"，已逐一还原。
`cppcheck` 亦抓到 `cls` 声明作用域过宽，已收进失败分支。

**验证**：`@build` 0 错 0 警告（`Code` 213,648、RO 18,860、`ER_IROM1` 232,508 B /
  22.2%、
`ROM 合计` 233,696；**RAM 三项零增量**）；`@test` PASS（692 ms，烧入戳 `Oct 23 01:35:32`）
且逐条读到被改模块的锚点：`SD2506 init: OK (ret=0)` 与 ID/时间/温度/电池四条读回正常、
`ADC init: OK`、`NAND init: OK`、`Map resumed: 14094/97504`、`adc=` 帧计数持续递增（证明
snapshot 三态未被改坏）、`[ERR]`/Fault/FAIL 0 条。主机单测：系统时钟 100/100、dhara NAND
移植层 149/149（两者都因本次改动需补 `Drivers/BSP` include 路径，补后在钩子内实跑 Passed）。
`pre-commit run` 全量 RC=0（20 个实跑钩子 Passed）；`bsp-err` 基线 **19 → 17**（还掉两个
`*_BUSY_TIMEOUT = -2`）、`--prune` 干净；`doc-links --all --sections-strict` 147 篇
  0 问题；
`id-check --strict`、`layer-deps`、`mem-numbers`、`mem-budget`、`ui-golden` 全过；33
  个文件
字节卫生 0 异常（无 CR / 无 U+FFFD / 无行尾空格 / 均有尾换行）。

**口径与数字联动**：新增 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.4（三类码与处置
理由）；`pre-commit使用说明.md` §2.27 与 `AGENTS.md` 基线计数 19 → 17；TPAFE README、
GD5F 测试指南与 Trap 记录均**保留旧名留痕**以便对旧日志；配图桶按 .map 对象级增量重算
（`dhara/FTL` 10,931 → 11,222，+291 全部落在 `nand_ftl.o`；应用代码/UI +36 落在
`app_main.o`；其余散量入"其他"7,557；桶和 = Code+RO 断言通过、文本溢出 0）；
`ram_baseline --update/--write`、`ram_report_20261023.md` 快照、报告 §1.3/§5.1/§5.4
  与
部署文档 §3.3 数字全部同步；报告 §0.4/§9 的 S-5 状态改为 🟡 主体已落地。
 2026-10-23 07:42:02 +08:00
wandering1 6ede1443e9 feat(门禁): 新增 layer-deps——BSP 反向 include App 的增量拦截（37→38） 
推荐清单第 5 步的拆分执行：反转依赖（5a）暂缓，**只把"防扩大"的门禁先上**。

**为什么门禁比搬迁值钱**：AGENTS.md 与分层图早就写着"六层单向依赖"，可从来没有
机械检查——于是同一件事的记载从 2026-09 审查报告的"NETCFG 一处"，漂到 2026-10-22
实测的 **8 个文件 9 处**，全靠人读代码才发现。边界的静默腐蚀只能靠门禁止住。

**机制（与 `id-check` 的增量拦截同构）**：`scripts/check_layer_deps.py` 扫
`Drivers/BSP/**.{c,h}` 的 include，按 `App/**` 头文件索引解析反向边（同名头按字面
路径消歧），命中分三类：
· ALLOW 永久豁免 3 条横切叶子头——`App/log/console_log.h`（日志后端，BSP 的
  dbg_log.h 就建在它上面）、`App/util/sys_clock.h`（时间源）、`App/util/sha256.h`
  （纯算法、无状态）。它们是"任何层都要用的叶子能力"，不是上层服务；新增豁免
  必须先回答"它为什么不是上层服务"。
· BASELINE 钉住存量 6 条：`cfg_file.h`×2（NETCFG）、`vol_lock.h`×1（lftpd_io）、
  `sys_log.h`×3（UI 两处 + `ui_w_records.h`）。**只减不增**（脚本没有 `--write`）。
· 新出现的 (BSP 文件, App 头) 组合 → FAIL，并给出三条出路（注入回调 / 上层传参 /
  确属叶子才可豁免）。
`--prune` 在某条存量还清时点名"可从基线删除"，于是"还欠几条"成为可见进度，而不是
文档里的一句口号。

**当场自证**：落地时临时给 `Drivers/BSP/RS485/rs485.c` 加了一行 include `cfg_file.h
`，钩子当场 FAIL 并点名该文件与该头（退出码 1），删掉后转绿——没被触发过的门禁
等于没有门禁。

**边界要说清（免得被误读成缺陷）**：本钩子只拦**静态 include 方向**。运行时的属主
纪律本来就没破——UI 只投递 `net_cfg_save_request()`，真正写盘在 defaultTask，模拟器
也早在主机侧跑整条配置链。

**口径同步**：钩子数 37 → 38 共 6 处（`AGENTS.md` 两处、`pre-commit使用说明.md` 两处
并新增 §2.26 详解、`并行任务工作树方案.md`、报告 §0.1/§1.1）；
`项目架构总览.md` §1 分层原则处补"此方向已机械检查"；报告 §0.4 的 S-1 计数由
"7 文件 15 处"更正为脚本口径的 8 文件 9 处，§9 状态改 🟡。

**暂缓项（都已在报告 §0.4 记因）**：5a 反转依赖——没有功能在等它，且要过"改 IP
免重启生效"整条真机链，留给下次真动 NETCFG/UI 时顺带做；5b 目录搬迁——uvprojx 326
条 + IncludePath + CMakeLists + 42 个 UI 文件 + 全库引用改写，收益只是"目录名好看"，
而远程 CI 仍刻意不跑 `@build`，兜底未成立。

门禁：`layer-deps` 自身通过；`check_doc_links.py --all --sections-strict` 146 文档 0
问题；`check_ids.py --strict` 增量拦截通过、可判定 82.84%；`mem-numbers` 0；
`py_compile` 通过。本轮无 `.c/.h` 改动，未重跑 `@build`。未推送。
 2026-10-22 19:30:02 +08:00
wandering1 43fbfa140b fix(门禁): 批 5 追溯器口径补齐——变更记录行不参与双向比对（未改任何号） 
结论先行：我上一轮说「批 2 模块码单词化漏扫了 4 篇属主文档」——**被证据推翻**

- 依据是 check_test_traceability.py 报的 DOC-ONLY 38 处里有 8 处旧模块码
  （TC-AI-070/080/090、TC-PH-001/030、TC-TS-001、TC-VL-001），我据此写好了
  逐号点名的改名映射表准备落盘
- 改名工具干跑 **0 处命中**：查下去这 8 处**全部在变更记录行**（| 2026-10-10 | … |）里，
  写的是**当年**的用例名；按编号规范 §8.1 冻结历史不回改，旧号靠别名解析——
  而 TC-AI-070 → TC-ADCIN-070 这批**早在批 2 就已登记在 id_aliases.json**
- 所以照原计划改等于**销毁历史记录、收益为零**。真缺口是判据：追溯器是唯一
  没有「变更记录 / [示例] / [计划] 行豁免」的一支（check_ids / rename_ids /
  doc-links 都有），它把冻结历史当活引用 → 系统性假阳性

改了什么（判据，不改数据）
- check_test_traceability.py 加 SKIP_LINE（与另三支脚本同源的豁免正则），两侧采集
  都改为逐行判定，被豁免的号收进 frozen_ids 留痕，--verbose 全量列出——
  **豁免不等于已对应**，别拿它当收敛
- 顺带把 has_intent() 的判定范围从整文件收窄到**同号所在行**（意图必须写在号旁边，
  原先整文件里任何位置有人话就算过关，太松）

实测（关键是"没吞掉真对应"）
- DOC-ONLY 38 → **29**（−9 全是冻结行假阳性，**不是真变好**）；总差异 45 → 36
- **交集 260 → 260 不变**：豁免只吐冻结行，没有让任何一条真实对应消失
- 代码侧 578 个号不变（识别面没缩，这是改名/改判据最容易踩的坑）
- 错误级 632 不变（追溯不参与错误级计数）；可判定比例 83.02%；--strict 通过

剩 29 处是真问题，但**不是编号问题**（要人裁决，不由门禁决定）
- 4 处无模块码形态（TC-1003 / TC-206 / TC-501 / TC-704）：② 大批的文档侧镜像
- TC-NET-607 一条是历史指称（原文「原 TC-NET-607/608/609，现 701/702/703」），
  一对多写不进一对一的别名表
- TC-NET-302/401/402/501 标题明写「（硬件层）」= 人工台架步骤，代码无载体是预期
- 其余 20 处（TC-NET-101/102/1101/601/606/701~704/801/802/901/902/1006/1501~1503、
  TC-GD5F-503）**全库无任何载体**：文档声明了用例而代码/台架/模拟器都没有实现

另一个我自己的错误，记进 §8.3 而不只是提交信息
- 补别名时把 8 个键写到了 JSON **顶层**（真容器是 aliases，515 条）→ 条目完全无效；
  是 assert k not in d['aliases'] 拦下的，删掉无效键后 id_aliases.json 字节与 HEAD 一致
- 教训：DOC-ONLY 这类两侧字面比对差异，先判它是不是冻结行/别名可解析，再谈改数据；
  改名工具 0 命中与 assert 失败都是**信号**，不是小故障

文档：docs/编号规范.md §8.1 口径修正记录 + §8.3 批 5 行与经过段（含被推翻的判断）+ 变更记录；
docs/代码规范/pre-commit使用说明.md §2.25 顺带收编行同步；脚本 docstring 同步

验证：check_doc_links.py --all 143 篇 0 失效；id-check --strict 通过；三个改动文件
BOM=否、CR=0；未改 C/H，不需 @build；台账无需收账（本轮 0 处销账）
 2026-10-21 13:25:06 +08:00
wandering1 64d8b052b1 docs(algo): App/algo/README 缩成目录索引，详细设计迁入 docs/算法 
拆分层级
- 新建 docs/算法/采集与算法层设计说明.md（413 行、13 节）承接机制、契约、
  判据与设计理由：定位与边界 / 数据流与初始化落点 / adc_input / adc_health /
  sample_ring / phasor / freq（7.1 为什么自适应窗、7.2 判据 J1~J6）/
  prot_set / prot_elm / 关键约定与禁令 / 资源足迹 / 验证与判读 / 相关文档
- App/algo/README.md 360 -> 128 行：只留文件清单、依赖、逐文件"改代码必须
  知道"的红线、构建与测试入口、新增模块动作；深挖改成逐条指针
- README 保留 §3.1-§3.7 原编号，既有"§3.7"引用不失效

索引与引用同步
- 索引：docs/README.md §5.2 新增行；项目架构总览主题表拆成"设计与判据 /
  目录索引"两行；AGENTS.md 与 App/README.md 指向（后者原文还写着 L1/L2）
- 按内容重指（编号仍在但内容已搬走，只核编号会静默指错）：App/algo/freq.h、
  test/host/freq/freq_test.c、run_unit_test.py、继电保护规划 L2-4 行、
  pre-commit使用说明 J4 行 -> 指向设计说明
- ADC采样节拍设计说明的两处指向同步改到新文档

修 README 内过时事实
- 挂载写"八个 .c"，实际 uvprojx 内 7 个
- SIM_EXEMPT 写"prot_set / freq 才登记豁免"，实际七个全在表内
- freq-unit-test 标"待登记"，实际已在 .pre-commit-config.yaml
- 定值项数一处 31->40、一处 32->40；blob 144->176 B 证明是 32->40
- 用例与判据数字不再三处复制：属主是 test/host/<模块>/ 与 docs/测试说明/

门禁
- doc-links --all 无新增问题；--sections-strict 覆盖 10 篇文档通过
- id-check 可判定 82.65%（基线 82.6，容差 0.1）；TC 双向追溯差异 124 处不变
- registration-check PASS（1 条已知 WARN）；freq 单测 46/46；@build 0 错 0 警
- 全部改动文件无 BOM、无 CR、U+FFFD = 0
 2026-10-21 11:39:53 +08:00
wandering1 858434492c feat(门禁): id-check 关闸——按债务台账增量拦截，warn-only 时代结束 
机制（--strict 不再「有错就失败」，而是只拦台账外的新账）
- scripts/id_known_backlog.json：340 条指纹覆盖 710 处存量（②167 类 / ⑥135 / ③38）
- 指纹 = (文件, 校验号, 字面量) → 计数，故意不含行号：行号每改必漂，
  用它当指纹会让台账天天假新增，三天后没人敢看 strict，台账失效比没台账更糟
- 带计数而非集合：同一文件里同一个号多出现一次也算新账（复制粘贴式扩散
  正是编号烂掉的主路径，只按「出现过没有」判会放过它）
- 新增 --write-backlog 与 --prune-backlog（只减不增；台账内条目变多当场点名）；
  --strict 缺台账返回 2，绝不退化成一次性拦死存量；--only 与 --strict 互斥
- 钩子 entry 加 --strict；--only 与 --strict 互斥
- 顺带修 _scan_malformed 的反向 bug：原条件 (skip and name != "空格形 Trap")
  语义正好写反，带 [示例] 的行反而专被 Trap 规则咬；改为示例行全部不判
- 第一次提交就被自己的台账咬住（id_known_backlog.json 里当然写着 P1-3 等号，
  被当成新引用）→ 台账加入 excluded_paths：登记号的表不是引用号的文档，
  与 id_aliases.json / id_registry.json 同一条道理

为什么不照「清零再升 strict」的原节奏（§8.4 详述）
- 存量 710 处清完要数周，这期间新债一条都不拦，而新增才是烂掉主因
- 「等清零」让人习惯「报红但照样提交」，真关闸那天没人再信门禁；
  本仓已有 mem-budget / mem-numbers 走 --no-verify 的先例，不再开第二个口子

关闸验收三例（临时件当场还原、git diff 干净）
- A 全新前缀 Z-99 → exit 1 点名 ✅ 咬
- B 同号计数 1→2 → exit 1 点名 ✅ 咬
- C 干净态 710 处 → exit 0 放行 ✅ 放（放不住存量就会逼出 --no-verify）

验证：--strict 干净态 exit 0；可判定比例 82.74%（基线 82.6%）；
doc-links 失效/待确认 0；未改 C/H 不需 @build。
文档：编号规范 §8 上线节奏改写 + 新增 §8.4 机制表；pre-commit使用说明 §2.25；
AGENTS.md 门禁行由 warn-only 改为已关闸增量拦截。
 2026-10-21 11:35:30 +08:00
wandering1 d74cd030ea fix(门禁): 追溯脚本与 B 层口径对齐 + [示例] 行豁免写反的 bug 
为什么改（第 1 件，用户裁定的顺序）
- B 层已认 test/host/<模块>/* 为 TC 号属主登记处，但 check_test_traceability.py
  仍按老规矩要求"每个号都必须出现在文档" → 两处判据互相打脸
- 实测矛盾面 284 处里有 173 处属于该口径：照老口径升 --strict 会当场拦死这些
  本不该写文档的号，唯一出路是 --no-verify——门禁公信力就是这么丢的

追溯差异改为三档（口径与编号门禁一致）
- DOC-ONLY：文档声明了、代码没有 → 真断链，38 处
- CODE-ONLY：代码有、母号不在登记处、**且号旁边没写人话意图** → 真未登记，7 处
- IN-CODE：靠"号旁写着意图"放过 → 238 处，**弱于文档的保证，单列示数不算过关**，
  对外举证仍需 C 层模块级说明（脚本里写明这条边界，禁止把它读成"已登记"）
- 小写子项后缀（TC-TIMESYNC-003b）按母号算，与 check_ids 的 subitem_ok 同口径
- 真差异从 284 降到 45（38 + 7）

顺带修两个自己的 bug
- TC_RE 模块码上界停在 {0,4}：批 2 模块码单词化（ADCHEALTH 9 位）后代码侧集合
  从 556 悄悄缩到 217（339 个号隐形）→ 放宽到 {0,8}。**同一个坑第二次踩**，
  第一次是 check_ids.py 的候选正则——改名必须复核**所有**识别面，已写进 §8.1
- _scan_malformed 的豁免条件写成 `(skip and name != "空格形 Trap")`，语义正好反了：
  带 [示例] 的行反而专门被 Trap 规则咬。改为示例行**全部**形态规则不判，
  并给引用示例号的两行文档补 [示例] 标记

验证
- 编号门禁：错误级 712 → 710，可判定比例 82.73%（基线 82.6% 未跌破），校验 1/4/5 仍 0
- 追溯：代码侧 578 / 文档侧 298 / 交集 260 / 差异 45；--board-only 回退口径不变
- check_doc_links.py --all 文档路径与章节引用均通过；字节卫生复查 BOM=否、CR=0
- 未改 C/H，不需 @build

文档：docs/编号规范.md §8「顺带收编」条目改写 + §8.1 口径修正记录补两行 + 变更记录；
docs/代码规范/pre-commit使用说明.md §2.25「顺带收编」行同步三档口径
 2026-10-21 11:24:05 +08:00
wandering1 4b9a4f4e24 refactor(编号): B 层口径落地——主机侧单测认代码为属主登记处 
为什么不是"补 7 篇文档"
- 实测这些号在代码目录外**零消费者**（NANDPORT 47 / PROTELEM 13 / PROTSET 11 /
  FREQ 11 / FTPAUTH 10 / SHA256 8 / SOE 7 / ADCHEALTH 11 / IEC104 23，共 141 号），
  唯一"外部引用"是 scripts/id_aliases.json 自己 → 逐号写文档等于造一份没人读、
  还要跟着代码同步改的复述层（违反"同一事实只在一处详述"）

判据与注册表改动
- 新增 9 族 TC-HOST-<模块码>：class 仍为 TC（跨模块同号照旧由校验 4 抓）、
  owner_docs_glob = test/host/<目录>/*、每模块游标做号段不越界（含 IEC104 补漏：
  它上批改名前是纯数字 TC-104-*，没进当时的悬空普查所以漏建族）
- 新旗标 allow_orphans（不补该旗标会让 141 号全变孤儿告警）、
  subitem_ok（小写子项后缀母号在册即算已定义，差异仍由双向追溯如实报）
- snapshot_only：§4.3 冻结快照族不参与"定义位优先"——先试无差别生效时，已销项的
  登记簿 N-21 被审计报告同号接管，校验 6 从 266 暴涨到 1437、可判定比例假崩 68.7%，
  且提示会教人补错文档名（正是 §1.2 的 N-31 撞号制造方式），故回退并改为快照族豁免
- excluded_paths 加 scripts/id_aliases.json 与 scripts/id_registry.json：
  别名表/注册表自身不得制造引用面
- T-2 / T-3 / T-4 / T-6 入别名表标 void（2026-10-02 复审专项条目，销项只删行没清引用）

修自己的漏配（这条是 bug 修复，不是口径）
- N / S-LDG / T-LDG 族漏登记 docs/任务规划/README.md（活登记处，N-21 在其中出现 2 次），
  只登记了 docs/任务规划/登记簿.md（N-21 为 0）→ 74 处真条目被误判

数字与诚实交代
- 错误级 1318 → 711（②398 + ③44 + ⑥269）；可判定比例 82.74%（基线 82.6%）
- ⚠ 其中 504 处属**口径修正**、74 处属**修 bug**，**真正变好 0 处**；已在
  docs/编号规范.md §8.1 写口径修正记录表，禁止拿 711 与 1318 直接比
- 文档：§4.1 补 TC-HOST 说明、§8.1 口径修正记录、§8.3 批 3 行、变更记录；
  pre-commit使用说明 §2.25 判定口径与最新实测同步
- 未改任何 C/H，不需 @build；提交钩子即 L0 + L0.5 全量验证
 2026-10-21 10:51:25 +08:00
wandering1 bda7ab2b50 refactor(编号): 16 个测试模块码单词化 + 门禁识别面连带放宽 
批 2（用户授权改名 + 「新名要一眼看懂」裁定）
- 16 个有歧义模块码单词化，共 1,146 处随 scripts/rename_ids.py 改写：
  AI→ADCIN、AH→ADCHEALTH、PS→PROTSET、PE→PROTELEM、PH→PHASOR、
  TS→TIMESYNC、VL→VOLLOCK、NP→NANDPORT、CFG→CONFIG、CLK→SYSCLK、
  WD→WATCHDOG、STO→STORAGE、SH→SHA256、FA→FTPAUTH、FR→FREQ、104→IEC104
- 不动 NET/GD5F/RTC/SOE/UI/ADC/LOG/RS485/TOOL（已是单词、芯片名或业界通用词，
  改了纯属 churn）
- 别名按全局登记：这批字面量已完全限定（TC-<码>-<nnn>），不存在裸形多义
- 映射表存档 scripts/rename_maps/batch2.json 作审计轨迹；§6 模块码表同步

连带修门禁（关键教训）
- 模块码涨到 9 位（ADCHEALTH/WATCHDOG）后，候选正则与族正则的 {0,4} 上界
  会让改名后的号**整批从门禁眼里消失**：实测编号字面量从 8271 掉到 7315、
  悬空假降 490 处。已放宽到 {0,9} 并写进 §6 注记
- 结论：改名批次必须连带复核识别面，只改数据不改判据 = 静默放行；
  这次是靠「可判定比例跌破基线即失败」那条线拦下来的

现状与遗留
- 校验 1 未登记前缀 0 处；可判定比例 82.71%（基线 82.6%，只涨不跌成立）
- 遗留：7 个模块的「单元测试说明.md」仍缺（PROTSET 116、NANDPORT 109、
  PROTELEM 65、FREQ 48、FTPAUTH 45、SHA256 25、SOE 14 处悬空）——改名不解决
  缺文档，处置方式待议
- 遗留：T-2/T-3/T-4/T-6 历史任务号悬空（别名表未收全，属本工具批次漏项）
- 未改任何 C/H 可编译语义（仅注释与宏名内的编号），故不需 @build
 2026-10-21 09:53:28 +08:00
wandering1 301c3e5183 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 迁移批次记录
 2026-10-21 09:33:54 +08:00
wandering1 44dec5c49b feat(UI): golden 像素回归入提交门禁（W6 U4 第三件，35→36 钩子） 
补上我上一轮自己标记为 2/3 的那块缺口：两个 golden 脚本早已存在且一直在
人工跑，但**从未进自动门禁**——"有基线"不等于"有门禁"（§6.1 原文即自认）。

## 先实测成本再定形态
改一个 UI 源文件后「增量重编模拟器 + 两条 golden」合计 **2~4 秒**，支持走
自动门禁。若实测要几分钟，正确做法是明确不挂、改为文档化人工门禁——一个
逼人 --no-verify 的门禁等于没有门禁，故这个数字是本决定的前提而非附注。

## 落地
新增 scripts/check_ui_golden.py：串「增量构建 → 菜单 8 状态 → 内容页 11 页
+ 池水位」。**有意忽略 argv 且 pass_filenames: false**——两条 golden 按整棵
菜单树 + 全量参考图工作，不接受文件参数，pre-commit 传的变更名对它无意义。
files: 覆盖 UI 源 + ui_task.{c,h} + 模拟器 tests/sim/src + main.c +
CMakeLists + lv_conf.h + 包装器与本配置自身（pre-commit 4.x 无 always: true，
files 是唯一触发手段）。

## 端到端验的是钩子，不是脚本
干净树连跑 3 次 rc=0 全 Passed；给 ui_page_dc.c 的 .top_y 注入 +5 位移 →
**钩子 Failed** 并点名 `[dc] FAIL 与参考页不一致（1882 px 差异）`；还原后
git diff 干净、simulator/tests/ref 的 git status 为空——**全程未用 --update
刷基线**（那正是本钩子要防的行为）。
诚实记录瑕疵：首次实测在"连续注入/还原的紧邻重建"之间偶发失败一次，疑似
MSBuild 节点争用，此后 3 次连跑均绿。已把"单次失败先复跑、连续两次才当真、
不许直接 --no-verify 绕过"写进钩子注释。

## 文档同步
AGENTS.md 钩子数与文末索引 35→36 + 钩子清单补 ui-golden；
pre-commit使用说明.md 概览计数同步；报告 §6.5 U4 由 2/3 → **3/3**（这次是
"真进了自动门禁"，不是"脚本存在"）、§6.1 golden 行转 ✅、§0.1 缺口描述更新。

## W6 剩余
U2 合并两页记录、U5 落地目标页（须先对齐"目标页 vs 现存 7 个 ui_page_*.c"
的差集——报告的"27 页"是目标数而非现状数）。
 2026-10-20 22:14:42 +08:00
wandering1 dafc18f5ed feat(UI): W6 第一波——设计令牌层、页面注册表生成器与 UI 门禁补强 
启动 docs/任务规划/README.md 的 W6 UI 扩展簇（用户裁定，覆盖 2026-10-11
的"本轮不排期"）。四个工作包，全部验证通过。

## U1 设计令牌层（零行为变化）
新建 Drivers/BSP/UI/ui_tokens.h（20 个宏），框架 + 7 个页面 + App/task/
ui_task.c 全部接入。屏幕几何**复用 ui_port.h 既有 UI_SCREEN_W/H**，不重复
定义；令牌头自身只 include ui_port.h，不把 LVGL 拖进全部消费者。
补收了报告没列但代码里真重复的量：UI_TEXT_BAND_H 15（7 次）、列表左右边界
与每页行数（各 4 个页面逐字复制）、推流协议几何与显示几何同源（此前硬编码
3200 且注释写着"须与 UI_FB_SIZE 一致"——典型漂移隐患）、UI_TASK_TICK_MS
（ui_port_step 与 osDelay 必须同值，原先靠注释维系）。
故意不收页面私有几何与"同形不同义"的值（device_info 的 pitch=15 与列表
UI_ROW_PITCH=14 合并即改像素）。

## U3 页面注册表与生成器（删手工分发）
ui_page_registry.{c,h} 由生成器产出，**手工 menu_content_page_for() 已删
除**（仓库内仅存 2 处历史说明注释）。密码页按代码实况**单独出口**
（ui_page_registry_password()）——它非节点绑定，任何 #P 叶子进同一页。
顺带落地此前判定"U1 阶段做不了"的共享 flat 样式 ui_style.{c,h}。
生成器除产注册表外**自动把新 .c 写进 uvprojx 与 CMakeLists.txt**，且
**双向对账**：加页打印 registered、删页打印 pruned，不留死条目；并双向
校验（#page 找不到实例报错、实例未被任何 #page 引用也报错）。

## U4 门禁补强（35 个钩子）
新增 font-charset 钩子（scripts/check_font_charset.py）：复用
tools/font_gen 的同一套提取与 cmap 解析规则（importlib 直载，零第二套
规则），A 段查源码在用 vs 字符集、B 段查字符集 vs 字体 cmap。
registration-check 补第 ④ 类：实测原规则对"进了两端构建但没接描述符表"
的页面**全绿**——desc 被链接器剥离、编译链接全过、菜单永远打不开的死代码。
仍照不出的两项已如实写进文档（枚举漏加归 @build、菜单树漏挂归 golden）。

## 字体子集瘦身（D 案，4 留 3 删）
ui_cn_chars.txt 122→119 字（恰删 上/电/重，零新增）。异/常/片/芯 进
KEEP_EXTRA 带理由白名单：它们曾在 9eb1bd63 被写进中文自检描述落盘
/log/selftest.log（定长 64B 记录跨固件持久），删字形会使历史故障记录
渲染空白且不可逆。保留字按**必需**处理，反向有牙——谁只跑 extract_cn
把它们静默洗掉，钩子直接 FAIL 并逐字打印理由。
--strict 口径为"未知冗余 = 0"而非"冗余 = 0"。

## 验证
@build 0 错 0 警；ER_IROM1 232,052 B（较 HEAD −228 B）、RW_IRAM1
75,232 B **零增量**、RW_CCM 87.9% 未变。golden：菜单 8 状态全像素一致 +
内容页 11 页逐字节一致，**参考图 sha256 差异 0 条**（未用 --update 刷
基线）；池水位菜单基线 5368 B、开页-关页往返 5448 B 与 U1 时相同。
38 个在途修改文件逐个核对 BOM/CRLF/U+FFFD 全部与 HEAD 一致。
L0 33 钩子 + L0.5 16 runner / 1104 断言全绿；check_doc_links --all
142 篇、无法判定 0；mem-budget / mem-numbers 已回填。

## 单位成本实测（U5 排期依据）
临时页 zzprobe 绑到"遥信量"叶子 → 只跑生成器 → 带页 @build 0/0 →
注册表出现 {5u, &ui_page_zzprobe_desc} → 回滚后 6 个产出文件 zzprobe
残留计数均 0、重编回基线。
**结论：新增一页 = 3 处人工（新 .c + 新 .h + 菜单树那一行加
 #page=<名>）+ 1 条生成器命令，手工编辑注册文件 0 处。**
据此修正报告原口径"8 处降到 1 处"——那个 1 只在"1 处对既有文件的修改"
意义下成立，页面自身 2 个文件本就要写，真实处数是 3。

## 文档同步与两处自我修正
§0.1 UI 行 B → B+；§6.1「内容页」「设计令牌」两行按实况回填；§6.5 U1/U3
状态更新；§6 顶部加"建议栏不可照抄"总警示（本轮四次证伪：ui_port.h 已有
同名宏、LV_COLOR_BLACK/WHITE 不存在且极性反了、27 页实为目标页数现存 7
个、生成器草图漏密码页非节点绑定）。
两处改口：① §6.5 U4 从我上一版**误写的 3/3 改回 2/3**——"golden 脚本早已
存在"不等于"已进自动门禁"，两个 golden 脚本至今未挂 pre-commit，该缺口
单列为待办；② 原计划"分三笔提交"**作废**，U1 与 U3 改同一批文件、文件内
交叠，硬切会产生不可编译的中间态，故整波一笔。
 2026-10-20 21:14:14 +08:00
wandering1 720f841494 fix(storage): dhara 移植层 is_free 整页精度 + HAL 越界守卫；日志读写批量化 
登记簿 N-21（报告 N-12/N-13）与 N-24（报告 N-16）两项未闭环问题修复并销项。

N-12：dhara_nand_is_free() 旧实现只读页首 64 B 判全 0xFF，会把"页首
0xFF、后段有数据"的已编程页误判空闲，dhara 遂往已编程页再编程 = 位碰撞、
journal/map 指向垃圾且不报任何错。改整页扫描（栈上 64 B 分块、页首命中即
早退，故"已编程且页首有数据"的绝大多数页成本与旧实现同价）。

N-13：报告原建议经核对不成立——本仓裁剪版 dhara 既无 DHARA_NO_PAGE（哨兵
实为 DHARA_PAGE_NONE，journal.h:46）也无 DHARA_E_UNSUPPORTED（error.h 枚举
里没有，照抄直接编译失败），且 map.c 三处 dhara_journal_copy 调用点各自已
挡掉哨兵。真风险是移植层零上界校验：越界页号被芯片地址位截断成某个真实页
→ 静默读写错页。改为六个 HAL 入口统一几何上界守卫 + DHARA_E_CORRUPT_MAP。
错误码选择是刻意的：BAD_BLOCK 会让 journal.c:904 标坏无辜好块，RECOVER 会
让 map.c:275 启动回收；无错误通道的 is_free/is_bad/mark_bad 一律取保守值。

N-16 写侧：一次排空合并成"每文件一次 open/write/close"（≤8 条 = 512 B
静态缓冲）。掉电语义不变——批次仍在同一次 drain 调用内 close，而 close
回写目录项这个不同 LPN 会把 FTL 单页写回缓存逼出到 NAND；失败尾部回投
队列，条目不丢（旧实现 -2 卷忙会直接丢掉那一条）。容量轮转仍只在按条慢
路径做，批量路径发现装不下一批就返回 -3 退回。
N-16 读侧：s_read_raw() 加 8 条滑动读窗口 + 写者代数失效，API 与 UI 零改动。

验证：@build 0 错 0 警（Code 213,540 / ER_IROM1 232,280 B = 22.2%，
RW_IRAM1 75,232 B = 57.4%，ZI +1,640 B 全为静态缓冲、不吃任务栈）；
@test PASS，且台架 journal 恢复点与修复前同轨——连续四次启动 sectors used
恒 14,094、Map head 每轮 +128 单调推进、epoch 稳定 3 → 整页 is_free 未
改变恢复语义、无双编程、无回退；stack_report 9 个任务全 PASS（defaultTask
静态最坏链 3,024 B / 余 40%，实测峰值 2,164 B / 余 57%）。

新增主机侧移植层单测 test/host/nand_port/（第 16 个 -unit-test 钩子）：
RAM 假芯片 + 真实 dhara map/journal 源，149 断言，含"旧算法只看页首 64 B"
对照用例（将来有人把 is_free 改回去会立刻红）与 dhara 级 resume 双编程计数
为 0 的场景。L0.5 由 15 runner / 955 断言 → 16 runner / 1,104 断言。

文档：存储架构说明 §5.3 加移植层两条硬约束；运行与自检记录设计说明
§4.4/§4.5 写批量化与读窗口；GD5F Trap Records 新增 Trap 07（含三条遗留
代价与一条待办编译期断言）；登记簿 N-21/N-24 删行销项并同步 README
§1/§2.0/§2.1、排期详述 C3、报告 §0.1/§0.2/§0.4/§4.x/§7 与去处表；
钩子计数 33→34、主机侧单测 15→16 全库同步。
 2026-10-15 12:34:39 +08:00
wandering1 506eccc68f docs: 错误码传播审计收口并删除该文档（E-xx 转历史编号族） 
本次会话先后销项与关闭：
- E-61 SD2506 清 INTAF：原实现只读取 CTR1，而按手册 ARST=0 时读操作
  不清标志，属空操作；改为读-改-写 CTR1，并按手册订正 CTR1 位宏
  （INTAF/INTDF/BLF 位置，ARST 归 CTR3）
- E-16 cfg_file：新增 CFG_FILE_MAX_NAME_LEN（段名/键名 ≤15），注册时
  拒绝超长键名；s_gen_document 两处 snprintf 改检查式；补 TC-CFG-024
  用例（主机单测 149→151 PASSED）
- E-23 TC704：PHASE7_MULTI_COUNT 8→5（并发上限 = 8 − 3 个常驻监听），
  accept 失败分支加网络代次检查（网络重建即重建监听）
- E-26（UDP）按“保留 API + 文档定案”关闭；E-30 评估为不必要后关闭；
  N-4（ACCEPT 决定不实施）关闭

审计文档剩余 5 项 P2 + 2 项监督，经用户裁定“都不重要”后整体删除：
- 删除 docs/问题记录/错误码传播审计.md（634 行）
- 九类缺陷模式表迁入 docs/编号规范.md §4.2.1（PAT-01~09）
- E-xx 转为纯历史编号族：编号规范 §4.1 属主改“无（原属主已删除）”，
  §4.3 保持冻结；全仓 26 处引用按“保留编号、去悬空文档名”处理
- 顺带修正 N-4 收口遗留：排期详述 C1 才是 E-25/E-27/E-28 的承载处
  （审计 §4 曾误写为登记簿）；README 两处 C1 旧名改回“net 层跨上下文收口”

一并提交此前遗留的体系层评审报告 2026-10-14 复核 WIP（六维评分复核、
未闭环 Top 5→3、三区水位实测刷新）。

校验：Keil 构建 0 错误 0 警告（Code=212344）；check_doc_links
--sections-strict 与 --all（142 文档）通过；内存双台账刷新后均 PASS。
 2026-10-15 07:39:38 +08:00
wandering1 09d6195906 chore: 收口已结束会话遗留的本地改动（RAM 台账/AGENTS/SOE 日志）
CI / L0 静态门禁 (pre-commit) (push) Failing after 1m12s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 17s
Details 
提交此前已结束会话在主工作区遗留、未提交的改动：
- docs/任务规划/ 与 RAM 占用台账、快照的同步更新
- AGENTS.md 索引与 scripts/ram_baseline.tsv 更新
- docs/测试说明/boot_log_data/ 新增 B9 IEC104/SOE 台架日志与解码产物
- .pre-commit-config.yaml 微调

来源为该会话结束时的未提交快照，整体收口便于并入 master。
 2026-10-12 20:10:12 +08:00
wandering1 0d39cf63b1 docs(b8): B8 销项回填——freq 钩子登记 + 规划 L3-5/P2 置位 + RAM 快照再生 
- RAM 快照再生（合并后 .map）：RW_IRAM1 96,776 B（73.8%）/ CCM 不变 /
  ram_baseline.tsv 追加 B8 行（B8 分支 --no-verify 时欠的两条钩子在此补平）
- .pre-commit-config.yaml：新增 freq-unit-test（31→32）；prot-elm /
  iec104 两钩子 files: 追加 App/algo/freq
- AGENTS.md：钩子计数 32 / 单测 14；算法层行补 freq = L2.5 测频（B8）
- pre-commit 使用说明：§2.21 freq-unit-test 详解 + 计数同步
- 保护规划：§3.3 L3-5 置 ✅（软件侧）、§7 P2 更新、变更记录 B8 行
  （自适应窗三代弯路 0.317→0.197→0.0101 Hz、J1~J6 判据、blob VER 1→2
  换代/损坏分流、prot_elm 7→9、OF/UF 暂只经 YX15 可见归 B10 分点）
- W1 卡：B8 销项删行；M2 注 B8 ✅；mermaid 代码道只剩 B9；
  写范围注更新（B9 sync 时 iec104_test.c 两边叠加）
- 任务规划 README：代码道 B7✅→B8✅→B9
- 合并侧已完成：merge 37f74f0（@build 0/0，L0 全绿）
- 验证：doc-links 全绿（142 文档）
 2026-10-12 19:29:34 +08:00
wandering1 d3107f374f docs: 待处理内容.md 解耦为 docs/任务规划/ 文件夹（README 排序权威 + 6 个职责单一文件） 
- rename_ref.py 搬迁：git mv + 全库引用改写 33 文件 82 处
- README.md 保留 §0 编号空间 / §1 未闭环一览 / §2 推进顺序权威 / §3 维护约定
- 拆出 6 文件：W1-采集保护收尾（任务卡五字段）、排期详述、暂缓-RS485、
  登记簿、测试与架构专项、基线与待确认
- 外部引用重定位 ~50 处：裸「登记簿 §X」、§5.1→基线与待确认 §2.1、
  §2.4→暂缓-RS485、§6→基线与待确认 §3、脚本注释 T-x/N-x→登记簿
- 新增并行写纪律：任务分支不改本文件夹，状态列由 Lead 主工作树更新
- 验证：doc-links 141 文档全绿；mem-numbers 一致；refgraph 重生成；
  @build 0 错误 0 警告；新文件无 BOM / LF / 零乱码
 2026-10-12 13:42:47 +08:00
wandering1 90db528032 W1 功能主线完成：内存台账三件套(W1-0) + IEC104 上行(B4) + protectTask 板端接线(B5) 
W1-0 台账三件套：scripts/ram_baseline.py（四模式）+ ram_baseline.tsv 趋势 +
docs/内存管理/RAM预算台账.md + pre-commit mem-budget 钩子（RW_IRAM1/RW_CCM >92%
即 FAIL + Top-10 附表）；审查报告 §5.5 三条闭环。

B4 IEC 60870-5-104 上行（被控站，TCP 2404）：App/protocol/iec104/ 三模块
（asdu 编解码 / pts 点表+数据源 vtable / link APCI+FSM，纯逻辑零 I/O）+
App/task/iec104_serv.c（iec104Task，NET_READY 屏障 100ms 分片喂位）。
82 断言 L0.5 全绿 + iec104-unit-test 钩子（第 31 钩子）；
设计说明 docs/子系统设计/IEC104上行设计说明.md 全量回填。

B5 protectTask（L3 板端接线）：App/task/protect_task.c——20ms 判据节拍
prot_elm_run + L5-4 采样故障闭锁（adc_health 电平位→元件复位）+ L5-1 定值
校验和巡检；新增 prot_elm_request_reset() 收口跨上下文复归（104 YK11 落请求、
eval 头部消费）；定值/元件初始化移入 app_main_init（内核前）。TC-PE-010
（prot_elm 28 用例）。

门禁与内存：TASK_WD_PROTECT=8 入 required_mask（产品 0x77→0x1F7、HW 层
0x1F5，看门狗单测 39 断言同步）；FreeRTOS 堆 48→56KB（.ioc L1 参数 +
FreeRTOSConfig.h 同步，RAM预算台账 §6 登记配额 48→56KB）。
ZI 144,008→152,204（+8,196 B = 堆 +8KB，B5 扩容）；Code=204,348。
stack_report：protectTask 512 words 静态链 872 B/余 57%、iec104Task
640 words 1456 B/余 43% 均 PASS；RW_IRAM1 73.1% / RW_CCM 87.9%（<92%）。

验证：@build 0 错 0 警；ci_local 全绿（31 钩子 + 13 主机侧单测）；
doc-links 135 文档 PASS。登记簿 B4/B5 销项、W1 波次完成；保护规划/看门狗
说明/AGENTS（9 任务）/RAM 三文档全部同步。

遗留（验收窗口，非代码空洞）：台架第三方 104 主站往返（送检窗口）、
标准源注入动作判据、@test PROT 锚点 + protect 栈水位 + 新堆 min_ever 复测。
 2026-10-12 12:36:23 +08:00
wandering1 d1e6bb4ba7 W5波+N-19收口：FTP鉴权落地、Trap25三连定案修复(N-30)、N-20/N-23/N-26 
N-19 FTP 鉴权：
- lftpd_auth（USER/PASS 状态机 + 连续5次失败锁60s）+ SHA-256
  (user||pwd) 口令哈希；config.ini [ftp] 段 user/pwd_hash/write，
  出厂 admin/admin 在用有启动告警；lftpd_log.c 删除并入 lftpd_auth
- ftp_cfg 配置读写；台架 ftp_auth_bench.py 13/13

N-30 / Trap 25（CH395F_Trap_Records.md 四次定案全记录）：
- 修复1 closed-with-data accept：客户端发完正常 FIN 后芯片按
  FUN_PARA(0x09) §5.52② 保留 Socket+RX 缓冲，旧代码把 CLOSED 一律
  relisten 自毁缓冲 → STOR 必挂 425；改为接受"已关但可读"连接排空
- 修复2 丢 CONNECT 中断探针 net_lost_connect_probe + last_peer_port
  幽灵甄别（拆链窗口握手完成但中断丢失，双信源去抖补 accept）
- 修复3 send_list/send_nlst 批量单发：背靠背 ~60B 小段毒化芯片 TX
  （芯片报 SEND_OK 但对端全丢），整份目录一次性写入
- 证伪存档：固定沉降/Socket 轮换冷却/listen 门控（台架 v7 矩阵）
- 台架工具 test/board/ch395f_reuse_bench.{c,h} + host 脚本存档
  （不注册编译；实验分支 n30-chip-bench 保留）

N-20：Error_Handler 死循环降级（记录+复位路径）
N-23：scripts/check_registration.py 双端注册反向校验（pre-commit）
N-26：GD5F NAND 直 DMA 调用方缓冲窗口断言

验证：BUILD_OK 0/0；ftp_regression 连跑 4 轮 11/11（修复前
LIST#4/#7 100% 挂、STOR#2 曾 100% 425）；ftp_auth_bench 13/13；
@test 启动标记 PASS；ci_local L0+L0.5 全过；doc-links 通过。
登记簿 N-30 已销项。
 2026-10-11 18:50:24 +08:00
wandering1 eddbedeee8 docs(AGENTS): 入口重构——补宏观概况与边界块，瘦身51KB→25.8KB，子域知识入skills
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
- AGENTS.md 51,067→25,828 B（−50%）：审计→迁移→删除，逐节 diff 零信息损失
- 按调研（agents.md 官方/aihero/airflow）补「项目概况」：一句话定位、
  数据主线、顶层目录地图、分层边界；平台约束 17 条分 5 组
- 新增「边界（Ask first / Never）」：git commit/push 须明确指示首次入库
- 串口助手、LVGL 模拟器两节移入 serial-assistant / 新建 lvgl-simulator skill
  （开关语义按 main.c 实锤）；LVGL 两条实证坑移入 ui-verify skill
- 9 条入口独有细节迁移至对应设计文档（存储/看门狗/启动顺序/文档规范/
  pre-commit 使用说明/keil-build skill）；@test 细节指向自动化测试流程
- 新增 docs/AGENTS编写指南.md：六原则/模板/反模式/维护纪律 + 本仓案例
- 修正 3 处对 AGENTS 串口节的过时引用；docs/README.md 登记新文档
 2026-10-11 10:44:50 +08:00
wandering1 c936441c83 门禁扩容：新增 lv-conf-sync、simulator/ 纳入全部钩子；含 L3 定值/元件框架落地 
本轮把"自研代码落在门禁之外"的口子收掉，同时落地 LVGL 特性裁剪与
L3 保护定值/元件框架。

门禁（.pre-commit-config.yaml，26 个钩子）
- 新增 scripts/check_lv_conf_sync.py + 钩子 lv-conf-sync：比对两份
  lv_conf.h 的**生效值**（未定义则取 lv_conf_internal.h 兜底默认），
  抓 MISMATCH / LVGL 不认的宏名 / 同文件重复定义
- 顶层 exclude 删掉 simulator/：其下 21 个 tracked 文件全是本项目自研
  代码，生成物（build/、SDL2/、tests/ref/、shot*）已在 .gitignore；
  doc-links 的 exclude 同步删除
- lv-conf-sync 的 files: 覆盖两端配置 → 只改 simulator/lv_conf.h 也触发
  （pre-commit 4.x 已移除 always: true，实测只告警并跳过，无兜底开关）
- 新增 prot-set-unit-test / prot-elm-unit-test 两个主机侧单测钩子
- S11(2.3.5) 判定细化：禁的是"用路径找文件"，尖括号系统头带子目录
  （如 <sys/stat.h>）不再误报；全仓库复核仅 2 处项目代码判定变化

模拟器代码整改（纳入钩子后暴露，全部修代码而非豁免）
- cppcheck 4 处：sim_syslog.c 判空分支内解引用 p_epoch（真实 bug）、
  2 处 struct tm 未初始化、1 处指针可加 const
- coding-standard 61 处：44 处函数左大括号并到右括号同行、8 处补函数
  注释、3 处补文件头注释块、2 处 __ 前缀保护宏改 XXX_H、2 处 sprintf
  改 snprintf（写入字节数与原来完全一致）

LVGL 特性裁剪（F-1/F-2/F-3）
- 两端 lv_conf.h 对齐同一特性子集：删 26 个 LVGL 9.3 不存在的选项名、
  3 处重复定义，10 项靠默认值隐式生效的改为显式固化
- 实测对镜像体积中性；价值在防漂移，且模拟器 golden 回归跑的正是固件
  实际编译的配置

L3 软件侧
- App/algo/prot_set.* Q10 定值模型（范围校验 / 整表 all-or-nothing /
  校验和封存-自检-闭锁）+ prot_elm.* 通用"滞回+定时限"元件框架 7 实例
- test/host/prot_set、test/host/prot_elm 主机侧单测；uvprojx 挂载两处

文档同步
- pre-commit使用说明：§2.8 S11 口径、§2.15 lv-conf-sync 详解、新增 §5.5
  复盘（教训：exclude 只写真正不该进钩子的路径）
- AGENTS.md、UI_设计架构 §1.4 第 10 条、RAM 分析、审查报告刷新与销项

验证
- @build BUILD_OK 0/0（Code=194276 RO=15872 RW=876 ZI=139892）
- 模拟器重建：菜单 8 状态像素逐字节一致（池 5368 B）、11 内容页黄金参考
  全过（往返 5448 B）、remo sink 0/25600 位差异、--logtest/--cfgtest PASS
- 全仓库 cppcheck / coding-standard / no-mojibake --all-files 全过
- check_doc_links --all 129/0；check_mem_numbers --check 内存数字一致
- 端到端：往 simulator/lv_conf.h 注入一行漂移 → 钩子 FAIL（exit 1）
 2026-10-11 08:48:49 +08:00
wandering1 5eed2151de CubeMX 生成 ADC1（9 通道）+ 复原重生成定制，FreeRTOS 加固迁 L1、钩子落 USER CODE 4/5，门禁豁免生成文件空白改写 2026-10-10 00:53:20 +08:00
wandering1 33a4aa4945 本地工具路径DTU_*环境变量改造落地：10处调用点去硬编码+变量优先解析，本机全链路验证通过，文档同步收口，requirements补pre-commit 2026-10-02 22:14:49 +08:00
wandering1 e90486524d CI：Gitea Actions 落地 L0+L0.5（补 T-6） 
新增 .gitea/workflows/ci.yml：push/PR 触发两个 Windows job——
l0-gates 跑 pre-commit --all-files（无 Keil .map 时自适应跳过 mem-numbers），
l05-host-unit-tests 遍历 test/host/**/run_unit_test.py（缺 MSVC 则告警降级跳过）。
刻意不跑 @build（需 Keil 授权）；L1/L2/L3 需真机+ST-LINK，不上 CI。

新增 scripts/ci_local.py：本地跑与 CI 等价的门禁（自动选用装了 pre-commit
的解释器；.map 自适应；退出码 0/1/2 与 CI 对齐），供提交前自查与 runner 就绪前过渡。

文档同步：测试开发标准流程 §9（CI 章节）/§1/§4.1、待处理内容 T-6 销项、
项目部署环境要求 §2.11（runner 前置）、pre-commit 使用说明 §1、scripts/README.md、AGENTS.md。

验证：scripts/ci_local.py rc=0（L0 14 钩子全过 + L0.5 39/39）。
 2026-10-01 10:19:38 +08:00
wandering1 2055de0303 测试：落地测试架构改进 T-1~T-5（套件开关门禁/汇总行校验/通用 harness/公共断言宏/多套件编排） 
背景：L0.5 主机侧单测落地后复审测试架构，给出 6 条改进意见（P0~P3），
登记进 docs/待处理内容.md「测试与验证基础设施」后逐条实施。

- T-1(P0) 测试套件开关门禁：新增 scripts/check_test_suite.py + pre-commit 钩子
  test-suite-switch，默认要求产品构建（全部 TEST_SUITE_* 注释），跑套件回归用
  --allow-test-build / ALLOW_TEST_BUILD=1 显式放行。顺带把 test_config.h 中长期
  开启的 TEST_SUITE_CH395F 改回注释（仓库此前躺着的是测试固件）。
- T-2(P1) verify_log.py 增加 --require-suite-summary：要求
  "=== <名称>: N/M PASSED (failed=0) ===" 且 N>0，堵住"套件没跑到汇总行/
  断言数为 0 仍判 PASS"的盲区；run_boot_test.py 同名参数透传。不传参向后兼容。
- T-3(P1) 抽取通用 harness test/host/common/unit_test_harness.py（工具链探测/
  INCLUDE-LIB 拼接/wd4819/GBK 解码/退出码契约）；watchdog 运行器 170→55 行，只声明 TestBuild。
- T-4(P2) 新增 test/board/test_common.h 集中断言内核（TEST_CHECK_IMPL/TEST_REPORT_IMPL），
  4 套件各用一行宏绑定自身统计变量（保持 g_xxx_stats 独立、防跨套件串数）。
  刻意不 include dbg_log.h——否则冻结 DBG_TAG 默认值触发 #47-D 重定义警告。
- T-5(P2) 新增 test/run_all_suites.py 多套件回归编排，try/finally 无条件还原套件开关。

验证：@build 产品构建 0 错 0 警；4 套件逐一构建均 0/0；看门狗单测 39/39 PASS；
pre-commit 14 钩子全通过；编排脚本 dry-run/开关切换/异常还原均实测通过。
 2026-10-01 07:28:57 +08:00
wandering1 7a18d2ce28 加 CubeMX 重生成存活审计：防标记区外定制被静默覆盖 
背景：.ioc 的 KeepUserCode 只保护 USER CODE 标记区，标记之外的手工改动
重生成即被覆盖，且多数不报编译错（2026-09-29 实测一次覆盖 4 处，含
HardFault_Handler 崩溃采集被打回空 while(1)、两个 FreeRTOS 加固宏被删）。

新增 scripts/check_cubemx_survival.py：
- 16 项易失清单（IWDG 延后启动 / 崩溃采集 / 栈溢出检测 / 堆失败钩子 /
  断言改造 / 看门狗模块与工程挂载 / 复位原因锁存 / HAL 驱动与使能 /
  .ioc 关键项），断言前剥掉 C 注释防误报
- 哈希基线漂移检测（.cubemx_survival_baseline.json），--write 重建
- 标记区外存量以 WARN 提示（3 个 Fault 处理函数、栈注释）

已挂 pre-commit cubemx-survival 钩子（改动 .ioc / Src / Inc /
task_watchdog / .uvprojx 时触发）。

文档：看门狗设计说明 §10.2 新增"重生成不丢的三层手段"方法论
（L1 写 .ioc > L2 搬进 USER CODE 区（可自造标记区）> L3 审计兜底）
及 .ioc / USER CODE 区可用位置 / 存量清单三张对照表；AGENTS.md 平台约束
新增该规则；pre-commit 使用说明 §2.12 新增钩子详解。

门禁：build 0 错误 0 警告；pre-commit 全通过。
 2026-09-29 07:30:00 +08:00
wandering1 a6cdebde62 文档体系重组与 D-7 一致性门禁落地，清理芯片手册孤儿图片 
- D-6 目录规范化：docs 根目录散落文档归入 UI设计/子系统设计/架构设计/审查记录/
  环境与部署/网络 等子目录，去掉目录名空格，重命名 嵌入式C语言代码规范_V1.0.md
- D-7 三档一致性门禁：新增 scripts/check_doc_links.py（链接存在性）、
  scripts/gen_task_table.py（FreeRTOS 任务表数值）、scripts/check_mem_numbers.py
  （内存/Flash 体积），均支持 --check/--write/--diff，pre-commit 钩子同步注册
- D-5 文档索引：新建 docs/README.md，新建 docs/文档规范.md 约束目录命名与链接写法
- D-1 芯片手册瘦身：删除 1069 张无引用孤儿图片（77.06 MB），
  docs/芯片手册 120 MB → 41 MB，已引用图片零断链
- 同步 C 源码注释中的文档路径引用（D-6 重组后），构建 0 错误 0 警告
 2026-09-26 00:51:53 +08:00
wandering1 7f0087d430 新增S10~S19代码规范检查并统一time_sync_task命名 
check_coding_standard.py 新增 9 条机械检查（S14 并入 S6）：
- S10 (3.3.1) 函数名全小写（HAL_ 厂商回调豁免）
- S11 (2.3.5) 禁止相对/绝对路径 include
- S12 (7.6)  禁止可变参数函数
- S13 (7.7)  禁止递归函数
- S15 (6.1.4) 文件作用域指针须初始化为 NULL
- S16 (3.2.2) 非 static 全局变量须 g_ 前缀
- S17 (2.2)  非 static 函数须在配对头文件声明
- S18 (6.3.1) 禁止 Yoda 条件（常量在右）
- S19 (4.4.2) 函数定义左大括号与右括号同行
S6 词表扩充 scanf/strtok
timeSyncTask 重命名为 time_sync_task（3 处代码引用）
更新 pre-commit 使用说明规则表
 2026-09-01 17:38:43 +08:00
wandering1 bb76cfd779 修复规范矛盾并定案5项规则，保护宏统一XXX_H 
规则定案：常量在右（a>5）、保护宏XXX_H（禁双下划线）、
头文件常量用#define、存储类前缀（g_/s_）优先、允许void返回值
全库32个.h头文件保护宏 __XXX_H → XXX_H 改名（字节级替换）
S1检查规则同步更新（拒绝双下划线），Inc/gpio.h 反向验证被正确拦截
规范示例矛盾修复：K&R括号、标准类型、变量初始化、命名常量、注释字段补全
 2026-09-01 16:07:00 +08:00
wandering1 2b66f96d01 新增代码规范检查钩子（规范V1.0 可机械校验项）并修复存量违规 
新增 scripts/check_coding_standard.py + coding-standard 钩子（S1~S9：
头文件保护宏、文件头注释、宏大写、_t 后缀、switch default、
禁 strcpy/sprintf/goto/Tab、函数注释）
修复存量违规：NET_* 字节序宏大写化、net_fd_set 等类型加 _t 后缀、
net_inet_ntoa 的 sprintf 改 snprintf、补 4 处函数注释与 ui_task.c 文件头
docs/代码规范/pre-commit使用说明.md：新增 2.8 节，修正失效文档路径
 2026-09-01 15:41:25 +08:00
wandering1 973bffcd7b 修改文档文件夹架构 2026-09-01 14:53:34 +08:00