Files

T

wandering1 511fd30cc6 docs: 清理全仓变更记录流水（43 篇整节删 / 23 篇留一行 / 5 篇保留）

用户裁定：文档只写现状，历史流水一律删掉，过程查 git log。

- 43 篇「变更记录 / 修订记录」整节删除：继电保护规划 12.6 KB、产品
  需求 11.8 KB、项目部署环境 5.5 KB、BSD Socket 指南 5.3 KB、架构
  总览 5.0 KB、实机测试实施指南 3.8 KB 等
- 23 篇别处仍有指向：只留节名 + 一行「本文件不再记流水账，过程查
  git log」，节号与锚点不位移（doc-links 不因此断链）
- 5 篇整表保留（被当唯一证据 / 活台账引用）：看门狗设计说明、配置
  文件设计说明、RAM预算台账、内容页架构、本地工具路径环境变量方案
- 规范同步：文档规范 §5.1 改新裁定；测试文档模板规范删示例节与
  登记句；测试开发标准流程 / UI 两篇 / 实机测试实施指南 / 四篇单测
  说明 / 并行任务工作树方案 / 编号规范 的「登记变更记录」改「写进
  正文」
- 技能同步：stale-doc-count-sweep / ui-verify / id-family 三个 SKILL
  正文不再要求追加流水行（顺带消掉 SKILL.md:121「产品需求 §12」
  失效引用）
- 修 5 处悬空指针：采样有效性校验目录锚点、BSD 指南「文末变更
  记录」、docs/README 过期描述、网络自愈架构两处指向面

72 篇文档净减 600 余行；check_doc_links --all --sections-strict 可判
定比例 61% → 78%、失效引用 0；静态门禁 passed=50 failed=0；gitlint
10 条历史提交信息 0 failed。

未提交他人在飞改动：.dsh/skills/keil-build/*（%SystemDrive% 守卫）。

2026-10-28 22:00:34 +08:00

4.5 KiB

Raw Blame History

name, description, whenToUse

name	description	whenToUse
ui-verify	UI 改动后的回归验证：5 步门禁（模拟器构建、菜单像素回归、内容页黄金参考、Keil 构建、代码规范）。	Drivers/BSP/UI、字体 ui_font_cn_12.c / ui_cn_chars.txt、菜单/内容页被修改的前后（写码前先读「两条实证坑」节），或用户要求"验证 UI / 跑 UI 回归 / UI 改动检查"时。

UI 回归验证

UI 相关改动完成后必须跑完 5 个门禁再提交。完整说明见 docs/UI设计/UI_自动化测试流程.md。

两条实证坑（写码前先读，模拟器照不出来）

I1 绘制缓冲含 8B palette 头：布局 [palette 8B][pixel data]，但 LVGL 容量校验只看 stride×h → 只给 stride×h 会把末 8 字节写到缓冲外。ui_port.c 按 stride×h + palette 供给并在 flush 时 +palette → docs/UI设计/UI_设计架构.md §1.4 第 8 条
MCU 端必须显式应用 mono 主题：lv_theme_mono_init(disp, true, ...) + lv_display_set_theme() + 对活动屏幕再 lv_theme_apply()，否则活动屏仍是默认浅灰而内容恒用白色 → 白底白字整屏纯白（远端"纯白屏"根因）→ docs/UI设计/UI_设计架构.md §1.4 第 9 条

步骤（仓库根目录执行，python 一律用 .venv）

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) 内容页黄金参考回归 + 往返池门禁
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py   # 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）→ 更新脚本常量 + 把新值与它的实测来源写进 `docs/UI设计/UI_自动化测试流程.md` 正文常量表（2026-10-28 起不再记流水，见 `docs/文档规范.md` §5.1）
菜单回归失败	结构断言（白带占比/边框/往返一致）	按脚本打印的未过断言清单逐项修代码，无参考文件可刷

池水位门禁常量（在脚本头部）

常量	脚本	当前值	含义
`MENU_POOL_BASELINE`	check_menu_rows.py	5368 B	菜单根框建完的 LVGL 池 used（x64 模拟器；2026-10-11 随 LVGL 控件裁剪由 4784 上移）
`POOL_AFTER_ROUNDTRIP`	check_content_pages.py	5448 B	开页-关页往返后 = 基线 + 80 B 一次性残留

⚠ 两个常量量的是池的 used，与 LV_MEM_SIZE 总大小无关 → 改池大小（如 2026-10-15 缩池 40→16 KB）不该动这两个数；动了就是页面结构变化或泄漏。

禁止为过门禁盲目改常量——无法解释的漂移 = 内存回归 bug。

关联注意

.venv 缺失/换机：& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt（requirements.txt 已含 pre-commit，重建后静态门禁直接可跑）
新增 UI .c 文件先走 new-source-file skill 双端注册，否则一端静默缺文件
改 ui_menu_tree.txt 或界面里的中文字符串 → 同一笔重跑生成器（tools/menu_gen/gen_menu.py；字体走 font-regen 四步），否则提交门禁 generated-fresh 直接拦：它把生成器拷进系统临时目录重跑、与工作区逐字节比对（实证 0f7b5a87 改了模板没重跑）→ docs/门禁说明/generated-fresh.md
字体重生成后全页大面积像素差异属预期：确认字形正确后 --update 刷参考
涉及新界面/大改时本 skill 是 P3 门禁，完整管线（P0~P5）见 docs/UI设计/UI_界面制作流程.md

4.5 KiB Raw Blame History Unescape Escape