写的页面架构
This commit is contained in:
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: font-regen
|
||||
description: 重生成中文子集字体 ui_font_cn_12（extract_cn 提取 → make_font 生成 → diff 检查，固定 4 步，.venv 解释器）。Use when UI 代码新增中文文案、用户报告屏幕缺字/空白块、或提交任何含新汉字的 UI 字符串之前。
|
||||
---
|
||||
|
||||
# 中文字体重生成
|
||||
|
||||
本工程**唯一字体** `ui_font_cn_12`（宋体 12px 1bpp 子集，MCU/模拟器双端共用）。**缺字渲染为空白**——新增汉字必须走以下固定顺序，不得跳过或调换。详细原理见 `docs/UI 设计/UI_中文字体生成与配置.md`。
|
||||
|
||||
## 固定顺序（仓库根目录执行）
|
||||
|
||||
```powershell
|
||||
# 1. 代码落库（新界面字符串已写入 ui_menu.c / ui_content_page.c 等 UI 源码）
|
||||
# 2. 提取字符集（纯标准库，任意 python3 均可）
|
||||
python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 → 仓库根 ui_cn_chars.txt
|
||||
# 3. 生成字体（需 fontTools，一律用 .venv；宋体 .ttc 的 face0 抽取与 ▶ 箭头补回均自动完成，幂等）
|
||||
.venv\Scripts\python.exe tools/font_gen/make_font.py
|
||||
# 变体：--bpp 2（宋体细笔画发虚时）/ --font C:/path/to/font.ttf（换字体）
|
||||
# 4. diff 检查：新增字在位、旧字不变、生成物 Opts 行字符集与预期一致
|
||||
```
|
||||
|
||||
## 提交清单
|
||||
|
||||
`ui_cn_chars.txt`（仓库根）+ `Drivers/BSP/UI/ui_font_cn_12.c` **随代码一起提交**，缺一个都会让另一端/下次构建字体与字集不一致。
|
||||
|
||||
## 坑
|
||||
|
||||
- 不要用 PATH 默认 `python`（msys64，无 fonttools）跑 make_font.py；`.venv` 缺失时按 AGENTS.md「Python 环境」重建
|
||||
- `requirements.txt` 必须**纯 ASCII**（Windows 下 pip 按 GBK 解码，中文注释 → UnicodeDecodeError）
|
||||
- 生僻字（宋体可能无字形）→ **写码前先手动验证字形**，避免"代码写完才发现是空白"
|
||||
- 生成成功后跑 `ui-verify` skill 全回归；黄金参考因字形变化而 FAIL 属预期 → `check_content_pages.py --update` 刷新
|
||||
- 字数变化时同步更新文档中的字符集计数（当前 97 汉字 + ASCII 0x20-0x7E，共 193 字形）：`UI_中文字体生成与配置.md`、`UI_界面制作流程.md` C3、`UI_设计架构.md`、`simulator/README.md` 已知坑 #4
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: new-source-file
|
||||
description: 新增 .c 源文件的双端注册：MDK-ARM/STM32F407-Demo.uvprojx 与 simulator/CMakeLists.txt 均为显式文件列表，新文件必须手动加进两处再双端构建验证。Use when 新建 App/、Drivers/BSP/ 下的 .c 文件，或构建/运行报 undefined reference、"改了代码没生效" 而怀疑文件漏注册。
|
||||
---
|
||||
|
||||
# 新文件双端注册
|
||||
|
||||
本工程 Keil 工程与 PC 模拟器都使用**显式文件列表**（无通配扫描）——新 `.c` 文件不手动注册就不会被编译；只注册一端 = 另一端**静默**缺文件（不一定报错，功能悄悄不生效）。
|
||||
|
||||
## 注册步骤
|
||||
|
||||
1. **Keil MDK**：编辑 `MDK-ARM/STM32F407-Demo.uvprojx`，在对应 `<GroupName>` 的 `<Files>` 中按相邻条目格式插入（`..\` 开头反斜杠路径）：
|
||||
|
||||
```xml
|
||||
<File>
|
||||
<FileName>ui_new_module.c</FileName>
|
||||
<FileType>1</FileType>
|
||||
<FilePath>..\Drivers\BSP\UI\ui_new_module.c</FilePath>
|
||||
</File>
|
||||
```
|
||||
|
||||
现有组：`App`、`Drivers/BSP`、`Drivers/BSP/UI`、`Test` 等；新文件放语义对应的组。
|
||||
|
||||
2. **模拟器**（仅当文件需 PC 端编译，如 `Drivers/BSP/UI/*.c`）：在 `simulator/CMakeLists.txt` 的 `set(UI_SOURCES ...)` 列表加一行 `${UI_DIR}/ui_new_module.c`。非 UI 模块文件通常不需模拟器注册。
|
||||
|
||||
3. **双端构建验证**（两端都必须过）：
|
||||
|
||||
```powershell
|
||||
cmake --build simulator/build --config Debug # 0 警告
|
||||
& "MDK-ARM\build.bat" # BUILD_OK，0 错 0 警
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- **禁止**把源文件复制进 `simulator/`——两端共用 `Drivers/BSP/` 原件（UI_界面制作流程.md C7）
|
||||
- 只注册 `.c`（含 `.s`）；`.h` 靠 include 路径找到，不加工程
|
||||
- 漏注册的典型症状：一端编译失败（undefined reference）或一端行为悄悄停留在旧逻辑
|
||||
- 注册完成后跑回归：UI 文件 → `ui-verify` skill；其他模块 → `@test`（`test/run_boot_test.ps1`）
|
||||
- 改过 `CMakeLists.txt` 后需重新 `cmake -B build` 配置
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: ui-verify
|
||||
description: UI 改动后的回归验证：5 步门禁（模拟器构建、菜单像素回归、内容页黄金参考、Keil 构建、代码规范）。Use whenever code under Drivers/BSP/UI, 字体 ui_font_cn_12.c / ui_cn_chars.txt、菜单/内容页被修改，或用户要求"验证 UI / 跑 UI 回归 / UI 改动检查"。
|
||||
---
|
||||
|
||||
# UI 回归验证
|
||||
|
||||
UI 相关改动完成后必须跑完 5 个门禁再提交。完整说明见 `docs/UI 设计/UI_自动化测试流程.md`。
|
||||
|
||||
## 步骤（仓库根目录执行，python 一律用 .venv）
|
||||
|
||||
```powershell
|
||||
cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警告）
|
||||
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 1) 菜单 8 状态像素回归 + 池基线门禁
|
||||
.venv\Scripts\python.exe simulator/tests/check_content_pages.py # 2) 内容页黄金参考回归 + 往返池门禁
|
||||
& "MDK-ARM\build.bat" # 3) Keil 构建（BUILD_OK，0 错 0 警）
|
||||
.venv\Scripts\python.exe scripts/check_coding_standard.py # 4) 代码规范检查（PASS）
|
||||
```
|
||||
|
||||
退出码：0=PASS / 1=断言失败 / 2=环境错误（exe 缺失等，先按 AGENTS.md 重建对应环境再重跑）。
|
||||
|
||||
## 失败处置决策
|
||||
|
||||
| 现象 | 判定 | 处置 |
|
||||
|---|---|---|
|
||||
| 内容页 FAIL，且**有意**改了该页视觉 | 预期变化 | 先肉眼确认新效果正确（窗口模式或 `i1_to_png.py` 出图对照 mockup），再 `.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 刷参考，`git diff` 检查 ref/ 变化后随代码提交 |
|
||||
| 内容页 FAIL，但**未**有意改视觉 | bug（缺字/几何漂移/样式回归） | 修代码；**禁止**刷参考掩盖 |
|
||||
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 在流程文档变更记录登记 |
|
||||
| 菜单回归失败 | 结构断言（白带占比/边框/往返一致） | 按脚本打印的未过断言清单逐项修代码，无参考文件可刷 |
|
||||
|
||||
## 池水位门禁常量（在脚本头部）
|
||||
|
||||
| 常量 | 脚本 | 当前值 | 含义 |
|
||||
|---|---|---|---|
|
||||
| `MENU_POOL_BASELINE` | check_menu_rows.py | 4784 B | 菜单根框建完的 LVGL 池 used（x64 模拟器） |
|
||||
| `POOL_AFTER_ROUNDTRIP` | check_content_pages.py | 4864 B | 开页-关页往返后 = 基线 + 80 B 一次性残留 |
|
||||
|
||||
**禁止为过门禁盲目改常量**——无法解释的漂移 = 内存回归 bug。
|
||||
|
||||
## 关联注意
|
||||
|
||||
- `.venv` 缺失/换机：`& 'C:\ProgramData\anaconda3\python.exe' -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`
|
||||
- 新增 UI `.c` 文件先走 `new-source-file` skill 双端注册，否则一端静默缺文件
|
||||
- 字体重生成后全页大面积像素差异属预期：确认字形正确后 `--update` 刷参考
|
||||
- 涉及新界面/大改时本 skill 是 P3 门禁，完整管线（P0~P5）见 `docs/UI 设计/UI_界面制作流程.md`
|
||||
Reference in New Issue
Block a user