Files

T

wandering1 c4edf352fe refactor(UI): 记录页改注入式 reader，layer-deps 基线 6->3(道B task-6)

B-6 分层收紧（UI_数据供给设计说明.md §7.2 契约原样落地）：
- ui_w_records：删 #include "sys_log.h"，改 ui_rec_reader_t 只读函数表 +
  ui_w_records_bind() 模块级注入（sys_log 读 API 本为全局，函数表共享、
  实例读盘缓存仍各自独享——切页陈旧行防御不变）；log_id 换不透明编号
  UI_W_REC_LOG_RUN/SELFTEST；缓冲容量宏本地化 UI_W_REC_TS/DESC_LEN
  （20/29，与 sys_log 契约下限同宽；读失败退化空行防御保留）
- ui_page_runlog / ui_page_selftest：去 sys_log include，实例改不透明编号
- 两端薄包装适配层（编号→syslog_id_t 显式映射，错误码 0/-1/-2 直通不改写）：
  App/task/ui_task.c 与 simulator/main.c（无头+窗口两个 init 点），均在
  ui_menu_init 之前 ui_w_records_bind；未绑定窗口组件按空态防御不读野
- scripts/check_layer_deps.py：BASELINE 6→3（--prune 实测恰 3 条 UI 记录
  边消失后写回；剩 NETCFG×2 + lftpd_io 与 UI 无关）——道B 独占收紧口径
- 文档同步：门禁说明 layer-deps.md §1/§6/§9 与 README 计数 6→3；
  UI_数据供给设计说明.md §7.2 加落地注记、§14"计划削减"改"已兑现"
- 首提被 id-check 拦下：注释/文档里自造"批卡编号"（B-6/道B-3）命中
  "未登记前缀"增量拦截——已全数改回 task-6/道B 普通指称（编号不回收、
  禁自造，教训入本提交）；id-check 复跑 RC=0（S10 告警为存量非本改动）

验证：
- 模拟器 0 警告；菜单 8 状态 + 内容页 11 页黄金参考逐字节 PASS
  （记录页数据流经 reader 后像素与基线一致，无基线更新提交）
- cppcheck/coding-standard/bsp-err/font-charset/no-mojibake 单跑全绿；
  layer-deps 复跑：6 处反向 include = 豁免 3 / 基线内 3 / 新增 0，
  --prune 显示"基线无需收紧（3 条存量全部仍成立）"
- doc-links --all 的 35 处告警全为本仓检出路径含空格误扫 SDL2 自带 md
  （环境问题、非本改动引入；提交门禁按暂存文件名过滤不受影响）
- @build 0 Error 0 Warning（终树复跑 BUILD_OK）；uvprojx 无 UV4 抖动、
  无新文件不涉注册；其余 38 钩全绿（ui-golden/font-charset/coding-standard/
  bsp-err/id-check/cppcheck…单跑复验 RC=0）

增量（A/B 同树 .map，基线 = 合入 c1b425d 后 HEAD）：
- Flash：Code +104 B、RO +8 B（两端薄包装代码 + reader 函数表 const）
- RAM：RW +4 B（s_reader 指针）/ ZI +4 B（两页实例 struct 枚举改 uint8
  本应 -8 B，链接段对齐后净 +4 B）；RW+ZI 合计 +8 B

gate: only mem-budget/mem-numbers pending lead ledger backfill
- pre-commit run --all-files 实测仅这两条失败（台账/RAM 文档 vs .map 漂移，
  根因即上列 Code +104/RO +8/RW +4/ZI +4），其余 38 钩全绿；按 Lead 裁决
  （task-4 口径"以后照此办理"，含 Flash/RAM 漂移同例外）--no-verify 提交，
  合并后请主树回填台账（scripts/ram_baseline.py --write 由 Lead 侧执行）
- 手工自查通过：5 个 BOM 文件 BOM=EF BB BF 齐全、docs/py/main.c 保持无 BOM，
  全部 10 文件 CR=0、U+FFFD=0
- 台账增量供回填：Flash Code +104 B、RO +8 B；RAM RW +4 B、ZI +4 B

2026-10-25 05:21:05 +08:00

8.6 KiB

Raw Blame History

门禁逐项说明（每种门禁一篇）

这一目录回答一个问题：提交时那 40 个钩子到底在干什么、拦谁、放谁、什么时候会骗人。 每个门禁一篇，八段固定结构：查什么 / 为什么要它 / 触发面 / 报错怎么读 / 好处 / 限制与盲区 / 豁免与基线 / 改门禁本身要注意什么。最后一节是这套文档存在的理由—— 一份只看"拦了什么"的门禁文档，会让人以为绿就是对的。

配置事实源：.pre-commit-config.yaml（39 个 - id:，2026-10-23 清点）。
通用机制（两阶段、stash 陷阱、always 已废、增量拦截三段式、旧 §2.x 查号表）： docs/代码规范/pre-commit使用说明.md §2。
快速自查（不等提交）：& '.venv\Scripts\python.exe' scripts/ci_local.py（L0 + L0b + L0.5）。

1. 三种拦截姿态（先分清这个，报错时才知道该干什么）

姿态	含义	有哪些	失败时该做什么
改写型	不报错，直接改你的文件	`trailing-whitespace`、`end-of-file-fixer`	重新 `git add` 被改的文件再提交（它改的是工作区，不是索引）
硬拦截	违反即失败，没有存量豁免	`cppcheck`、`coding-standard`、`doc-links`、`no-mojibake`、`mem-budget`、`ui-golden`、`font-charset`、`lv-conf-sync`、`task-table`、`mem-numbers`、`registration-check`、`cubemx-survival`、`test-suite-switch`、16 个主机单测、官方 5 个、`gitlint`	只能改代码或改文档；不要找豁免开关
增量拦截	规则恒生效，但存量钉在基线/台账里，只许减不许增	`layer-deps`（3 条，2026-10-25 还清 UI 记录 3 条）、`bsp-err`（38 条）、`id-check`（`scripts/id_known_backlog.json` 台账）	报错先分清是新增还是存量搬家：`--verbose` 看归类，`--prune` 看已还清

⚠ 增量拦截最容易误会的一点：绿灯不等于没问题，只等于"没有比上次更差"。每个增量拦截门禁的基线数字都写进它自己的文档，读那篇时第一眼看的就是"现在在册多少条"。

2. 索引（40 个 hook → 23 篇 + 1 根在 docs/测试说明/）

门禁文档	覆盖的 hook id	一句话它在查什么	改了哪类文件才会跑	文档
`bsp-err.md`	`bsp-err`	BSP 的对外 API 面：错误通道类型、超时宏命名、必须写返回值、返回值不得裸丢弃	`Drivers/BSP/**` 或门禁自身	已写
`layer-deps.md`	`layer-deps`	分层方向：`Drivers/BSP/` 不得 include `App/`	`Drivers/BSP/**`	已写
`id-check.md`	`id-check`	实体编号的八项校验（未登记前缀、裸形、重复定义、孤儿、悬空引用…）	几乎所有文本文件	已写
`doc-links.md`	`doc-links`	文档里的路径引用是否存在；`--sections-strict` 另查章节号是否还存在	任意 `.md`	已写
`cppcheck.md`	`cppcheck`、`test-cppcheck`	静态分析（真机侧与 `test/` 侧两套范围与抑制项）	C/H 源文件	已写
`coding-standard.md`	`coding-standard`	编码规范 V1.0 的可机械检查子集（命名、头文件保护宏、模块头注释块…）	C/H 源文件	已写
`no-mojibake.md`	`no-mojibake`	禁 `U+FFFD`——中文被按错误编码重解码后不可逆损坏的痕迹	全部文本	已写
`mem-numbers.md`	`mem-numbers`	文档里引用的 RAM/Flash 数字与最新 `.map` 报告是否一致（体积档）	`docs/内存管理/**`、相关脚本	已写
`mem-budget.md`	`mem-budget`	RAM 总量红线：`RW_IRAM1` / `RW_CCM` 超 92% 即拦	代码与配置改动	已写
`task-table.md`	`task-table`	README/AGENTS 里的任务表是否与 `Src/freertos.c` 一致	`README.md`、`AGENTS.md`、`Src/freertos.c`	已写
`registration-check.md`	`registration-check`	新 `.c` 是否双端注册（Keil 工程 + 模拟器 CMake）；UI 页面描述符表是否接线	`.c`、`.uvprojx`、`CMakeLists.txt`	已写
`lv-conf-sync.md`	`lv-conf-sync`	两份 `lv_conf.h`（MCU / 模拟器）的特性子集是否一致	两份 lv_conf 或脚本	已写
`cubemx-survival.md`	`cubemx-survival`	CubeMX 重生成会不会把定制静默抹掉（L3 审计兜底）	`.ioc`、`Src/`、`Inc/`	已写
`test-suite-switch.md`	`test-suite-switch`	板级套件开关必须互斥；全注释 = 产品构建	`test/board/test_config.h`	已写
`font-charset.md`	`font-charset`	UI 用到的汉字是否都在子集字体里（缺字 = 白框）	`Drivers/BSP/UI/**`、字体脚本	已写
`ui-golden.md`	`ui-golden`	UI 像素回归：菜单 8 状态 + 内容页 11 页黄金参考图比对	UI 源码、模拟器	已写
`host-unit-tests.md`	16 个 `*-unit-test`	主机侧单测（同一机制 16 个实例）：逻辑层在无硬件的 PC 上编译并跑断言	各自被测模块与其测试目录	已写
详解在 `../测试说明/主机单测覆盖率口径.md`（口径 / 分母 / 基线 / 盲区都在那篇，本目录不重复）	`test-coverage`	覆盖率总闸：跑全部 28 套主机单测 + 已覆盖行只增不减的回退台账	`App/`、`Drivers/BSP/`、`test/host/`、脚本与基线	已写（在 `docs/测试说明/`）
`trailing-whitespace.md`	`trailing-whitespace`	行尾空白（改写型；CubeMX/Keil 生成文件豁免）	全部	已写
`end-of-file-fixer.md`	`end-of-file-fixer`	文件末尾必须恰好一个换行（改写型；同豁免）	全部	已写
`check-added-large-files.md`	`check-added-large-files`	别把大文件（日志/镜像/二进制）误提进仓库	全部	已写
`check-merge-conflict.md`	`check-merge-conflict`	别把没解完的冲突标记（`<<<<<<<`）提上去	全部	已写
`check-yaml.md`	`check-yaml`	YAML 语法是否可解析（门禁配置自己坏了会静默不跑）	`.yml`/`.yaml`	已写
`gitlint.md`	`gitlint`	提交信息规则：标题长度、正文每行 ≤80、空行要求	提交信息（commit-msg 阶段）	已写

3. 每篇文档的固定八段

它在查什么——逐条判据，能对着代码复核的粒度；
为什么要它——它拦下过什么真事，没有它会怎样（没有真事的门禁要老实写"预防性"）；
触发面——files: / exclude: / pass_filenames / 阶段，以及看不见哪些文件；
报错怎么读——样例输出、怎么单独跑、常见"假报警"（含 stash 陷阱）；
好处——它把哪件事从"口头约定"变成了机器判定；
限制与盲区——什么写法能骗过它、什么错它照不到、判据的启发式在哪里；
豁免与基线——白名单形状、在册数量、还债口径（只减不增）；
改门禁本身——自测怎么做、改名会波及什么（例如基线键）、为什么不许拿基线洗假阳性。

4. 现状与下一步

本目录 23 篇已全部成文（上表「文档」列 = 覆盖的 hook id，全部可达）。
新增/改动一个门禁时的三步：① 在 .pre-commit-config.yaml 落地；② 在本目录照八段结构新增或更新一篇（"限制与盲区"一节必须写真实判据的限度，不许留空）；③ 在本 README 索引加一行。
收敛已完成（2026-10-23）：docs/代码规范/pre-commit使用说明.md 的原 §2「各钩子规则详解」（27 个小节、约 480 行）已删除，本节改为 docs/代码规范/pre-commit使用说明.md §2 —— 只留跨钩子的通用机制（两阶段、stash 陷阱、always 已废、改写型与只读型豁免不对称、增量拦截三段式、没有 .map 即跳过、配置自己坏的验收方式、新增门禁三步）与旧 §2.N → 新文档查号表。同一事实只留一处（docs/文档规范.md 的要求）。
收敛时按内容重指了引用：skill 与 AGENTS 文档表、配置文件头注释、手册自己的文件清单行与 §5.5 里那句"判定见旧小节 2.8"。历史变更记录里的旧编号按"冻结历史不回改"保留，靠查号表读。

8.6 KiB Raw Blame History Unescape Escape

门禁逐项说明（每种门禁一篇）

1. 三种拦截姿态（先分清这个，报错时才知道该干什么）

2. 索引（40 个 hook → 23 篇 + 1 根在 docs/测试说明/）

3. 每篇文档的固定八段

4. 现状与下一步

8.6 KiB

Raw Blame History