docs(ui): UI_数据供给设计改为现状设计并去「说明」,引用与注释全仓校准

- 改名走 rename_ref.py:22 文件 55 处路径引用随迁;764 行规划态
  重写为 584 行现状设计,删落地步骤/验收判据两章与全部历史注
- 新增 §6.4:维护动作/遥测整定/通讯参数/录波回放四条常驻注入
  通道写成现状表;§7.4 SOE 改「已绑定」现状
- ui_data.h 注释修正:rt 帧 212 B→216 B 两处(uint64 位图使整帧
  按 8 对齐,单测 021g 钉 216);录波注入「通道六」改「通道七」
  (与通讯参数撞号)
- 既有断链债清 4 处:屏板链路旧 §9.1/§9.2 ×3、覆盖率口径
  §4.5→§4.4、登记簿标注已删除;check_doc_links 外部名单加
  IEC 60870
- 并发会话的 UI_时间响应分析.md 及其四篇修订不在本笔:README
  行级拆分只暂存数据供给摘要行

验证:keil-build 0 错误 0 警告;pre_commit --all-files 全过;
check_doc_links --all 237 篇零问题;ui_data 主机单测 303/303。
This commit is contained in:
2026-11-17 11:59:45 +08:00
parent 8ebef82c20
commit b7a3e18dca
24 changed files with 645 additions and 823 deletions
@@ -115,5 +115,5 @@ version: 1.1.0
7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。 7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。
8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。 8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。
9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。 9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。
10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md` 里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。 10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md`(已删除)里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。
11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。 11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。
+1 -1
View File
@@ -549,7 +549,7 @@ repos:
# NULL 防御);② 跨层不透明下标与显示名映射的**现场一致性**——测试单元在同一 # NULL 防御);② 跨层不透明下标与显示名映射的**现场一致性**——测试单元在同一
# TU 里同时 include BSP 侧与 App/algo、App/log 真头,逐项比对 adc_semantic_t / # TU 里同时 include BSP 侧与 App/algo、App/log 真头,逐项比对 adc_semantic_t /
# prot_set_id_t / soe_type_t / prot_elm_id_t(解耦换来的"魔法下标"风险,口径 # prot_set_id_t / soe_type_t / prot_elm_id_t(解耦换来的"魔法下标"风险,口径
# docs/UI设计/UI_数据供给设计说明.md §9.4;SOE 类型含未标定闭锁=7/复归=8)。 # docs/UI设计/UI_数据供给设计.md §9.4;SOE 类型含未标定闭锁=7/复归=8)。
# files 覆盖被测两件 + 编号真源四头 + 页面消费面(ui_content_page/ui_menu*)+ harness。 # files 覆盖被测两件 + 编号真源四头 + 页面消费面(ui_content_page/ui_menu*)+ harness。
- id: ui-data-unit-test - id: ui-data-unit-test
name: UI 数据快照层单测(主机侧) name: UI 数据快照层单测(主机侧)
+4 -4
View File
@@ -1,7 +1,7 @@
/* /*
* 模块名称:UI 数据组装器(ui_data_feed) * 模块名称:UI 数据组装器(ui_data_feed)
* 模块功能:App → UI 数据通道的写侧——按节拍从采集/标定/相量/测频/保护/协议/墙钟 * 模块功能:App → UI 数据通道的写侧——按节拍从采集/标定/相量/测频/保护/协议/墙钟
* 各模块取数,组装成 docs/UI设计/UI_数据供给设计说明.md §4 契约的三帧 * 各模块取数,组装成 docs/UI设计/UI_数据供给设计.md §4 契约的三帧
* (实时量 rt / 参数 par / 装置信息 info),经 Drivers/BSP/UI/ui_data.h * (实时量 rt / 参数 par / 装置信息 info),经 Drivers/BSP/UI/ui_data.h
* 的发布 API 推给 UI 层;本模块是快照的**唯一填充者**,不含任何布局、 * 的发布 API 推给 UI 层;本模块是快照的**唯一填充者**,不含任何布局、
* 格式化与 LVGL 调用(显示规格全在页面行表,同文档 §8) * 格式化与 LVGL 调用(显示规格全在页面行表,同文档 §8)
@@ -95,7 +95,7 @@
/* 私有宏定义区 */ /* 私有宏定义区 */
/* 实时帧与信息帧发布节拍(ms);参数帧只在定值校验和变化时发布 /* 实时帧与信息帧发布节拍(ms);参数帧只在定值校验和变化时发布
* (节拍依据 docs/UI设计/UI_数据供给设计说明.md §5.2) */ * (节拍依据 docs/UI设计/UI_数据供给设计.md §5.2) */
#define FEED_RT_PERIOD_MS 200u #define FEED_RT_PERIOD_MS 200u
/* 遥信位号:**与 App/protocol/iec104/iec104_pts.c 板端源的位图同源**(该文件把 /* 遥信位号:**与 App/protocol/iec104/iec104_pts.c 板端源的位图同源**(该文件把
@@ -134,7 +134,7 @@
/* 编译期一致性守卫(ARMCC C99 无 _Static_assert,用项目惯用的数组宽度法, /* 编译期一致性守卫(ARMCC C99 无 _Static_assert,用项目惯用的数组宽度法,
* 先例 App/cfg/cfg_file.c 与 Drivers/BSP/UI/ui_menu_tab.h): * 先例 App/cfg/cfg_file.c 与 Drivers/BSP/UI/ui_menu_tab.h):
* 快照下标空间与各 App 枚举一旦漂移,编译即失败,不留到运行期 * 快照下标空间与各 App 枚举一旦漂移,编译即失败,不留到运行期
* (契约 docs/UI设计/UI_数据供给设计说明.md §9.4 第 1/2 条) */ * (契约 docs/UI设计/UI_数据供给设计.md §9.4 第 1/2 条) */
typedef char feed_chk_yc_n_t[(UI_DATA_YC_N == (uint32_t)ADC_SEM_COUNT) ? 1 : -1]; typedef char feed_chk_yc_n_t[(UI_DATA_YC_N == (uint32_t)ADC_SEM_COUNT) ? 1 : -1];
typedef char feed_chk_set_n_t[(UI_DATA_SET_N == (uint32_t)PS_ID_COUNT) ? 1 : -1]; typedef char feed_chk_set_n_t[(UI_DATA_SET_N == (uint32_t)PS_ID_COUNT) ? 1 : -1];
/* 写路径注入表的 id 形参是 uint8_t(BSP 侧不透明编号宽度,位图只有 64 位): /* 写路径注入表的 id 形参是 uint8_t(BSP 侧不透明编号宽度,位图只有 64 位):
@@ -822,7 +822,7 @@ static uint8_t s_comm_bound; /* 道G task-9 通讯参数表懒绑门(同款
* 限定条件:uiTask 上下文(读侧;写者 = iec104Task 的 set_sealed 与装载路径, * 限定条件:uiTask 上下文(读侧;写者 = iec104Task 的 set_sealed 与装载路径,
* 读到的永远是"值区与封存一致"的完整快照) * 读到的永远是"值区与封存一致"的完整快照)
* 函数说明:只搬 Q10 原值不换算小数位——换算属表现层 * 函数说明:只搬 Q10 原值不换算小数位——换算属表现层
* (docs/UI设计/UI_数据供给设计说明.md §8) * (docs/UI设计/UI_数据供给设计.md §8)
*/ */
static void feed_fill_par(ui_data_par_t *p_snap, uint32_t sum) { static void feed_fill_par(ui_data_par_t *p_snap, uint32_t sum) {
uint8_t i; uint8_t i;
+4 -4
View File
@@ -1,17 +1,17 @@
/* /*
* 模块名称:UI 数据组装器(ui_data_feed) * 模块名称:UI 数据组装器(ui_data_feed)
* 模块功能:App → UI 数据通道的"写侧"——按节拍从采集/算法/保护/协议/时钟各模块 * 模块功能:App → UI 数据通道的"写侧"——按节拍从采集/算法/保护/协议/时钟各模块
* 取数,组装成 docs/UI设计/UI_数据供给设计说明.md §4 契约的三帧 * 取数,组装成 docs/UI设计/UI_数据供给设计.md §4 契约的三帧
* (实时量 rt / 参数 par / 装置信息 info),经 Drivers/BSP/UI/ui_data.h * (实时量 rt / 参数 par / 装置信息 info),经 Drivers/BSP/UI/ui_data.h
* 的发布 API 推给 UI 层;本模块是快照的**唯一填充者** * 的发布 API 推给 UI 层;本模块是快照的**唯一填充者**
* 适用范围:App/app(装配层:可同时 include 两侧头,方向仍是上层依赖下层, * 适用范围:App/app(装配层:可同时 include 两侧头,方向仍是上层依赖下层,
* scripts/check_layer_deps.py 只拦"Drivers/BSP 目录反向 include App 目录") * scripts/check_layer_deps.py 只拦"Drivers/BSP 目录反向 include App 目录")
* 线程约定:uiTask 上下文,主循环每轮调 ui_data_feed_tick() 一次;与页面读写同 * 线程约定:uiTask 上下文,主循环每轮调 ui_data_feed_tick() 一次;与页面读写同
* 上下文串行 → 无锁(docs/UI设计/UI_数据供给设计说明.md §5.1)。 * 上下文串行 → 无锁(docs/UI设计/UI_数据供给设计.md §5.1)。
* ⚠ 不得在 adcTask/protectTask/netTask 里调用本模块 * ⚠ 不得在 adcTask/protectTask/netTask 里调用本模块
* 端接法:MCU = App/task/ui_task.c 主循环;PC 模拟器**不链接本文件**(模拟器不跑 * 端接法:MCU = App/task/ui_task.c 主循环;PC 模拟器**不链接本文件**(模拟器不跑
* 固件装配链,快照由 simulator/main.c 直接发布固定帧保证像素回归可复现, * 固件装配链,快照由 simulator/main.c 直接发布固定帧保证像素回归可复现,
* 见 docs/UI设计/UI_数据供给设计说明.md §9.2;模拟器豁免登记在 * 见 docs/UI设计/UI_数据供给设计.md §9.2;模拟器豁免登记在
* scripts/check_registration.py 的 SIM_EXEMPT) * scripts/check_registration.py 的 SIM_EXEMPT)
* 作者:王建锋 * 作者:王建锋
* 创建日期:2026-10-25 * 创建日期:2026-10-25
@@ -39,7 +39,7 @@ extern "C" {
* (Drivers/BSP/UI/ui_data.h 写路径节) * (Drivers/BSP/UI/ui_data.h 写路径节)
* 函数说明:本函数每轮代价 = 一次 tick 差值比较 + 一次校验和比较 + 一次 * 函数说明:本函数每轮代价 = 一次 tick 差值比较 + 一次校验和比较 + 一次
* ui_data_param_drain()(队列空时只是一次计数判断);真正的取数与组装 * ui_data_param_drain()(队列空时只是一次计数判断);真正的取数与组装
* 只在到期时发生(docs/UI设计/UI_数据供给设计说明.md §5.2)。 * 只在到期时发生(docs/UI设计/UI_数据供给设计.md §5.2)。
* ⚠ drain 排在取校验和**之前**:本轮写入的定值要在本轮就被"校验和变化 * ⚠ drain 排在取校验和**之前**:本轮写入的定值要在本轮就被"校验和变化
* 才发"那道门看见,页面才能在同一帧里同时显示 OK 与新值 * 才发"那道门看见,页面才能在同一帧里同时显示 OK 与新值
* 内部零阻塞、零堆分配、零日志(日志每条约 90 B Flash + 216 B 栈, * 内部零阻塞、零堆分配、零日志(日志每条约 90 B Flash + 216 B 栈,
+1 -1
View File
@@ -178,7 +178,7 @@ static int ui_task_rec_get(uint8_t log_id, uint32_t idx, char *ts, uint32_t ts_l
* sys_clock / prot_elm / sys_log 是分层方向的反例(layer-deps 拦),更关键的是 * sys_clock / prot_elm / sys_log 是分层方向的反例(layer-deps 拦),更关键的是
* **模拟器根本不链 sys_clock**(simulator/dbg_log.h:4「模拟器无 sys_clock/RTC」)—— * **模拟器根本不链 sys_clock**(simulator/dbg_log.h:4「模拟器无 sys_clock/RTC」)——
* 页面里用一次就是"MCU 编得过、模拟器链接期爆"。写动作一律走 ui_data_maint_ops_t, * 页面里用一次就是"MCU 编得过、模拟器链接期爆"。写动作一律走 ui_data_maint_ops_t,
* 两端各给实现(口径 docs/UI设计/UI_数据供给设计说明.md §6.2/§7.2)。 * 两端各给实现(口径 docs/UI设计/UI_数据供给设计.md §6.2/§7.2)。
* *
* uiTask 阻塞上界(IWDG 800ms 窗、本任务在 required_mask 内):本通道里只有 * uiTask 阻塞上界(IWDG 800ms 窗、本任务在 required_mask 内):本通道里只有
* 时钟设置会碰硬件——sys_clock_set_unix 内含 1 次 SD2506 写,再叠加本适配层刻意 * 时钟设置会碰硬件——sys_clock_set_unix 内含 1 次 SD2506 写,再叠加本适配层刻意
+3 -3
View File
@@ -4,12 +4,12 @@
* 只读访问——本模块是纯内存叶子:不取数、不格式化、不判断业务含义、 * 只读访问——本模块是纯内存叶子:不取数、不格式化、不判断业务含义、
* 不碰 LVGL、不 include 任何 App 头(职责边界与依赖方向 = * 不碰 LVGL、不 include 任何 App 头(职责边界与依赖方向 =
* Drivers/BSP/UI/ui_data.h 文件头与 * Drivers/BSP/UI/ui_data.h 文件头与
* docs/UI设计/UI_数据供给设计说明.md §3.2) * docs/UI设计/UI_数据供给设计.md §3.2)
* 并发模型:单写者同上下文——唯一发布者 App/app/ui_data_feed.c 与全部页面钩子都在 * 并发模型:单写者同上下文——唯一发布者 App/app/ui_data_feed.c 与全部页面钩子都在
* uiTask 内串行执行,故无锁、无双缓冲、无 seqlock;将来真出现第二个 * uiTask 内串行执行,故无锁、无双缓冲、无 seqlock;将来真出现第二个
* 发布者,保护收在本模块内部(双槽 + 每槽 seq + 单字节活动下标,照 * 发布者,保护收在本模块内部(双槽 + 每槽 seq + 单字节活动下标,照
* App/algo/phasor.c 双区先例),页面代码不受影响 * App/algo/phasor.c 双区先例),页面代码不受影响
* (判据 docs/UI设计/UI_数据供给设计说明.md §5.1) * (判据 docs/UI设计/UI_数据供给设计.md §5.1)
* 写路径(定值整定请求队列)同理:生产者是页面"保存"按键钩子、消费者是 * 写路径(定值整定请求队列)同理:生产者是页面"保存"按键钩子、消费者是
* App 侧节拍里的 ui_data_param_drain(),两者同在 uiTask → 环形队列照旧 * App 侧节拍里的 ui_data_param_drain(),两者同在 uiTask → 环形队列照旧
* 无锁;若将来出现第二个投递上下文,唯一要做的是给 request/drain 两侧 * 无锁;若将来出现第二个投递上下文,唯一要做的是给 request/drain 两侧
@@ -142,7 +142,7 @@ int ui_data_publish_rt(const ui_data_rt_t *a_snap) {
* 入口参数:a_snap - 源帧 const ui_data_par_t * * 入口参数:a_snap - 源帧 const ui_data_par_t *
* 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int * 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int
* 限定条件:同上;发布节拍 = 定值校验和变化才发 * 限定条件:同上;发布节拍 = 定值校验和变化才发
* (docs/UI设计/UI_数据供给设计说明.md §5.2) * (docs/UI设计/UI_数据供给设计.md §5.2)
*/ */
int ui_data_publish_par(const ui_data_par_t *a_snap) { int ui_data_publish_par(const ui_data_par_t *a_snap) {
if (a_snap == NULL) { if (a_snap == NULL) {
+14 -13
View File
@@ -3,16 +3,16 @@
* 模块功能:App 层 → UI 层唯一数据通道的"存侧"——只持有最新一帧实时量(rt)/ * 模块功能:App 层 → UI 层唯一数据通道的"存侧"——只持有最新一帧实时量(rt)/
* 参数(par)/装置信息(info) 快照 + 发布序号,给页面只读访问; * 参数(par)/装置信息(info) 快照 + 发布序号,给页面只读访问;
* 不取数、不格式化、不判断业务含义(职责边界 = * 不取数、不格式化、不判断业务含义(职责边界 =
* docs/UI设计/UI_数据供给设计说明.md §3.2) * docs/UI设计/UI_数据供给设计.md §3.2)
* 适用范围:Drivers/BSP/UI(表现层叶子:不 include 任何 App 头、不 include 任何 * 适用范围:Drivers/BSP/UI(表现层叶子:不 include 任何 App 头、不 include 任何
* 页面头、不碰 LVGL——分层方向由 scripts/check_layer_deps.py 守护, * 页面头、不碰 LVGL——分层方向由 scripts/check_layer_deps.py 守护,
* BSP → App 反向 include 一律拦提交) * BSP → App 反向 include 一律拦提交)
* 并发模型:写侧 = App/app/ui_data_feed.c(唯一发布者);读侧 = ui_page_* 的绘制/ * 并发模型:写侧 = App/app/ui_data_feed.c(唯一发布者);读侧 = ui_page_* 的绘制/
* 按键钩子。两侧同在 uiTask 上下文串行执行 → 无锁、无双缓冲、无 seqlock * 按键钩子。两侧同在 uiTask 上下文串行执行 → 无锁、无双缓冲、无 seqlock
* (判据与"将来出现第二发布者"时的扩展路径见 * (判据与"将来出现第二发布者"时的扩展路径见
* docs/UI设计/UI_数据供给设计说明.md §5.1) * docs/UI设计/UI_数据供给设计.md §5.1)
* 页面用法:行缓存按"发布序号变过才整帧拷"门控,勿逐行整帧拷贝 * 页面用法:行缓存按"发布序号变过才整帧拷"门控,勿逐行整帧拷贝
* (docs/UI设计/UI_数据供给设计说明.md §5.4): * (docs/UI设计/UI_数据供给设计.md §5.4):
* static ui_data_rt_t s_rt; * static ui_data_rt_t s_rt;
* static uint32_t s_seq; * static uint32_t s_seq;
* if (ui_data_rt_seq() != s_seq) { * if (ui_data_rt_seq() != s_seq) {
@@ -73,12 +73,12 @@ extern "C" {
/* /*
* 契约版本:结构体字段只允许尾部追加,追加即升此值并在写侧填默认值 * 契约版本:结构体字段只允许尾部追加,追加即升此值并在写侧填默认值
* (禁止删除或重排字段——页面按名字取,重排是静默错位; * (禁止删除或重排字段——页面按名字取,重排是静默错位;
* 口径 docs/UI设计/UI_数据供给设计说明.md §4.3) * 口径 docs/UI设计/UI_数据供给设计.md §4.3)
*/ */
/* v2(2026-10-26,道F task-1):ui_data_par_t 尾追加 cal_block——版本号是页面与 /* v2(2026-10-26,道F task-1):ui_data_par_t 尾追加 cal_block——版本号是页面与
* 写侧唯一的对齐凭据,追加字段不升版 = 老页面按新帧长 memcpy 时静默错位 * 写侧唯一的对齐凭据,追加字段不升版 = 老页面按新帧长 memcpy 时静默错位
* v3(2026-11-16):「开入开出」页——ui_data_rt_t 尾追加 dio_di_mask/dio_di_valid/ * v3(2026-11-16):「开入开出」页——ui_data_rt_t 尾追加 dio_di_mask/dio_di_valid/
* dio_do_mask/dio_do_valid(板级开入开出,208 B → 212 B,见 ui_data_rt_t 字段注) */ * dio_do_mask/dio_do_valid(板级开入开出,208 B → 216 B,见 ui_data_rt_t 字段注) */
#define UI_DATA_VER 3u #define UI_DATA_VER 3u
/* ── 通道数量 ─────────────────────────────────────────────────────────────── */ /* ── 通道数量 ─────────────────────────────────────────────────────────────── */
@@ -86,7 +86,7 @@ extern "C" {
/* 遥测语义通道数:下标序 = adc_semantic_t(UA/UB/UC/UN/IA/IB/IC/IN/TEMP)。 /* 遥测语义通道数:下标序 = adc_semantic_t(UA/UB/UC/UN/IA/IB/IC/IN/TEMP)。
* BSP 侧不得 include App 头,故"两数相等"的编译期守卫落在写侧 * BSP 侧不得 include App 头,故"两数相等"的编译期守卫落在写侧
* App/app/ui_data_feed.c,语义逐项对齐的断言落在 test/host/ui_data/ * App/app/ui_data_feed.c,语义逐项对齐的断言落在 test/host/ui_data/
* (docs/UI设计/UI_数据供给设计说明.md §9.4 一致性测试) */ * (docs/UI设计/UI_数据供给设计.md §9.4 一致性测试) */
#define UI_DATA_YC_N 9u #define UI_DATA_YC_N 9u
/* 遥信点数:与 104 点表同序(bit i = 第 i 点),页面名表按点表逐行登记 */ /* 遥信点数:与 104 点表同序(bit i = 第 i 点),页面名表按点表逐行登记 */
#define UI_DATA_YX_N 33u #define UI_DATA_YX_N 33u
@@ -183,7 +183,8 @@ typedef struct {
* 冒充点表事实,主站与屏会按两套语义读同一组位——那正是本仓最忌的静默错。 * 冒充点表事实,主站与屏会按两套语义读同一组位——那正是本仓最忌的静默错。
* 两族字段互不引用,页面各画各的,谁改了谁也不会悄悄改到另一边。 * 两族字段互不引用,页面各画各的,谁改了谁也不会悄悄改到另一边。
* 字段宽度:8 路 / 4 路各一字节即够,两块 mask/valid 合占 4 B,struct 由 208 B * 字段宽度:8 路 / 4 路各一字节即够,两块 mask/valid 合占 4 B,struct 由 208 B
* 变 212 B(对齐只到 4,无尾部填充);写侧共用缓冲 s_scr 因此 +4 B(宿主机单测 * 变 216 B(帧内 uint64_t 位图成员使整帧按 8 对齐,尾部再补 4 B);写侧共用
* 缓冲 s_scr 因此 +8 B(宿主机单测
* TC-UIDATA-021g 钉尺寸,改字段要同步那里) */ * TC-UIDATA-021g 钉尺寸,改字段要同步那里) */
uint8_t dio_di_mask; /* 8 路开入去抖后状态:bit n = 通道 n 合(1)。 uint8_t dio_di_mask; /* 8 路开入去抖后状态:bit n = 通道 n 合(1)。
* 来源 = defaultTask 的 DI 去抖快照 * 来源 = defaultTask 的 DI 去抖快照
@@ -213,7 +214,7 @@ typedef struct {
* 参数快照:40 项定值 Q10 原值 + 封存态 * 参数快照:40 项定值 Q10 原值 + 封存态
* 存 Q10 而非 float 的理由:定值是整表校验和覆盖的定点值,快照存浮点会引入 * 存 Q10 而非 float 的理由:定值是整表校验和覆盖的定点值,快照存浮点会引入
* "显示值与校验和口径不一致"的二义性(Q10 → 显示小数位换算属表现层,见 * "显示值与校验和口径不一致"的二义性(Q10 → 显示小数位换算属表现层,见
* docs/UI设计/UI_数据供给设计说明.md §8) * docs/UI设计/UI_数据供给设计.md §8)
*/ */
typedef struct { typedef struct {
uint32_t seq; /* 发布序号(本层盖章) */ uint32_t seq; /* 发布序号(本层盖章) */
@@ -240,7 +241,7 @@ typedef struct {
/* /*
* 装置信息快照(通道划分理由见本头文件头,契约侧同一条登记在 * 装置信息快照(通道划分理由见本头文件头,契约侧同一条登记在
* docs/UI设计/UI_数据供给设计说明.md §4.4——同一事实只在一处详述) * docs/UI设计/UI_数据供给设计.md §4.4——同一事实只在一处详述)
* 写侧随 rt 同节拍发布(内容基本不变,代价是一次约 90 B 拷贝) * 写侧随 rt 同节拍发布(内容基本不变,代价是一次约 90 B 拷贝)
*/ */
typedef struct { typedef struct {
@@ -302,7 +303,7 @@ int ui_data_publish_rt(const ui_data_rt_t *a_snap);
* 入口参数:a_snap - 源帧 const ui_data_par_t * * 入口参数:a_snap - 源帧 const ui_data_par_t *
* 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int * 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int
* 限定条件:同上;发布节拍 = 定值校验和变化才发 * 限定条件:同上;发布节拍 = 定值校验和变化才发
* (docs/UI设计/UI_数据供给设计说明.md §5.2) * (docs/UI设计/UI_数据供给设计.md §5.2)
*/ */
int ui_data_publish_par(const ui_data_par_t *a_snap); int ui_data_publish_par(const ui_data_par_t *a_snap);
@@ -370,7 +371,7 @@ uint32_t ui_data_info_seq(void);
/* ── 写路径:定值整定请求(页面只投递,执行在 App 侧)───────────────────── */ /* ── 写路径:定值整定请求(页面只投递,执行在 App 侧)───────────────────── */
/* /*
* 请求队列深度(契约 docs/UI设计/UI_数据供给设计说明.md §6.2 定死 4) * 请求队列深度(契约 docs/UI设计/UI_数据供给设计.md §6.2 定死 4)
* 为什么是 4 不是 1:整定页"保存"是用户按键,一条请求要等 App 侧 drain 才落定; * 为什么是 4 不是 1:整定页"保存"是用户按键,一条请求要等 App 侧 drain 才落定;
* 深度 1 会让连按两次保存把第二条判成"忙",而 4 格 = 本层 .bss 多 * 深度 1 会让连按两次保存把第二条判成"忙",而 4 格 = 本层 .bss 多
* 4 × sizeof(ui_data_param_req_t)(168 B/格,主机单测 TC-UIDATA-016 钉住尺寸, * 4 × sizeof(ui_data_param_req_t)(168 B/格,主机单测 TC-UIDATA-016 钉住尺寸,
@@ -461,7 +462,7 @@ int ui_data_param_request(const ui_data_param_req_t *a_req);
* 限定条件:无(只读单字,任意上下文安全) * 限定条件:无(只读单字,任意上下文安全)
* 函数说明:ERR_TIMEOUT(契约 §6.3 的"3 s 未取走")本层**不产出**——uiTask 每 * 函数说明:ERR_TIMEOUT(契约 §6.3 的"3 s 未取走")本层**不产出**——uiTask 每
* 10 ms 就 drain 一次,真出现"永不落定"说明 App 侧没接线,属装配缺陷; * 10 ms 就 drain 一次,真出现"永不落定"说明 App 侧没接线,属装配缺陷;
* 页面若要兜底可自己按投递时刻计时(docs/UI设计/UI_数据供给设计说明.md * 页面若要兜底可自己按投递时刻计时(docs/UI设计/UI_数据供给设计.md
* §6.3 已把它列为页面本地可选项) * §6.3 已把它列为页面本地可选项)
*/ */
int ui_data_param_state(void); int ui_data_param_state(void);
@@ -970,7 +971,7 @@ int ui_data_comm_set(uint8_t a_idx, uint32_t a_val);
*/ */
uint8_t ui_data_comm_pending(void); uint8_t ui_data_comm_pending(void);
/* ── 通道六:故障录波(wave)──────────────────────────────────────────────── /* ── 通道七:故障录波(wave)────────────────────────────────────────────────
* 页面零 App include、零存储触点:录波执行侧(触发投递 / 段索引 / 段头字段 / * 页面零 App include、零存储触点:录波执行侧(触发投递 / 段索引 / 段头字段 /
* 窗口码值与峰值 mV)全部经本注入表进来,真实现见 App/task/ui_task.c 的 * 窗口码值与峰值 mV)全部经本注入表进来,真实现见 App/task/ui_task.c 的
* s_wave_ops;PC 模拟器绑同一形状的假件(simulator/main.c)。取数口径的 * s_wave_ops;PC 模拟器绑同一形状的假件(simulator/main.c)。取数口径的
+1 -1
View File
@@ -41,7 +41,7 @@ void ui_w_records_bind(const ui_rec_reader_t *a_reader) {
* "清除"之后条数归零就是它唯一的真反馈),而 reader 是本组件私有 * "清除"之后条数归零就是它唯一的真反馈),而 reader 是本组件私有
* 的注入表;不开放一个只读入口,页面就只能自己去注第二份 reader, * 的注入表;不开放一个只读入口,页面就只能自己去注第二份 reader,
* 那正好把 task-6 刚削掉的分层反向边又接回来(口径见 * 那正好把 task-6 刚削掉的分层反向边又接回来(口径见
* docs/UI设计/UI_数据供给设计说明.md §7.2/§7.3)。 * docs/UI设计/UI_数据供给设计.md §7.2/§7.3)。
* 本函数不带行缓存:缓存属于"某一条记录的字段",与条数无关 * 本函数不带行缓存:缓存属于"某一条记录的字段",与条数无关
*/ */
uint16_t ui_w_records_count_of(uint8_t a_log_id) { uint16_t ui_w_records_count_of(uint8_t a_log_id) {
+1 -1
View File
@@ -113,7 +113,7 @@ void ui_w_records_bind(const ui_rec_reader_t *a_reader);
* 限定条件:uiTask 上下文(绘制/按键链) * 限定条件:uiTask 上下文(绘制/按键链)
* 函数说明:reader 是本组件私有的注入表,不开放只读入口的话,想按行显示条数的 * 函数说明:reader 是本组件私有的注入表,不开放只读入口的话,想按行显示条数的
* 页面只能自己去注第二份 reader——那正好把 task-6 刚削掉的分层反向边 * 页面只能自己去注第二份 reader——那正好把 task-6 刚削掉的分层反向边
* 接回来(口径 docs/UI设计/UI_数据供给设计说明.md §7.2/§7.3); * 接回来(口径 docs/UI设计/UI_数据供给设计.md §7.2/§7.3);
* 本函数不带行缓存(缓存属于"某条记录的字段",与条数无关) * 本函数不带行缓存(缓存属于"某条记录的字段",与条数无关)
*/ */
uint16_t ui_w_records_count_of(uint8_t a_log_id); uint16_t ui_w_records_count_of(uint8_t a_log_id);
+1 -1
View File
@@ -13,7 +13,7 @@
* ——id 与 App/algo/prot_set.h 枚举序的一致性由 test/host/ui_data 的主机单测 * ——id 与 App/algo/prot_set.h 枚举序的一致性由 test/host/ui_data 的主机单测
* 在两侧头文件同时可见的地方钉住(BSP 侧看不到 App 头,物理上无法自证) * 在两侧头文件同时可见的地方钉住(BSP 侧看不到 App 头,物理上无法自证)
* 值语义:q10[i] = 工程量 × 1024(App/app/ui_data_feed.c 只搬原值不换算,换算属表现层, * 值语义:q10[i] = 工程量 × 1024(App/app/ui_data_feed.c 只搬原值不换算,换算属表现层,
* docs/UI设计/UI_数据供给设计说明.md §8),本模块按行表 decimals 换算成 * docs/UI设计/UI_数据供给设计.md §8),本模块按行表 decimals 换算成
* "工程量 × 10^decimals" 交给 ui_w_setlist(其值通道契约) * "工程量 × 10^decimals" 交给 ui_w_setlist(其值通道契约)
* 适用平台:STM32F407ZGTx / PC 模拟器(共用源码) * 适用平台:STM32F407ZGTx / PC 模拟器(共用源码)
* 作者:王建锋 * 作者:王建锋
+1 -1
View File
@@ -10,7 +10,7 @@
* 显示名映射(本组件私有,属表现层):事件类型与元件都按**不透明编号**入参, * 显示名映射(本组件私有,属表现层):事件类型与元件都按**不透明编号**入参,
* 编号值与 App 侧枚举逐项相等(一致性由 test/host/ui_data 主机单测 * 编号值与 App 侧枚举逐项相等(一致性由 test/host/ui_data 主机单测
* 现场核对,不是照抄文档转述);文案是显示规格,不进快照也不进 App 层 * 现场核对,不是照抄文档转述);文案是显示规格,不进快照也不进 App 层
* (口径 docs/UI设计/UI_数据供给设计说明.md §8) * (口径 docs/UI设计/UI_数据供给设计.md §8)
* 适用范围:Drivers/BSP/UI(分层方向由 scripts/check_layer_deps.py 守护) * 适用范围:Drivers/BSP/UI(分层方向由 scripts/check_layer_deps.py 守护)
* 说明:reader 注入点已备好但**两端均未绑定**——SOE 文件的只读 API * 说明:reader 注入点已备好但**两端均未绑定**——SOE 文件的只读 API
* (条数 / 按序号读一条)尚未在落盘侧提供,绑定与页面接线属道E 后续 * (条数 / 按序号读一条)尚未在落盘侧提供,绑定与页面接线属道E 后续
+584
View File
@@ -0,0 +1,584 @@
# UI 数据供给设计
> **定位**:App 层到 UI 层(`Drivers/BSP/UI`)数据供给架构的**唯一权威描述**——三类快照帧的数据契约、写路径与分页读取的注入执行侧、并发模型、测试策略。读这一篇能回答"页面怎么拿到数、怎么落数、数从哪条通道来"。
> **问题来源**:`docs/UI设计/页面补齐规划.md` §1/§2.1(本层落地前,交流量/直流量全部为硬编码占位值)。
> **门禁口径**:`scripts/check_layer_deps.py` 的文件头写明三种合法做法(注入 / 上层取好传进来 / 叶子工具进 ALLOW)。本文选择并细化前两种。
> **前置阅读**:`docs/UI设计/内容页架构.md`(页面描述符与 4 个钩子)、`docs/架构设计/项目架构总览.md`(六层单向依赖)。
---
## 1. 问题与约束
### 1.1 为什么 UI 拿数据必须走专用通道
六层单向依赖规定 `Drivers/BSP/**` 不得 include `App/**` 的头,且这条规则已机械化(`scripts/check_layer_deps.py` 拦新增)。而 UI 需要的全部数据都在 `App/`:
| 数据 | 现居位置 | 层 |
|---|---|---|
| 相量(有效值/相角) | `App/algo/phasor.h` | 算法层 |
| 频率 | `App/algo/freq.h` | 算法层 |
| 定值(40 项 + 封存态) | `App/algo/prot_set.h` | 算法层 |
| 遥信位图 / 品质 | `App/protocol/iec104/iec104_pts.h` | 协议层 |
| 时钟 | `App/util/sys_clock.h` | 工具层(**已在 ALLOW 豁免内**) |
| 运行/自检记录 | `App/log/sys_log.h` | 服务层 |
历史上记录页曾为绕开这条规则直接 include `App/log/sys_log.h`,欠下三条分层基线——本层落地后那三条已还清(见 §7.3),`check_layer_deps.py` 的 `BASELINE` 现存三条全部属配置引擎与卷锁,与 UI 无关。
### 1.2 反模式:`extern` 全局变量
门禁只扫 `#include`。因此在 BSP 里写 `extern const float g_phasor_ua;` 就能**完全绕过检查**。
这是本设计明确禁止的做法,理由不是"门禁会拦",而是它比 include 更糟:
| 维度 | include 头 | extern 全局 |
|---|---|---|
| 编译期契约 | 有(类型/签名) | 无(类型写错是未定义行为) |
| 所有权 | 明确 | 无(谁写谁读说不清) |
| 并发 | 至少能看到调用 | 完全隐式 |
| 可测性 | 可桩替 | 必须链接真实现 |
| 门禁可见性 | 会报警 | **静默通过** |
**结论**:数据通道必须是**显式的、有契约的、可测的**,不能靠"能编过"。
---
## 2. 通道选型
### 2.1 候选与结论
| 方案 | 做法 | 依赖方向 | 绘制路径开销 | 可测性 | 并发 |
|---|---|---|---|---|---|
| **A 直连** | BSP include `App/algo/phasor.h` | BSP → App(**反向**) | 每行一次跨层调用 | 差(要链真实现) | 隐式 |
| **B extern** | BSP 声明 `extern` 全局 | 无(不可见) | 读全局 | 差 | 无保护 |
| **C 注入(pull)** | BSP 定义函数表、App 注入实现;UI 主动调 | App → BSP(**正确**) | 每行一次函数指针调用 | 好 | 调用时序耦合 |
| **D 快照推送(push)** | BSP 拥有快照存储 + 发布 API;App 周期组装并发布;页面只读本地快照 | App → BSP(**正确**) | 纯本地读 | 好(直接 publish 假帧) | 单写者 + 同上下文 |
取舍依据:A/B 依赖方向或契约不成立,直接出局;C 与 D 方向都正确,差别在**绘制路径是否还有跨层调用**、**页面是否与数据源解耦**(D 下页面只认快照结构,换数据源不改页面)、以及**模拟器能否发布固定帧喂黄金参考**(D 天然支持)。
**选 D 为主通道,C(注入)用于两类不适合快照的场景**:写路径(定值整定、维护动作——快照是只读语义,塞不进"请求")与分页读取(记录/SOE/录波——条数随运行增长,不能全量快照)。现行态 = 三类快照帧(§4.1/§4.2/§4.4)+ 一组注入函数表(§6.2/§6.4/§7.2/§7.4)。
### 2.2 为什么 D 能做到"高内聚"
- **内聚**:`ui_data` 只干一件事——存最新一帧并给出只读访问;`ui_data_feed` 只干一件事——把 App 的散装数据组装成一帧。两者都不含对方的知识。
- **耦合**:页面只依赖**一个结构体**,不依赖任何 App 模块;App 只依赖**一个发布函数**,不依赖任何 UI 概念(页面、行、几何一概不知)。
- **变化隔离**:将来遥测链(谐波方和根 + 平均 + 死区)深化,只改 `ui_data_feed` 里的取数来源,**页面零改动**;反过来页面改版式,**App 零改动**。
---
## 3. 总体架构
### 3.1 依赖方向
```mermaid
flowchart TB
subgraph APP["App 层(业务)"]
F["App/app/ui_data_feed.c<br/>组装一帧(唯一填充者)"]
SRC["phasor / freq / prot_set / iec104_pts / sys_clock"]
F --> SRC
end
subgraph BSP["Drivers/BSP/UI(表现层)"]
D["ui_data.c/h<br/>快照存储 + 只读访问器<br/>+ 定值写入队列与状态机"]
P["ui_page_ac / ui_page_yx / ui_w_setview+ui_w_setlist ...<br/>只读快照 + 格式化 + 布局(整定页另加写投递)"]
P --> D
P -- "整定保存:ui_data_param_request(&req)" --> D
end
T["App/task/ui_task.c<br/>调度:每轮调 feed_tick()"] --> F
T --> P
F -- "ui_data_publish_rt/par(&帧)" --> D
F -- "落定:ui_data_param_drain(&ops),执行侧由 App 注入" --> D
```
**include 方向**(全部合法):
| 文件 | include | 方向 |
|---|---|---|
| `App/app/ui_data_feed.c` | `ui_data.h`(BSP)+ 各 App 头 | App → BSP ✓ |
| `App/task/ui_task.c` | `ui_data_feed.h` + `ui_menu.h` | App → BSP ✓ |
| `Drivers/BSP/UI/ui_page_*.c` | `ui_data.h`(同层 BSP) | 同层 ✓ |
| `Drivers/BSP/UI/ui_data.c` | 仅 `stdint.h` / `string.h` | 零依赖 ✓ |
**`ui_data.c` 不 include 任何 App 头,也不 include 任何页面头**——它是叶子。
写路径与分页读取不给上表新增任何一行:它们走**反向调用**(BSP 声明函数表、App 提供实现并按节拍把表传进来,见 §6.2/§6.4/§7),所以 include 方向不变、`layer-deps` 基线不变。这类"下层定义抽象、上层实现并注入"的第三条腿全部通道共用,一条 `ALLOW` 都不新增。
### 3.2 三个模块的职责边界
| 模块 | 位置 | 只做 | 绝不做 |
|---|---|---|---|
| `ui_data` | `Drivers/BSP/UI/` | 存最新一帧、给只读访问、记发布序号;存定值写入请求队列、跑那台状态机(越界与闭锁的判定按注入的 ops 问,自己一条业务规则都不持有) | 取数、格式化、判断业务含义、碰 `prot_set` 与文件系统 |
| `ui_data_feed` | `App/app/` | 按节拍从各 App 模块取数、组装、发布;变化检测;每轮 drain 一条定值请求并注入执行侧实现 | 布局、字符串格式化、LVGL 调用 |
| 页面 `ui_page_*` | `Drivers/BSP/UI/` | 读快照、按行表格式化、交给框架绘制;整定态把改动攒在**编辑叠层**里(改动位图 + 工作值,`ui_w_setview.c` 模块级一份——同屏只开一页,与各查看页的行缓存同一假设),只在按"保存"时投递一次 | 直接调 App、自己算业务量、自己判越界(行内上下限只是**镜像**,用于早拦一手;真源在 App,见 §9.4 一致性测试) |
---
## 4. 数据契约
供给形态两条腿:**快照帧**(push,本节)适合"页面随帧刷新"的量;**注入函数表**(pull / 写)适合"按动作发生"与"分页读盘"的量,契约分别写在 §6.2(定值写)、§6.4(维护/整定/通讯/录波)、§7(记录/SOE)。
| 通道(快照) | 内容 | 节拍 | 写者 | 契约 |
|---|---|---|---|---|
| `rt`(实时量) | 遥测 9 路 + 品质、相量实例槽带、遥信位图、频率、时钟、板级开入开出 | 200 ms | `ui_data_feed`(uiTask 上下文) | §4.1 |
| `par`(参数) | 定值 40 项(Q10)+ 校验和 + 封存态 + 越界位图 + 未标定闭锁 | 变化触发 | `ui_data_feed`(同上下文) | §4.2 |
| `info`(装置信息) | 装置身份 + 通讯参数 + 运行时长 + 运行报告观测数 | 随 `rt` 同拍 | `ui_data_feed`(同上下文) | §4.4 |
### 4.1 实时快照 `ui_data_rt_t`
```c
#define UI_DATA_YC_N 9u /* 语义通道数:UA/UB/UC/UN/IA/IB/IC/IN/温度 */
#define UI_DATA_YX_N 33u /* 遥信点数(与 104 点表同序) */
#define UI_DATA_PH_MAX 8u /* 相量实例槽上限(含谐波),见正文槽带说明 */
/* 品质位(与 104 QDS 语义对齐,页面只消费自己关心的位) */
#define UI_DATA_Q_IV 0x01u /* 无效:该通道无源/不可用 → 页面显示 "--" */
#define UI_DATA_Q_NT 0x02u /* 未就绪:尚未攒满一周波/未收敛 */
#define UI_DATA_Q_OV 0x04u /* 越限:超过量程/削顶 */
#define UI_DATA_Q_SB 0x08u /* 取代值(虚拟注入/替身值) */
#define UI_DATA_Q_BL 0x10u /* 闭锁:该量被业务闭锁 */
#define UI_DATA_Q_RAW 0x20u /* 原始码值域:val 不是工程量而是转换器码值(TEMP 用) */
typedef struct {
float val; /* 数值;口径由 ui_data_rt_t.eng 决定 */
uint8_t qds; /* 品质位组合 */
uint8_t rsv[3]; /* 对齐填充(显式命名,勿留匿名空洞) */
} ui_data_yc_t; /* 每元素 8 B */
typedef struct {
uint32_t seq; /* 发布序号(单调递增;页面据此判"是否需重建行缓存") */
uint32_t tick_ms; /* 发布时刻(tick 域,差值法可比) */
uint8_t valid; /* 0 = 尚无首帧(页面显示 "--") */
uint8_t eng; /* 量纲口径:0 = 引脚电压(现状)/ 1 = 二次值 / 2 = 一次值(预留) */
uint8_t rsv[2];
ui_data_yc_t yc[UI_DATA_YC_N]; /* 下标 = adc_semantic_t 语义序(基波有效值) */
uint8_t ph_n; /* 本帧发布的相量实例槽数(0..UI_DATA_PH_MAX) */
uint8_t rsv4[3];
ui_data_yc_t ph[UI_DATA_PH_MAX]; /* 下标 = 相量实例序(含谐波) */
uint64_t yx_bits; /* 遥信位图:bit i = 第 i 点"合/动作" */
uint64_t yx_valid; /* 遥信有效位图:bit i = 1 该点有硬件来源 */
uint64_t yx_dp; /* 遥信双点位图:bit i = 1 该点是双点型(M_DP) */
uint8_t freq_valid;
float freq_hz;
uint8_t clock_ok; /* 0 = 时钟无效(RTC 异常) */
char clock[20]; /* "YYYY-MM-DD HH:MM:SS" 固定长度,无指针 */
/* 板级开入开出(遥信量页末尾 12 行消费),与上面三张点表位图互不引用 */
uint8_t dio_di_mask; /* 8 路开入去抖后状态:bit n = 通道 n 合 */
uint8_t dio_di_valid; /* 0 = 无数据源 / 本次读失败(mask 为上次已知值,不可当新数据) */
uint8_t dio_do_mask; /* 4 路开出影子寄存器:bit n = 吸合(**软件意图**,非机械反馈) */
uint8_t dio_do_valid; /* 0 = 本帧未取到影子寄存器 */
} ui_data_rt_t; /* 216 B:uint64_t 成员使整帧按 8 对齐,尾部 4 B 填充 */
```
**要点**:
- **`eng` 字段是诚实性的关键**:标定层 `adc_cal` 的 ROM 默认系数按**引脚侧 LSB** 定死(TPAFE 152.59 µV/码、STM32 805.66 µV/码),采样环折算出来的 `val` 现在是 **ADC 引脚电压 V**——既不是千级码值,也不是端子二次值。承诺边界的依据是 `docs/算法/采集与算法层设计说明.md` §13.5:这一波只承诺到"引脚电压","端子二次值"要等变比确认与多点标定。所以页面文案是 `eng=0` → "未标定"、`eng=1` → "二次值",而不是"码值";升档条件写在 `App/app/ui_data_feed.c` 的 `feed_eng()`——**电气 8 路 `adc_cal_flags()` 的 VALID 全置位才升**(整帧共用一个 `eng`,只要还有一路是引脚电压就不能给整帧贴"二次值"标签,宁可整体保守)。TEMP 不参与线性标定 → 该路恒带 `UI_DATA_Q_RAW`,页面据此不挂单位、不与其他路互比。
- **`ph[]` 相量实例槽带**与 `yc[]` 语义通道带并存的理由:谐波(`Ia` 的二次/五次)无法在"语义通道"下标空间里表达——同一通道的谐波会与基波撞位,而交流量页要显示它们(`docs/UI设计/页面扩充详细方案.md` §3.1.1)。槽带按**相量实例序**索引,实际发布槽数由 `ph_n` 给出、超上限的实例本帧不发布(写侧口径在 `App/app/ui_data_feed.c` 的 `fill_rt()`)。两条带的元素同形(数值 + 品质),页面行表按需选一条。上限 8 = 现用 5 实例(UA/UN/IA 基波 + IA 二次/五次)+ 遥测谐波轨留位。
- **字符串只用定长数组**:`clock[20]` 在结构体内,无指针、无生命周期问题(跨层传指针是经典事故源)。
- **`yx_valid` 与 `yx_bits` 分开**:无效点不参与显示、不参与变位判断(沿用 104 点表的既有做法,避免"IV 通道抖动成变位")。
- **`yx_dp`**:单点还是双点是 **104 点表事实**(`App/protocol/iec104/iec104_pts.c` 的 `YX_DP_N` / `iec104_pts_yx_is_dp()`),由写侧 `ui_data_feed.c` 逐点问点表后下发位图;页面只按位图选词(双点"合位/分位"、单点"动作/复归"、无效 "--")。把"前 4 点是双点"抄进表现层就是第二真相:点表改成双点段挪位或加高起始下标,屏上不会报错,只会用错词形容同一个点。V0.1 这 4 点无开入硬件 → 不在 `yx_valid` 内,值列仍打 "--"(本字段不参与无效判定)。点数一致性由写侧一条一次性 `DBG_ERROR` 兜(`UI_DATA_YX_N` 与 `iec104_pts_yx_count()` 不等时留痕),因为该常量在协议层是 .c 内的 `#define`,编译期拿不到。
- **板级开入开出四字段**(`dio_di_*` / `dio_do_*`)四条口径:
1. **板级引脚 ≠ 104 点表**:这四字段与 `yx_bits` / `yx_valid` / `yx_dp` 互不引用。板级开入 8 路与点表 33 点没有映射关系,把引脚状态塞进点表位图 = 篡改点表事实(点表 YX1~4 开关位置点在 V0.1 仍恒无效)。
2. **读失败语义**:开入经 `ioboard_di_snap_lookup()` → `ioboard_di_snap_read()` 取数(defaultTask 的 DI 去抖快照,`App/util/ioboard_di.h`,写侧按序号协议取一致值,不直接读引脚)。读不到(未登记 / 快照无效 / 读期被持续抢占)时 `dio_di_valid = 0`、mask 沿用**上一次成功读到的值**,绝不填 0——全 0 在现场等于"开入全部复归"。开出只读驱动影子寄存器(`ioboard_do_get()`),零硬件访问。
3. **`dio_do_mask` 是软件意图**(上次成功写入的值),不是继电器机械吸合实测;本平台无辅助触点回读通路,屏上文案不得让人以为读到了机械反馈。
4. **消费者**:遥信量页(`ui_page_yx.c`)末尾 12 行——前 8 行开入、后 4 行开出,与 33 点遥信同页不同源;模拟器构建无 ioboard 驱动,`dio_di_valid = 0`、显 "--"。
### 4.2 参数快照 `ui_data_par_t`
```c
#define UI_DATA_SET_N 40u /* 定值项数(与 prot_set 枚举同序,见 §9.4 一致性测试) */
#define UI_DATA_VER 3u /* 契约版本;字段只尾追加、追加即升版(§4.3) */
typedef struct {
uint32_t seq;
uint32_t checksum; /* 与 prot_set_checksum() 同值:页面据此判"参数是否变过" */
uint8_t valid;
uint8_t locked; /* 定值闭锁(校验和自检失败等)—— 定值**写不进去** */
uint8_t bad_valid; /* 越界位图有效 */
uint8_t rsv;
uint64_t bad_mask; /* 40 位:置 1 = 该定值项越界 */
int32_t q10[UI_DATA_SET_N]; /* Q10 原值;页面按行表的小数位换算显示 */
uint8_t cal_block; /* 未标定闭锁(判据停走)—— 定值**仍可改** */
} ui_data_par_t; /* 192 B(8 字节对齐,尾部补齐) */
```
**为什么存 Q10 而不是 float**:定值是**整表校验和覆盖的定点值**,快照存浮点会引入"显示值与校验和口径不一致"的二义性。Q10 → 显示值的小数位换算属表现层(§8)。
**`locked` 与 `cal_block` 是两个事实,屏上是两条通道、两个词,不得合并**(判据口径 `docs/算法/采集与算法层设计说明.md` §13.4):
| 字段 | 真源 | 说的是什么事 | 屏上落点 | 还能改定值吗 |
|---|---|---|---|---|
| `locked` | `prot_set_locked()`(定值校验和自检失配) | 这台装置现在**写不进去** | 整定页保存行值列 `LOCK`,且 ENTER 一律不消费(禁编辑) | ❌ |
| `cal_block` | `adc_cal_prot_blocked()`(`App/algo/adc_cal.c`:UA/UN/IA 三路 `ADC_CAL_F_VALID` 全齐才放行。**判据停走用的是同一个函数**——`App/task/protect_task.c` 的 `s_cal_locked()` 也调它,全仓一份判定;机器证据 = `test/host/adc_cal` 的 host 单测) | 定值能改,但**改了也不会动作**(判据停走) | 整定页标题右侧「未标定」徽标 | ✅ |
合成一个词就等于互相冒充:现场看到 `LOCK` 会以为"改了白改"而不去标定,看到「未标定」会以为"这台装置写不进定值"而放弃正当的整定操作。两个字段的取数都在 `App/app/ui_data_feed.c` 完成,页面零 App include(分层方向由 `scripts/check_layer_deps.py` 守住)。
**`cal_block` 的口径不是 `rt.eng`**:`eng` 是整帧量纲档(要求电气 8 路全 VALID),V0.1 双转换器下 UB/UC/IB/IC/IN 永不置位 → `eng` 恒为引脚档,照 `eng` 画徽标就成了"标定做完屏上仍永不解锁"。
**尺寸纪律**:帧长与关键字段偏移由 `test/host/ui_data` 的尺寸/偏移断言钉住——组装缓冲 `s_scr` 是 rt/par/info 的联合体、最大者是 rt,par 的字段追加是否"免费"取决于这条关系,帧长一变那处就是唯一会撒谎的地方。
### 4.3 扩展规则
- **只允许尾部追加字段**,结构体开头保留 `seq/valid`。
- 追加字段必须同时升 `UI_DATA_VER`(编译期常量),并在 `ui_data_feed` 里填默认值。版本号是页面与写侧唯一的对齐凭据,追加字段不升版 = 老页面按新帧长 memcpy 时静默错位。
- **禁止删除或重排字段**(页面按名字取,重排是静默错位)。
### 4.4 装置信息快照 `ui_data_info_t`
`info` 承载**既不属于 200 ms 实时量、也不属于校验和门控参数帧**的那批量:
| 字段组 | 内容 | 为什么不塞进已有的两条通道 |
|---|---|---|
| `model` / `sw_ver` / `hw_ver` / `build_date` / `sw_sum` | 装置身份(型号、软硬件版本、程序日期、软件校验) | 编译期常量,一辈子不变;塞进 `rt` 等于每 200 ms 白拷约 60 B 字符串 |
| `uptime_s` | 开机运行时长 | 每秒都在变;塞进 `par` 会被"校验和没变就不重发"的门控冻住(页面显示一个不再增长的时长 = 假数据) |
| `port_104` / `port_disp` / `ftp_user` | 通讯参数(104 端口、远程显示端口、FTP 用户名) | 值必须在 App 侧取(页面不得自己 include 协议头,`docs/UI设计/页面扩充详细方案.md` §3.5),但它们是静态量,与遥测节拍无关 |
| `boot_count` / `boot_seq_state` / `boot_write_failed` / `rst_cause` / `boot_ready` | 开机账本(运行报告页前半) | 与装置身份同属"慢变、非节拍、零指针"的一批,info 帧已是它们的属主 |
| `iec104_conn_up` / `iec104_apdu_tx` / `iec104_tx_fail` / `iec104_rx_bytes` | 104 观测计数(运行报告页后半) | 同上;四个数是 `App/task/iec104_serv.h` 的只读观测值,搬运不换算 |
- 结构与两条主通道同构:`seq` + `valid` 打头、定长字符数组、零指针、由 `ui_data` 盖章序号、由 `App/app/ui_data_feed.c` 独家填充(`feed_fill_info()` 只做逐字段拷贝,不换算、不在别处再算一份时长——`uptime_s` 仍由该函数按 tick 差算),随实时帧同节拍发布。
- **公共地址 CA 故意不在本帧**:固件里 CA 是逐帧从 ASDU 头解析的,没有集中常量可取;等 104 侧给出查询点再按 §4.3 的扩展规则追加字段并升 `UI_DATA_VER`。通讯设置页要显示/修改的 CA 走通讯参数注入表(§6.4),那是"读写"不是"快照"。
- **`boot_ready == 0` 表示整组开机账本不可信**,页面必须显示 `--` 而不是 0;`boot_seq_state` 的四态(未判定 / 首次 / 延迟写入 / 掉电丢失)语义唯一出处是 `App/util/boot_stats.h` 的四数台账,屏上文案(类别标签、"禁写终身次数""跨开机累计不做"两条口径)归 `Drivers/BSP/UI/ui_page_runreport.c` 文件头。同一事实只在一处详述。
- 版本类字段目前是 `App/app/ui_data_feed.c` 里的宏(仓库内没有产品级版本登记表,值沿用页面既有显示值,有正式口径后只改那一处);**软件校验位在拿到构建期 CRC 生成步骤之前一律显示 `--`**,不抄参考项目遗留值。
---
## 5. 并发与时序
### 5.1 单写者 + 同上下文(核心简化)
**约定**:`rt` / `par` / `info` 的**唯一发布者**是 `ui_data_feed_tick()`,它在 **uiTask 上下文**运行;页面的读取也在 uiTask 上下文(绘制钩子与按键钩子都跑在 `ui_task_func` 主循环里,见 `docs/UI设计/内容页架构.md` §六)。
→ **读写同线程,不需要锁、不需要双缓冲、不需要 seqlock。**
这一点值得展开,因为它与"直觉上要加保护"相反:
| 顾虑 | 实际情况 |
|---|---|
| 发布时页面正在绘制? | 不可能:绘制与发布都在 uiTask,串行执行 |
| 104 主站写定值会改快照? | 不会:主站只改 `prot_set`,快照由 feed 下一拍重新拉取 |
| 其他任务要推数据? | 不允许——要加新数据,就在 feed 里加取数,仍由 uiTask 发布 |
**如果将来真出现第二个发布者**(例如 netTask 收到主站写定值后要"立刻"刷新 UI),扩展路径是:给 `ui_data` 内部加"双槽 + 每槽 seq"(写非活动槽 → 盖 seq → 翻转单字节活动下标,同 `phasor` 双区先例)。**页面代码不受影响**——这正是把并发策略藏在 `ui_data` 内部的价值。
### 5.2 发布节拍
| 通道 | 节拍 | 理由 |
|---|---|---|
| `rt`(`info` 同拍两帧连发) | **200 ms**(内部计数分频,UI tick 10 ms × 20,`FEED_RT_PERIOD_MS`) | 与遥测链目标刷新率一致;人眼在 160×160 单色屏上感知不到更快 |
| `par` | **变化触发**:每轮比三个各自独立的变化源——`prot_set_checksum()`(定值改动)、`prot_set_locked()`(自检闭锁)、`cal_block`(标定完成),**任一翻转就重发一帧** | 定值变化是低频事件,只盯校验和能省下每拍的 192 B 拷贝;但 `locked` 与 `cal_block` 都**不改动校验和**,只盯校验和会让保存行的 `LOCK` 与标题的「未标定」永远停在旧值上(真机现象:标定做完了徽标还挂着,直到某次定值改动被顺带刷掉——那是把两件不相干的事当同步点) |
`ui_data_feed_tick()` 每轮调用是**廉价**的:一次 tick 差值判断 + 一次 uint32 比较 + 两次字节比较(`locked`/`cal_block` 上一帧值)。真正的组装只在到期或有源翻转时发生,无变化时零拷贝。
### 5.3 启动时序
```
内核启动前:ui_data_init()(清零 + valid=0)—— 纯内存操作,无 OS 依赖
↓
uiTask 起来(NET_READY 屏障后):注入类绑定先完成(见 §6.4 绑定时序)→ ui_menu_init() → 进入主循环
↓
首轮循环:ui_data_feed_tick() 立即发布首帧(不等 200 ms)
↓
首帧之前任何页面被打开:valid=0 → 全部显示 "--"(不显示 0.000,避免误读为真实零值)
```
**为什么首帧要立即发**:待机屏与菜单屏在启动早期就可能被远端推流打开,若等 200 ms 会出现"一闪的 `--`"。首帧立即发布后,页面从第一帧就是真值(或明确的"未就绪")。
### 5.4 页面的行缓存(性能)
框架的 `refresh(row, name, value)` 是**逐行调用**的(每帧每行一次)。若每行都 `ui_data_rt(&snap)` 拷 216 B,一页 8 行 = 1.7 KB/帧的冗余拷贝。
**做法**:页面用 `ui_data_rt_seq()` 判"快照是否变过",变过才整帧拷进**页面私有静态缓存**,其余行只读缓存。
```c
static ui_data_rt_t s_rt; /* 页面私有缓存 */
static uint32_t s_seq; /* 上次拷贝时的序号 */
static void pg_refresh(uint16_t row, char *name, char *value) {
uint32_t seq = ui_data_rt_seq(); /* 轻量查询:只读一个 uint32 */
if (seq != s_seq) { /* 快照变过才整帧拷贝 */
(void)ui_data_rt(&s_rt);
s_seq = seq;
}
/* 以下只读 s_rt,按行表格式化 */
}
```
> 用 `ui_data_rt_seq()` 门控而不是"row==0 才刷新",是为了避免依赖"框架总从第 0 行开始绘制"这一隐式时序假设——框架换绘制顺序时页面不会静默出错。
### 5.5 框架级自动失效(实时页不靠按键也有新数)
§5.4 的 seq 门解决"取数不冗余",不解决"什么时候该重绘":框架旧行为是**按键触发绘制才走 `refresh()`**——`rt` 帧每 200 ms 在发,人停在「交流量」页不动按键,屏上数值就是冻结的。
机制:`content_page_def_t` 尾部两个可选字段,定时器由**框架 `ui_content_page` 统一持有**(开页创建、关页销毁,同时最多一只),页面模块禁止自造轮询定时器:
| 字段 | 语义 |
|---|---|
| `uint16_t auto_ms` | 0 = 关闭(保持旧行为;指定初始化未写即 0);>0 = 该页打开期间的轮询周期 |
| `uint32_t (*auto_seq)(void)` | 新鲜度来源;NULL(缺省)= `ui_data_rt_seq()`;读 `info` 通道的页面可填 `ui_data_info_seq()` |
每拍框架调 `ui_content_page_auto_poll()`(回调经 uiTask 主循环 `lv_timer_handler` 触发,与绘制钩子同上下文):**序号变了才整页失效,没变零动作**——不拷帧、不失效、不重绘,稳态开销与旧行为一致;取数门控仍走 §5.4 的页面私有 seq 缓存,失效只是把"下次按键才有机会读新帧"变成"到点就有机会读新帧"。
当前口径:
- **六个实时页全部接入**。seq 恒随帧前进,所以轮询周期 = 稳态整页重绘频率——可见内容变化越慢取档越大:`ac`/`dc` 300 ms(电气量随 rt 帧帧帧推进;取值账目:轮询不得快于 200 ms 发布节拍、避开 400 ms 与其锁相、300 = 15 × LVGL 整刷周期 20 ms(两端 `LV_DEF_REFR_PERIOD` 同值),最坏屏上滞后 200 + 300 = 500 ms;全文在 `ui_page_ac.c` 的 `AC_AUTO_MS` 注释);`yx` 500 ms(变位低频事件,按"1 s 内上屏"到位——最坏 700 ms,较 300 档少 40% 稳态重绘);`clock` 1000 ms(快变项只有墙钟秒尾,快于 1 s 的轮询只会把同一秒多画几遍);`device_info`/`runreport` 1000 ms 并显式 `.auto_seq = ui_data_info_seq`(`info` 与 `rt` 同拍,见 §5.2)。各页取值账目在该页描述符注释里,本文不复述。
- **不迁移**:待机屏 `ui_standby.c`(自持 1 s 整屏定时器 + seq 门控)、整定视图 `ui_w_setview.c`(`sv_poll` 定时器盯 `par` 通道)——两处各自已有节拍,纳入框架只会多一只定时器。
**回归确定性**:无头模式(`--keys` / 74 张黄金参考)从不跑 `lv_timer_handler`,定时器不可能在截屏前触发,且仿真仍是"一次发布冻结帧"——黄金参考逐字节不变(`check_content_pages.py` 实证)。自动失效路径的验证走开关 `--rtlive <键序> <A.bin> <B.bin>`:开页截 A → 发布第 1 号确定性斜坡帧 → **直接调用** `ui_content_page_auto_poll()`(等价定时器到点)→ 截 B;A≠B 即证明"零按键、新帧落屏"。窗口模式每 200 ms 发一帧斜坡值,屏上数值自己会走。
---
## 6. 写路径
### 6.1 为什么 UI 不能直写
- `prot_set_set()` 之后**必须** `prot_set_seal()` 重算校验和;逐项写会把校验和打成中间态,被自检判为损坏。
- 落盘由 `defaultTask`(配置引擎属主)执行,UI 直接写盘会撞单写者纪律。
- 越界校验是 all-or-nothing:任一项越界整表不装载。
### 6.2 定值写:请求 / 状态交接(复用 `net_cfg` 范式)
交接链路:
```
ui_page_view_param / _set / _word / _plate(整定态:123 授权 → attach_edit 绑 set/commit/state)
│ 选中"保存"行按 ENTER(组件 ui_w_setlist_key 先过两道门:可写权限 + state()!=LOCK)
▼
sv_commit():req.mask = 改动位图;req.q10[] 只按 mask 置位的槽换算(显示值 → Q10)
▼
ui_data_param_request(&req) ← 本层只投递,不执行、不判越界、不碰文件系统
│ 静态环形队列,深度 4(UI_DATA_PARAM_QD);满 → -1(页面显 ERR + 页脚"忙")
│ 入队 = 168 B 整条拷入(.bss 4 × 168 = 672 B;零堆、零变长拷贝)
▼
ui_data_feed_tick()(App 侧,uiTask 上下文;先 drain 再比校验和,顺序即判据)
│ ui_data_param_drain(&s_param_ops):每轮最多落定一条
│ ② ops->locked() == 1 → ERR_LOCKED,**本条丢弃**(不排队等解锁)
│ ③ ops->check() 按 mask 逐项整批预检,任一项越界 → ERR_RANGE + err_mask,一字不写
│ ④ 预检全过再逐项 ops->apply() → prot_set_set_sealed()(只写 mask 内的 id)→ OK
│ 值真的变了 → 同轮重发 par 帧(页面按 seq 失效缓存)
▼
ui_data_param_state() / ui_data_param_err_mask()(保存行显词 + 越界行反显)
```
四个公开函数(声明 `Drivers/BSP/UI/ui_data.h`、实现 `ui_data.c`,全在本层,零 App include):
| 函数 | 作用 | 返回值口径 |
|---|---|---|
| `ui_data_param_request()` | 投递一条请求(页面"保存"的唯一出口) | `0` 已入队;**`mask=0` 的空请求也返 0**,但不占槽位、直接落终态 OK(一个都没改就按保存是正常操作,报 ERR 会让现场以为装置有问题);`-1` 队列满;`-2` 参数无效(NULL,或 `mask` 含 `UI_DATA_SET_N` 以上的位——调用方的编程错误不该落成屏上的"越界") |
| `ui_data_param_state()` | 回读写路径状态 | `UI_DATA_PARAM_ST_{IDLE,WAIT,OK,ERR_RANGE,ERR_LOCKED,ERR_BUSY}` |
| `ui_data_param_err_mask()` | 最近一条**被本次预检挡下**的项位图 | bit i = 1 → 第 i 项越界;最近终态不是 `ERR_RANGE` 时恒 0 |
| `ui_data_param_drain()` | 落定一条(App 装配节拍入口) | `1` 处理并提交了一条;`0` 队列空(状态不动);`-1` ops 或其函数指针为 NULL |
**"算不算越界"与"现在能不能写"都是 App 侧事实,本层一份都不复制**:执行能力经 `ui_data_param_ops_t`(`locked` / `check` / `apply` 三个函数指针)由 `App/app/ui_data_feed.c` **每次调 drain 时注入**,本层不保存副本。原因有两条,都不含糊:① 分层方向硬约束——`Drivers/BSP/**` 不得 include `App/**`(`scripts/check_layer_deps.py` 拦提交),而上下限真源在 `App/algo/prot_set.c` 的 `g_prot_set_meta`;② 注入表**刻意不含任何范围数值**,多传一份上下限就是第二真源、就会漂。与 §7.2 记录页的注入式 reader 一条路子,额外的好处是主机单测可以把三个指针换成桩件,于是**队列与状态机的生产代码**(不是副本)能在 PC 上把"满队列 / 越界不改值 / 闭锁拒写 / 正常往返"跑全(`test/host/ui_data/`)。
**请求形状 = 「位图 + 定长 40 槽」(168 B)而不是「项数 + 变长 id 数组」**:表现层的编辑叠层本就是一张改动位图 + 一张工作值表,本形状与它逐位同构 → 提交侧一次赋值、执行侧逐项按位取,两侧都不必维护第三种表示;定长还让队列退化成 O(1) 静态数组。边界与代价:`mask` 只有 64 位 → 定值项数硬上限 64(`ui_data.c` 有编译期守卫,破 64 是编译失败而不是静默丢项);队列 672 B + 控制字 16 B 是买"整批原子 + 零变长 + 零堆"的价钱(`docs/内存管理/RAM使用分析与优化方案.md`)。
> ⚠ **提交侧必须只提交 `mask` 内置位的 id,绝不"从显示值回提全表"**:Q10 存不下 0.95 这类返回系数(实际存 972/1024),按显示域往返会把用户没动的项顺手改掉。判据"越界值不落盘"与"改哪条只落哪条"都建在这条上(判据见 `docs/UI设计/内容页架构.md` §7.1)。换算的往返精度因此也**不需要**逐位可逆:没动的行根本不进换算函数。
**这套结构与 `net_cfg` 的 `net_cfg_save_request` / `net_cfg_save_state` 完全同构**(`Drivers/BSP/NETCFG/net_cfg.h`),不引入新范式——这是"低耦合"的另一个含义:**项目里同类问题只有一种解法**。
### 6.3 失败语义
落定结果只有 6 个值(`UI_DATA_PARAM_ST_*`),页面侧的**词与位置**由整定视图统一映射,四张整定页共用一套(组件按 `state()` 回调给的值画保存行值列,页面不参与解释):
| 状态 | 含义 | 保存行值列 | 页面附带动作 | 产出方 |
|---|---|---|---|---|
| `IDLE` | 本次打开页面从未投递过 | `ENTER` | — | 本层初值 |
| `WAIT` | 已投递、队列里还有请求在路上 | `WAIT` | 编辑叠层**保留**(不清稿) | `request` 受理 / `drain` 未排空 |
| `OK` | 已逐项写入并置脏 | `OK` | 按 `commit` 位图清掉叠层,让位给新帧 | `drain` 第④步 |
| `ERR_RANGE` | 整批预检有任一项越界 → **一字未写** | `ERR` | 用 `ui_data_param_err_mask()` 反显越界行 | `drain` 第③步 |
| `ERR_LOCKED` | 投递时定值闭锁 → **本条丢弃** | `LOCK` | 反显同 `ERR_RANGE`;`drain` 不回滚(`prot_set` 无回滚接口,谎称"整批未写"比如实报更坏) | `drain` 第②步 |
| `ERR_BUSY` | 投递被拒:队列满 | `ERR` | 页脚"忙,请重试";**在队请求一条不动**,用户直接再按一次保存 | `request` 返 -1 |
三条实现侧口径:
1. **`LOCK` 还有一个与状态机无关的来源**:帧里 `par.locked == 1` 时保存行**直接显 `LOCK` 并禁 ENTER**(优先级高于历史结果)。闭锁是持续状态,不该只在"某次投递被拒"那一帧才说一次;禁编辑必须落在键路上,只靠屏上词会让用户白改一轮。
2. **`ERR_TIMEOUT`("3 s 未取走")本层不产出**——uiTask 每 10 ms 就 drain 一次,真出现"永不落定"是 App 侧没接线的装配缺陷,不是运行期状态。页面若要兜底,可自己按投递时刻计时(属页面本地可选项,当前没做:没有消费者就别先加一条无人走的分支)。
3. **状态是全局单值,页面必须锁存显示**:`ui_data_param_state()` 落定后一直停在那个值上,直读会让用户移动一下光标就看到别的页留下的旧结果。整定视图把它锁存成"本页投过一次才显示那次的答案、开页复位成 `ENTER`"(`ui_w_setview.c` 的 `s_disp`)。
> 词表刻意用 ASCII(`ENTER`/`WAIT`/`OK`/`ERR`/`LOCK`)与 `net_cfg` 保存行同排;中文「未标定」徽标是**另一件事**(`cal_block`),见 §4.2 的两源两通道表,不要为了省一个词把它并进 `LOCK`。
### 6.4 其余注入执行侧(常驻函数表)
定值写之外的四条"按动作发生"的通道,全部走同一个模式:**BSP 声明函数表 + 绑定入口,App 提供实现,模拟器镜像一份实现**;执行侧表里刻意不含任何范围数值(第二真源会漂)。与定值通道的差别只在绑定时机——定值 ops 是每次调 drain 现传(本来就有每轮节拍),这四张表**常驻绑定**(维护动作无固定节拍,每轮传 = 空转)。
| 通道(语义名) | 函数表 | 件数与要点 | 消费者 | 行为与数值的权威描述 |
|---|---|---|---|---|
| 维护动作 | `ui_data_maint_ops_t`(`ui_data_maint_bind()`,uiTask 启动时绑) | `clock_set`(写后必须回读复核)/ `reset_req`(`prot_elm_request_reset()`)/ `active_count`(`popcount(prot_elm_active_mask())`)/ `oper_note`(`syslog_post_quiet(SYSLOG_OPER)`,谁触发谁投 104 与本地各一条)/ `clear_req`(`syslog_request_clear()`)/ `clear_state`(`syslog_clear_state()`) | 装置维护 3 页(对时 / 强制复归 / 清除记录) | `docs/UI设计/内容页架构.md` §7 |
| 遥测整定 | `ui_data_yt_ops_t`(`ui_data_yt_bind()`,feed 首轮懒绑,先于 `ui_menu_init`) | 死区 9 行(电气 8 + 频率,与 104 0x8030~0x8038 同序)+ 系数 8 路:`db_n/db_row/db_set`、`cal_n/cal_row/cal_k_set`、`cal_blocked`、`pending` | 遥测整定页(`ui_w_ytview`) | 行语义/单位/上下限归 `App/algo/run_par.c` 与 `App/algo/adc_cal.c`;`unit`/`decimals` 归装配层 `ui_data_feed.c`;lo/hi 唯一出口 `run_par_db_range()` / `RUN_PAR_K_MAX_UV`,页面不得抄数 |
| 通讯参数 | `ui_data_comm_ops_t`(`ui_data_comm_bind()`,与遥测整定同点位相邻) | `row` / `set` / `pending` 共 2 行:CA(1..65535,**改后重启生效**)与 104 端口(1024..65535,下次重 bind 监听生效) | 通讯设置页 | 真源 `App/protocol/iec104/iec104_comm.h`;行名行数归页面 |
| 录波回放 | `ui_data_wave_ops_t`(`ui_data_wave_bind()`,uiTask 启动时绑) | 7 件:`manual_req`(手动触发录波)/ 入场作废缓存钩子 / `seg_first/seg_prev/seg_next`(段导航,环形回绕)/ `seg_head`(事件名+触发字+削顶)/ `seg_win`(40 点码值 + 窗口峰值) | 录波回放页 | 取数口径唯一真源 `docs/子系统设计/故障录波设计说明.md` §6.3 |
三条共用口径:
- **三态诚实**:录波通道的段读取返回 `UI_WAVE_OK / NONE(无段)/ BAD(不可读)`——画直线冒充波形 = 伪造证据;未绑定按 NONE 渲染空态,不崩。遥测整定的 `cal_blocked` 与定值通道的 `cal_block` 同一判据(§4.2)。
- **结果锁存**:遥测整定的落定是**整档全局**的(`[run_par]` 9 键 + `[adc_cal]` 两段一趟落盘),落定状态是全局单值——页面必须按 §6.3 第 3 条同款锁存显示,不得直读。
- **为什么必须常驻注入而不能页面直调 App**:模拟器不链 `sys_clock` / `prot_elm` / `iec104_serv` / 录波存储,页面直调真源函数是"MCU 编得过、模拟器链接期爆";注入表让两端各给实现,像素回归才有稳定的执行侧。
另有一对**纯换算 helper**(不属任何函数表):`ui_data_clock_to_epoch()` / `ui_data_clock_from_epoch()`(`ui_data.c`)——把 `clock[20]` 串与 Unix epoch 互转,供对时页预填。口径:**本地域无时区**(sys_clock 的 epoch 域本身就是本地时间,"顺手 +28800"是经典错);年 2000..2038、epoch ≤0x7FFFFFFF(2000 下限 = SD2506 年字段的相对值),闰年规则在 `to_epoch` 内判;两函数往返互逆由 `test/host/ui_data` 钉住。
清除记录状态常量的映射纪律:`UI_DATA_CLEAR_ST_NONE/OK/WAIT/FAIL` 与 `SYSLOG_CLEAR_*` **逐值相等**,由主机单测在同一 TU 里断言(值漂了编译期就红);模拟器侧记录是同步删除,没有 `WAIT` 态属正常。
---
## 7. 记录页:另一种通道(注入式 reader)
### 7.1 为什么记录不走快照
记录是**分页读文件**:条数随运行增长,不可能全量快照;且读盘有 I/O 延迟,不能放在绘制路径里同步做。
### 7.2 注入式 reader
`ui_w_records` 不接受任何 App 头,只接受一个只读函数表:
```c
/* Drivers/BSP/UI/ui_w_records.h —— 不含任何 App 头 */
typedef struct {
uint16_t (*count)(uint8_t log_id);
/* 返回 0 成功;-1 越界;-2 读失败 */
int (*get)(uint8_t log_id, uint32_t idx,
char *ts, uint32_t ts_len, char *desc, uint32_t desc_len);
} ui_rec_reader_t;
void ui_w_records_bind(const ui_rec_reader_t *reader); /* App 启动时注入 */
```
- `log_id` 用 `uint8_t`(**不透明编号**),BSP 不知道 `SYSLOG_RUN` 是什么,只知道"0 号日志"。
- 真机注入点在 `App/task/ui_task.c`(`ui_menu_init` 之前),实现体是 `sys_log` 的两个薄包装;模拟器同形镜像(`simulator/main.c` 的 `sim_rec_count/sim_rec_get`),无头与窗口两个初始化点都在 `ui_menu_init` 前调 `ui_w_records_bind`。UI 侧编号常量 `UI_W_REC_LOG_*` 的映射只在这两处适配层,UI 组件不感知 `syslog_id_t`。
- 七类记录(运行 / 自检 / 事故 / 告警 / 启动操作 / 遥控)共用这一张表,记录页与待机屏入口的映射表见 `docs/UI设计/内容页架构.md`。
### 7.3 收益:还掉三条存量分层基线
记录页走注入后,`scripts/check_layer_deps.py` 的 `BASELINE` 删掉了三条 UI 条目(`ui_page_runlog.c` / `ui_page_selftest.c` / `ui_w_records.h` → `App/log/sys_log.h`),基线 6 → 3。**基线"只减不增"**:现存 3 条全部属配置引擎(`net_cfg` / `ftp_cfg` → `cfg_file.h`)与卷锁(`lftpd_io` → `vol_lock.h`),与 UI 无关,明细见 `docs/门禁说明/layer-deps.md` §1。
### 7.4 SOE 记录:同构 reader(已绑定)
`/log/soe.log` 是**二进制**定长 64 B 记录(时标/类型/元件号/序号/值),不是"时间戳 + 文本描述",不能与 `ui_w_records` 混读,故另立同构组件 `Drivers/BSP/UI/ui_w_soe.c`:
- **注入式 reader** `ui_soe_reader_t`(`count()` + `get(idx, &view)`,错误码 0/-1 与 `ui_rec_reader_t` 同族);`get` 返回的是 **UI 侧视图结构** `ui_w_soe_rec_t`(时标串 + 不透明类型号 + 不透明元件号 + 标志 + 序号/值),适配层负责解码与 CP56 → 文本换算,UI 不 include `App/log/soe_rec.h`。
- **已绑定**:落盘侧只读 API `soe_store_count()` / `soe_store_read()` 在 `App/log/soe_store.h`;真机 reader 实现在 `App/task/ui_task.c`(`ui_task_soe_count/ui_task_soe_get`),模拟器在 `simulator/main.c` 同形假源。`soe_store_read()` 是 try 锁非阻塞——读盘绝不拖住 UI 节拍,读失败该行退化显示、不猜。
- **CP56 时标口径**:时标**取记录内的 CP56**(事件自己的时间),不用"现在"换算;CP56 分内毫秒字段在写侧恒为秒 ×1000,**不造假亚秒**;换算**不加 8 小时**——`sys_clock` 的 epoch 域本身就是本地时间,且 `App/log/soe_rec.c` 的 epoch→CP56 分解不加任何时区偏移,两条口径叠加后与文本记录页一致;哪天真要引入显式时区,两侧必须一起改(跨模块陷阱,注释即防线)。时钟无效(`SOE_FLG_IV`)是**显示语义**,由 UI 侧决定打"时钟无效",App 只交代原始记录。
- **显示名映射在 UI 侧**(`ui_w_soe_type_name()` / `ui_w_soe_elm_name()`):类型与元件都是**表现层文案**,不进快照也不回落到 App 层(同 §8 的格式化归属结论)。UI 侧另立一套不透明编号常量(`UI_W_SOE_T_*` / `UI_W_SOE_ELM_*`),其**数值与 App 枚举逐项相等**——这条等价关系不靠文档转述,由主机单测在同一 TU 里 include 两侧头逐项核对。
- 两条容易悄悄发生的错由单测钉住:**八类事件必须各自有名**(忘配名只会在屏上显示 `--`,像素门禁照不出来);**"采样闭锁/恢复"与"标定闭锁/复归"四名必须互不相同**(同名 = 现场把未标定闭锁读成采样故障)。缺的中文字形随事件走字体重生成流程补齐(`font-regen` skill)。
---
## 8. 格式化归属:谁决定小数位
**结论:格式化属表现层,全部在页面行表里;快照只给数值与品质。**
| 信息 | 归属 | 理由 |
|---|---|---|
| 数值(float / Q10) | 快照 | 业务事实 |
| 品质(IV/NT/OV) | 快照 | 业务事实 |
| 通道名("Ua"/"Ia") | 页面行表 | 显示文案 |
| 小数位(2 位/3 位) | 页面行表 | 显示规格 |
| 单位(V/A/Hz) | 页面行表 | 显示规格 |
| 无效符号(`--`) | 页面行表 | 显示规格 |
| 排序/分组/分页 | 页面行表 | 版式 |
行表结构相应扩展(在现有 `cp_row_t` 基础上加两个字段,或新增页面侧结构):
```c
typedef struct {
const char *name; /* "Ua" */
uint8_t src; /* 快照内下标(0..UI_DATA_YC_N-1) */
uint8_t dot; /* 小数位:电压 2 / 电流 3 / 频率 3 */
const char *unit; /* "V" / "A" / "Hz" */
} ui_ac_row_t;
```
**为什么不在快照里放格式化后的字符串**:那会让 App 知道"电压要 2 位小数",把显示规格漏进业务层——这正是要避免的耦合。
---
## 9. 可测试性
### 9.1 主机侧纯逻辑单测
`ui_data` 是纯内存模块,天然可测(`test/host/ui_data/`,已挂 pre-commit 钩子):
| 用例 | 判据 |
|---|---|
| 首帧前读取 | `ui_data_rt()` 返回 -1,`valid=0` |
| 发布后读取 | 字段逐项一致;`seq` 递增 |
| 参数变化检测 | checksum 不变 → 不重发;变 → 重发 |
| 请求队列 | 深度 4;满则 -1;取走后可再投 |
| 状态回读 | OK/ERR_RANGE/ERR_LOCKED 正确映射 |
| 尺寸与偏移 | rt/par/info 帧长与关键字节偏移逐项断言(字段追加改错对齐当场红) |
| 时钟换算 | `to_epoch/from_epoch` 往返互逆、闰年、上下限 |
页面渲染可在模拟器侧断言(见 §9.2),主机侧只测数据模块。
### 9.2 模拟器:固定帧保证 golden 稳定
`simulator/main.c` 不链接 `App/task/ui_task.c`,因此需要自己发布快照并注入实现:
- **golden 模式(现状唯一形态)**:`sim_publish_data_frames()` 一次性发布一帧**固定数据**(9 路值 + 位图 + 三帧),无头与窗口两个初始化点都调,与记录/SOE reader 注入同址、同"先于 `ui_menu_init`"纪律。**动态合成帧模式未实现**——golden 只需要固定帧,真需要人眼观察动态刷新时再加。
- 固定帧里的定值**不手抄 40 个数字**:把 `App/algo/prot_set.c`(零平台依赖的纯算法,双端共享核心)链进模拟器、`prot_set_init()` 后取出厂默认——抄表等于造第二真相。
- `build_date` 用**固定串**而不是 `__DATE__`:否则跨天重建会把装置信息页的黄金参考刷掉,而黄金参考是判据本身。
- 固定帧的 `cal_block` 显式填 1、`rt.eng` 按同一条口径钉在引脚档:**真机现在就是**未标定态,屏上的话必须与本机一致,模拟器才配当像素基准。
- **写路径在模拟器侧有一份同构的执行实现**(`sim_param_locked/check/apply` + `sim_param_pump()`,维护/整定/通讯/录波/reader 各通道同这条纪律):真机那段在 `App/app/ui_data_feed.c` 的 tick 里,模拟器不链接装配器,就在 `main.c` 里镜像一份——`check()` 用的仍是同一份 `g_prot_set_meta` 真源(链进来的 `App/algo/prot_set.c`),因此"模拟器里越界被拒"与"真机上越界被拒"是同一个判定,不是两份规矩。
- **落定与"页面自己发现数据变了"的分工**:`sim_param_pump()` 在无头模式排在注键之后、截图之前同步排空(真机由每 10 ms 的 tick 排);整定视图另有一条 100 ms 的 LVGL 轮询定时器,负责把"主站写进来的新值 / 标定完成 / 落定但不改校验和的 ERR"推上屏。**这条定时器在无头回归里一次都不会触发**——`run_headless()` 严禁调 `lv_timer_handler()`(I1+FULL 全屏刷新会进渲染死循环),所以黄金像素与它无关;两次连跑逐字节一致即为证据(`simulator/README.md` 同条注)。窗口模式才用它。
### 9.3 与"虚拟注入"的关系
`docs/UI设计/页面补齐规划.md` §5 记的厂家调试"虚拟注入"(未做),**天然落在 `ui_data_feed` 上**:注入值只要在 feed 组装时覆盖对应字段即可,**页面完全不知情**。
约束(必须写进代码注释):虚拟注入**只能在 feed 层覆盖快照字段**,绝不能改 `prot_set` / `phasor` 的输入——否则会污染保护判据路径。
### 9.4 一致性测试(防"魔法下标"漂移)
页面行表用**不透明下标**(`src` / `set_idx`),BSP 侧不知道它对应哪个 App 枚举——这是解耦的代价,必须用测试兜住:
| 断言 | 位置 | 内容 |
|---|---|---|
| 通道数一致 | `App/app/ui_data_feed.c` | `typedef char chk[(UI_DATA_YC_N == ADC_SEM_COUNT) ? 1 : -1];` |
| 定值项数一致 | 同上 | `typedef char chk2[(UI_DATA_SET_N == PS_ID_COUNT) ? 1 : -1];` |
| 整定行数与 `run_par` 一致、开入/开出数与 `ioboard` 一致 | 同上 | 同形编译期守卫(写侧是仓库内唯一同时见两侧头文件的 TU,守卫全部落这里) |
| 下标语义一致 | `test/host/ui_data/` | 主机测试同时 include 两侧头,逐项断言"页面表的 src/set_idx 指向预期枚举" |
最后一条是关键:**它把"跨层魔法数字"从运行期风险降级为编译/测试期错误**。
---
## 10. 内存与性能
| 项 | 量 | 说明 |
|---|---|---|
| `rt` 帧 | 216 B | 遥测 9 路 + 相量槽带 + 三张位图 + 时钟串 + 板级开入开出;三帧串行组装用的 `s_scr` 是联合体,**取最大者 = rt** |
| `par` 帧 | 192 B | 40×4 Q10 + 头部 + `cal_block`(8 字节对齐补齐);最大者是 rt,par 的字段追加由 rt 兜住,**净增 0**(尺寸关系由主机单测钉住,见 §4.2) |
| `info` 帧 | 116 B | 全部定长数组;预算 ≤128 B 由主机单测断言 |
| `ui_data.o` 全部静态 | `.bss` 约 1,200 B(`.map` 实测) | 三帧存储、`s_scr` 联合体、定值请求队列 4×168 = 672 B、控制字位图与状态机 |
| `ui_w_setview.o` 静态 | `.bss` 352 B / `.data` 48 B | 四视图行缓存 + **整定编辑叠层 190 B**(`int32_t[40]` + 三张位图 + 锁存态) |
| 页面行缓存 | 每页 ≈ 52 B(`ui_page_view_*.o` 各 `.bss` 52 B) | 定值相关页共用一份视图缓存(同屏只开一页),所以四张整定页**没有**再各存一份 192 B |
| LVGL 池 | 快照 0 B | 快照不进池(不是 LVGL 对象);池对象只有定时器:框架自动失效一只(统一持有,同时最多一只)+ 整定视图 `sv_poll` 一只 |
| 每 200 ms 拷贝 | 一帧(≤216 B),且只在变化时 | 一次 memcpy,微秒级 |
| 每轮(10 ms) | 0 次拷贝 | 比 seq / 比三个变化源;见 §5.2、§5.4 |
栈侧:uiTask 静态最坏链 **1,336 B / 配置 16 KB(余 15,048 B,91%)**,最坏链是 LVGL 建树那条;写路径自身都不深(`sv_commit` 帧 192 B 含 168 B 请求体、「未标定」徽标帧 160 B、按键链 `pg_key` 起算 480 B),**没有换人**。判据工具:`scripts/stack_report.py` 对每次权威构建跑调用图。
**结论**:代价 = 约 1.5 KB 静态 + 每 200 ms 一次 memcpy,换来整个 UI 层的数据可及性与一条可测的写路径。区域水位(RW_IRAM1 / RW_CCM / Flash)**不在本文复制**——那是受管快照,由 `scripts/ram_baseline.py` 从每次 `/keil-build` 的 `.map` 生成,第二处写死就是一份会过期的真源(口径见 `docs/内存管理/RAM使用分析与优化方案.md` §2.1 与 `docs/内存管理/RAM预算台账.md`)。
---
## 11. 反模式清单(禁止事项)
| # | 禁止 | 原因 |
|---|---|---|
| 1 | BSP 里 `extern` App 全局变量 | 绕过门禁且比 include 更危险(无契约/无所有权) |
| 2 | 页面直接 include `App/**` 头 | 门禁拦截;且页面被绑死在具体 App API |
| 3 | 快照里放指针或动态字符串 | 跨层生命周期事故;只用定长数组 |
| 4 | 每行 `refresh` 都整帧拷贝快照 | 8 行/帧冗余;用 seq 门控 |
| 5 | 在快照里放格式化后的字符串 | 显示规格漏进业务层 |
| 6 | 多个任务同时发布同一通道 | 破坏单写者约定;需要时在 `ui_data` 内部加保护,不改页面 |
| 7 | 虚拟注入改 `prot_set`/`phasor` 输入 | 会污染保护判据路径 |
| 8 | 定值逐项 `prot_set_set()` 不封存 | 校验和中间态 → 自检判损坏 |
| 9 | 为省事把 `sys_log.h` 加进 `ALLOW` | ALLOW 是"叶子工具"通道,`sys_log` 是有状态服务,加进去等于永久开后门 |
---
## 12. 与既有文档和门禁的关系
- **门禁**:`scripts/check_layer_deps.py` 的三种合法做法本文全部用上(快照推送=②,写路径与分页 reader=①),`ALLOW` 与 `BASELINE` 均无新增;`BASELINE` 现存 3 条无一属 UI(明细 `docs/门禁说明/layer-deps.md` §1)。
- **页面框架**:`docs/UI设计/内容页架构.md` 的 `refresh` / `count_cb` 钩子**签名不变**,页面只是改为从 `ui_data` 取数;装置维护 3 页与整定行为归 §7 该文档管辖。
- **页面清单**:`docs/UI设计/页面补齐规划.md` §2.1 的交流量/直流量两页即本文的消费端;其 §5 厂家设置支是"虚拟注入"(§9.3)的候选消费场景。
- **行表真值**:四张整定/查看行表与 `prot_set` 元数据的上下限一致性由 `tools/setview_check/check_setview_limits.py` 核验(BSP 侧看不到 App 头,物理上无法自证,必须有人从外面钉)——背景见 `docs/UI设计/页面扩充详细方案.md` §3.2。
- **录波取数口径**:本文只写通道形状(§6.4);段数据语义的唯一真源是 `docs/子系统设计/故障录波设计说明.md` §6.3。
- **数据真实性**:`docs/问题记录/采集与数据处理短板评测.md` 的标定(§4.1)与遥测链(§4.2)深化后,只需改 `ui_data_feed` 的取数来源与 `eng` 取值,页面零改动。
@@ -1,764 +0,0 @@
# UI 数据供给设计说明(高内聚低耦合)
> **定位**:解决"内容页拿不到实时数据"的架构问题——给出数据从 App 层到 UI 层的**唯一通道**、数据契约、并发模型、写路径与测试策略。
> **问题来源**:`docs/UI设计/页面补齐规划.md` §1/§2.1(本层落地前,交流量/直流量全部为硬编码占位值)。
> **门禁口径**:`scripts/check_layer_deps.py` 的文件头已写明三种合法做法(注入 / 上层取好传进来 / 叶子工具进 ALLOW)。本文选择并细化前两种。
> **前置阅读**:`docs/UI设计/内容页架构.md`(页面描述符与 4 个钩子)、`docs/架构设计/项目架构总览.md`(六层单向依赖)。
---
## 1. 问题与约束
### 1.1 现象
| 页 | 应该显示 | 实际显示 |
|---|---|---|
| 交流量 | 8 路电气量 + 温度的有效值 | 第 1 页写死实测值,第 2/3 页写死占位值 |
| 直流量 | 直流通道 | 3 行写死(`3.01/3.15/3.288`) |
页面代码本身没问题——**问题在于页面没有任何合法途径拿到 App 层的数据**。
### 1.2 根因
六层单向依赖规定 `Drivers/BSP/**` 不得 include `App/**` 的头,且这条规则已经机械化(`scripts/check_layer_deps.py`,2026-10-22 起拦新增)。而 UI 需要的全部数据都在 `App/`:
| 数据 | 现居位置 | 层 |
|---|---|---|
| 相量(有效值/相角) | `App/algo/phasor.h` | 算法层 |
| 频率 | `App/algo/freq.h` | 算法层 |
| 定值(40 项 + 封存态) | `App/algo/prot_set.h` | 算法层 |
| 遥信位图 / 品质 | `App/protocol/iec104/iec104_pts.h` | 协议层 |
| 时钟 | `App/util/sys_clock.h` | 工具层(**已在 ALLOW 豁免内**) |
| 运行/自检记录 | `App/log/sys_log.h` | 服务层 |
**已有的 3 条基线违规**(`ui_page_runlog.c` / `ui_page_selftest.c` / `ui_w_records.h` → `sys_log.h`)就是这条通道缺失的化石证据——当时为了做记录页,选择了"直接 include 上层头",门禁注释里写着"记录读取应由上层递进来",但**递进来的机制一直没建**。
### 1.3 反模式:`extern` 全局变量
门禁只扫 `#include`。因此在 BSP 里写 `extern const float g_phasor_ua;` 就能**完全绕过检查**。
这是本设计要明确禁止的做法,理由不是"门禁会拦",而是它比 include 更糟:
| 维度 | include 头 | extern 全局 |
|---|---|---|
| 编译期契约 | 有(类型/签名) | 无(类型写错是未定义行为) |
| 所有权 | 明确 | 无(谁写谁读说不清) |
| 并发 | 至少能看到调用 | 完全隐式 |
| 可测性 | 可桩替 | 必须链接真实现 |
| 门禁可见性 | 会报警 | **静默通过** |
**结论**:数据通道必须是**显式的、有契约的、可测的**,不能靠"能编过"。
---
## 2. 方案选型
### 2.1 四个候选
| 方案 | 做法 | 依赖方向 | 绘制路径开销 | 可测性 | 并发 |
|---|---|---|---|---|---|
| **A 直连** | BSP include `App/algo/phasor.h` | BSP → App(**反向**) | 每行一次跨层调用 | 差(要链真实现) | 隐式 |
| **B extern** | BSP 声明 `extern` 全局 | 无(不可见) | 读全局 | 差 | 无保护 |
| **C 注入(pull)** | BSP 定义 `ui_data_src_t` 函数指针表,App 启动时注入;UI 主动调 `src->get_yc(i)` | App → BSP(**正确**) | 每行一次函数指针调用 | 好 | 调用时序耦合 |
| **D 快照推送(push)** | BSP 拥有快照存储 + 发布 API;App 周期组装并发布;页面只读本地快照 | App → BSP(**正确**) | 纯本地读 | 好(直接 publish 假帧) | 单写者 + 同上下文 |
### 2.2 评分
| 维度 | A | B | C | D |
|---|---|---|---|---|
| 依赖方向正确 | ✗ | ✗ | ✓ | ✓ |
| 页面与数据源解耦(换数据源不改页面) | ✗ | ✗ | 部分(接口在 BSP,实现可换) | ✓(页面只认快照结构) |
| 绘制路径无跨层调用 | ✗ | ✓ | ✗ | ✓ |
| 主机单测可驱动 | ✗ | ✗ | ✓ | ✓ |
| 并发模型简单 | ✗ | ✗ | ✓ | ✓(单写者同上下文) |
| 模拟器 golden 可稳定 | ✗ | ✗ | 需假实现 | ✓(publish 固定帧) |
| 新增字段的扩散面 | 大 | 大 | 中(改接口 + 实现) | 小(改结构体 + 填充处) |
**选 D 为主通道**,C(注入)用于两类不适合快照的场景:**写路径**(定值整定)与**记录分页读取**(数据量随记录增长,不能全量快照)。
### 2.3 为什么 D 能做到"高内聚"
- **内聚**:`ui_data` 只干一件事——存最新一帧并给出只读访问;`ui_data_feed` 只干一件事——把 App 的散装数据组装成一帧。两者都不含对方的知识。
- **耦合**:页面只依赖**一个结构体**,不依赖任何 App 模块;App 只依赖**一个发布函数**,不依赖任何 UI 概念(页面、行、几何一概不知)。
- **变化隔离**:将来遥测链(谐波方和根 + 平均 + 死区)落地,只改 `ui_data_feed` 里的取数来源,**页面零改动**;反过来页面改版式,**App 零改动**。
---
## 3. 总体架构
### 3.1 依赖方向
```mermaid
flowchart TB
subgraph APP["App 层(业务)"]
F["App/app/ui_data_feed.c<br/>组装一帧(唯一填充者)"]
SRC["phasor / freq / prot_set / iec104_pts / sys_clock"]
F --> SRC
end
subgraph BSP["Drivers/BSP/UI(表现层)"]
D["ui_data.c/h<br/>快照存储 + 只读访问器<br/>+ 定值写入队列与状态机"]
P["ui_page_ac / ui_page_yx / ui_w_setview+ui_w_setlist ...<br/>只读快照 + 格式化 + 布局(整定页另加写投递)"]
P --> D
P -- "整定保存:ui_data_param_request(&req)" --> D
end
T["App/task/ui_task.c<br/>调度:每轮调 feed_tick()"] --> F
T --> P
F -- "ui_data_publish_rt/par(&帧)" --> D
F -- "落定:ui_data_param_drain(&ops),执行侧由 App 注入" --> D
```
**include 方向**(全部合法):
| 文件 | include | 方向 |
|---|---|---|
| `App/app/ui_data_feed.c` | `ui_data.h`(BSP)+ 各 App 头 | App → BSP ✓ |
| `App/task/ui_task.c` | `ui_data_feed.h` + `ui_menu.h` | App → BSP ✓ |
| `Drivers/BSP/UI/ui_page_*.c` | `ui_data.h`(同层 BSP) | 同层 ✓ |
| `Drivers/BSP/UI/ui_data.c` | 仅 `stdint.h` / `string.h` | 零依赖 ✓ |
**`ui_data.c` 不 include 任何 App 头,也不 include 任何页面头**——它是叶子。
写路径没有给上表新增任何一行:它走的是**反向调用**(BSP 声明函数表、App 提供实现并按节拍
把表传进来,见 §6.2),所以 include 方向不变、`layer-deps` 基线不变。这类"下层定义抽象、
上层实现并注入"的第三条腿在 §7.2 的记录页 reader 上已经用过一次,两次都不新增 `ALLOW` 条目。
### 3.2 三个模块的职责边界
| 模块 | 位置 | 只做 | 绝不做 |
|---|---|---|---|
| `ui_data` | `Drivers/BSP/UI/` | 存最新一帧、给只读访问、记发布序号;**存定值写入请求队列、跑那台状态机**(越界与闭锁的判定按注入的 ops 问,自己一条业务规则都不持有) | 取数、格式化、判断业务含义、碰 `prot_set` 与文件系统 |
| `ui_data_feed` | `App/app/` | 按节拍从各 App 模块取数、组装、发布;变化检测;**每轮 drain 一条定值请求并注入执行侧实现** | 布局、字符串格式化、LVGL 调用 |
| 页面 `ui_page_*` | `Drivers/BSP/UI/` | 读快照、按行表格式化、交给框架绘制;整态把改动攒在**编辑叠层**里(改动位图 + 工作值,`ui_w_setview.c` 模块级一份——同屏只开一页,与各查看页的行缓存同一假设),只在按"保存"时投递一次 | 直接调 App、自己算业务量、自己判越界(行内上下限只是**镜像**,用于早拦一手;真源在 App,见 §9.4 一致性测试) |
---
## 4. 数据契约
分**两条独立通道**,因为更新频率与语义完全不同:
| 通道 | 内容 | 节拍 | 写者 |
|---|---|---|---|
| `rt`(实时量) | 遥测 9 路 + 品质、遥信位图、频率、时钟 | 200 ms | `ui_data_feed`(uiTask 上下文) |
| `par`(参数) | 定值 40 项(Q10)+ 校验和 + 封存态 + 越界位图 | 变化触发 | `ui_data_feed`(同上下文) |
### 4.1 实时快照 `ui_data_rt_t`
```c
#define UI_DATA_YC_N 9u /* 语义通道数:UA/UB/UC/UN/IA/IB/IC/IN/温度 */
#define UI_DATA_YX_N 33u /* 遥信点数(与 104 点表同序) */
/* 品质位(与 104 QDS 语义对齐,页面只消费前 3 位) */
#define UI_DATA_Q_IV 0x01u /* 无效:该通道无源/不可用 */
#define UI_DATA_Q_NT 0x02u /* 未就绪:尚未攒满一周波 */
#define UI_DATA_Q_OV 0x04u /* 越限:超过量程/削顶 */
#define UI_DATA_Q_SB 0x08u /* 取代值 */
#define UI_DATA_Q_BL 0x10u /* 闭锁 */
#define UI_DATA_Q_RAW 0x20u /* 原始码值域:val 不是工程量而是转换器码值(TEMP 用) */
typedef struct {
float val; /* 数值;口径由 ui_data_rt_t.eng 决定 */
uint8_t qds; /* 品质位组合 */
} ui_data_yc_t;
typedef struct {
uint32_t seq; /* 发布序号(单调递增;页面据此判"是否需重建行缓存") */
uint32_t tick_ms; /* 发布时刻(tick 域,差值法可比) */
uint8_t valid; /* 0 = 尚无首帧(页面显示 "--") */
uint8_t eng; /* 量纲口径:0 = ADC 引脚电压(现状)/ 1 = 二次值 /
* 2 = 一次值(预留)——真值语义见下方"要点"第 1 条 */
ui_data_yc_t yc[UI_DATA_YC_N];
uint64_t yx_bits; /* 遥信位图:bit i = 第 i 点"合/动作" */
uint64_t yx_valid; /* 遥信有效位图:bit i = 1 该点有硬件来源 */
uint64_t yx_dp; /* 遥信双点位图:bit i = 1 该点是双点型(M_DP) */
uint8_t freq_valid;
float freq_hz;
uint8_t clock_ok; /* 0 = 时钟无效(RTC 异常) */
char clock[20]; /* "YYYY-MM-DD HH:MM:SS" 固定长度,无指针 */
/* v3 尾追加:板级开入开出(「开入开出」页),与上面三张点表位图互不引用 */
uint8_t dio_di_mask; /* 8 路开入:bit n = 通道 n 合 */
uint8_t dio_di_valid; /* 0 = 无数据源 / 本次读失败(mask 为上次已知值,不可当新数据) */
uint8_t dio_do_mask; /* 4 路开出影子寄存器:bit n = 吸合(**软件意图**,非机械反馈) */
uint8_t dio_do_valid; /* 0 = 本帧未取到影子寄存器 */
} ui_data_rt_t;
```
**要点**:
- **`eng` 字段是诚实性的关键**(【2026-10-25 落地注】本条原写"0 = 原始码值(未标定)、`val` 是 ADC 码值(千级)",那是标定落地前的旧口径,已按现场改真值语义):标定层 `adc_cal` 的 ROM 默认系数按**引脚侧 LSB**定死(TPAFE 152.59 µV/码、STM32 805.66 µV/码),采样环折算出来的 `val` 现在是 **ADC 引脚电压 V**——既不是千级码值,也不是端子二次值。承诺边界的依据是 `docs/算法/采集与算法层设计说明.md §13.5`:这一波只承诺到"引脚电压","端子二次值"要等变比确认与多点标定。所以页面文案是 `eng=0` → "未标定"、`eng=1` → "二次值",而不是"码值";升档条件写在 `App/app/ui_data_feed.c` 的 `feed_eng()`——**电气 8 路 `adc_cal_flags()` 的 VALID 全置位才升**(整帧共用一个 `eng`,只要还有一路是引脚电压就不能给整帧贴"二次值"标签,宁可整体保守)。TEMP 不参与线性标定 → 该路恒带 `UI_DATA_Q_RAW`,页面据此不挂单位、不与其他路互比。
- **字符串只用定长数组**:`clock[20]` 在结构体内,无指针、无生命周期问题(跨层传指针是经典事故源)。
- **`yx_valid` 与 `yx_bits` 分开**:无效点不参与显示、不参与变位判断(沿用 104 点表的既有做法,避免"IV 通道抖动成变位")。
- **`yx_dp`(2026-10-25 批 4 追加)**:单点还是双点是 **104 点表事实**(`iec104_pts.c` 的 `YX_DP_N`
/ `iec104_pts_yx_is_dp()`),由写侧 `ui_data_feed.c` 逐点问点表后下发位图;页面只按位图选词
(双点"合位/分位"、单点"动作/复归"、无效 "--")。把"前 4 点是双点"抄进表现层就是第二真相:
点表改成双点段挪位或加高起始下标,屏上不会报错,只会用错词形容同一个点。V0.1 这 4 点无开入
硬件 → 不在 `yx_valid` 内,值列仍打 "--"(本字段不参与无效判定)。点数一致性由写侧一条
一次性 `DBG_ERROR` 兜(`UI_DATA_YX_N` 与 `iec104_pts_yx_count()` 不等时留痕),因为该常量
在协议层是 .c 内的 `#define`,编译期拿不到。
### 4.2 参数快照 `ui_data_par_t`
```c
#define UI_DATA_SET_N 40u /* 定值项数(与 prot_set 枚举同序,见 §9.2 一致性测试) */
#define UI_DATA_VER 3u /* 契约版本;字段只尾追加、追加即升版(§4.3) */
typedef struct {
uint32_t seq;
uint32_t checksum; /* 与 prot_set_checksum() 同值:页面据此判"参数是否变过" */
uint8_t valid;
uint8_t locked; /* 定值闭锁(校验和自检失败等)—— 定值**写不进去** */
uint8_t bad_valid; /* 越界位图有效 */
uint8_t rsv;
uint64_t bad_mask; /* 40 位:置 1 = 该定值项越界 */
int32_t q10[UI_DATA_SET_N]; /* Q10 原值;页面按行表的小数位换算显示 */
uint8_t cal_block; /* v2 尾追加:未标定闭锁(判据停走)—— 定值**仍可改** */
} ui_data_par_t; /* 当前 192 B(v2 前 184 B;尾字节由 8 字节对齐补齐) */
```
**为什么存 Q10 而不是 float**:定值是**整表校验和覆盖的定点值**,快照存浮点会引入"显示值与校验和口径不一致"的二义性。Q10 → 显示值的小数位换算属表现层(§8)。
**`locked` 与 `cal_block` 是两个事实,屏上是两条通道、两个词,不得合并**(判据口径
`docs/算法/采集与算法层设计说明.md §13.4`):
| 字段 | 真源 | 说的是什么事 | 屏上落点 | 还能改定值吗 |
|---|---|---|---|---|
| `locked` | `prot_set_locked()`(定值校验和自检失配) | 这台装置现在**写不进去** | 整定页保存行值列 `LOCK`,且 ENTER 一律不消费(禁编辑) | ❌ |
| `cal_block` | `adc_cal_prot_blocked()`(`App/algo/adc_cal.c`:UA/UN/IA 三路 `ADC_CAL_F_VALID` 全齐才放行。**判据停走用的是同一个函数**——`App/task/protect_task.c` 也调它,道F task-16 起全仓一份判定、`DTU_BENCH` 旁路也只有这一处;机器证据 = `test/host/adc_cal` 的 TC-ADCCAL-018) | 定值能改,但**改了也不会动作**(判据停走) | 整定页标题右侧「未标定」徽标 | ✅ |
合成一个词就等于互相冒充:现场看到 `LOCK` 会以为"改了白改"而不去标定,看到「未标定」
会以为"这台装置写不进定值"而放弃正当的整定操作。两个字段的取数都在 `App/app/ui_data_feed.c`
完成,页面零 App include(分层方向由 `scripts/check_layer_deps.py` 守住)。
> 【v2 落地注(2026-10-26,道F task-1)】本次只尾追加 `cal_block`,帧长 184 → 192 B;
> 组装缓冲 `s_scr` 是 rt/par/info 的联合体,而最大者是 **rt(208 B)**,所以这笔追加
> 实际**没多花一字节 RAM**——这条"谁兜住了谁"的关系由主机单测的尺寸断言钉住
> (帧长一变,那处注释就是唯一会撒谎的地方)。升 `UI_DATA_VER` 是必须的:版本号是
> 页面与写侧唯一的对齐凭据,追加字段不升版 = 老页面按新帧长 memcpy 时静默错位。
> 【v3 落地注(2026-11-16,「开入开出」页)】`ui_data_rt_t` 尾追加
> `dio_di_mask` / `dio_di_valid` / `dio_do_mask` / `dio_do_valid`(板级 8 路开入 +
> 4 路开出),`UI_DATA_VER` 2 → 3。四条口径:
> 1. **板级引脚 ≠ 104 点表**:这四字段与 `yx_bits` / `yx_valid` / `yx_dp` 互不引用。
> 板级开入 8 路与点表 33 点没有映射关系,把引脚状态塞进点表位图 = 篡改点表事实
> (点表 YX1~4 开关位置点在 V0.1 仍恒无效)。
> 2. **读失败语义**:开入经 `ioboard_di_snap_lookup()` → `ioboard_di_snap_read()`
> 取数。读不到(未登记 / 快照无效 / 读期被持续抢占)时 `dio_di_valid = 0`、mask
> 沿用**上一次成功读到的值**,绝不填 0——全 0 在现场等于"开入全部复归"。
> 开出只读驱动影子寄存器(`ioboard_do_get()`),零硬件访问。
> 3. **`dio_do_mask` 是软件意图**(上次成功写入的值),不是继电器机械吸合实测;
> 本平台无辅助触点回读通路,屏上文案不得让人以为读到了机械反馈。
> 4. **尺寸**:4 字段偏移 208..211 连续,但整帧 208 → **216 B**(尾部 `char[20]` 后
> 原有 4 B 对齐填充被顶满,再补 4 B 新填充)。组装缓冲 `s_scr` 以 rt 为最大者,
> 故 .bss 实涨 8 B。偏移与尺寸由 `test/host/ui_data` 的 TC-UIDATA-021g/i~j/o~r 钉住。
### 4.3 扩展规则
- **只允许尾部追加字段**,结构体开头保留 `seq/valid`。
- 追加字段必须同时升 `UI_DATA_VER`(编译期常量),并在 `ui_data_feed` 里填默认值。
- **禁止删除或重排字段**(页面按名字取,重排是静默错位)。
### 4.4 通道三:装置信息 `ui_data_info_t`(2026-10-25 落地新增)
落地时比本文原稿多出一条同构通道,承载**既不属于 200 ms 实时量、也不属于校验和门控参数帧**的那批量:
| 字段 | 内容 | 为什么不塞进已有的两条通道 |
|---|---|---|
| `model` / `sw_ver` / `hw_ver` / `build_date` / `sw_sum` | 装置身份(型号、软硬件版本、程序日期、软件校验) | 编译期常量,一辈子不变;塞进 `rt` 等于每 200 ms 白拷约 60 B 字符串 |
| `uptime_s` | 开机运行时长 | 每秒都在变;塞进 `par` 会被"校验和没变就不重发"的门控冻住(页面显示一个不再增长的时长 = 假数据) |
| `port_104` / `port_disp` / `ftp_user` | 通讯参数(104 端口、远程显示端口、FTP 用户名) | 值必须在 App 侧取(页面不得自己 include 协议头,`docs/UI设计/页面扩充详细方案.md` §3.5),但它们是静态量,与遥测节拍无关 |
- 结构与两条主通道同构:`seq` + `valid` 打头、定长字符数组、零指针、由 `ui_data` 盖章序号、由 `App/app/ui_data_feed.c` 独家填充,随实时帧同节拍发布。
- **公共地址 CA 故意不在本帧**:固件里 CA 是逐帧从 ASDU 头解析的,没有集中常量可取;等 104 侧给出查询点再按 `docs/UI设计/UI_数据供给设计说明.md` §4.3 的扩展规则追加字段并升 `UI_DATA_VER`。
- 版本类字段目前是 `App/app/ui_data_feed.c` 里的宏(仓库内没有产品级版本登记表,值沿用页面既有显示值,有正式口径后只改那一处);**软件校验位在拿到构建期 CRC 生成步骤之前一律显示 `--`**,不抄参考项目遗留值。
**2026-10-28 追加(「运行报告」页落地)**:info 帧尾部追加 9 个字段,把运行报告要用的四个数从 App 侧搬下来——
`boot_count` / `boot_seq_state` / `boot_write_failed` / `rst_cause` / `boot_ready`(来自 `App/util/boot_stats.h` 的开机账本)与
`iec104_conn_up` / `iec104_apdu_tx` / `iec104_tx_fail` / `iec104_rx_bytes`(来自 `App/task/iec104_serv.h` 的四个只读观测计数)。
- **为什么不另开第二条注入通道**:这些量与装置身份同属`慢变、非节拍、零指针`的一批,info 帧已是它们的属主;
再开一个 reader 就是把 task-6 刚收紧的分层反向边接回来(记录页那套注入表是因为要读**盘**,本批不读盘)。
- **搬运不算第二份口径**:`feed_fill_info()` 只做逐字段拷贝,不换算、不在别处再算一份时长(`uptime_s` 仍由本函数按 tick 差算)。
- **屏上文案归 UI**:四个数各自的类别标签(「自电池周期」「本次开机」)、`boot_ready == 0` 显 `--` 而不是 0、
以及「禁写终身次数」「跨开机累计不做」这两条口径,落在 `Drivers/BSP/UI/ui_page_runreport.c` 文件头;口径出处只在
`App/util/boot_stats.h` 四数台账与本节各述一次(同一事实只在一处详述,`docs/文档规范.md` 同此要求)。
- 代价(本批
`/keil-build` 实测,0 错 0 警):
`Program Size` 由本批前
Code=235536 RO=26392 RW=1572 ZI=136924 变为 Code=236456 RO=28124 RW=1876 ZI=137084(ROM 合计 +2,652 B)
→ **RAM 合计 +464 B**(RW +304 / ZI +160)。逐对象(.map):5 个记录页各 60 B
`.data`(每页一份
`ui_w_records_t` 读盘缓存,
按实例存是记录页注入改造时定下的纪律,共享会串页);`ui_page_runreport.o` 116 B
`.bss`(信息帧本地缓存 + 发布序号);
info 帧字段增量落在 `ui_data.o`(1,192 B
`.bss`,同对象还装 rt / par 两通道的双区)与 `ui_data_feed.o`(217 B)里。
随帧发布不新增拷贝节拍。水位:
`RW_IRAM1` 62.2% / `RW_CCM` 87.9%(阈值 92%),
`mem-budget` PASS,
台账已由 `scripts/ram_baseline.py --update` / `--write` 回填(docs/内存管理/RAM预算台账.md)。 `/keil-build` 后回填),未触 `mem-budget` 92% 红线。
> 另一处落地细化:`ui_data_rt_t` 除 `yc[]`(语义通道序基波有效值)外还带一条 `ph[]` 相量实例槽带(`ph_n` 给实际槽数)。原因是谐波(`Ia` 的二次/五次)无法在"语义通道"下标空间里表达——同一通道的谐波会与基波撞位,而交流量页要显示它们(`docs/UI设计/页面扩充详细方案.md` §3.1.1 第 4/5 行)。两条带的元素同形(数值 + 品质),页面行表按需选一条。
---
## 5. 并发与时序
### 5.1 单写者 + 同上下文(核心简化)
**约定**:`rt` 与 `par` 的**唯一发布者**是 `ui_data_feed_tick()`,它在 **uiTask 上下文**运行;页面的读取也在 uiTask 上下文(绘制钩子与按键钩子都跑在 `ui_task_func` 主循环里,见 `docs/UI设计/内容页架构.md` §六)。
→ **读写同线程,不需要锁、不需要双缓冲、不需要 seqlock。**
这一点值得展开,因为它与"直觉上要加保护"相反:
| 顾虑 | 实际情况 |
|---|---|
| 发布时页面正在绘制? | 不可能:绘制与发布都在 uiTask,串行执行 |
| 104 主站写定值会改快照? | 不会:主站只改 `prot_set`,快照由 feed 下一拍重新拉取 |
| 其他任务要推数据? | 不允许——要加新数据,就在 feed 里加取数,仍由 uiTask 发布 |
**如果将来真出现第二个发布者**(例如 netTask 收到主站写定值后要"立刻"刷新 UI),扩展路径是:给 `ui_data` 内部加"双槽 + 每槽 seq"(写非活动槽 → 盖 seq → 翻转单字节活动下标,同 `phasor` 双区先例)。**页面代码不受影响**——这正是把并发策略藏在 `ui_data` 内部的价值。
### 5.2 发布节拍
| 通道 | 节拍 | 理由 |
|---|---|---|
| `rt` | **200 ms**(内部计数分频,UI tick 10 ms × 20) | 与遥测链目标刷新率一致;人眼在 160×160 单色屏上感知不到更快 |
| `par` | **变化触发**:每轮比三个各自独立的变化源——`prot_set_checksum()`(定值改动)、`prot_set_locked()`(自检闭锁)、未标定判定(标定完成),**任一翻转就重发一帧** | 定值变化是低频事件,只盯校验和能省下每拍的 192 B 拷贝;但 `locked` 与 `cal_block` 都**不改动校验和**,只盯校验和会让保存行的 `LOCK` 与标题的「未标定」永远停在旧值上(真机现象:标定做完了徽标还挂着,直到某次定值改动被顺带刷掉——那是把两件不相干的事当同步点) |
`ui_data_feed_tick()` 每轮调用是**廉价**的:一次 tick 差值判断 + 一次 uint32 比较 + 两次字节比较(`locked`/`cal_block` 上一帧值)。真正的组装只在到期或有源翻转时发生,无变化时零拷贝。
### 5.3 启动时序
```
内核启动前:ui_data_init()(清零 + valid=0)—— 纯内存操作,无 OS 依赖
↓
uiTask 起来(NET_READY 屏障后):ui_menu_init() → 进入主循环
↓
首轮循环:ui_data_feed_tick() 立即发布首帧(不等 200 ms)
↓
首帧之前任何页面被打开:valid=0 → 全部显示 "--"(不显示 0.000,避免误读为真实零值)
```
**为什么首帧要立即发**:待机屏与菜单屏在启动早期就可能被远端推流打开,若等 200 ms 会出现"一闪的 `--`"。首帧立即发布后,页面从第一帧就是真值(或明确的"未就绪")。
### 5.4 页面的行缓存(性能)
框架的 `refresh(row, name, value)` 是**逐行调用**的(每帧每行一次)。若每行都 `ui_data_rt(&snap)` 拷 130 B,一页 8 行 = 1 KB/帧的冗余拷贝。
**做法**:页面用 `ui_data_rt_seq()` 判"快照是否变过",变过才整帧拷进**页面私有静态缓存**,其余行只读缓存。
```c
static ui_data_rt_t s_rt; /* 页面私有缓存 */
static uint32_t s_seq; /* 上次拷贝时的序号 */
static void pg_refresh(uint16_t row, char *name, char *value) {
uint32_t seq = ui_data_rt_seq(); /* 轻量查询:只读一个 uint32 */
if (seq != s_seq) { /* 快照变过才整帧拷贝 */
(void)ui_data_rt(&s_rt);
s_seq = seq;
}
/* 以下只读 s_rt,按行表格式化 */
}
```
> 用 `ui_data_rt_seq()` 门控而不是"row==0 才刷新",是为了避免依赖"框架总从第 0 行开始绘制"这一隐式时序假设——框架换绘制顺序时页面不会静默出错。
### 5.5 框架级自动失效(实时页不靠按键也有新数)
§5.4 的 seq 门解决"取数不冗余",不解决"什么时候该重绘":框架旧行为是**按键触发绘制才走 `refresh()`**——`rt` 帧每 200 ms 在发,人停在「交流量」页不动按键,屏上数值就是冻结的。
新机制(task-2):`content_page_def_t` 尾部新增两个可选字段,定时器由**框架 `ui_content_page` 统一持有**(开页创建、关页销毁,同时最多一只),页面模块禁止自造轮询定时器:
| 字段 | 语义 |
|---|---|
| `uint16_t auto_ms` | 0 = 关闭(保持旧行为;指定初始化未写即 0);>0 = 该页打开期间的轮询周期 |
| `uint32_t (*auto_seq)(void)` | 新鲜度来源;NULL(缺省)= `ui_data_rt_seq()`;读 `info` 通道的页面可填 `ui_data_info_seq()` |
每拍框架调 `ui_content_page_auto_poll()`(回调经 uiTask 主循环 `lv_timer_handler` 触发,与绘制钩子同上下文):**序号变了才整页失效,没变零动作**——不拷帧、不失效、不重绘,稳态开销与旧行为一致;取数门控仍走 §5.4 的页面私有 seq 缓存,失效只是把"下次按键才有机会读新帧"变成"到点就有机会读新帧"。
当前口径:
- **六个实时页全部接入(用户裁定 2026-11-13)**。seq 恒随帧前进,所以轮询周期 = 稳态整页重绘频率——可见内容变化越慢取档越大:`ac`/`dc` 300 ms(电气量随 rt 帧帧帧推进;取值账目:轮询不得快于 200 ms 发布节拍、避开 400 ms 与其锁相、300 = 15 × LVGL 整刷周期 20 ms(两端 `LV_DEF_REFR_PERIOD` 同值),最坏屏上滞后 200 + 300 = 500 ms;全文在 `ui_page_ac.c` 的 `AC_AUTO_MS` 注释);`yx` 500 ms(变位低频事件,按"1 s 内上屏"到位——最坏 700 ms,较 300 档少 40% 稳态重绘);`clock` 1000 ms(快变项只有墙钟秒尾,快于 1 s 的轮询只会把同一秒多画几遍);`device_info`/`runreport` 1000 ms 并显式 `.auto_seq = ui_data_info_seq`(通道二;`info` 与 `rt` 同拍——`ui_data_feed_tick` 每 200 ms 拍两帧连发,见 §5.2)。各页取值账目在该页描述符注释里,本文不复述。
- **不迁移**:待机屏 `ui_standby.c`(自持 1 s 整屏定时器 + seq 门控)、整定视图 `ui_w_setview.c`(`sv_poll` 定时器盯 `par` 通道)——两处各自已有节拍,纳入框架只会多一只定时器。
**回归确定性**:无头模式(`--keys`/74 张黄金参考)从不跑 `lv_timer_handler`,定时器不可能在截屏前触发,且仿真仍是"一次发布冻结帧"——黄金参考逐字节不变(`check_content_pages.py` 实证)。自动失效路径的验证走新开关 `--rtlive <键序> <A.bin> <B.bin>`:开页截 A → 发布第 1 号确定性斜坡帧 → **直接调用** `ui_content_page_auto_poll()`(等价定时器到点)→ 截 B;A≠B 即证明"零按键、新帧落屏"。窗口模式(真机行为仿真)每 200 ms 发一帧斜坡值,屏上数值自己会走。
---
## 6. 写路径(定值整定)
### 6.1 为什么 UI 不能直写
- `prot_set_set()` 之后**必须** `prot_set_seal()` 重算校验和;逐项写会把校验和打成中间态,被自检判为损坏。
- 落盘由 `defaultTask`(配置引擎属主)执行,UI 直接写盘会撞单写者纪律。
- 越界校验是 all-or-nothing:任一项越界整表不装载。
### 6.2 请求 / 状态交接(复用 `net_cfg` 范式)
落地形态(道F task-1 落本层队列与状态机,task-2 落页面侧消费者,2026-10-26):
```
ui_page_view_param / _set / _word / _plate(整定态:123 授权 → attach_edit 绑 set/commit/state)
│ 选中"保存"行按 ENTER(组件 ui_w_setlist_key 先过两道门:可写权限 + state()!=LOCK)
▼
sv_commit():req.mask = 改动位图;req.q10[] 只按 mask 置位的槽换算(显示值 → Q10)
▼
ui_data_param_request(&req) ← 本层只投递,不执行、不判越界、不碰文件系统
│ 静态环形队列,深度 4(UI_DATA_PARAM_QD);满 → -1(页面显 ERR + 页脚"忙")
│ 入队 = 168 B 整条拷入(.bss 4 × 168 = 672 B;零堆、零变长拷贝)
▼
ui_data_feed_tick()(App 侧,uiTask 上下文;先 drain 再比校验和,顺序即判据)
│ ui_data_param_drain(&s_param_ops):每轮最多落定一条
│ ② ops->locked() == 1 → ERR_LOCKED,**本条丢弃**(不排队等解锁)
│ ③ ops->check() 按 mask 逐项整批预检,任一项越界 → ERR_RANGE + err_mask,一字不写
│ ④ 预检全过再逐项 ops->apply() → prot_set_set_sealed()(只写 mask 内的 id)→ OK
│ 值真的变了 → 同轮重发 par 帧(页面按 seq 失效缓存)
▼
ui_data_param_state() / ui_data_param_err_mask()(保存行显词 + 越界行反显)
```
四个公开函数(声明 `Drivers/BSP/UI/ui_data.h`、实现 `ui_data.c`,全在本层,零 App include):
| 函数 | 作用 | 返回值口径 |
|---|---|---|
| `ui_data_param_request()` | 投递一条请求(页面"保存"的唯一出口) | `0` 已入队;**`mask=0` 的空请求也返 0**,但不占槽位、直接落终态 OK(一个都没改就按保存是正常操作,报 ERR 会让现场以为装置有问题);`-1` 队列满;`-2` 参数无效(NULL,或 `mask` 含 `UI_DATA_SET_N` 以上的位——调用方的编程错误不该落成屏上的"越界") |
| `ui_data_param_state()` | 回读写路径状态 | `UI_DATA_PARAM_ST_{IDLE,WAIT,OK,ERR_RANGE,ERR_LOCKED,ERR_BUSY}` |
| `ui_data_param_err_mask()` | 最近一条**被本次预检挡下**的项位图 | bit i = 1 → 第 i 项越界;最近终态不是 `ERR_RANGE` 时恒 0 |
| `ui_data_param_drain()` | 落定一条(App 装配节拍入口) | `1` 处理并提交了一条;`0` 队列空(状态不动);`-1` ops 或其函数指针为 NULL |
**"算不算越界"与"现在能不能写"都是 App 侧事实,本层一份都不复制**:执行能力经
`ui_data_param_ops_t`(`locked` / `check` / `apply` 三个函数指针)由 `App/app/ui_data_feed.c`
**每次调 drain 时注入**,本层不保存副本。原因有两条,都不含糊:① 分层方向硬约束——
`Drivers/BSP/**` 不得 include `App/**`(`scripts/check_layer_deps.py` 拦提交),而上下限真源
在 `App/algo/prot_set.c` 的 `g_prot_set_meta`;② 注入表**刻意不含任何范围数值**,多传一份
上下限就是第二真源、就会漂。同 §7.2 记录页的注入式 reader 一条路子,额外的好处是主机单测
可以把三个指针换成桩件,于是**队列与状态机的生产代码**(不是副本)能在 PC 上把"满队列 /
越界不改值 / 闭锁拒写 / 正常往返"跑全(`test/host/ui_data/`)。
**请求形状 = 「位图 + 定长 40 槽」(168 B)而不是「项数 + 变长 id 数组」**:表现层的编辑叠层
本就是一张改动位图 + 一张工作值表,本形状与它逐位同构 → 提交侧一次赋值、执行侧逐项按位取,
两侧都不必维护第三种表示;定长还让队列退化成 O(1) 静态数组。边界与代价:`mask` 只有 64 位
→ 定值项数硬上限 64(`ui_data.c` 有编译期守卫,破 64 是编译失败而不是静默丢项);队列 672 B
+ 控制字 16 B 是买"整批原子 + 零变长 + 零堆"的价钱(`docs/内存管理/RAM使用分析与优化方案.md`)。
> ⚠ **提交侧必须只提交 `mask` 内置位的 id,绝不"从显示值回提全表"**:Q10 存不下 0.95 这类
> 返回系数(实际存 972/1024),按显示域往返会把用户没动的项顺手改掉。判据"越界值不落盘"与
> "改哪条只落哪条"都建在这条上(判据见 `docs/UI设计/内容页架构.md` §7.1)。
> 换算的往返精度因此也**不需要**逐位可逆:没动的行根本不进换算函数。
**这套结构与 `net_cfg` 的 `net_cfg_save_request` / `net_cfg_save_state` 完全同构**
(`Drivers/BSP/NETCFG/net_cfg.h`),不引入新范式——这是"低耦合"的另一个含义:
**项目里同类问题只有一种解法**。
### 6.3 失败语义
落定结果只有 5 个值(`UI_DATA_PARAM_ST_*`),页面侧的**词与位置**由整定视图统一映射,
四张整定页共用一套(组件按 `state()` 回调给的值画保存行值列,页面不参与解释):
| 状态 | 含义 | 保存行值列 | 页面附带动作 | 产出方 |
|---|---|---|---|---|
| `IDLE` | 本次打开页面从未投递过 | `ENTER` | — | 本层初值 |
| `WAIT` | 已投递、队列里还有请求在路上 | `WAIT` | 编辑叠层**保留**(不清稿) | `request` 受理 / `drain` 未排空 |
| `OK` | 已逐项写入并置脏 | `OK` | 按 `commit` 位图清掉叠层,让位给新帧 | `drain` 第④步 |
| `ERR_RANGE` | 整批预检有任一项越界 → **一字未写** | `ERR` | 用 `ui_data_param_err_mask()` 反显越界行 | `drain` 第③步 |
| `ERR_LOCKED` | 投递时定值闭锁 → **本条丢弃** | `LOCK` | 反显同 `ERR_RANGE`;`drain` 不回滚(`prot_set` 无回滚接口,谎称"整批未写"比如实报更坏) | `drain` 第②步 |
| `ERR_BUSY` | 投递被拒:队列满 | `ERR` | 页脚"忙,请重试";**在队请求一条不动**,用户直接再按一次保存 | `request` 返 -1 |
三条实现侧口径,都是原稿没写死的:
1. **`LOCK` 还有一个与状态机无关的来源**:帧里 `par.locked == 1` 时保存行**直接显 `LOCK`
并禁 ENTER**(优先级高于历史结果)。闭锁是持续状态,不该只在"某次投递被拒"那一帧才说一次;
禁编辑必须落在键路上,只靠屏上词会让用户白改一轮。
2. **`ERR_TIMEOUT`(原稿的"3 s 未取走")本层不产出**——uiTask 每 10 ms 就 drain 一次,
真出现"永不落定"是 App 侧没接线的装配缺陷,不是运行期状态。页面若要兜底,可自己按投递
时刻计时(属页面本地可选项,当前没做:没有消费者就别先加一条无人走的分支)。
3. **状态是全局单值,页面必须锁存显示**:`ui_data_param_state()` 落定后一直停在那个值上,
直读会让用户移动一下光标就看到别的页留下的旧结果。整定视图把它锁存成"本页投过一次
才显示那次的答案、开页复位成 `ENTER`"(`ui_w_setview.c` 的 `s_disp`)。
> 词表刻意用 ASCII(`ENTER`/`WAIT`/`OK`/`ERR`/`LOCK`)与 `net_cfg` 保存行同排;
> 中文「未标定」徽标是**另一件事**(`cal_block`),见 §4.2 的两源两通道表,不要为了
> 省一个词把它并进 `LOCK`。
---
## 7. 记录页:另一种通道(注入式 reader)
### 7.1 为什么记录不走快照
记录是**分页读文件**:条数随运行增长,不可能全量快照;且读盘有 I/O 延迟,不能放在绘制路径里同步做。
### 7.2 注入式 reader
把 `ui_w_records` 从"直接 include `sys_log.h`"改为"接受一个只读函数表":
```c
/* Drivers/BSP/UI/ui_w_records.h —— 不含任何 App 头 */
typedef struct {
uint16_t (*count)(uint8_t log_id);
/* 返回 0 成功;-1 越界;-2 读失败 */
int (*get)(uint8_t log_id, uint32_t idx,
char *ts, uint32_t ts_len, char *desc, uint32_t desc_len);
} ui_rec_reader_t;
void ui_w_records_bind(const ui_rec_reader_t *reader); /* App 启动时注入 */
```
- `log_id` 用 `uint8_t`(**不透明编号**),BSP 不知道 `SYSLOG_RUN` 是什么,只知道"0 号日志"。
- 注入点在 `App/task/ui_task.c`(`ui_menu_init` 之前),实现体是 `sys_log` 的两个薄包装。
- 【2026-10-25 落地注】模拟器同形镜像:`simulator/main.c` 的 `sim_rec_count/sim_rec_get`,
无头与窗口两个初始化点都在 `ui_menu_init` 前调 `ui_w_records_bind`;UI 侧编号常量
`UI_W_REC_LOG_RUN/SELFTEST`(映射只在两端适配层,UI 不感知 `syslog_id_t`)。
`ui_rec_reader_t` 按本文契约**原样**实现(`int` 错误码 0/-1/-2 未改型)。
### 7.3 收益:可削减 3 条既有基线
改造完成后,`scripts/check_layer_deps.py` 的 `BASELINE` 可删掉:
```
("Drivers/BSP/UI/ui_page_runlog.c", "App/log/sys_log.h"),
("Drivers/BSP/UI/ui_page_selftest.c", "App/log/sys_log.h"),
("Drivers/BSP/UI/ui_w_records.h", "App/log/sys_log.h"),
```
基线"只减不增"——**本设计顺带把存量债还掉三条**,而不是新增。
> 另外两条(`net_cfg` / `ftp_cfg` → `cfg_file.h`)属配置引擎,与 UI 无关,不在本文范围。
### 7.4 SOE 记录:同构 reader + UI 侧显示名映射(2026-10-25 落地新增)
`/log/soe.log` 是**二进制**定长 64 B 记录(时标/类型/元件号/序号/值),不是"时间戳 + 文本描述",不能与 `ui_w_records` 混读,故另立同构组件 `Drivers/BSP/UI/ui_w_soe.c`:
- **注入式 reader** `ui_soe_reader_t`(`count()` + `get(idx, &view)`,错误码 0/-1/-2 与 `ui_rec_reader_t` 同族);`get` 返回的是 **UI 侧视图结构** `ui_w_soe_rec_t`(时标串 + 不透明类型号 + 不透明元件号 + 标志 + 序号/值),适配层负责解码与 CP56 → 文本换算,UI 不 include `App/log/soe_rec.h`。
- **显示名映射在 UI 侧**(`ui_w_soe_type_name()` / `ui_w_soe_elm_name()`):类型与元件都是**表现层文案**,不进快照也不回落到 App 层(同 `docs/UI设计/UI_数据供给设计说明.md` §8 的格式化归属结论)。UI 侧另立一套不透明编号常量(`UI_W_SOE_T_*` / `UI_W_SOE_ELM_*`),其**数值与 App 枚举逐项相等**——这条等价关系不靠文档转述,由主机单测在同一 TU 里 include 两侧头逐项核对(`test/host/ui_data/` 的用例 `TC-UIDATA-012`/`013`,2026-10-25 现场核对结果:类型 1..8 + 哨兵 9、`ELM_NONE=0xFF`、`FLG_IV=0x80`、元件 0..8 与 `PE_COUNT=9`)。
- **未标定闭锁/标定复归两类新事件已进映射表**(`UI_W_SOE_T_CAL_BLOCK=7` / `UI_W_SOE_T_CAL_RESUME=8`,缺字 采/样/恢/效 已走字体重生成 + 像素回归)。单测额外钉了两条容易悄悄发生的错:八类事件必须有名(忘配名只会在屏上显示 `--`,像素门禁照不出来)、"采样闭锁/恢复"与"标定闭锁/复归"四名必须互不相同(同名 = 现场把未标定闭锁读成采样故障)。
- **本批不绑定 reader**:落盘侧还没有只读 API(`App/log/soe_store.c` 只有 `post/drain/dropped`),需要加法式的 `soe_count()` / `soe_read(idx, &rec)`(FatFs `f_open` + `f_lseek`,与 `syslog_get_record` 同构);该文件属道F 的潜在写域,先后次序由 Lead 排。未注入期间组件按空态渲染("无记录"伪行),因此本批**不产生任何像素变化**。
---
## 8. 格式化归属:谁决定小数位
**结论:格式化属表现层,全部在页面行表里;快照只给数值与品质。**
| 信息 | 归属 | 理由 |
|---|---|---|
| 数值(float / Q10) | 快照 | 业务事实 |
| 品质(IV/NT/OV) | 快照 | 业务事实 |
| 通道名("Ua"/"Ia") | 页面行表 | 显示文案 |
| 小数位(2 位/3 位) | 页面行表 | 显示规格 |
| 单位(V/A/Hz) | 页面行表 | 显示规格 |
| 无效符号(`--`) | 页面行表 | 显示规格 |
| 排序/分组/分页 | 页面行表 | 版式 |
行表结构相应扩展(在现有 `cp_row_t` 基础上加两个字段,或新增页面侧结构):
```c
typedef struct {
const char *name; /* "Ua" */
uint8_t src; /* 快照内下标(0..UI_DATA_YC_N-1) */
uint8_t dot; /* 小数位:电压 2 / 电流 3 / 频率 3 */
const char *unit; /* "V" / "A" / "Hz" */
} ui_ac_row_t;
```
**为什么不在快照里放格式化后的字符串**:那会让 App 知道"电压要 2 位小数",把显示规格漏进业务层——这正是要避免的耦合。
---
## 9. 可测试性
### 9.1 主机侧纯逻辑单测
`ui_data` 是纯内存模块,天然可测:
| 用例 | 判据 |
|---|---|
| 首帧前读取 | `ui_data_rt()` 返回 -1,`valid=0` |
| 发布后读取 | 字段逐项一致;`seq` 递增 |
| 参数变化检测 | checksum 不变 → 不重发;变 → 重发 |
| 请求队列 | 深度 4;满则 -1;取走后可再投 |
| 状态回读 | OK/ERR_RANGE/ERR_LOCKED 正确映射 |
页面渲染可在模拟器侧断言(见 9.2),主机侧只测数据模块。
### 9.2 模拟器:固定帧保证 golden 稳定
`simulator/main.c` 不链接 `App/task/ui_task.c`,因此需要自己发布快照:
- **默认(golden 模式)**:发布一帧**固定数据**(写死的 9 路值 + 位图),保证像素参考可复现。
- **`--live` 模式**:用合成正弦逐帧更新,供人工观察动态刷新(不参与 golden)。
这是本设计对"可测性"的直接贡献:**页面数据来源可注入 → 像素回归不再依赖真实硬件**。
> 【2026-10-25 落地注】`simulator/main.c` 的实现形态与两条原稿未写死的细节:
> 1. 固定帧由 `sim_publish_data_frames()` 一次性发布,**无头与窗口两个初始化点都调**(与记录 reader 注入同址、同"先于 `ui_menu_init`"纪律);
> 2. 固定帧里的定值**不手抄 40 个数字**,而是把 `App/algo/prot_set.c`(零平台依赖的纯算法,双端共享核心)链进模拟器、`prot_set_init()` 后取出厂默认——抄表等于造第二真相(同 `scripts/check_font_charset.py` 的"单一规则源"口径);
> 3. `build_date` 用**固定串**而不是 `__DATE__`:否则跨天重建会把装置信息页的黄金参考刷掉,而黄金参考是判据本身。
> 4. 原稿设的 `--live` 合成正弦模式**尚未实现**(当前无消费者,等动态刷新真的需要人眼观察时再加)。
> 5. **定值写路径在模拟器侧有一份同构的执行实现**(`sim_param_locked/check/apply` +
> `sim_param_pump()`):真机那段在 `App/app/ui_data_feed.c` 的 tick 里,而模拟器不链接装配器,
> 所以在 `main.c` 里镜像一份——`check()` 用的仍是同一份 `g_prot_set_meta` 真源(链进来的
> `App/algo/prot_set.c`),因此"模拟器里越界被拒"与"真机上越界被拒"是同一个判定,不是两份规矩。
> 固定帧的 `cal_block` 显式填 1:**真机现在就是**未标定态(`rt.eng` 也按同一条口径钉在引脚档),
> 屏上的话必须与本机一致,模拟器才配当像素基准。
> 6. 落定与"页面自己发现数据变了"的分工:`sim_param_pump()` 在无头模式排在注键之后、截图之前
> 同步排空(真机由每 10 ms 的 tick 排);整定视图另有一条 100 ms 的 LVGL 轮询定时器,
> 负责把"主站写进来的新值 / 标定完成 / 落定但不改校验和的 ERR"推上屏。**这条定时器在无头
> 回归里一次都不会触发**——`run_headless()` 严禁调 `lv_timer_handler()`(I1+FULL 全屏刷新会
> 进渲染死循环),所以黄金像素与它无关;两次连跑逐字节一致即为证据(`simulator/README.md`
> 的同条注)。窗口模式才用它。
### 9.3 与"虚拟注入"的关系
`docs/UI设计/页面补齐规划.md` §5 记的厂家调试"虚拟注入"(未做),**天然落在 `ui_data_feed` 上**:注入值只要在 feed 组装时覆盖对应字段即可,**页面完全不知情**。
约束(必须写进代码注释):虚拟注入**只能在 feed 层覆盖快照字段**,绝不能改 `prot_set` / `phasor` 的输入——否则会污染保护判据路径。
### 9.4 一致性测试(防"魔法下标"漂移)
页面行表用**不透明下标**(`src` / `set_idx`),BSP 侧不知道它对应哪个 App 枚举——这是解耦的代价,必须用测试兜住:
| 断言 | 位置 | 内容 |
|---|---|---|
| 通道数一致 | `App/app/ui_data_feed.c` | `typedef char chk[(UI_DATA_YC_N == ADC_SEM_COUNT) ? 1 : -1];` |
| 定值项数一致 | 同上 | `typedef char chk2[(UI_DATA_SET_N == PS_ID_COUNT) ? 1 : -1];` |
| 下标语义一致 | `test/host/ui_data/` | 主机测试同时 include 两侧头,逐项断言"页面表的 src/set_idx 指向预期枚举" |
第 3 条是关键:**它把"跨层魔法数字"从运行期风险降级为编译/测试期错误**。
---
## 10. 内存与性能
| 项 | 量(`.map` 实测) | 说明 |
|---|---|---|
| `rt` 帧 | 208 B | 遥测 9 路 + 相量槽带 + 位图 + 时钟串;三帧串行组装用的 `s_scr` 是联合体,**取最大者 = rt** |
| `par` 帧 | 192 B | 40×4 Q10 + 头部 + `cal_block`(v2);追加这 8 B 由 rt 兜住,**净增 0**(尺寸关系由主机单测钉住,见 §4.2 落地注) |
| `info` 帧 | 随字符串字段定长 | 与 rt 同节拍发布,同样落在联合体里,不额外占 |
| `ui_data.o` 全部静态 | `.bss` 1,168 B | 含三帧存储、`s_scr` 联合体、**定值请求队列 4×168 = 672 B + 控制字 16 B** |
| `ui_w_setview.o` 静态 | `.bss` 352 B / `.data` 48 B | 四视图行缓存 + **整定编辑叠层 190 B**(`int32_t[40]` + 三张位图 + 锁存态) |
| 页面行缓存 | 每页 ≈ 52 B(`ui_page_view_*.o` 各 `.bss` 52 B) | 定值相关页共用一份视图缓存(同屏只开一页),所以四张整定页**没有**再各存一份 192 B |
| LVGL 池 | 快照 0 B;轮询定时器一只 | 快照不进池(不是 LVGL 对象);定时器是 LVGL 池对象,只建一次不删 |
| 每 200 ms 拷贝 | 一帧(≤208 B),且只在变化时 | 一次 memcpy,微秒级 |
| 每轮(10 ms) | 0 次拷贝 | 比 seq / 比三个变化源;见 §5.2、§5.4 |
栈侧(同一份 `.map` 的调用图,改前改后各跑一次 `scripts/stack_report.py`):uiTask 静态最坏链
**1336 B / 配置 16 KB(余 15,048 B,91%)在接入写路径前后逐字节不变**——新链路自身都不深
(`sv_commit` 帧 192 B 含 168 B 请求体、链深 208 B;「未标定」徽标帧 160 B、链深 536 B;按键链
`pg_key` 起算 480 B),最坏链仍是 LVGL 建树那条,**没有换人**。这是"页面 commit 会在 uiTask 栈上
放 168 B 局部量"这类担心的实测答案,也是本表值得写实测数而不写"约几百字节"的理由。
**结论**:代价 = 约 1.5 KB 静态 + 每 200 ms 一次 memcpy,换来整个 UI 层的数据可及性与一条
可测的写路径。区域水位(RW_IRAM1 / RW_CCM / Flash)**不在本文复制**——那是受管快照,
由 `scripts/ram_baseline.py` 从每次 `/keil-build` 的 `.map` 生成,第二处写死就是一份会过期的
真源(本仓已有一条门禁在钉这个,口径见 `docs/内存管理/RAM使用分析与优化方案.md` §2.1 与
`docs/内存管理/RAM预算台账.md`)。本次新增约 1.5 KB 静态 + 一条 LVGL 池定时器,量级无压力。
---
## 11. 落地步骤(每步可独立验证)
| 步 | 内容 | 验证 | 依赖 |
|---|---|---|---|
| **步骤1** | `ui_data.h/.c` + 主机单测(无任何消费者) | `test/host/ui_data` 全绿;`layer-deps` 无新增 | 无 |
| **步骤2** | `App/app/ui_data_feed.c` + `ui_task.c` 接线(每轮调 tick) | 串口打印首帧(临时锚点);`/keil-build` 0/0 | 步骤1 |
| **步骤3** | 交流量 / 直流量回炉(接快照 + 行表加 `src/dot/unit`) | 模拟器固定帧 golden 更新;台架看真实码值变化 | 步骤2 |
| **步骤4** | 遥信量 + 定值/控制字/软压板查看(4 页) | 主站改定值 → 页面 200 ms 内变 | 步骤3 |
| **步骤5** | 写路径(请求/状态)+ 整定 4 页 | 就地改定值 → 保存 → 掉电重启 → 值保持 | 步骤4。**已落**(道F task-1 落本层队列与状态机、task-2 落整定 4 页与模拟器侧,2026-10-26);「掉电重启值保持」只能上板收口,见 §12 判据 6 |
| **步骤6** | 记录 reader 注入 + 删 3 条 layer-deps 基线 | `check_layer_deps.py` 基线由 6 → 3 | 可与步骤3 并行 |
**步骤1~步骤2 是关键路径**:它们不产出任何用户可见效果,但决定后面所有页面是否可信。**不要跳过步骤1 直接改页面**——那会退化成"页面里塞假数据 2.0"。
> 【2026-10-25 落地进度】步骤1、步骤2 已落(道E task-14,分支 `task/ui-data-feed`):`ui_data` 三通道 + 主机单测 82 项全绿(`test/host/ui_data/`,已挂 `ui-data-unit-test` 钩子)、`ui_data_feed` 已在 `App/task/ui_task.c` 主循环接线并在建页前发首帧。**改动两处与原稿不同**:① 实时帧的 `eng` 与品质位按标定层真值语义落地(见 `docs/UI设计/UI_数据供给设计说明.md` §4.1 的落地注);② 新增第三条通道 `info`(同文档 §4.4)。**写路径(步骤5 的 `ui_data_param_request/state`)随整定 4 页一起落**,本批无消费者,先落等于落一段永不执行的代码。步骤3 起(页面接线)在道E 第二个工作项。
>
> 【2026-10-25 落地进度·二】步骤3 的第一批页面已接(道E task-15,分支 `task/pages-ui`):**装置信息**读 `info`
> 通道(型号/软件/硬件/校验/日期/运行时长)+ `net_cfg` RAM 副本(MAC/IP),**交流量**读 `rt`
> 的 `ph[]` 实例槽与 `freq_*`、第 7 行读 `eng`,**直流量**读 `rt.yc[TEMP]` 并透传 `Q_RAW`。
> 三条纪律在页面侧被验证:① 页面只读快照、零 App include(分层基线不变);② 帧缓存按 `seq`
> 门控整帧拷一次,逐行只读标量;③ 品质位判空一律 `--`,"有数但不可信"与"没数"同形。参数帧
> `par` 的首批消费者是定值/参数查看页(本批未接,`bad_mask`/`locked` 的屏上表达随那 4 页落)。
>
> 【2026-10-25 落地进度·三】`par` 的首批消费者已落(同分支批 3):**参数 / 定值 / 控制字 / 软压板**四个查看页
> (`ui_w_setview` 四张行表 + `ui_w_setlist` 组件,查看态 `commit=NULL` 无保存行)。Q10 → 显示值的换算落在**表现层**
> (本契约 §8 的分工:写侧只搬原值),换算式在 `ui_w_setview.c` 里做整数拆分而非浮点/64 位除(MicroLIB
> 软浮点与 `__aeabi_ldiv` 一进镜像几百字节,模拟器永远照不出这笔代价)。`bad_mask` 的屏上表达 =
> 该行反显高亮(且只在 `bad_valid=1` 时参与,把没数据画成有毛病是假告警);`locked` 的屏上表达是
> **禁编辑**,查看页本来就无编辑通路,它随整定 4 页一起显形。四个返回系数按 2 位小数显示的理由见
> `docs/UI设计/页面扩充详细方案.md` §3.2.2 落地注;行表与 `prot_set` 枚举序/上下限的一致性由
> `tools/setview_check/check_setview_limits.py` 核验(BSP 侧看不到 App 头,物理上无法自证,必须有人从外面钉)。
> 【2026-10-25 落地进度·四】遥信通道已被消费:**遥信量**页(`ui_page_yx.c`,33 行固定名表,
> 方案 A)按 `yx_valid` → `yx_dp` → `yx_bits` 的次序取值列(先判无效:无效位上的位值不代表任何
> 事实;再判单/双点选词;最后才看动作态)。起草时为此补了 `yx_dp` 一个字段(§4.1),由
> `ui_data_feed.c` 逐点问 `iec104_pts_yx_is_dp()` 得到——**点数与单双点性质都留在协议层**,页面
> 不复制这些事实;`UI_DATA_YX_N` 与 `iec104_pts_yx_count()` 一旦不等,写侧打一条一次性
> `DBG_ERROR`(点数在协议层是 .c 内的宏,编译期拿不到,只能运行期留痕)。模拟器侧同步发布
> `yx_dp = 0x0F` 但**不**把这 4 位置进 `yx_valid`:V0.1 没有开入硬件,屏上就是 `--`——刻意不用
> 「让它显示合位/分位」的假数据把画面填满,那等于让黄金参考声称本机有开关位置遥信。因此
> 「合位/分位」这条词映射当前**没有任何自动化证据覆盖**(像素恒 IV、页面依赖 LVGL 也进不了
> 主机单测),它已登记为开入落地后的台架判据,而不是假装测过。
> 【落地注·五(写路径判据的前置口径,指针级,不重述细节)】带 `#P` 注记的叶子**第一屏是密码
> 页、不是内容页**:真机实测里三帧「深页盲走」的落点都是密码输入页(墨量 512,与黄金参考
> 的两张密码态逐字对得上)。所以批 5 的写路径判据必须把「过密码」当**显式状态**处理——快照
> 层不提供「曾否进过某页」这种隐式状态,可写性只由 UI 侧权限态与 `par.locked` 共同决定,
> 「当前是否已过密码」既不真实也不该被推断。判据侧的过法只有一套(查看密码 = 出厂 000 /
> 修改密码 = 123,键序与黄金回归的网口设置编辑态完全一致),口径与纪律见
> `docs/UI设计/UI_自动化测试流程.md` §7.5;本节只登记这条事实,避免两份文档各说各话。
>
> 【落地注·六(写路径消费者已上屏,2026-10-26,道F task-2)】整定 4 页(参数 / 定值 /
> 控制字 / 软压板)绑到与查看列**同一批行表、同一个 `ui_w_setlist` 组件**:同一份页面
> 描述符按 `ui_content_page_is_editable()` 分派只读 / 可写两态,两态的差别只有绑不绑
> `set/commit/state` 三个回调。于是本节契约里原本只是示意图的那条链路第一次真的被按到:
> **越界值不落盘**(提交只带改动位图)、**闭锁禁编辑**(`state()` 回 LOCK 或帧里
> `locked=1` 就直接挡住 ENTER,而不是只换个屏上词)、**落定要自己上屏**(`ERR_RANGE` 与
> `ERR_LOCKED` 都不改校验和,页面收不到新帧,靠的是整定视图那条 100 ms 轮询,见 §9.2 注 6)。
>
> 这一批还暴露了两条「只有第一个消费者才会暴露」的缺陷,都已修(为什么必现写在
> `docs/UI设计/页面扩充详细方案.md` §3.2 落地注):二态行 ENTER 不回绕(写出 opts 之外的
> 下标:屏上看着没变、叠层里已是越界值,保存必被预检挡回);「参数帧已就位」原先只在
> **绘制路径**里被置位,而按键门读它 → 无头回归里开页后的第一个 ENTER 永远被挡(真机开页
> 10 ms 内就重绘,症状只在测试侧出现)。第二条的修法是把「数据就位」与「画过没有」解耦:
> 判就位之前先按 seq 做一次 sync(帧没变时只是一次 uint32 比较)。
>
> 另记一条同批暴露、与本契约无关的事实:菜单树重跑时 `ui_menu_tab.h` 有一行注释
> 跟着生成器的模板文字变了 —— 说明 HEAD 上「生成器模板」与「已提交生成物」本就不同步
> (改模板那笔没重跑生成器)。生成物以生成器输出为准即可,但这条滞后该补一条门禁,
> 已登记为待办「生成器幂等性检查」。
---
## 12. 验收判据
| # | 判据 | 方法 |
|---|---|---|
| 1 | `Drivers/BSP/**` 无新增 App include | `scripts/check_layer_deps.py` 退出码 0 |
| 2 | 记录页改造后基线由 6 条减到 3 条 | 同上 `--prune` |
| 3 | 交流量页显示真实相量(非写死值) | 台架:注入已知信号 → 页面值随信号变 |
| 4 | 未标定时页面明确标识(不把码值当伏特) | 目检 + 文本断言(`eng=0` 时带标记) |
| 5 | 首帧前显示 `--` 而非 `0.000` | 模拟器:不 publish 直接开页,断言文本 |
| 6 | 定值整定全链闭环 | 就地改 → 保存 → 重启 → 值保持 + 校验和自检通过 + 主站 C_RD 一致。**半收口(2026-10-26)**:模拟器侧「改 → 保存 → OK → 回首屏新值已在帧里」已由像素 + 文本断言覆盖(黄金用例 `sparam_save` / `sparam_landed`,越界侧 `sparam_oob`);**重启保持与主站 C_RD 一致只能上板**——模拟器没有 NAND,`apply()` 到 `prot_set_set_sealed()` 就是终点,这条差距已登记在 `docs/测试说明/专项验证/模拟器差距清单.md`;另注意 40 项里有 13 项 `comm_addr=0`(纯本地项),主站侧根本读不到,不能拿 C_RD 当它们的判据 |
| 7 | 像素回归稳定 | `ui-golden` 连续两次运行零差异。**已验(2026-10-26,当时下限为 27 页)**:27 页连跑两次逐字节一致(含整定 9 态)——**集合现已扩至 74 张**,**双次一致已验(2026-10-29:同一批 66 张连跑三次逐字节一致,池水位 5,448 B;菜单 8 状态连跑三次亦一致,5,368 B)**;轮询定时器不影响——无头模式不调 `lv_timer_handler()`(§9.2 注 6) |
| 9 | 「写不进去」与「改了不动作」两条事实互不冒充 | 反向文本断言(`check_content_pages.py` 的 `ABSENT`:查看页与只读态不得出现「未标定」徽标与「保存」行)+ 台架:未制造该态——要它必须改坏 /prot_set.bin(破坏产品配置存储,用户裁定 2026-10-26 不做),故 LOCK 态目前只有代码级证据与三重反证(ENTER 被正常消费、遥信 YX31=OFF、开机 CORRUPT=0),**没有像素证据** |
| 8 | 主机单测覆盖数据模块 | `test/host/ui_data` 全绿并挂 pre-commit 钩子 |
---
## 13. 反模式清单(禁止事项)
| # | 禁止 | 原因 |
|---|---|---|
| 1 | BSP 里 `extern` App 全局变量 | 绕过门禁且比 include 更危险(无契约/无所有权) |
| 2 | 页面直接 include `App/**` 头 | 门禁拦截;且页面被绑死在具体 App API |
| 3 | 快照里放指针或动态字符串 | 跨层生命周期事故;只用定长数组 |
| 4 | 每行 `refresh` 都整帧拷贝快照 | 8 行/帧冗余;用 seq 门控 |
| 5 | 在快照里放格式化后的字符串 | 显示规格漏进业务层 |
| 6 | 多个任务同时发布同一通道 | 破坏单写者约定;需要时在 `ui_data` 内部加保护,不改页面 |
| 7 | 虚拟注入改 `prot_set`/`phasor` 输入 | 会污染保护判据路径 |
| 8 | 定值逐项 `prot_set_set()` 不封存 | 校验和中间态 → 自检判损坏 |
| 9 | 为省事把 `sys_log.h` 加进 `ALLOW` | ALLOW 是"叶子工具"通道,`sys_log` 是有状态服务,加进去等于永久开后门 |
---
## 14. 与既有文档和门禁的关系
- **门禁**:`scripts/check_layer_deps.py` 的三种合法做法本文全部用上(快照推送=②,写路径与记录 reader=①),**不新增任何 `ALLOW` 或 `BASELINE` 条目**;计划的 3 条削减**已于 2026-10-25 兑现**(task/UI-rec-reader 落地 §7.2 契约,基线 6 → 3,详见 `docs/门禁说明/layer-deps.md` §1)。
- **页面框架**:`docs/UI设计/内容页架构.md` 的 `refresh` / `count_cb` 钩子**签名不变**,页面只是改为从 `ui_data` 取数。
- **页面清单**:`docs/UI设计/页面补齐规划.md` §2.1 的交流量/直流量两页即本文的消费端。
- **数据真实性**:`docs/问题记录/采集与数据处理短板评测.md` 的标定(§4.1)与遥测链(§4.2)落地后,只需改 `ui_data_feed` 的取数来源与 `eng` 取值,页面零改动。
+11 -11
View File
@@ -1,7 +1,7 @@
# 页面扩充详细方案(27 个空叶子 + 3 页回炉) # 页面扩充详细方案(27 个空叶子 + 3 页回炉)
> **定位**:`docs/UI设计/页面补齐规划.md` 回答"现在有哪些页、每页是什么形态";本文回答**每一页显示什么、数据从哪来、要改哪些代码**——可直接照着开工的粒度。 > **定位**:`docs/UI设计/页面补齐规划.md` 回答"现在有哪些页、每页是什么形态";本文回答**每一页显示什么、数据从哪来、要改哪些代码**——可直接照着开工的粒度。
> **数据通道**:`docs/UI设计/UI_数据供给设计说明.md`(快照推送 + 写路径 + 记录 reader 注入)。 > **数据通道**:`docs/UI设计/UI_数据供给设计.md`(快照推送 + 写路径 + 记录 reader 注入)。
> **数据真实性**:`docs/问题记录/采集与数据处理短板评测.md`(标定、遥测链、运行参数段的缺口)。 > **数据真实性**:`docs/问题记录/采集与数据处理短板评测.md`(标定、遥测链、运行参数段的缺口)。
> **统计口径**:本文所有节点/叶子数字均由 `ui_menu_tree.txt` 脚本统计 + `Drivers/BSP/UI/ui_page_registry.c` 交叉核对,不引用旧文档结论。 > **统计口径**:本文所有节点/叶子数字均由 `ui_menu_tree.txt` 脚本统计 + `Drivers/BSP/UI/ui_page_registry.c` 交叉核对,不引用旧文档结论。
@@ -131,13 +131,13 @@
- **第 7 行是诚实性行**:它不是测量值,是"上面 6 行的口径说明"。标定落地后自动变"二次值",无需改页面。 - **第 7 行是诚实性行**:它不是测量值,是"上面 6 行的口径说明"。标定落地后自动变"二次值",无需改页面。
- 单页 7 行(8 行/页),不分页。 - 单页 7 行(8 行/页),不分页。
- 数据来源:`ui_data_rt_t` 的 `yc[0..5]`(下标语义见 `docs/UI设计/UI_数据供给设计说明.md` §9.4 一致性测试)。 - 数据来源:`ui_data_rt_t` 的 `yc[0..5]`(下标语义见 `docs/UI设计/UI_数据供给设计.md` §9.4 一致性测试)。
- 规模:**S**(改行表 + `refresh` 钩子,约 80 行)。 - 规模:**S**(改行表 + `refresh` 钩子,约 80 行)。
**待拍板**:是否接受"7 行"而非参考的"24 行"。若产品要求保留 24 行骨架(便于将来扩通道),则改成 24 行固定表、当前 17 行显 `--`。 **待拍板**:是否接受"7 行"而非参考的"24 行"。若产品要求保留 24 行骨架(便于将来扩通道),则改成 24 行固定表、当前 17 行显 `--`。
【2026-10-25 落地】按 7 行落了(`Drivers/BSP/UI/ui_page_ac.c`):品质位 IV/NT/RAW/SB/BL/OV 一律显 `--`, 【2026-10-25 落地】按 7 行落了(`Drivers/BSP/UI/ui_page_ac.c`):品质位 IV/NT/RAW/SB/BL/OV 一律显 `--`,
第 7 行走快照 `eng` 真值语义(口径见 `docs/UI设计/UI_数据供给设计说明.md` §4.1)。24 行骨架并 第 7 行走快照 `eng` 真值语义(口径见 `docs/UI设计/UI_数据供给设计.md` §4.1)。24 行骨架并
没有"便于将来扩通道"的价值——真扩通道要连采样源一起动,那时页面改行表就是一行表的事。 没有"便于将来扩通道"的价值——真扩通道要连采样源一起动,那时页面改行表就是一行表的事。
#### 3.1.2 直流量(回炉,3 行 → 2 行) #### 3.1.2 直流量(回炉,3 行 → 2 行)
@@ -181,7 +181,7 @@ V0.1 **无直流采样通道**(`ADC_SEM` 只有 8 路电气 + 温度),点
| 24~30 | `外部遥信1~7` | ❌ | `--` | | 24~30 | `外部遥信1~7` | ❌ | `--` |
| 31~33 | `闭锁1~3` | 31 ✅ | 其余 `--` | | 31~33 | `闭锁1~3` | 31 ✅ | 其余 `--` |
- 名表放页面侧(Flash const),**不进快照**——显示文案属表现层(`docs/UI设计/UI_数据供给设计说明.md` §8)。 - 名表放页面侧(Flash const),**不进快照**——显示文案属表现层(`docs/UI设计/UI_数据供给设计.md` §8)。
- 双点遥信 4 点用 `iec104_pts_yx_is_dp()` 决定是否显示"分/合",当前恒无效。 - 双点遥信 4 点用 `iec104_pts_yx_is_dp()` 决定是否显示"分/合",当前恒无效。
- 规模:**M**(33 行名表 + `refresh` + 值映射,约 150 行)。 - 规模:**M**(33 行名表 + `refresh` + 值映射,约 150 行)。
@@ -193,7 +193,7 @@ V0.1 **无直流采样通道**(`ADC_SEM` 只有 8 路电气 + 温度),点
> idx4~13 与 idx31~32 点表未定义功能名,屏上如实写点号占位(`YX5`…、`YX32`),**不编造功能名**。 > idx4~13 与 idx31~32 点表未定义功能名,屏上如实写点号占位(`YX5`…、`YX32`),**不编造功能名**。
> 2. **值映射判定次序是「先无效、再单双点、最后位值」**:无效位上的位值不代表任何事实,排在 > 2. **值映射判定次序是「先无效、再单双点、最后位值」**:无效位上的位值不代表任何事实,排在
> 后面就会把垃圾位画成「复归」。单/双点由快照 `yx_dp` 决定,不在页面复制点表事实(理由见 > 后面就会把垃圾位画成「复归」。单/双点由快照 `yx_dp` 决定,不在页面复制点表事实(理由见
> `docs/UI设计/UI_数据供给设计说明.md` §4.1 的 `yx_dp` 条目)。 > `docs/UI设计/UI_数据供给设计.md` §4.1 的 `yx_dp` 条目)。
> 3. 本表「双点遥信用 `is_dp()` 决定是否显示分/合」落地为 **合位/分位** 两词,但该支路 V0.1 恒 > 3. 本表「双点遥信用 `is_dp()` 决定是否显示分/合」落地为 **合位/分位** 两词,但该支路 V0.1 恒
> 无效(无开入硬件),像素与主机单测都覆盖不到 → 已登记为开入落地后的台架判据,不假装测过。 > 无效(无开入硬件),像素与主机单测都覆盖不到 → 已登记为开入落地后的台架判据,不假装测过。
> 4. 落地时踩到一条对所有名表页通用的陷阱:把既有的 `*_PUT(dst, 字面量)` 宏用在 > 4. 落地时踩到一条对所有名表页通用的陷阱:把既有的 `*_PUT(dst, 字面量)` 宏用在
@@ -306,7 +306,7 @@ V0.1 **无直流采样通道**(`ADC_SEM` 只有 8 路电气 + 温度),点
| `edit_capable` | 描述符置 1,但 `is_editable()` 为假 → 走只读 attach | 同一份描述符,`is_editable()` 为真 → 走 `attach_edit` | | `edit_capable` | 描述符置 1,但 `is_editable()` 为假 → 走只读 attach | 同一份描述符,`is_editable()` 为真 → 走 `attach_edit` |
| 组件回调 | `commit = state = NULL` → **不画保存行**、ENTER 不消费(绑了 `key_cb` 也等价于没绑) | 绑 `set/commit/state` → 画保存行、放开编辑 | | 组件回调 | `commit = state = NULL` → **不画保存行**、ENTER 不消费(绑了 `key_cb` 也等价于没绑) | 绑 `set/commit/state` → 画保存行、放开编辑 |
| 页脚 | 只显示页码 | 额外一行"保存"(挂在**末行之后**,不是固定第 8 行) | | 页脚 | 只显示页码 | 额外一行"保存"(挂在**末行之后**,不是固定第 8 行) |
| 提交 | — | 只提交**改动位图**内的 id(一次封存、一次校验和),经 `ui_data_param_request()` 投递,App 侧 `drain` 落定 → 见 `docs/UI设计/UI_数据供给设计说明.md` §6.2 | | 提交 | — | 只提交**改动位图**内的 id(一次封存、一次校验和),经 `ui_data_param_request()` 投递,App 侧 `drain` 落定 → 见 `docs/UI设计/UI_数据供给设计.md` §6.2 |
| 越界反显来源 | `par.bad_mask`(装载侧,且 `bad_valid=1` 才参与) | 同上 **+** `ui_data_param_err_mask()`(本次提交被整批预检挡下的项) | | 越界反显来源 | `par.bad_mask`(装载侧,且 `bad_valid=1` 才参与) | 同上 **+** `ui_data_param_err_mask()`(本次提交被整批预检挡下的项) |
| 闭锁 | 无写通路,不需要表达 | `par.locked=1` 或投递回 `ERR_LOCKED` → 保存行显 `LOCK` **且 ENTER 一律不消费**(禁编辑,不是只换个词) | | 闭锁 | 无写通路,不需要表达 | `par.locked=1` 或投递回 `ERR_LOCKED` → 保存行显 `LOCK` **且 ENTER 一律不消费**(禁编辑,不是只换个词) |
| 未标定 | 不画(查看页像素恒零变化) | 标题右侧「未标定」徽标(`par.cal_block`);与 `LOCK` 是两件事,两源两通道两词 | | 未标定 | 不画(查看页像素恒零变化) | 标题右侧「未标定」徽标(`par.cal_block`);与 `LOCK` 是两件事,两源两通道两词 |
@@ -320,7 +320,7 @@ V0.1 **无直流采样通道**(`ADC_SEM` 只有 8 路电气 + 温度),点
> 返回系数(真存 972/1024),从显示值回提全表会把用户没动的项顺手改掉。 > 返回系数(真存 972/1024),从显示值回提全表会把用户没动的项顺手改掉。
> >
> 这一批暴露了两条「只有第一个消费者才会暴露」的缺陷(都已修;写路径口径见 > 这一批暴露了两条「只有第一个消费者才会暴露」的缺陷(都已修;写路径口径见
> `docs/UI设计/UI_数据供给设计说明.md` §6.2/§6.3): > `docs/UI设计/UI_数据供给设计.md` §6.2/§6.3):
> ① `ui_w_setlist` 的二态行 ENTER **不回绕**——落在最后一项时写出 opts 之外的 > ① `ui_w_setlist` 的二态行 ENTER **不回绕**——落在最后一项时写出 opts 之外的
> 下标,屏上看着「按了没反应」,叠层里却已是越界值,随保存投出去必被预检判 `ERR_RANGE`; > 下标,屏上看着「按了没反应」,叠层里却已是越界值,随保存投出去必被预检判 `ERR_RANGE`;
> 控制字 4 行与软压板 10 行的出厂值**全是**最后一项(跳闸 / 投入),所以是必现而不是边角。 > 控制字 4 行与软压板 10 行的出厂值**全是**最后一项(跳闸 / 投入),所以是必现而不是边角。
@@ -414,7 +414,7 @@ int run_par_set_deadband(uint8_t yc_idx, float v); /* 范围校验 */
| 3 | `显示端口` | RemoDispBus 端口常量 | | 3 | `显示端口` | RemoDispBus 端口常量 |
| 4 | `FTP用户` | FTP 配置(`admin`,鉴权启用后) | | 4 | `FTP用户` | FTP 配置(`admin`,鉴权启用后) |
- 需要在 `ui_data_rt_t` **尾部追加**一个 `comm` 子结构(`port`/`ca`/`disp_port` + 8 B 用户名),按 `docs/UI设计/UI_数据供给设计说明.md` §4.3 的扩展规则升 `UI_DATA_VER`。 - 需要在 `ui_data_rt_t` **尾部追加**一个 `comm` 子结构(`port`/`ca`/`disp_port` + 8 B 用户名),按 `docs/UI设计/UI_数据供给设计.md` §4.3 的扩展规则升 `UI_DATA_VER`。
- 规模:**S**(快照 +4 字段,页面 60 行)。 - 规模:**S**(快照 +4 字段,页面 60 行)。
- **SNTP设置**:等 SNTP 客户端(`App/` 下无任何 SNTP 代码)。现在建页只能存"没人读的参数"。 - **SNTP设置**:等 SNTP 客户端(`App/` 下无任何 SNTP 代码)。现在建页只能存"没人读的参数"。
@@ -607,7 +607,7 @@ SNTP 客户端 ──────→ 批4 SNTP设置
| Flash(组件) | ≈ 8 KB | 6 个组件(`ui_data`/`ui_data_feed`/`ui_w_setlist`/`ui_w_editor`/`ui_w_soe`/`ui_page_action`)× ~1.4 KB | | Flash(组件) | ≈ 8 KB | 6 个组件(`ui_data`/`ui_data_feed`/`ui_w_setlist`/`ui_w_editor`/`ui_w_soe`/`ui_page_action`)× ~1.4 KB |
| Flash(字库) | ≈ **+10 KB** | 新增约 25 字(段/投/延/零/频/荷/闸/跳/低/过/Ⅰ/Ⅱ/Ⅲ 等),12 px 1 bpp ≈ 370 B/字 | | Flash(字库) | ≈ **+10 KB** | 新增约 25 字(段/投/延/零/频/荷/闸/跳/低/过/Ⅰ/Ⅱ/Ⅲ 等),12 px 1 bpp ≈ 370 B/字 |
| ROM 总量 | 268 KB → ≈ 298 KB | 1 MB Flash,余量充足 | | ROM 总量 | 268 KB → ≈ 298 KB | 1 MB Flash,余量充足 |
| RAM(`ui_data`) | ≈ 380 B | 见 `docs/UI设计/UI_数据供给设计说明.md` §10 | | RAM(`ui_data`) | ≈ 380 B | 见 `docs/UI设计/UI_数据供给设计.md` §10 |
| RAM(页面缓存) | ≈ 130 B/数据页 | 6 个数据页 ≈ 800 B | | RAM(页面缓存) | ≈ 130 B/数据页 | 6 个数据页 ≈ 800 B |
| LVGL 池 | 0 增量 | 页面全自绘,无子对象 | | LVGL 池 | 0 增量 | 页面全自绘,无子对象 |
| 记录存储 | +160 KB NAND | 5 类新日志,需核 NAND 余量 | | 记录存储 | +160 KB NAND | 5 类新日志,需核 NAND 余量 |
@@ -625,7 +625,7 @@ SNTP 客户端 ──────→ 批4 SNTP设置
| 3 | 未标定态可见 | `eng=0` 时交流量第 7 行显示"未标定" | | 3 | 未标定态可见 | `eng=0` 时交流量第 7 行显示"未标定" |
| 4 | 无源点显示 `--` | 遥信量无效点、直流量直流通道 | | 4 | 无源点显示 `--` | 遥信量无效点、直流量直流通道 |
| 5 | 定值整定闭环 | 改 → 保存 → 重启 → 值保持 + 校验和自检通过 + 主站 C_RD 一致。**2026-10-26 半收口**:模拟器侧「改 → 保存 → `OK` → 回首屏新值已在帧里」与「越界被拒、值不落盘」已由像素 + 文本断言覆盖(`sparam_save` / `sparam_landed` / `sparam_oob`);**重启保持与 C_RD 一致只能上板**(模拟器无 NAND)。另注意 40 项里 **13 项 `comm_addr = 0`**(投退、返回系数、过频/低频段、全局软压板)主站不可寻址,不能拿 C_RD 当它们的判据 | | 5 | 定值整定闭环 | 改 → 保存 → 重启 → 值保持 + 校验和自检通过 + 主站 C_RD 一致。**2026-10-26 半收口**:模拟器侧「改 → 保存 → `OK` → 回首屏新值已在帧里」与「越界被拒、值不落盘」已由像素 + 文本断言覆盖(`sparam_save` / `sparam_landed` / `sparam_oob`);**重启保持与 C_RD 一致只能上板**(模拟器无 NAND)。另注意 40 项里 **13 项 `comm_addr = 0`**(投退、返回系数、过频/低频段、全局软压板)主站不可寻址,不能拿 C_RD 当它们的判据 |
| 6 | 分层门禁无新增 | `check_layer_deps.py` 退出码 0,基线 6 → 3。**现状:3**(记录 reader 已削 3 条;写路径走注入式 ops 函数表,未新增 include,见 `docs/UI设计/UI_数据供给设计说明.md` §6.2) | | 6 | 分层门禁无新增 | `check_layer_deps.py` 退出码 0,基线 6 → 3。**现状:3**(记录 reader 已削 3 条;写路径走注入式 ops 函数表,未新增 include,见 `docs/UI设计/UI_数据供给设计.md` §6.2) |
| 7 | 像素回归稳定 | `ui-golden` 连续两次零差异。**已验(2026-10-26)**:27 页连跑两次逐字节一致——**该下限此后已扩至 66 张**(新增 clock / reset / clear 系列 13 张,其后 47→53→60→66,2026-10-29 录波 UI 道 +6 张),66 张上的双次逐字节一致**已验(2026-10-29:任务树重建模拟器后同一批 66 张连跑三次逐字节一致,页面池水位 5,448 B;菜单侧 `check_menu_rows.py` 8 状态连跑三次亦逐字节一致,5,368 B;三次之间未用更新模式写过任何参考图,故这是同口径的传递性证据)**。集合其后扩至 74 张——2026-11-13 按同口径跑过 74 张零差异(task-3 五页接自动刷新,无头不跑 `lv_timer_handler`,往返水位 5,448 B / 菜单 5,368 B 均不动) | | 7 | 像素回归稳定 | `ui-golden` 连续两次零差异。**已验(2026-10-26)**:27 页连跑两次逐字节一致——**该下限此后已扩至 66 张**(新增 clock / reset / clear 系列 13 张,其后 47→53→60→66,2026-10-29 录波 UI 道 +6 张),66 张上的双次逐字节一致**已验(2026-10-29:任务树重建模拟器后同一批 66 张连跑三次逐字节一致,页面池水位 5,448 B;菜单侧 `check_menu_rows.py` 8 状态连跑三次亦逐字节一致,5,368 B;三次之间未用更新模式写过任何参考图,故这是同口径的传递性证据)**。集合其后扩至 74 张——2026-11-13 按同口径跑过 74 张零差异(task-3 五页接自动刷新,无头不跑 `lv_timer_handler`,往返水位 5,448 B / 菜单 5,368 B 均不动) |
| 8 | 每个新页有 golden 参考 | `simulator/tests/ref/` 新增对应 `.bin`。**整定 4 页已有 9 张**(含保存/越界/落定/回绕各态);参考图入库,改它 = 改判据,须逐页过目 | | 8 | 每个新页有 golden 参考 | `simulator/tests/ref/` 新增对应 `.bin`。**整定 4 页已有 9 张**(含保存/越界/落定/回绕各态);参考图入库,改它 = 改判据,须逐页过目 |
@@ -650,6 +650,6 @@ SNTP 客户端 ──────→ 批4 SNTP设置
|---|---| |---|---|
| `docs/UI设计/页面补齐规划.md` | 现状规模、逐页形态与数据来源、未绑三叶的原因 | | `docs/UI设计/页面补齐规划.md` | 现状规模、逐页形态与数据来源、未绑三叶的原因 |
| **本文** | 每一页显示哪些行、数据从哪来、要改哪些代码 | | **本文** | 每一页显示哪些行、数据从哪来、要改哪些代码 |
| `docs/UI设计/UI_数据供给设计说明.md` | 数据怎么从 App 到 UI(通道/契约/并发/写路径) | | `docs/UI设计/UI_数据供给设计.md` | 数据怎么从 App 到 UI(通道/契约/并发/写路径) |
| `docs/UI设计/内容页架构.md` | 页面框架本身(描述符/钩子/权限) | | `docs/UI设计/内容页架构.md` | 页面框架本身(描述符/钩子/权限) |
| `docs/问题记录/采集与数据处理短板评测.md` | 为什么有些数据现在没有(标定/遥测链/运行参数/录波) | | `docs/问题记录/采集与数据处理短板评测.md` | 为什么有些数据现在没有(标定/遥测链/运行参数/录波) |
@@ -627,7 +627,7 @@ flowchart LR
「记录类型 = 日志 ID 本身」(一类记录一个文件,记录体内无类型字段位);UI 六页已绑 「记录类型 = 日志 ID 本身」(一类记录一个文件,记录体内无类型字段位);UI 六页已绑
(记录 5 页 + 运行报告,2026-10-28)。运行报告的四个数取自 boot_stats(SD2506 用户 SRAM (记录 5 页 + 运行报告,2026-10-28)。运行报告的四个数取自 boot_stats(SD2506 用户 SRAM
上电次数 + 本次复位原因快照)与 iec104_serv 的四个只读观测计数,经 info 帧下发 上电次数 + 本次复位原因快照)与 iec104_serv 的四个只读观测计数,经 info 帧下发
(口径 docs/UI设计/UI_数据供给设计说明.md §4.4)。 (口径 docs/UI设计/UI_数据供给设计.md §4.4)。
- 判据:五类记录各有写入点、可翻最近 20 条、空记录明确显示"无记录"、共用 reader——**软件面已满足** - 判据:五类记录各有写入点、可翻最近 20 条、空记录明确显示"无记录"、共用 reader——**软件面已满足**
(空态与四个范围标签由 74 张像素黄金钉住;模拟器侧这些文件没有写入方,只拍到空态)。 (空态与四个范围标签由 74 张像素黄金钉住;模拟器侧这些文件没有写入方,只拍到空态)。
真记录翻页、掉电后保持(复位代理口径)、清除记录后归零、boot_count 自增、rst_cause=IWDG、 真记录翻页、掉电后保持(复位代理口径)、清除记录后归零、boot_count 自增、rst_cause=IWDG、
@@ -1149,8 +1149,8 @@ for (i = 1; i < LED_COUNT; i++) /* LE
| 8 | 键值集(网络通道) | 8 键(含 F1 / F2) | 6 键(无 F1 / F2) | 补 F1 / F2;**仅网络通道**——屏板无 F1/F2 物理键(§5.16.3 ②) | | 8 | 键值集(网络通道) | 8 键(含 F1 / F2) | 6 键(无 F1 / F2) | 补 F1 / F2;**仅网络通道**——屏板无 F1/F2 物理键(§5.16.3 ②) |
| 9 | 任务模型 | 独立任务 prio 111 / 栈 212 KB | `uiTask` 10 ms 轮询(prio BelowNormal / 16 KB) | **形态差异,不追平**(X1 / X2) | | 9 | 任务模型 | 独立任务 prio 111 / 栈 212 KB | `uiTask` 10 ms 轮询(prio BelowNormal / 16 KB) | **形态差异,不追平**(X1 / X2) |
| 10 | 接收侧 CRC | 仅 LCDMEM / KEY 校验 | 全帧校验 | **本产品更严,保留** | | 10 | 接收侧 CRC | 仅 LCDMEM / KEY 校验 | 全帧校验 | **本产品更严,保留** |
| 11 | **串口屏板通道** | **有**:显存 3200 B + 状态灯 4 B 下行、键号上行,变化驱动 + 500 ms 兜底 | **已交付**:700000 8N1、一召一答 4208 B、键号上行(docs/子系统设计/屏板链路设计.md) | 验收尾巴见该设计说明 §9.2 | | 11 | **串口屏板通道** | **有**:显存 3200 B + 状态灯 4 B 下行、键号上行,变化驱动 + 500 ms 兜底 | **已交付**:700000 8N1、一召一答 4208 B、键号上行(docs/子系统设计/屏板链路设计.md) | 验收尾巴见该设计说明 §9 |
| 12 | 双出口并发 | 同一份显存同时喂串口与网络,互不阻塞 | 两出口并存(7003 + 串口通道),60 s 并发台架无互扰 | —(屏板链路设计 §9.1) | | 12 | 双出口并发 | 同一份显存同时喂串口与网络,互不阻塞 | 两出口并存(7003 + 串口通道),60 s 并发台架无互扰 | —(双出口并发模型见屏板链路设计) |
| 13 | 屏板状态指示灯 | 20 路(ID 0 电源常亮 + ID 1~19 位掩码),**4 B 小端**随每帧下发 | **已交付**:5 位映射 `App/algo/sb_led_map.h`(屏板链路设计 §6);主板另有 6 路 GPIO LED(`LED1~6`) | 逐位目视验收未闭环(设计说明 §9.2) | | 13 | 屏板状态指示灯 | 20 路(ID 0 电源常亮 + ID 1~19 位掩码),**4 B 小端**随每帧下发 | **已交付**:5 位映射 `App/algo/sb_led_map.h`(屏板链路设计 §6);主板另有 6 路 GPIO LED(`LED1~6`) | 逐位目视验收未闭环(设计说明 §9.2) |
| 14 | 背光 / 对比度 | 主机 BSP 有 `Lcd_BackLight` / `Lcd_SetContrast` + 空闲 120 s 熄灭 | 无 | **不做**——屏板固件自管背光,两条路径不能同时启用 | | 14 | 背光 / 对比度 | 主机 BSP 有 `Lcd_BackLight` / `Lcd_SetContrast` + 空闲 120 s 熄灭 | 无 | **不做**——屏板固件自管背光,两条路径不能同时启用 |
@@ -1687,7 +1687,7 @@ pre-commit run --all-files
| **SNTP 对时** | 17 | 参考对时走 SNTP | **SNTP 客户端已落地**(2026-11-04:coreSNTP 序列化器 + `[sntp]` 配置 + UI 设置页 + timeSyncTask 接入,判据 §5.3 FR-TIME-3);另有 104 `C_CS`(私有 TCP 8888 已随 #78 退役删除) | 台架真机对时判据(现场时间源,见 `docs/子系统设计/系统墙钟时间维护说明.md` §16) | | **SNTP 对时** | 17 | 参考对时走 SNTP | **SNTP 客户端已落地**(2026-11-04:coreSNTP 序列化器 + `[sntp]` 配置 + UI 设置页 + timeSyncTask 接入,判据 §5.3 FR-TIME-3);另有 104 `C_CS`(私有 TCP 8888 已随 #78 退役删除) | 台架真机对时判据(现场时间源,见 `docs/子系统设计/系统墙钟时间维护说明.md` §16) |
| **固有参数** | 1 | `8001H~800AH` 字符串类参数 | 未实现(无法短浮点上送) | 随送检点表设计 | | **固有参数** | 1 | `8001H~800AH` 字符串类参数 | 未实现(无法短浮点上送) | 随送检点表设计 |
| **遥测增强** | 4、5 | k=1~9 谐波方和根 + 4 点平均 | 仅基波轨 | 谐波 / 等周波调频 / 零序自产外接切换 三条算法轨 | | **遥测增强** | 4、5 | k=1~9 谐波方和根 + 4 点平均 | 仅基波轨 | 谐波 / 等周波调频 / 零序自产外接切换 三条算法轨 |
| **屏板链路对齐** | 20 | **串口屏板通道**(**700000 8N1 / USART1 TTL 直连、无 DE**,帧 A 6 B 召唤、帧 B **4208 B** 应答:显存 3200 B + **状态灯 4 B 位掩码** + 4 B info)+ **7003 四命令**(INIT **16 B**,单色口径)+ 续传 / 拒绝握手 / 链路监视 / F1·F2 | **串口通道已交付**(4208 B 应答 / 状态灯掩码 / 键上行 / 双出口并发,屏板链路设计 §9.1);7003 四命令(INIT **8 B**);无续传、无 `bNeedFlash` 拒绝、无 1 分钟监视、键值 6 个 | 7003 报文口径 6 项(`参考产品复刻明细.md` §11 第 2~9 条);串口侧验收尾巴见屏板链路设计 §9.2 | | **屏板链路对齐** | 20 | **串口屏板通道**(**700000 8N1 / USART1 TTL 直连、无 DE**,帧 A 6 B 召唤、帧 B **4208 B** 应答:显存 3200 B + **状态灯 4 B 位掩码** + 4 B info)+ **7003 四命令**(INIT **16 B**,单色口径)+ 续传 / 拒绝握手 / 链路监视 / F1·F2 | **串口通道已交付**(4208 B 应答 / 状态灯掩码 / 键上行 / 双出口并发,屏板链路设计);7003 四命令(INIT **8 B**);无续传、无 `bNeedFlash` 拒绝、无 1 分钟监视、键值 6 个 | 7003 报文口径 6 项(`参考产品复刻明细.md` §11 第 2~9 条);串口侧验收尾巴见屏板链路设计 §9 |
> **一句话**:**「标定闭锁」是唯一"再排期也没用"的缺口**(等标准源);「出口与开入」「三相与同期」 > **一句话**:**「标定闭锁」是唯一"再排期也没用"的缺口**(等标准源);「出口与开入」「三相与同期」
> 「电度计量」等 V0.2 硬件;「对下采集」等用户决策;其余规模型条目**全部可在现有硬件上推进**, > 「电度计量」等 V0.2 硬件;「对下采集」等用户决策;其余规模型条目**全部可在现有硬件上推进**,
+2 -2
View File
@@ -292,7 +292,7 @@ flowchart TB
- **单一事实源 = 仓根 `ui_menu_tree.txt`**(61 行,16 个受保护叶 ` #P`):缩进即层级,`#page=<模块>` 把叶子绑到 `ui_page_<模块>.c` 的描述符;重跑 `tools/menu_gen/gen_menu.py` 生成 `ui_menu_tab.*` 与 `ui_page_registry.*`,并**自动把新页写进双端注册文件**(`uvprojx` + `CMakeLists.txt`)。写了却不绑定的 `ui_page_*.c` 生成器直接报错(不留死代码)。 - **单一事实源 = 仓根 `ui_menu_tree.txt`**(61 行,16 个受保护叶 ` #P`):缩进即层级,`#page=<模块>` 把叶子绑到 `ui_page_<模块>.c` 的描述符;重跑 `tools/menu_gen/gen_menu.py` 生成 `ui_menu_tab.*` 与 `ui_page_registry.*`,并**自动把新页写进双端注册文件**(`uvprojx` + `CMakeLists.txt`)。写了却不绑定的 `ui_page_*.c` 生成器直接报错(不留死代码)。
- 内容页为**独立全屏屏**,由框架一次性自绘(**零 LVGL 子对象**),ESC 返回菜单屏。 - 内容页为**独立全屏屏**,由框架一次性自绘(**零 LVGL 子对象**),ESC 返回菜单屏。
- 菜单受保护叶子(行尾 ` #P`):先弹密码页,授权后 `menu_password_ok` **先关页再续进入动作**。 - 菜单受保护叶子(行尾 ` #P`):先弹密码页,授权后 `menu_password_ok` **先关页再续进入动作**。
- **数据供给**:页面不直接伸手进业务模块,一律读 `ui_data.h` 三帧快照(实时量/参数/装置信息);写侧唯一填充者 `ui_data_feed`(装配层,可双向 include 不违分层)。契约属主 `docs/UI设计/UI_数据供给设计说明.md`。 - **数据供给**:页面不直接伸手进业务模块,一律读 `ui_data.h` 三帧快照(实时量/参数/装置信息);写侧唯一填充者 `ui_data_feed`(装配层,可双向 include 不违分层)。契约属主 `docs/UI设计/UI_数据供给设计.md`。
- **显存一份三出**(§5):屏板串口为主出口(4208 B 帧 B 点阵,memcmp 判变才组帧),:7003 为网络镜像,模拟器与固件同一份 UI 源码;屏板按键经 uiTask 映射 `UI_KEY_*` 回注。→ `docs/子系统设计/屏板链路设计.md` - **显存一份三出**(§5):屏板串口为主出口(4208 B 帧 B 点阵,memcmp 判变才组帧),:7003 为网络镜像,模拟器与固件同一份 UI 源码;屏板按键经 uiTask 映射 `UI_KEY_*` 回注。→ `docs/子系统设计/屏板链路设计.md`
- 录波两页:`wave_manual`(装置上手动触发录波)与 `wave_play`(现场单通道回放)——判据与显示契约见 `docs/子系统设计/故障录波设计说明.md` §8。 - 录波两页:`wave_manual`(装置上手动触发录波)与 `wave_play`(现场单通道回放)——判据与显示契约见 `docs/子系统设计/故障录波设计说明.md` §8。
- 待机屏:空闲超时(默认 60s)自动切入,仅确认键回菜单;数据源同实时量页。 - 待机屏:空闲超时(默认 60s)自动切入,仅确认键回菜单;数据源同实时量页。
@@ -402,7 +402,7 @@ flowchart LR
| 栈/内存观测工具 | `scripts/stack_report.py`(Keil 静态调用图 × 串口 `[STACK]` 水位,判定取两者更坏者)· `scripts/ram_report.py`(.map 静态占用)—— 用法与基线见内存方案 §4.0.6 | | 栈/内存观测工具 | `scripts/stack_report.py`(Keil 静态调用图 × 串口 `[STACK]` 水位,判定取两者更坏者)· `scripts/ram_report.py`(.map 静态占用)—— 用法与基线见内存方案 §4.0.6 |
| FTP 功能与陷阱 | `docs/测试说明/板级测试/FTP_Test_Guide.md` §8.6(启动门)/ §8.7(单客户端)· 脚本 `test/host/ftp_up_dl_test.py`、`test/host/ftp_regression.py`、`test/host/ftp_integrity_test.py` | | FTP 功能与陷阱 | `docs/测试说明/板级测试/FTP_Test_Guide.md` §8.6(启动门)/ §8.7(单客户端)· 脚本 `test/host/ftp_up_dl_test.py`、`test/host/ftp_regression.py`、`test/host/ftp_integrity_test.py` |
| UI 设计架构 / 内容页 / 菜单 | `docs/UI设计/UI_设计架构.md` · `内容页架构.md` · `菜单页面设计.md` | | UI 设计架构 / 内容页 / 菜单 | `docs/UI设计/UI_设计架构.md` · `内容页架构.md` · `菜单页面设计.md` |
| UI 数据供给契约(rt/par/info 三帧) | `docs/UI设计/UI_数据供给设计说明.md` | | UI 数据供给契约(rt/par/info 三帧) | `docs/UI设计/UI_数据供给设计.md` |
| RemoDispBus 远程显示协议(:7003) | `docs/UI设计/RemoDispBus协议与接收设计说明.md` | | RemoDispBus 远程显示协议(:7003) | `docs/UI设计/RemoDispBus协议与接收设计说明.md` |
| UI 自动化测试 | `docs/UI设计/UI_自动化测试流程.md` | | UI 自动化测试 | `docs/UI设计/UI_自动化测试流程.md` |
| 驱动已知陷阱 | `docs/问题记录/{CH395F,GD5F2GQ5UE,SD2506}_Trap_Records.md` | | 驱动已知陷阱 | `docs/问题记录/{CH395F,GD5F2GQ5UE,SD2506}_Trap_Records.md` |
@@ -424,7 +424,7 @@ uint16_t ch395f_link_change_count(void);
该文件 80 次提交、15 次 fix/refactor,值;但**一次做完必翻车**(先求把状态机进分母,别求百分比)。 该文件 80 次提交、15 次 fix/refactor,值;但**一次做完必翻车**(先求把状态机进分母,别求百分比)。
2. **`sys_log_mcu.c`(458) + `cfg_file_store_mcu.c`(129) + `soe_store.c`(123) = 710 行** —— 一套假 FatFs 2. **`sys_log_mcu.c`(458) + `cfg_file_store_mcu.c`(129) + `soe_store.c`(123) = 710 行** —— 一套假 FatFs
吃三块,性价比最高的第二批。判据现成:`docs/子系统设计/运行与自检记录设计.md` §3.2(写侧批量合并 + **掉电语义不变** + 吃三块,性价比最高的第二批。判据现成:`docs/子系统设计/运行与自检记录设计.md` §3.2(写侧批量合并 + **掉电语义不变** +
失败回投不丢条目 + 容量轮转只在慢路径)与 `docs/子系统设计/运行与自检记录设计.md` §4.5 失败回投不丢条目 + 容量轮转只在慢路径)与 `docs/子系统设计/运行与自检记录设计.md` §4.4
(读侧 8 条窗口 + 写者代数失效 + API 不变)。 (读侧 8 条窗口 + 写者代数失效 + API 不变)。
这块的历史教训就是"日志读写放大"与"`mkdir` 失败静默不再重试"。 这块的历史教训就是"日志读写放大"与"`mkdir` 失败静默不再重试"。
3. **`console_log.c`(265)** —— 单写者契约 K1/K2 已经写成表,照抄成用例最省力: 3. **`console_log.c`(265)** —— 单写者契约 K1/K2 已经写成表,照抄成用例最省力:
+1 -1
View File
@@ -25,7 +25,7 @@
`NET/lftpd/lftpd_io.c` → `App/fs/vol_lock.h`。 `NET/lftpd/lftpd_io.c` → `App/fs/vol_lock.h`。
已还清:`UI/ui_page_runlog.c`、`UI/ui_page_selftest.c`、`UI/ui_w_records.h` → `App/log/sys_log.h` 已还清:`UI/ui_page_runlog.c`、`UI/ui_page_selftest.c`、`UI/ui_w_records.h` → `App/log/sys_log.h`
(2026-10-25 task/UI-rec-reader:`ui_w_records` 改注入式 `ui_rec_reader_t`,契约见 (2026-10-25 task/UI-rec-reader:`ui_w_records` 改注入式 `ui_rec_reader_t`,契约见
`docs/UI设计/UI_数据供给设计说明.md` §7.2,绑定在 `App/task/ui_task.c` 与 `simulator/main.c`)。 `docs/UI设计/UI_数据供给设计.md` §7.2,绑定在 `App/task/ui_task.c` 与 `simulator/main.c`)。
修法是**注入 / 传参**(上层把数据或回调递进 BSP),不是把上层服务搬进 BSP。 修法是**注入 / 传参**(上层把数据或回调递进 BSP),不是把上层服务搬进 BSP。
## 2. 为什么要它 ## 2. 为什么要它
+1 -1
View File
@@ -86,7 +86,7 @@
## 7. 豁免与基线 ## 7. 豁免与基线
无存量豁免、无基线文件、无 `--write`。定值项数改变(`PS_ID_COUNT` ≠ 40)时必须同步:脚本里的 无存量豁免、无基线文件、无 `--write`。定值项数改变(`PS_ID_COUNT` ≠ 40)时必须同步:脚本里的
期望行数与 id 上界、`ui_data.h` 的 `UI_DATA_SET_N`、以及 `docs/UI设计/UI_数据供给设计说明.md` 期望行数与 id 上界、`ui_data.h` 的 `UI_DATA_SET_N`、以及 `docs/UI设计/UI_数据供给设计.md`
的参数通道说明。 的参数通道说明。
一条**已修正的原口径**记在这里免得被"改回去":四个返回系数按 2 位小数显示。原方案文档写 3 位, 一条**已修正的原口径**记在这里免得被"改回去":四个返回系数按 2 位小数显示。原方案文档写 3 位,
@@ -248,7 +248,7 @@
- **现状**:`Drivers/BSP/UI/ui_page_ac.c` 是硬编码占位数据(`"1.03"` 等),不接相量/频率。 - **现状**:`Drivers/BSP/UI/ui_page_ac.c` 是硬编码占位数据(`"1.03"` 等),不接相量/频率。
- **后果**:现场无法就地读数,只能靠主站;产品需求的内容页要求显示实时值。 - **后果**:现场无法就地读数,只能靠主站;产品需求的内容页要求显示实时值。
- **建议**:走 UI 数据快照层(App 侧 `ui_data_feed` 推、BSP 侧 `ui_data` 存、页面只读),**不能**让页面直接 include `phasor.h` / `freq.h`——分层门禁禁止。方案见 `docs/UI设计/UI_数据供给设计说明.md`。**放在标定(§4.1)之后做**——没有工程量,显示出来也是码值。 - **建议**:走 UI 数据快照层(App 侧 `ui_data_feed` 推、BSP 侧 `ui_data` 存、页面只读),**不能**让页面直接 include `phasor.h` / `freq.h`——分层门禁禁止。方案见 `docs/UI设计/UI_数据供给设计.md`。**放在标定(§4.1)之后做**——没有工程量,显示出来也是码值。
- **规模**:S。 - **规模**:S。
--- ---
+2 -1
View File
@@ -113,7 +113,8 @@ SEC_TERMINATORS = "。;!?"
CHANGELOG_WORDS = ("变更记录", "更新记录", "修订记录", "历史", "changelog") CHANGELOG_WORDS = ("变更记录", "更新记录", "修订记录", "历史", "changelog")
# 外部资料编号(芯片手册等):不受本仓库标题编号约束 # 外部资料编号(芯片手册等):不受本仓库标题编号约束
EXTERNAL_HINTS = ("RM0090", "参考手册", "数据手册", "手册", "datasheet", EXTERNAL_HINTS = ("RM0090", "参考手册", "数据手册", "手册", "datasheet",
"FreeRTOS", "CMSIS", "FatFs", "dhara", "LVGL", "Graphviz", "RFC") "FreeRTOS", "CMSIS", "FatFs", "dhara", "LVGL", "Graphviz", "RFC",
"IEC 60870")
# D 类计数(覆盖率可见化:每次跑都打印,防止比例悄悄回落) # D 类计数(覆盖率可见化:每次跑都打印,防止比例悄悄回落)
SEC_STATS = Counter() SEC_STATS = Counter()
# 机器判不了目标的 § 引用清单(--section-todo 打印,供逐步改成紧邻写法) # 机器判不了目标的 § 引用清单(--section-todo 打印,供逐步改成紧邻写法)
+2 -2
View File
@@ -116,7 +116,7 @@ LVGL 场景(同一份 ui_menu.c)
| 日志 | `Drivers/BSP/dbg_log.h`(USART1 + RTC 时间戳) | `simulator/dbg_log.h`(printf stub) | | 日志 | `Drivers/BSP/dbg_log.h`(USART1 + RTC 时间戳) | `simulator/dbg_log.h`(printf stub) |
| 业务任务 | netTask / ftpTask / timeSyncTask 等 | 无(仅编译纯软件部分的配置文件引擎 net_cfg/cfg_file,可离线验证配置加载/保存) | | 业务任务 | netTask / ftpTask / timeSyncTask 等 | 无(仅编译纯软件部分的配置文件引擎 net_cfg/cfg_file,可离线验证配置加载/保存) |
| 时钟 | `lv_tick_inc` 由 ui_task 手动喂(10ms 周期) | SDL 驱动内部 `lv_tick_set_cb(SDL_GetTicks)`,**不可再手动喂** | | 时钟 | `lv_tick_inc` 由 ui_task 手动喂(10ms 周期) | SDL 驱动内部 `lv_tick_set_cb(SDL_GetTicks)`,**不可再手动喂** |
| UI 数据来源 | `App/app/ui_data_feed.c` 每轮从 phasor / prot_set / 104 点表…装配并发布三帧 | `main.c` 一次性发布**固定帧**(定值不手抄数字,取链进来的 `App/algo/prot_set.c` 出厂默认);口径 `docs/UI设计/UI_数据供给设计说明.md` §9.2 | | UI 数据来源 | `App/app/ui_data_feed.c` 每轮从 phasor / prot_set / 104 点表…装配并发布三帧 | `main.c` 一次性发布**固定帧**(定值不手抄数字,取链进来的 `App/algo/prot_set.c` 出厂默认);口径 `docs/UI设计/UI_数据供给设计.md` §9.2 |
| 定值写路径(保存) | `ui_data_feed_tick()` 里 `ui_data_param_drain()` 落定 → 置脏 → defaultTask 写 `/prot_set.bin` | `sim_param_pump()` 用**同一份** `g_prot_set_meta` 上下限预检后落值到 RAM,**到此为止**:模拟器无 NAND,"重启值保持 / 主站 C_RD 读到同值"只能上板验(差距登记 `docs/测试说明/专项验证/模拟器差距清单.md`) | | 定值写路径(保存) | `ui_data_feed_tick()` 里 `ui_data_param_drain()` 落定 → 置脏 → defaultTask 写 `/prot_set.bin` | `sim_param_pump()` 用**同一份** `g_prot_set_meta` 上下限预检后落值到 RAM,**到此为止**:模拟器无 NAND,"重启值保持 / 主站 C_RD 读到同值"只能上板验(差距登记 `docs/测试说明/专项验证/模拟器差距清单.md`) |
### 2.4 关键设计决策 ### 2.4 关键设计决策
@@ -238,7 +238,7 @@ UI 改动的自动化门禁脚本(完整流程见 `docs/UI设计/UI_自动化
① 界面侧任何**周期性 LVGL 定时器**(如定值视图为"落定/主站写值/标定完成"上屏而建的 100 ms ① 界面侧任何**周期性 LVGL 定时器**(如定值视图为"落定/主站写值/标定完成"上屏而建的 100 ms
轮询)在回归里一次都不会触发 → 像素与它无关,只有窗口模式才用它;② 两次注键之间不发生 轮询)在回归里一次都不会触发 → 像素与它无关,只有窗口模式才用它;② 两次注键之间不发生
重绘,所以"数据就位"不能依赖"这一页画过没有"——判据连跑两次逐字节一致即为证据,设计口径见 重绘,所以"数据就位"不能依赖"这一页画过没有"——判据连跑两次逐字节一致即为证据,设计口径见
`docs/UI设计/UI_数据供给设计说明.md` §9.2 注 6。 `docs/UI设计/UI_数据供给设计.md` §9.2。
- **池水位常量漂移**:菜单/页面结构变更导致门禁失败时,确认新值合理后再更新脚本内常量并登记流程文档变更记录;无法解释的漂移 = 内存回归 bug。 - **池水位常量漂移**:菜单/页面结构变更导致门禁失败时,确认新值合理后再更新脚本内常量并登记流程文档变更记录;无法解释的漂移 = 内存回归 bug。
- 退出码均为 0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等)。 - 退出码均为 0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等)。
+2 -2
View File
@@ -13,13 +13,13 @@
快照层是页面看到的整个世界,但 ui-golden 只覆盖"已接线的页面"——遥信 27 点、 快照层是页面看到的整个世界,但 ui-golden 只覆盖"已接线的页面"——遥信 27 点、
定值 40 项、遥测 9 路这类"还没接线的通道"错了不会让任何一张参考图变红。 定值 40 项、遥测 9 路这类"还没接线的通道"错了不会让任何一张参考图变红。
跨层不透明下标(yc 序 = adc_semantic_t、q10 序 = prot_set_id_t)正是解耦换来 跨层不透明下标(yc 序 = adc_semantic_t、q10 序 = prot_set_id_t)正是解耦换来
的风险面,契约把它钉在编译/测试期(docs/UI设计/UI_数据供给设计说明.md §9.4)。 的风险面,契约把它钉在编译/测试期(docs/UI设计/UI_数据供给设计.md §9.4)。
用法(仓库根目录): 用法(仓库根目录):
python test/host/ui_data/run_unit_test.py python test/host/ui_data/run_unit_test.py
退出码:0=PASS / 1=测试失败 / 2=环境错误。 退出码:0=PASS / 1=测试失败 / 2=环境错误。
设计依据:docs/UI设计/UI_数据供给设计说明.md §9.1 / §12 判据 8(道E task-14); 设计依据:docs/UI设计/UI_数据供给设计.md §9.1(主机单测判据)/ §9.4(一致性测试);
创建日期:2026-10-25 创建日期:2026-10-25
""" """
import os import os
+2 -2
View File
@@ -13,7 +13,7 @@
* 2) 跨层"魔法下标"(yc 序 = adc_semantic_t、q10 序 = prot_set_id_t)是解耦的 * 2) 跨层"魔法下标"(yc 序 = adc_semantic_t、q10 序 = prot_set_id_t)是解耦的
* 代价,契约把它从运行期风险降级为编译/测试期错误的第 3 条断言就落在这里 * 代价,契约把它从运行期风险降级为编译/测试期错误的第 3 条断言就落在这里
* (同一 TU 里同时 include 两侧头,见 * (同一 TU 里同时 include 两侧头,见
* docs/UI设计/UI_数据供给设计说明.md §9.4); * docs/UI设计/UI_数据供给设计.md §9.4);
* 3) "首帧之前显示 -- 而不是 0.000"是诚实性判据,板子上电只有一次、台架碰不到, * 3) "首帧之前显示 -- 而不是 0.000"是诚实性判据,板子上电只有一次、台架碰不到,
* 主机侧可以随时复现。 * 主机侧可以随时复现。
* *
@@ -312,7 +312,7 @@ static void tc_constants(void)
CHECK((UI_DATA_Q_IV & UI_DATA_Q_NT) == 0u, "TC-UIDATA-008c IV/NT disjoint"); CHECK((UI_DATA_Q_IV & UI_DATA_Q_NT) == 0u, "TC-UIDATA-008c IV/NT disjoint");
CHECK((UI_DATA_Q_OV & UI_DATA_Q_SB) == 0u, "TC-UIDATA-008d OV/SB disjoint"); CHECK((UI_DATA_Q_OV & UI_DATA_Q_SB) == 0u, "TC-UIDATA-008d OV/SB disjoint");
CHECK((UI_DATA_Q_BL & UI_DATA_Q_RAW) == 0u, "TC-UIDATA-008e BL/RAW disjoint"); CHECK((UI_DATA_Q_BL & UI_DATA_Q_RAW) == 0u, "TC-UIDATA-008e BL/RAW disjoint");
/* 内存预算护栏(docs/UI设计/UI_数据供给设计说明.md §10):快照是 .bss 里的 /* 内存预算护栏(docs/UI设计/UI_数据供给设计.md §10):快照是 .bss 里的
* 定长结构,不是 LVGL 对象;一旦有人往里塞大数组或指针,这里先响 */ * 定长结构,不是 LVGL 对象;一旦有人往里塞大数组或指针,这里先响 */
CHECK(sizeof(ui_data_rt_t) <= 256u, "TC-UIDATA-008f rt frame within budget (<=256B)"); CHECK(sizeof(ui_data_rt_t) <= 256u, "TC-UIDATA-008f rt frame within budget (<=256B)");
CHECK(sizeof(ui_data_par_t) <= 200u, "TC-UIDATA-008g par frame within budget (<=200B)"); CHECK(sizeof(ui_data_par_t) <= 200u, "TC-UIDATA-008g par frame within budget (<=200B)");