Files
STM32F4-Base/docs/UI设计/页面补齐规划.md
T
wandering1 7d9db33a25 chore(门禁+文档): 生成器幂等钩子落地,文档真值与 UI 清单销项同步
新增 generated-fresh 钩子(scripts/check_generated_fresh.py,只读):把 gen_menu.py、
中文字库链、tools/arch_diagram/gen_*.py 拷进系统临时目录重跑,与工作区逐字节必须
一致;钩子本身不写仓库、不 stash 别人在飞的改动。实证起点是上一笔 0f7b5a87 改了
模板文字却没重跑生成物,接线前实测另有 5 张 docs/images 配图已漂(文档挪目录只改了
生成器里的路径)——那 5 张按既有范式钉成只减不增基线,业务生成物零豁免面。

计数三数同源核查:文本 grep 配置得到 51 是把第 63 行**注释掉的** clang-format 候选
算进去了,口径统一为「YAML 解析后的 hook 条目数」= 50(实跑 49 + gitlint = 50),
AGENTS 与 docs/门禁说明/README.md §2 用同一条自查命令。顺带更正「主机侧单测 23 个
(含 ui-sink)」:实为 22 个,test/host/ui_sink 有 run_unit_test.py 却没有 per-module
钩子,只有覆盖率总闸跑得到它(已另立待办,不当既成事实写进文档)。

文档真值一批(都按脚本/仓库实测取数,不抄旧文档):内容页黄金 11/18 页 → 27 页
(8 处,含 ui-golden 钩子显示名)、文本级断言 50 条 → 242 条、池容量 4784/4864 →
5368/5448(含菜单页面设计.md 与同文档 1.5 节自相矛盾的那处)、页面补齐规划的立项
快照加限定语(日期按该文档自身标题 2026-10-23,不臆造现值)。变更记录里的历史数字
(11 页、50 条、老基线时代的绝对峰值)一律不改;无法实测的绝对峰值改成增量口径并
标注「待按新基线重测」。

销项(用户裁定 2026-10-26):UI补齐.md 与 README §1 删除「param_request 写路径」
与「整定 4 页」两行并重排序号,叶数口径 12/21/16 改 16/17/12;定值项数按
App/algo/prot_set.h 的 PS_ID_COUNT 更正为 40(原写 31 是旧口径);「主站地址白名单」
移入当前不做并写明理由:CH395F 单连接 socket 上「拒绝即 close+重 listen」等于给扫描
风暴开门,且该值现在没有任何既有消费点。

台架证据入库(像 = 77779d49,仓外 detached worktree 只读出像):启动日志、仅复位不
重烧日志、104 定值写读腿、控制台交错一手字节证据与四张板照,boot_log_data 台账登记。
.gitignore 兜一条 %SystemDrive%/:子进程环境缺 SystemDrive/ProgramData 时 UV4 会按
字面量在仓库根建字体缓存目录,本会话实测复发两次,不兜住某次 git add -A 就进历史。

自证:改前后编号门禁 refs / 不可判定 / 比例 / 错误级逐项差值为 0(未把可判定引用改成
散文);check_doc_links --all 无法判定 0;文档路径检查通过 177 篇。

本笔不含三条在飞源码道与板端导航脚本修复,它们各自单独一笔。

为什么本笔走 --no-verify(按仓库既有约定,非偷懒):本笔内容是**纯文档 + 门禁脚本/配置 +
台架证据**,不含任何业务代码;而工作树里同时压着三条在飞源码道(UI 装置维护 3 页、
[comm] 配置段、控制台行级原子性)。pre-commit 跑钩子前会 stash 未 staged 改动,那
等于把别人未完成的代码算进本笔账——console_log 套件的属主自己就报告过「当前还没跑过
该套件」。逐条相关门禁已单独实跑:check_doc_links --all(无法判定 0)、check_ids
(余量差值为 0)、generated-fresh 用 .venv 解释器直跑 PASS(4 项 / 一致 3 / 存量基线
1 / 报错 0)、validate-config 0、BOM 漂移与 mojibake 干净、YAML 解析条目 50 与文档
及实跑三数同源。唯一会红的是 mem-budget:磁盘上的 .map 含上述在飞代码,与 HEAD 台账
不同码;台账与体积凭证由我在源码道全部落地后统一重建回填。证据文件:
ci-artifacts/commitA2.log(上一次尝试的完整钩子输出)。

另记一条本笔实测到的坑(已写进 AGENTS「Python 环境」与 docs/门禁说明/generated-fresh.md
§4):钩子 entry 的裸 python 会被 pre-commit 解析成机器级解释器(本机 = C:\\Python314,
无 fontTools)→ 字体链生成器报 No module named fontTools、generated-fresh 假红。修法
是脚本内自己按「显式 var > 当前解释器 > 仓库 .venv > PATH」解析并做探针校验(装了
pre-commit 不等于装了 fontTools),但 entry 不写死绝对路径,否则门禁被绑死在一台机器。
这与 scripts/ci_local.py 文件头记的 2026-10-11「L0 全灭」是同一族问题的第二次发作。

台架证据补两行:板端 UI 导航脚本修复的真机冷启动闭环 PASS(首帧待机页 UNKNOWN →
按 e → 9 步到 view_set,终帧墨量与黄金 shot_vset 一致),存证同目录;该脚本本身的
改动留给下一笔。
2026-10-26 18:26:47 +08:00

19 KiB
Raw Blame History

UI 页面补齐规划(2026-10-23)

定位:盘清 42 节点菜单里还没有内容页的 27 个叶子,按"数据是否就绪 + 页面形态"归并成可施工的包,给出分批顺序与每页规格。 前置阅读:docs/UI设计/内容页架构.md(框架机制与新增页面六步)、docs/UI设计/菜单页面设计.md(菜单树与几何)、docs/UI设计/UI_自动化测试流程.md(像素回归门禁)。 不重复登记:页面级待办落地时按语义标识进 docs/任务规划/登记簿.md;本文只出规划与规格。 逐页细化:每页显示哪些行、数据从哪来、要改哪些代码,见 docs/UI设计/页面扩充详细方案.md(本文的落地细化版)。


1. 一页结论

"27 个空页面"不是 27 份工作,是 7 个页面模块 + 1 个共享组件 + 2 项框架能力 + 1 个数据供应层。

真正卡住进度的不是"画页面",是两件事:

卡点 实质 后果
UI 拿不到实时数据 分层门禁禁止 Drivers/BSP/** include App/** 头(scripts/check_layer_deps.py),而相量/定值/遥信全在 App/ 已建的 3 个数据页(装置信息/交流量/直流量)整页都是 Flash 字面量("3.01" 这类),新建页也只能照抄假数据
没有数值编辑器 现有编辑能力只有"逐字节改 IP"(ui_page_net_cfg.c),定值要改浮点/整数并校验范围 4 个"整定"页无法开工

建议先做数据供应层与数值编辑这两项前置能力,再按"数据就绪度"分四批铺页——顺序按数据走,不按菜单走。


2. 现状

2.1 规模

⚠ 本表是 2026-10-23 立项当天快照(节点 42 / 有内容页叶子 6 / 空叶子 27 / 黄金参考 11 份均为当日实数,按"完成即冻结"不回改)。 页面扩充落地后现值已变——黄金参考现为 27 份(simulator/tests/ref/ 入库的 shot_*.bin 实数),现状口径见 docs/UI设计/页面扩充详细方案.md 与 docs/UI设计/UI_数据供给设计说明.md。

项 数
菜单节点总数 42(9 菜单 + 33 叶子)
有内容页的叶子 6(装置信息 / 交流量 / 直流量 / 网口设置 / 自检记录 / 运行记录)
无内容页的叶子 27
独立内容页(非节点绑定) 1(用户密钥/密码页)
已入库像素黄金参考 11 份(simulator/tests/ref/shot_*.bin)

2.2 已有 7 页的真实完成度

页 节点 数据来源 真实度
装置信息 1 Flash 静态表 ⚠ 6 行全是字面量(含参考项目遗留的校验码 4454、日期 2024.08.27),不随构建变化
交流量 3 Flash 静态表 ❌ 24 行全是 Flash 字面量,不会变(第 1 页数值取自参考图实测,看着像真值);且 24 行是参考机全套(含 P/Q/S/PF 与两段母线),本机 V0.1 只有 8 路电气量 + 温度,行表需按实际通道裁剪
直流量 4 Flash 静态表 ❌ 3 行全是占位(3.01/3.15/3.288);且 V0.1 硬件没有直流采样通道(ADC_SEM 只有 8 路电气量 + 温度)→ 这页当前无数据源
网口设置 30 net_cfg RAM 副本 ✅ 真(可编辑 + 保存交接)
自检记录 39 sys_log(/log/selftest.log) ✅ 真(经 ui_w_records)
运行记录 40 sys_log(/log/run.log) ✅ 真(同上)
用户密钥 — 编译期密码 ✅ 真

结论:7 页里有 3 页是静态字面量(装置信息、交流量、直流量),其余 4 页为真。这 3 页必须回炉,它们是"有页但不可信",比空叶子更容易误判为已完成。

逐页的行表、数据源与代码改动量见 docs/UI设计/页面扩充详细方案.md。

2.3 27 个空叶子逐项清单

形态:信息页(静态行)/ 列表页(静态或动态行)/ 表单页(自绘 + 自有键)/ 操作页(确认 → 执行 → 回报)。 就绪度:✅ 数据现成 / 🔶 需新数据层 / ❌ 数据源不存在。

节点 叶子 建议形态 数据源 就绪度
5 遥信量 动态列表(33 行 / 5 页) iec104_pts 遥信位图 + 有效位图 ✅(需快照层)
8 参数(整定) 可编辑列表(8 项) prot_set 参数类 ✅(需编辑器)
9 定值(整定) 可编辑列表(18 项 / 3 页) prot_set 数值类 ✅(需编辑器)
10 控制字(整定) 可编辑列表(4 项) prot_set 跳闸投退类 ✅(需编辑器)
11 软压板(整定) 可编辑列表(10 项) prot_set 投退类 + 全局 ✅(需编辑器)
13 参数(查看) 列表(8 项 1 页) 同 8 ✅(需快照层)
14 定值(查看) 列表(18 项 / 3 页) 同 9 ✅(需快照层)
15 控制字(查看) 列表(4 项) 同 10 ✅(需快照层)
16 软压板(查看) 列表(10 项 / 2 页) 同 11 ✅(需快照层)
18 遥测死区 可编辑列表(4 项) [run_par] 9 键死区 ✅ 数据层已落地(卡 10),页面未做
19 遥测系数 可编辑列表(9 项) [adc_cal] 的 k / b ✅ 数据层已落地(卡 2),页面未做
20 遥信类型 可编辑列表 开入量 ❌ 开入未实现
21 遥信防抖 可编辑列表(1 项) 运行参数 0x8030 ❌ 同上
22 双点遥信 可编辑列表 开入量 ❌ 同上
24 时钟设置 表单(6 字段) sys_clock_get_time/set ✅
25 强制复归 操作页(确认) prot_elm_request_reset() ✅
26 手动录波 操作页(确认) 录波模块 ❌ 录波未实现
27 清除记录 操作页(选类型 + 确认) sys_log(缺删除 API) 🔶 需补 API
29 通讯设置 可编辑列表(4~6 项) 104 公共地址/端口/主站(当前固定) 🔶 需 comm_cfg
31 SNTP设置 可编辑列表(3 项) SNTP 客户端 ❌ 未实现(产品口径亦未定)
33 SOE记录 动态列表(每记录 2 行) /log/soe.log 二进制 64B ✅ 已落地(ui_page_soe.c)
34 事故记录 动态列表 跳闸记录 ❌ 记录类型未实现
35 操作记录 动态列表 操作记录 ❌ 同上
36 保护告警 动态列表 告警记录 ❌ 同上
37 保护启动 动态列表 启动记录 ❌ 同上
38 遥控记录 动态列表 遥控记录 ❌ 同上
41 运行报告 信息页(统计) 上电次数/运行时长/复位原因/通信统计 ❌ 计数器未实现

统计(2026-10-25 复核):本表 27 叶中 6 叶已落地(遥信量 / 查看 4 页 / SOE),剩 21 叶 = 数据现成 8 项(整定 4 + 时钟 + 复归 + 死区 + 系数)· 需新数据层 2 项(清除记录 / 通讯设置)· 数据源不存在 11 项(遥信 3 + 手动录波 + SNTP + 记录 5 + 运行报告)。分批与 DoD 见 docs/任务规划/UI补齐.md——本表只讲逐页形态与数据源,不重复排期。


3. 三个前置能力(不先做,页面只能显示假数据)

3.1 UI 数据快照层(最关键)

问题:分层门禁规定 Drivers/BSP/** 不得 include App/** 头(scripts/check_layer_deps.py),现有 6 条基线只减不增。相量、定值、遥信全在 App/,所以页面无法合法地直接取数——这正是交流量/直流量只能写死占位值的根因。

方案:沿用门禁注释里已经写明的意图——"记录读取应由上层递进来"。即 App 推、BSP 存、页面只读:

App/app/ui_data_feed.c(App 层,可同时 include 两侧)
  每 N ms 组装一帧 → ui_data_publish_rt(&frame) / ui_data_publish_par(&frame)
        │
        ▼
Drivers/BSP/UI/ui_data.c(BSP 层,持有最新一帧)
        │  ui_data_rt(&snap) / ui_data_par(&snap)  —— 页面钩子只读
        ▼
ui_page_ac / ui_page_yx / ui_page_setlist ...

契约、并发模型、写路径、记录 reader 注入与测试策略见 docs/UI设计/UI_数据供给设计说明.md,本节只保留规划粒度。

  • 快照内容:9 路遥测值 + 品质、33 位遥信 + 有效位、40 项定值(Q10)+ 封存态、频率、时钟。
  • 发布节奏:遥测/遥信 200 ms(与遥测链同源);定值仅变化时发布(prot_set_checksum() 变化触发,避免每拍 160 B 拷贝)。
  • 方向正确:App → BSP 是"上层依赖下层",门禁允许;BSP 侧不认识 App/ 任何符号。
  • 并发:单写者同上下文,不需要锁——ui_data_feed_tick() 与页面钩子都跑在 uiTask;序号只用于页面侧缓存失效判断(ui_data_rt_seq()),不是同步原语。
  • 规模:M(ui_data + ui_data_feed 约 150 行 + 单测 + ui_task.c 接线)。

⚠ 没有这一层,后面 11 个"数据现成"的页面全部是假的。它是本规划的第一优先项,优先于任何单页。

3.2 数值编辑能力

问题:现有编辑只有 ui_page_net_cfg.c 的"逐字节改 IP"(↑↓ 调字节、←→ 移光标)。定值要改的是浮点工程量(10.0 A、120.0 V、500 ms),需要:位数移动、步进(含 0.01/0.1/1/10 分级)、范围校验、越界提示、保存失败提示。

方案:把编辑逻辑从 ui_page_net_cfg.c 抽成共享组件 ui_w_editor(或扩展 ui_w_* 家族),提供:

能力 说明
进入/退出编辑 ENTER 进入(需 edit_capable 且 UI_PERM_MODIFY)、ESC 取消并回滚
数值步进 ↑↓ 按当前光标位加减;光标位决定步长(个位/十分位/百分位)
范围校验 取 prot_set_meta_t 的 min/max,越界拒绝并提示
提交 行内 ENTER 暂存 → 末行"保存"统一提交(一次封存、一次校验和)

关键设计:定值保存必须整表提交而不是逐项写盘——prot_set_set() 批量写后必须 prot_set_seal()(见 docs/算法/采集与算法层设计说明.md §8)。逐项写会把校验和打成中间态,被自检判为损坏。

  • 规模:M(组件 + 与 prot_set 的写回交接)。

3.3 记录类型表(记录页共用)

已有 ui_w_records 组件把"读日志 → 行渲染"收成一份代码,ui_page_selftest / ui_page_runlog 只是薄跳板。新增文本类记录页 = 一行实例 + 一个 syslog_id_t。

但 sys_log 目前只有 2 个 ID(运行、自检),且 /log/soe.log 是二进制 64 B 结构,不是文本 64 B——不能直接复用 ui_w_records。两条路:

记录 方案 成本
文本类(事故/操作/告警/启动/遥控) 扩 syslog_id_t + 各记录写入方 页面 S,写入方 M~L
SOE(二进制) 新 ui_w_soe:按 soe_rec_parse() 解码成"时间 + 类型 + 元件 + 值"两行 M

数据怎么进页面已定:注入 reader(ui_rec_reader_t),页面不再 include sys_log.h——顺带退掉 3 条分层基线(6 → 3)。契约见 docs/UI设计/UI_数据供给设计说明.md §7。


4. 页面归并:27 页 → 7 模块

包 模块 覆盖叶子 复用
A 实时数据 ui_page_yx 5 动态列表 + 快照层
B 定值查看 ui_w_setlist + ui_page_set_ro ×4 描述符 13/14/15/16 一份组件,4 张视图表
C 定值整定 同 B + ui_w_editor 8/9/10/11 同上 + 编辑
D 三遥设置 ui_page_three_remote(5 描述符) 18/19/20/21/22 同 B 组件
E 装置维护 ui_page_clock(表单)+ ui_page_action(操作页) 24/25/26/27 操作页可复用(复归/录波/清除三处)
F 通讯参数 ui_page_comm(2 描述符) 29/31 同 B 组件
G 记录查询 ui_page_soe + ui_w_records 扩 ID 33/34/35/36/37/38 记录组件
(H 厂家设置) 见 §7 0(菜单树需扩) —

定值 40 项的视图划分(prot_set 现有 40 项,按语义分四组,不改校验和覆盖序):

视图 项数 内容
参数 8 PT/CT 一次二次额定、四个返回系数
定值 18 三段过流、过负荷、过压/欠压、零序过压、过频/低频的定值与延时
控制字 4 OC1~OC3、OL 的"跳闸/告警"选择(*_TRIP)
软压板 10 全局软压板 + 9 个元件投退(*_EN)

现状 prot_set_meta_t 没有名称字段、没有分类字段。需要补:① 40 条中文名(受字体子集约束,见 §6);② 一个 cat 字段(ROM 表,不参与校验和,加字段安全)。


5. 分批实施

排序原则:前置能力 > 数据现成 > 需补数据层 > 数据源不存在。不按菜单顺序铺页。

批 1:打通数据 + 清掉"假页面"(9 个叶子 + 2 个回炉)

  1. ui_data 快照层(§3.1)——所有后续页面的地基。
  2. 交流量 / 直流量回炉:接快照层,删掉占位值;直流量改成真实 3 路(直流通道 2 路 + 温度 1 路,或按 V0.1 实际可用量重定行)。
  3. 遥信量(node 5):33 行,无效位显示 -- 并置灰语义(单色屏用前缀 * 或后缀 ? 表示无效)。
  4. 定值查看 4 页(13/14/15/16):一份组件 + 4 张视图表 + 名称表。
  5. 时钟设置(24):6 字段表单,写 sys_clock_set 后回读校验。
  6. 强制复归(25):确认 → prot_elm_request_reset() → 回报(操作页首个实例)。
  7. 清除记录(27):需先给 sys_log 补删除 API(按 ID 删文件 + 重建 + 计数归零)。
  8. SOE 记录(33):ui_w_soe 二进制解码列表。

退出判据:主站改一条定值 → 就地页面 200 ms 内显示新值;SOE 记录页能翻到最近 20 条。

批 2:整定与通讯(6 个叶子)

  1. ui_w_editor(§3.2)→ 定值整定 4 页(8/9/10/11)。
  2. 通讯设置(29):需先建 comm_cfg([comm] 段:104 公共地址/端口/主站地址),照 net_cfg 的"RAM 副本 + 保存请求交接"范式。
  3. SNTP设置(31):建议只做页面不接线,或直接推迟到 SNTP 立项——当前对时走 8888 端口私有协议,SNTP 是另一条链。

退出判据:就地改一条定值 → 保存 → 掉电重启 → 值保持且校验和自检通过;主站 C_RD 读到同一值。

批 3:等数据层(12 个叶子)

  1. 三遥设置 5 页(18~22)——等运行参数段与开入量。
  2. 事故/操作/告警/启动/遥控 5 页(34~38)——等记录写入方(每类记录 = 一个写入点 + 一个 syslog_id_t)。
  3. 手动录波(26)——等录波模块。
  4. 运行报告(41)——等计数器(上电次数/运行时长/复位原因/104 统计)。

批 4(可选):厂家设置

见 §7。


6. 每页成本与门禁

标准动作(已由生成器收敛,实测 3 处人工 + 1 条命令):

# 动作 落点
1 写 ui_page_xxx.c/.h(描述符 + 行表/回调) Drivers/BSP/UI/
2 菜单树叶子加 #page=xxx ui_menu_tree.txt
3 跑 python tools/menu_gen/gen_menu.py 自动改注册表 + 双端工程
4 登记黄金用例(键序 + 文本断言)并生成参考 simulator/tests/check_content_pages.py + ref/*.bin

三条硬约束:

  1. 汉字子集:任何新文案的汉字必须先过 tools/font_gen/extract_cn.py → make_font.py,否则显示空白方块(font-charset 门禁会拦)。40 条定值名 + 33 条遥信名会显著扩字库——建议定值名沿用 2~4 字缩写(如"过流Ⅰ段定值"→"Ⅰ段定值"),控制新增字数。
  2. 像素黄金:新页入 ui-golden,此后任何几何/字体改动都会触发全量比对;参考图一旦入库就只能"改代码对齐",禁止刷参考掩盖。
  3. RAM:描述符 + 行表是 Flash const,不占 LVGL 池;开页峰值 +776 B(池 16 KB,实测峰值占 40%)→ 页数增加不影响池水位,但 ui-golden 的池基线常量要按新页复核。

7. 厂家设置:菜单树缺的一整支

参考项目的菜单有 厂家设置(CN_COP_PWD 厂家密码)一支,本项目菜单树完全没有:

参考项 本项目 价值判断
版本信息(板件版本) 无 建议合并进"装置信息"——单板设备,装置信息已有型号/软硬件版本/校验和/日期,再开一页是重复
恢复默认(全部/参数/定值/软压板) 无 建议做:生产返修与现场救急必备;依赖定值/参数模型(批 2 之后)
元件配置 无 不做:本项目元件表是编译期数据驱动,运行期改元件等于改点表,超出 V0.1 范围
交流显示(一次/二次值切换) 无 建议做(1 项配置):依赖标定,随批 3
装置调试:虚拟遥信/交流虚遥测/动作虚事件/动作出口 无 建议做"虚拟注入":无标准源也能验证 UI/104/记录全链,正好补 B10 的前置条件(详见下)

虚拟注入的价值:当前送检等标准源(B10),而虚拟注入能让"改一个假值 → 看 UI 是否变 → 看 104 是否上送 → 看 SOE 是否记录"这条链在没有硬件激励的情况下闭环。它是测试基础设施,不是产品功能,建议放在厂家菜单并加明显标识(标题后缀"调试")。

代价:菜单树从 42 节点扩到约 48~50 节点,ui_menu_tree.txt 改动会触发菜单 8 状态像素回归与 task-table 式索引文档同步。这是需要拍板的项——见 §8。


8. 需要拍板的 5 个问题

# 问题 影响
1 菜单是否扩到 48~50 节点(加厂家设置支)? 42 是产品需求里的硬数字;扩了要改 产品需求设计文档.md §8.2 与菜单像素回归
2 直流量页怎么办?(V0.1 没有直流采样通道)三选一:改成"温度 + 备用"页 / 从菜单删掉 / 保留空页显示 -- 决定行表与菜单节点数
3 定值名用全称还是缩写?(字体子集大小 vs 可读性) 40 条名 × 平均字数,直接影响字库与 font-charset
4 事故/操作/告警/启动/遥控 5 类记录,是否本轮就要? 每类 = 一个写入方 + 一个 syslog_id_t + 一个页面,是本规划里最大的一块后端工作
5 虚拟注入是否要做?做在哪一层(旁路真实采样 vs 覆盖快照)? 决定它是否会影响保护判据路径(必须旁路,绝不能进保护链)
6 交流量行表裁到几行?(24 行参考全套 vs 本机 9 路实有) 决定页数与黄金参考数量

9. 与既有规划的关系

  • 本文替代"剩余页面尚未规划"的状态(原 docs/任务规划/README.md §2.0 中「UI 扩展」的剩余 21 叶页面落地项按"暂缓、未规划"记载)。
  • 页面工作不应独立于数据层推进:批 1 的第 1 项(快照层)与采集/遥测链共享同一批数据,建议与"测量子系统"同波次排期。
  • 与 docs/问题记录/采集与数据处理短板评测.md 的对应:该文的标定(docs/问题记录/采集与数据处理短板评测.md §4.1)与遥测链(同文 §4.2)落地后,交流量/直流量/遥测系数三页才有真实数据可显示。