wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
dc44c1e54e8309b3139fd5292eab3a4e15a4abb7
STM32F4-Base/docs/门禁说明/font-charset.md
T
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

3.7 KiB
Raw Blame History

font-charset — UI 字符集差集（防"缺字显示白框"）

一句话：本仓唯一中文字体是子集字体；UI 字符串用了没进字体的汉字，上机就是空白方框， 没有日志、没有报错。本门把"改了 UI 文案要重跑字体生成链"这条约定机械化。

  • 配置：entry: python scripts/check_font_charset.py、pass_filenames: false、 files: 覆盖 Drivers/BSP/UI/、App/task/ui_task.(c|h)、ui_cn_chars.txt、tools/font_gen/。
  • 生成链（四步，见 font-regen skill）：UI 源码 →extract_cn.py→ ui_cn_chars.txt →make_font.py→ ui_font_cn_12.c。

1. 它在查什么（两段链条，缺一环即白框）

段 比对 不满足时
A 必需字符集（源码在用 ∪ KEEP_EXTRA 保留字） vs ui_cn_chars.txt 必需而 txt 无 → GAP FAIL（字体必然缺字形）；txt 有但非必需 → 告警不拦（只费 Flash）；--strict 升级为 FAIL
B ui_cn_chars.txt vs ui_font_cn_12.c 的 cmap txt 有而字体无 → GAP FAIL（转换器对缺字形/低码位会静默丢字）

A 通过 + B 通过 ⟹ 字体覆盖"源码在用"与"刻意保留"的每一个字。 KEEP_EXTRA 的存在理由：防止将来 extract_cn.py 按"源码已不用"静默删掉已落盘记录里还在用的字。

2. 为什么要它

  • 生成期的 verify_coverage() 只校验"txt ⊆ 字体 cmap"，管不到"源码用到的字有没有进 txt"； 改了 UI 字符串却忘跑生成链时，此前提交期没有任何门禁能拦——只能靠肉眼截图发现白框。

3. 触发面

  • 只跑改动的 .c/.h（types: [c]）。

4. 报错怎么读 / 单独跑

  • & '.venv\Scripts\python.exe' scripts/check_font_charset.py --strict（严格档：冗余字也拦）； --chars / --font 换输入用于测脚本自己。
  • 修法是重跑生成链（font-regen skill 四步），不是把字从 UI 里删掉凑绿。

5. 好处

  • 把一种"上机才知道、且完全没有日志"的显示缺陷压到提交前；
  • KEEP_EXTRA 用"逐条带理由"的形式沉淀，避免将来被无声删掉。

6. 限制与盲区

  1. 只看 C/H 源文件：types: [c]。写进 ui_menu_tree.txt（生成菜单表的文本源）里的汉字 不在直接扫描面内——它靠"重新生成 UI 表 → 落到 .c → 被扫"这条间接路径生效；手工改生成物 或跳过生成器时，覆盖关系可能出现空洞。
  2. 必需集来自"源码里出现的汉字"，运行期拼出来的字符串（格式化进来的字、外部配置文件里的字、 记录内容回显）完全在视野外——那类白框本门照不到。
  3. 只校验码位覆盖，不校验字形是否美观/是否为所需点阵尺寸。
  4. 拉丁字母、数字、标点不在本门范围（另有字体与布局约定）。
  5. --strict 不在钩子默认档位里（默认只拦 GAP）：冗余字形长期靠人自觉清理。
  6. 字体文件本身若被手工编辑（不跑生成器），A/B 两段仍可能同时"通过"而与实际 cmap 不符—— 因为它读的就是生成物。

7. 豁免与基线

  • KEEP_EXTRA 是刻意保留清单（存量 + 逐条理由），性质同 registration-check 的已知缺口表； 新增要写理由，删掉等于放弃保护。
  • 没有"只减不增"的债务基线。

8. 改这个门禁本身

  • 放宽"必需集"来源（比如不再扫某个目录）前先确认该目录的字最终确实会进生成链；
  • 与 ui-golden 是互补关系：本门管"有没有字形"，golden 管"像素对不对"。

9. 变更记录

日期 变更
2026-10-23 首篇逐项文档（两段链条判定口径 + 生成期校验覆盖不到的那一环）
Reference in New Issue View Git Blame Copy Permalink