docs(UI设计): 字体字符集计数回填 179字/274字形并登记cmap首命中事故
- UI_中文字体生成与配置.md: §3 计数、§4 输出样例与补回规则(cmap 插入 位置/可达性守卫)、§7 体积口径；文末安全流程追加 2026-10-25 实测事故 - UI_界面制作流程.md: C3 计数 + 变更记录行(并校正 2026-10-15 瘦身后 119字/214字形未回填本表的历史计数) - UI_设计架构.md: 关键约束表默认字体计数 + 变更记录行 - simulator/README.md: 已知坑 #4 计数 - .dsh/skills/font-regen/SKILL.md: 步骤2 增 KEEP_EXTRA 并回警示；坑新增 "低于最小码位扩字移动稀疏 range 起点"条目；计数更新
This commit is contained in:
@@ -55,7 +55,7 @@ scanned 13 files; unique non-ASCII chars: 78
|
||||
-> D:\Code\DTU Code\STM32F4-Base\ui_cn_chars.txt
|
||||
```
|
||||
|
||||
产物 `ui_cn_chars.txt` 为本工程实际显示的汉字清单（当前 122 字，含 ▶/，等符号），可留作字符集记录。
|
||||
产物 `ui_cn_chars.txt` 为本工程实际显示的汉字清单（当前 179 字，含 ▶/，/： 等符号；其中 60 字为 2026-10-25 按页面扩充规划显示串预置，源码未用前由 font-charset 门禁记 WARN 放行），可留作字符集记录。
|
||||
|
||||
---
|
||||
|
||||
@@ -85,16 +85,16 @@ npm i -g lv_font_conv # TTF/OTF -> LVGL 字体 离线转换器
|
||||
```
|
||||
extracted SimSun regular (face0) -> C:\Users\...\Temp\simsun_regular.ttf
|
||||
RUN: lv_font_conv.cmd --font ... --size 12 --bpp 1 -r 0x20-0x7E --symbols ... --no-compress --format lvgl --lv-font-name ui_font_cn_12 -o ...\ui_font_cn_12.c
|
||||
已合并箭头 U+25B6：位图+10 字节，glyph_id=206
|
||||
已合并 U+FF0C '，'：1 字节位图，glyph_id=207
|
||||
OK 43614 bytes -> ...\Drivers\BSP\UI\ui_font_cn_12.c
|
||||
已合并箭头 U+25B6：位图+10 字节，glyph_id=274
|
||||
U+FF0C '，' 已可经既有 cmap 解析，跳过合并
|
||||
OK 58192 bytes -> ...\Drivers\BSP\UI\ui_font_cn_12.c
|
||||
```
|
||||
|
||||
> **▶ 箭头自动合并**：宋体（`simsun.ttc`）没有 U+25B6（▶）字形，`lv_font_conv` 会静默跳过 → 真机显示成方框。`make_font.py` 在生成后自动调用 `merge_arrow_glyph()`，把从 **Segoe UI Symbol**（`seguisym.ttf`，Windows 自带）预提取的箭头字形（位图 10 字节 + `glyph_dsc` + `cmap`）补回 `ui_font_cn_12.c`。该合并**幂等**（已存在则跳过），所以重生成字体后箭头不会丢。换用自带 ▶ 的字体（如黑体/Segoe）时可忽略此步。
|
||||
|
||||
> **低码位符号自动合并**：`lv_font_conv` 的稀疏 cmap 从符号集最小码位起算，**低于该起点的符号被静默丢弃**（实测 U+3001/U+FF0C 等：U+FF0C 全角逗号 < 0x4E2D 范围起点时丢失，页脚"第 X 页，共 Y 页"的逗号长期渲染为空白）。`make_font.py` 的 `merge_extra_symbols()` 对每个此类符号单独生成迷你字体（真实宋体位图/度量），再并入主字体（位图 + `glyph_dsc` + 单码位 `cmap`），同样**幂等**。新增此类符号时把它加入脚本的 `EXTRA_SYMBOLS` 列表即可。
|
||||
> **低码位符号自动合并**：`lv_font_conv` 的稀疏 cmap 从符号集最小码位起算，**低于该起点的符号被静默丢弃**（实测 U+3001/U+FF0C 等：U+FF0C 全角逗号 < 0x4E2D 范围起点时丢失，页脚"第 X 页，共 Y 页"的逗号长期渲染为空白）。`make_font.py` 的 `merge_extra_symbols()` 对每个此类符号单独生成迷你字体（真实宋体位图/度量），再并入主字体（位图 + `glyph_dsc` + 单码位 `cmap`），同样**幂等**。新增此类符号时把它加入脚本的 `EXTRA_SYMBOLS` 列表即可。**两条 2026-10-25 规则**：合并前先用 `_cmap_lookup_gid()` 判可达（可达即跳过，不产生死条目）；新 cmap 条目**插到第一个包含该码位的既有 range 之前**——LVGL `get_glyph_dsc_id()` 线性扫描、首个包含码位的 range 直接返回，追加在宽稀疏 range 之后的条目永远轮不到（见文末事故记录）。
|
||||
|
||||
> **生成后覆盖率断言**：`make_font.py` 在合并后调用 `verify_coverage()`——解析生成字体的 cmap，校验 `ui_cn_chars.txt` 的**全部码位**都进了字体，缺一个即以非零退出码报错（列出 `U+XXXX`）。把 lv_font_conv 的静默丢字（低码位、源字体缺字形）从"上线后才发现空白"变成"生成期硬错误"。
|
||||
> **生成后覆盖率断言**：`make_font.py` 在合并后调用 `verify_coverage()`——解析生成字体的 cmap，校验 `ui_cn_chars.txt` 的**全部码位**都进了字体，缺一个即以非零退出码报错（列出 `U+XXXX`）。把 lv_font_conv 的静默丢字（低码位、源字体缺字形）从"上线后才发现空白"变成"生成期硬错误"。判据自 2026-10-25 起按 **LVGL 首命中语义**解析（进了某个 range ≠ 能渲染：旧判据下 cmap 条目顺序倒置可全绿而上屏全方框，见文末事故记录）。
|
||||
|
||||
参数说明：
|
||||
- `--bpp 1`：单色无抗锯齿；体积最小。**注意** lv_font_conv 在 1bpp 下斜线/细笔画偶发"丢像素"，宋体尤甚。
|
||||
@@ -152,7 +152,7 @@ OK 43614 bytes -> ...\Drivers\BSP\UI\ui_font_cn_12.c
|
||||
1. **1bpp 细笔画发虚**：宋体在 1bpp 下可能丢像素。若上板/客户端中文偏淡，把第 4 节 `--bpp` 改为 `2` 重生成即可（子集小，体积可接受）。
|
||||
2. **字符集变更**：以后新增中文菜单项，须重跑第 3、4 节（重新提取 `ui_cn_chars.txt` 并生成），否则新字显示为方框。
|
||||
3. **编码**：UI 源文件须为 **UTF-8（带 BOM）**，LVGL 按 UTF-8 解码中文串；字体 `.c` 为纯 ASCII，无编码风险。当前 Keil 已加 Misc Controls 抑制项，无需额外 `--locale=english`。
|
||||
4. **字体体积**：12px + 1bpp + 122 字（含 ASCII/符号，共 217 字形）≈ 44.4KB（RO-data）；改 bpp 2 约翻倍，仍在 F407 Flash 余量内。
|
||||
4. **字体体积**：12px + 1bpp + 179 字（含 ASCII/符号，共 274 字形）源文件 ≈ 56.8KB；ROM 增量以 `.map` 为准（2026-10-25 扩 60 字实测 `RO-data` +1,528 B、RAM 0）；改 bpp 2 约翻倍，仍在 F407 Flash 余量内。
|
||||
5. **换字体**：黑体用 `simhei.ttf`（单文件免抽取）；其余字体同理替换 `--font` 路径后重生成。
|
||||
|
||||
---
|
||||
@@ -184,3 +184,5 @@ OK 43614 bytes -> ...\Drivers\BSP\UI\ui_font_cn_12.c
|
||||
|
||||
> **保留字形（`KEEP_EXTRA`）的存在理由**：`ui_cn_chars.txt` 里除了"源码在用"，还可能有**刻意保留**的字——当前为 异 / 常 / 片 / 芯，因为它们曾在 2026-09-14 `9eb1bd63` 被写进中文自检描述落盘 `/log/selftest.log`（定长 64 B 记录跨固件升级持久），删字形会使历史故障记录渲染空白且不可逆。`scripts/check_font_charset.py` 把这类字**按必需处理**：既照"缺字"，也照"保留字被静默剔除"（严格模式下 FAIL 并逐字打印保留理由）。
|
||||
> **所以"只跑 `extract_cn` 重新生成字符集"会把保留字洗掉**——这是本流程最容易犯的错，钩子就是为了挡住它。`--strict` 的判据因此是"**未知**冗余 = 0"，而不是"冗余 = 0"。
|
||||
|
||||
> **2026-10-25 实测事故（扩字 Ⅰ/Ⅱ/Ⅲ，页面扩充预置字批）**：新字 Ⅰ(U+2160) 低于既有最小码位，稀疏 cmap range 起点由 0x4E09 下探到 0x2160，把宋体缺字补回的 U+25B6 单码位条目**吞进了宽 range**——旧 `verify_coverage()` 判"进了 range 即覆盖"全绿，模拟器/真机箭头却全变方框（菜单截图 658 px 差异，A/B 同树定位）。根因：LVGL `get_glyph_dsc_id()` 线性扫描 cmaps[]，**首个包含码位的 range 直接返回**，其 sparse 列表缺该码位也不再向后找。修复：`_insert_cmap_entry()` 把补回条目插到包含它的 range 之前 + `_cmap_lookup_gid()` 可达性守卫（可达即跳过合并且不再追加死条目）+ `verify_coverage()` 改按首命中语义。**结论：低于最小码位的扩字 = cmap 结构变更，结构对账（第 3 步）照不出解析路径倒置，模拟器像素回归必跑。**
|
||||
|
||||
@@ -48,7 +48,7 @@ flowchart TD
|
||||
|---|---|---|---|
|
||||
| C1 | 屏幕 | 160×160，1bpp 单色（`LV_COLOR_FORMAT_I1`），无物理屏（远端客户端显示） | `ui_port.h` |
|
||||
| C2 | 字体 | **唯一**：`ui_font_cn_12`（宋体 12px 1bpp）。汉字 12px/字，ASCII 6px/字，行高 13px。需要其他字号 = 大工程（新字体 + 双端 `lv_conf.h`），默认禁止 | `ui_font_cn_12.c` |
|
||||
| C3 | 字符集 | 子集字体（当前 122 汉字/符号 + ASCII 0x20-0x7E，共 217 字形）；**缺字显示空白**；新字必须重生成字体 | `tools/font_gen/` |
|
||||
| C3 | 字符集 | 子集字体（当前 179 汉字/符号 + ASCII 0x20-0x7E，共 274 字形）；**缺字显示空白**；新字必须重生成字体 | `tools/font_gen/` |
|
||||
| C4 | LVGL 内存池 | 16KB（`LV_MEM_SIZE`，2026-10-15 由 40KB 收缩；实测峰值 6,568 B = 池的 40%）；任一时刻只放"当前导航路径 + 当前内容页" | `Lib/lv_conf.h` |
|
||||
| C5 | 文本 | 一律静态字符串（`lv_label_set_text_static`），禁止动态字符串/strdup | 架构文档 |
|
||||
| C6 | 编码 | `Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**；改动只用 Edit 工具，**禁止** PowerShell/cmd 整文件重写（U+FFFD 不可逆） | AGENTS.md 铁律 |
|
||||
@@ -412,3 +412,4 @@ P4 [ ] UI_设计架构.md 变更记录更新
|
||||
| 2026-09-10 | 网口设置内容页落地后回填：C3 字符集 102→111 字符（208 字形，补网口设置/地址/掩码等，并修复 `lv_font_conv` 丢弃的低码位符号 U+FF0C 全角逗号 → 页脚逗号不再空白）；新文案走 P4 字体重生成 + `check_content_pages.py` 新增网口设置 4 状态黄金参考（可编辑/只读/编辑光标反显/保存 OK）；模拟器 `main` 调 `net_cfg_load` 使参考图显示工厂默认值 |
|
||||
| 2026-09-13 | 移除 HTML 样机阶段：五阶段 → **四阶段管线**（P0 需求录入+设计规格 / P1 规格→代码 / P2 模拟器 / P3 MCU / P4 归档）；设计基准改为"规格布局参数表 + 参考图"，P2 比对基准由"样机渲染图"改为"参考图 + 规格参数表"（根因分流：修代码 / 回 P0 修规格）；用户视觉确认点由 HTML 浏览器移到 P2 模拟器窗口/出图；删除 `mockups/01_主界面.html`、`render_01.png`、`tools/ui_mock/render_mockup.py`（**均已删除**），保留 `NN_说明.md` 规格与原始参考图；`NN_说明.md` 升格为唯一设计基准（P1 照参数表翻译代码，P2 出图对照参数表 + 原图）；`UI_自动化测试流程.md` 门禁编号同步改为 P2/P3 |
|
||||
| 2026-09-14 | 运行记录/自检记录页 + 待机屏落地后回填：C3 字符集 111→122 字（217 字形，补输/入/错/误/上/电/重/芯/片/异/常——**故障描述串在非 UI 源码中 extract_cn 扫不到，须手动补字**）；新文案走 P4 字体重生成 + `check_content_pages.py` pwc 态参考更新（密码错误提示）；池基线 4784→5440 / 往返 4864→5520（+656B = 待机模块常驻屏+容器，见两测试脚本头部注记） |
|
||||
| 2026-10-25 | 字库扩充（页面扩充规划预置字）：C3 字符集 122→179 字（217→274 字形；上次入表后 2026-10-15 字体瘦身实测 119 字/214 字形未回填本表，本次一并校正）。+60 字取自 `docs/UI设计/页面补齐规划.md`、`docs/UI设计/页面扩充详细方案.md` 的页面显示串（段/投/延/零/频/荷/闸/跳/低/过/Ⅰ/Ⅱ/Ⅲ 等 + 年/月/分/秒/分合/已请求/确认/取消/越界用字）；源码未用期间 font-charset 记 [WARN] 属预期，批 2 页面接线后自然转"在用"。顺带修复 `make_font.py` 两处缺陷：补回字形 cmap 条目被宽稀疏 range 吞掉（Ⅰ 下探起点 0x2160 → ▶ 全变方框，A/B 同树实测）与 `verify_coverage()` 非首命中判定；菜单 8 状态 + 内容页 11 页黄金参考逐字节不变；ROM +1,528 B、RAM 0。详见 `docs/UI设计/UI_中文字体生成与配置.md` §4 与文末事故记录 |
|
||||
|
||||
@@ -38,7 +38,7 @@ MCU **无物理屏幕**：LVGL 做 160×160 **1bpp 单色离屏渲染**，帧缓
|
||||
| LVGL 内存池 | 16 KB（`LV_MEM_SIZE`，2026-10-15 由 40 KB 收缩；实测峰值 6,568 B = 池的 40%） | `Lib/lv_conf.h` |
|
||||
| 刷新周期 | 10 ms（`ui_port_step(10)` + `osDelay(10)`） | `ui_task.c` |
|
||||
| 推流端口 | 7003（TCP，与 DTU-RemoteLCD 客户端对齐） | `ui_net_sink.h` |
|
||||
| 默认字体 | `ui_font_cn_12`（12px 1bpp，122 汉字/符号 + ASCII 0x20–0x7E，共 217 字形） | `Lib/lv_conf.h` |
|
||||
| 默认字体 | `ui_font_cn_12`（12px 1bpp，179 汉字/符号 + ASCII 0x20–0x7E，共 274 字形） | `Lib/lv_conf.h` |
|
||||
| uiTask 栈 | 16384 words（BelowNormal） | `Src/freertos.c` |
|
||||
|
||||
### 1.4 硬约束（改 UI 必须遵守）
|
||||
@@ -285,3 +285,4 @@ ENTER/→ 进子框：
|
||||
| 2026-09-09 | 用户密钥密码页落地（首个表单/操作页，§4.7 / `内容页架构.md` §4.1）：框架描述符新增 title_y/hide_deco/hide_footer/key_intercept + 新 API `ui_content_page_invalidate`；新模块 `ui_page_password`（3 数字框反显光标 + arm API）；菜单受保护叶子路由（arm→开密码页，确认一致后回调**先关页再续做进入动作**）；字体 97→102 汉字（198 字形）；双端注册；回归扩至 7 页 + 往返水位，五门禁全绿 |
|
||||
| 2026-09-10 | 网口设置内容页（§4.7 / `内容页架构.md`）：新增 `Drivers/BSP/NETCFG`（Flash 持久化 + CRC-16，工厂默认 192.168.1.100/24）+ 页面插件 `ui_page_net_cfg`（5 行动态值 + 可编辑：↑↓调字节/←→移光标/ENTER 确认，保存行 ENTER → `net_cfg_save` 下次上电生效）；框架新增钩子 `init_cb` + API `ui_content_page_selected_row`；`net_init` 增 `mac` 参数、netTask 等 `SYS_EVT_STORAGE_READY` → `net_cfg_load` → `net_init(ip,mask,gw,mac)` → 回写实际 MAC 影子；字体 102→111 字符（208 字形，修复低码位符号丢失）；双端注册；回归扩至 11 页，五门禁全绿 |
|
||||
| 2026-09-14 | 运行记录/自检记录内容页 + 待机显示模块：新增 `App/log/sys_log`（定长 64B 文本记录引擎，MCU 落 NAND `/log/run.log`、`/log/selftest.log`，FTP 可直下）+ 页面插件 `ui_page_runlog` / `ui_page_selftest`（动态列表：count_cb + refresh，每条 2 行时间戳/描述）+ `ui_standby`（空闲超时自动切待机屏，仅确认键回菜单）；密码页错误提示"密码输入错误"+清空重输；字体 111→122 字（217 字形）；详见 `docs/子系统设计/运行与自检记录设计说明.md` |
|
||||
| 2026-10-25 | 字库扩充（页面扩充规划预置字 +60，含罗马数字 Ⅰ/Ⅱ/Ⅲ）：默认字体升至 179 字符/274 字形，像素基线不变，ROM +1,528 B、RAM 0；修复生成器 `make_font.py` 的 cmap 插入顺序缺陷——LVGL `get_glyph_dsc_id()` 线性扫描首个包含即返回，补回字形（▶）单码位条目被下探后的宽稀疏 range 吞掉即全渲染方框，现按首命中语义插位/守卫/校验（详见 `docs/UI设计/UI_中文字体生成与配置.md` 文末事故记录） |
|
||||
|
||||
Reference in New Issue
Block a user