Replace task/batch shorthand IDs and residual layer labels in human-facing docs with semantic phrases. Add the new cleanup policy to docs/编号规范.md and update the entry docs. Machine keys (TC/CODE-RULE/MENU-STATE/TRAP/FR), hardware designators/pins/MAC, protocol/version numbers and frozen historical evidence are intentionally kept. Docs only; no code behavior change. Verified with check_doc_links.py --all and git diff --check.
22 KiB
UI 页面补齐规划(2026-10-23)
定位:盘清当时 42 节点菜单里还没有内容页的 27 个叶子(节点数现值 43 = 9 菜单 + 34 叶, 2026-10-29 录波道加「录波回放」叶后升级;本文其余数字是 2026-10-23 立项快照,按 §1 的「完成即冻结」不回改),按"数据是否就绪 + 页面形态"归并成可施工的包,给出分批顺序与每页规格。 前置阅读:
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 份均为当日实数,按"完成即冻结"不回改)。 页面扩充落地后现值已变——黄金参考现为 66 份(
simulator/tests/ref/入库的shot_*.bin实数,2026-10-28 记录 5 页与运行报告页落地 +7 张;2026-10-29 录波 UI 道 +6 张),现状口径见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 键死区 |
✅ 已落地(ui_page_deadband.c,2026-10-27) |
| 19 | 遥测系数 | 可编辑列表(9 项) | [adc_cal] 的 k / b |
✅ 已落地(ui_page_calib.c,2026-10-27) |
| 20 | 遥信类型 | 可编辑列表 | 开入量 | ❌ 开入未实现 |
| 21 | 遥信防抖 | 可编辑列表(1 项) | 运行参数 0x8030 | ❌ 同上 |
| 22 | 双点遥信 | 可编辑列表 | 开入量 | ❌ 同上 |
| 24 | 时钟设置 | 表单(6 字段) | sys_clock_get_time/set |
✅ |
| 25 | 强制复归 | 操作页(确认) | prot_elm_request_reset() |
✅ |
| 26 | 手动录波 | 操作页(确认) | wave_ring_request 手动触发经 ui_data_wave_ops_t 注入 |
✅ 已落地(ui_page_wave_manual.c,2026-10-29 录波 UI 道;配套新增「录波回放」叶 node 43 = ui_page_wave_play.c,不在本表 27 叶之列) |
| 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 | 事故记录 | 动态列表 | /log/accid.log(SYSLOG_ACCIDENT,写入点 protect_task.c) | ✅ 已落地(ui_page_accident.c,2026-10-28) |
| 35 | 操作记录 | 动态列表 | /log/oper.log(SYSLOG_OPER,写入点 4 处:定值保存 / 复归 / 对时 / 清除记录) | ✅ 已落地(ui_page_oper.c,2026-10-28) |
| 36 | 保护告警 | 动态列表 | /log/alarm.log(SYSLOG_ALARM,asserted 且跳闸投退=0) | ✅ 已落地(ui_page_alarm.c,2026-10-28) |
| 37 | 保护启动 | 动态列表 | /log/start.log(SYSLOG_START,picked 上升沿) | ✅ 已落地(ui_page_start.c,2026-10-28) |
| 38 | 遥控记录 | 动态列表 | /log/yk.log(SYSLOG_YK,写入点 iec104_pts.c 遥控段) | ✅ 已落地(ui_page_yk.c,2026-10-28) |
| 41 | 运行报告 | 列表页(12 行 / 2 页,四数逐个挂范围标签) | boot_stats(上电次数 + 复位原因)+ 四个 104 观测计数 + uptime_s,经 ui_data info 帧下发 | ✅ 已落地(ui_page_runreport.c,2026-10-28;跨开机累计按裁定不做) |
统计(2026-10-25 复核):本表 27 叶中 6 叶已落地(遥信量 / 查看 4 页 / SOE),剩 21 叶 = 数据现成 8 项(整定 4 + 时钟 + 复归 + 死区 + 系数)· 需新数据层 2 项(清除记录 / 通讯设置)· 数据源不存在 11 项(遥信 3 + 手动录波 + SNTP + 记录 5 + 运行报告)。分批与 DoD 见 docs/任务规划/UI补齐.md——本表只讲逐页形态与数据源,不重复排期。
2026-10-28 复核:本表 27 叶中 22 叶已落地(本批 +6:记录 5 页与运行报告,见 docs/任务规划/UI补齐.md §2 与 docs/任务规划/登记簿.md §7);未落地的 5 叶 = 遥信类型 / 遥信防抖 / 双点遥信(无开入硬件)+ 手动录波(无录波模块)+ SNTP设置(产品口径未定),取舍与重开条件见 docs/任务规划/UI补齐.md §5。口径闭合:本表 22 叶 + 立项前就已绑定、不在本表内的 6 叶(装置信息 / 交流量 / 直流量 / 网口设置 / 自检记录 / 运行记录)= 现值已绑 28 叶(= UI_PAGE_MAP_COUNT);本表未落地 5 叶 = 菜单树未绑 5 叶(33 − 28)。复核方法:按缩进判叶子(有更深缩进后继者即非叶子),再按行内 #page= 数已绑。2026-10-29 补充:「手动录波」已随故障录波独立立项(docs/子系统设计/故障录波设计说明.md;原卡片登记簿 2026-10-30 销项并入该文 §10),上面那行数字仍是 2026-10-28 当日复核值,未随立项改动。 2026-10-29 二补(录波 UI 道落地):本表「手动录波」转已落地(23 叶);菜单树另新增「录波回放」叶(node 43,不在本表立项快照内)——现值 43 节点 / 34 叶 / 已绑 30 / 未绑 4(= 遥信 3 + SNTP 1,UI_PAGE_MAP_COUNT = 30),口径复核方法与上一段相同
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 个回炉)
ui_data快照层(§3.1)——所有后续页面的地基。- 交流量 / 直流量回炉:接快照层,删掉占位值;直流量改成真实 3 路(直流通道 2 路 + 温度 1 路,或按 V0.1 实际可用量重定行)。
- 遥信量(node 5):33 行,无效位显示
--并置灰语义(单色屏用前缀*或后缀?表示无效)。 - 定值查看 4 页(13/14/15/16):一份组件 + 4 张视图表 + 名称表。
- 时钟设置(24):6 字段表单,写
sys_clock_set后回读校验。 - 强制复归(25):确认 →
prot_elm_request_reset()→ 回报(操作页首个实例)。 - 清除记录(27):需先给
sys_log补删除 API(按 ID 删文件 + 重建 + 计数归零)。 - SOE 记录(33):
ui_w_soe二进制解码列表。
退出判据:主站改一条定值 → 就地页面 200 ms 内显示新值;SOE 记录页能翻到最近 20 条。
第二轮:整定与通讯(6 个叶子)
ui_w_editor(§3.2)→ 定值整定 4 页(8/9/10/11)。- 通讯设置(29):需先建
comm_cfg([comm]段:104 公共地址/端口/主站地址),照net_cfg的"RAM 副本 + 保存请求交接"范式。 - SNTP设置(31):建议只做页面不接线,或直接推迟到 SNTP 立项——当前对时走 8888 端口私有协议,SNTP 是另一条链。
退出判据:就地改一条定值 → 保存 → 掉电重启 → 值保持且校验和自检通过;主站 C_RD 读到同一值。
批 3:等数据层(12 个叶子)
- 三遥设置 5 页(18~22)——等运行参数段与开入量。
- 事故/操作/告警/启动/遥控 5 页(34~38)——等记录写入方(每类记录 = 一个写入点 + 一个
syslog_id_t)。 - 手动录波(26):操作页(
ui_page_action确认链,受理后回「已请求录波」)——已落地(2026-10-29);同批新增「录波回放」单页(上下键切通道、左右键切段、阶梯线 3px/点、0 线虚线、峰值 mV 经wave_store_code_to_milli唯一口径、削徽标、空态/坏段显式文案,规格见 docs/子系统设计/故障录波设计说明.md §8.1)。 - 运行报告(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 |
三条硬约束:
- 汉字子集:任何新文案的汉字必须先过
tools/font_gen/extract_cn.py→make_font.py,否则显示空白方块(font-charset门禁会拦)。40 条定值名 + 33 条遥信名会显著扩字库——建议定值名沿用 2~4 字缩写(如"过流Ⅰ段定值"→"Ⅰ段定值"),控制新增字数。 - 像素黄金:新页入
ui-golden,此后任何几何/字体改动都会触发全量比对;参考图一旦入库就只能"改代码对齐",禁止刷参考掩盖。 - RAM:描述符 + 行表是 Flash const,不占 LVGL 池;开页峰值 +776 B(池 16 KB,实测峰值占 40%)→ 页数增加不影响池水位,但
ui-golden的池基线常量要按新页复核。
7. 厂家设置:菜单树缺的一整支
参考项目的菜单有 厂家设置(CN_COP_PWD 厂家密码)一支,本项目菜单树完全没有:
| 参考项 | 本项目 | 价值判断 |
|---|---|---|
| 版本信息(板件版本) | 无 | 建议合并进"装置信息"——单板设备,装置信息已有型号/软硬件版本/校验和/日期,再开一页是重复 |
| 恢复默认(全部/参数/定值/软压板) | 无 | 建议做:生产返修与现场救急必备;依赖定值/参数模型(第二轮 之后) |
| 元件配置 | 无 | 不做:本项目元件表是编译期数据驱动,运行期改元件等于改点表,超出 V0.1 范围 |
| 交流显示(一次/二次值切换) | 无 | 建议做(1 项配置):依赖标定,随批 3 |
| 装置调试:虚拟遥信/交流虚遥测/动作虚事件/动作出口 | 无 | 建议做"虚拟注入":无标准源也能验证 UI/104/记录全链,正好补 第三方送检验收 的前置条件(详见下) |
虚拟注入的价值:当前送检等标准源(第三方送检验收),而虚拟注入能让"改一个假值 → 看 UI 是否变 → 看 104 是否上送 → 看 SOE 是否记录"这条链在没有硬件激励的情况下闭环。它是测试基础设施,不是产品功能,建议放在厂家菜单并加明显标识(标题后缀"调试")。
代价:菜单树从当时 42 节点扩到约 48~50 节点(节点数现值 43,2026-10-29 录波道加「录波回放」叶),
ui_menu_tree.txt改动会触发菜单 8 状态像素回归与task-table式索引文档同步。这是需要拍板的项——见 §8。
8. 需要拍板的 5 个问题
| # | 问题 | 影响 |
|---|---|---|
| 1 | 菜单是否扩到 48~50 节点(加厂家设置支)? | 节点数以 产品需求设计文档.md §8.2 为准(2026-10-29 现值 43,此前 42);扩了要改该节与菜单像素回归 |
| 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)落地后,交流量/直流量/遥测系数三页才有真实数据可显示。