Files
STM32F4-Base/Drivers/BSP/UI/ui_w_records.h
T
wandering1 b7a3e18dca 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。
2026-11-17 11:59:45 +08:00

143 lines
8.2 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 模块名称:UI 记录页共享组件(运行记录 / 自检记录两页的公共实现)
* 模块功能:把"定长记录 -> 每记录 2 行(偶数行时间戳、奇数行描述)+ 同记录读盘缓存
* + 空态单条伪行"这套逻辑收成一份,供多个日志页按实例复用;
* 数据经注入式 reader 回调取(UI_数据供给设计说明.md §7.2 契约),
* 本头**不含任何 App 头**——记录属主 sys_log 留在 App 侧,启动时由
* App/task/ui_task.c(MCU)与 simulator/main.c(PC)各注入一份薄包装
* 适用范围:Drivers/BSP/UI(仅 UI 层;分层方向由 check_layer_deps 门禁守护)
* 说明:缓存必须按实例存放而非文件级静态——两页共用代码但各有独立实例,
* 若共享缓存,从 A 页切到 B 页会命中上一记录号而显示另一页的陈旧行(静默错数据)。
* 作者:王建锋
* 创建日期:2026-10-20
* 修改记录:
* v1.0 2026-10-20 王建锋 创建(W6:合并 ui_page_runlog / ui_page_selftest 的重复实现)
* v2.0 2026-10-25 王建锋 记录 reader 注入(道B task-6):删 #include "sys_log.h",
* 改 ui_rec_reader_t 函数表 + ui_w_records_bind();
* log_id 换不透明编号(UI_W_REC_LOG_*);缓冲容量宏本地化
* (与 sys_log 契约下限同宽,逐字节一致)
*/
#ifndef UI_W_RECORDS_H
#define UI_W_RECORDS_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/* 记录源不透明编号:UI 侧只认"N 号日志",App 侧适配层映射到 syslog_id_t
* (映射表见 App/task/ui_task.c 与 simulator/main.c 的绑定处;新增记录页 =
* 这里加编号 + 两端适配层各加一条映射)
* ⚠ **顺序契约(Lead 裁定 2026-10-26,task-6 起 7 条)**:本表顺序必须逐字等于
* App/log/sys_log.h 的 syslog_id_t 枚举序(RUN/SELFTEST/ACCIDENT/ALARM/START/
* OPER/YK),且**只准尾部追加**——枚举序就是两端 s_paths[]/s_caps[] 的下标,
* 中间插值会安静地把事故写进告警文件(记录侧已有 TC-SYSLOG-130/131/131b 那条
* 机械防线,UI 侧对应的那条 = test/host/ui_data 的 TC-UIDATA-024 逐项核对 +
* 两端适配层里的编译期数组守卫;编号"不透明"指的是**页面不得依赖**这个相等,
* 不是允许两者各数各的:适配层始终显式映射,从不把本编号强转成 syslog_id_t)。
* 追加之外的任何改动(换序/删号/复用号)都会让已落盘的记录被读成别的类别。 */
#define UI_W_REC_LOG_RUN 0u /* 0 号:运行记录(MCU /log/run.log) */
#define UI_W_REC_LOG_SELFTEST 1u /* 1 号:自检记录(MCU /log/selftest.log) */
#define UI_W_REC_LOG_ACCIDENT 2u /* 2 号:事故记录(/log/accid.log,跳闸型动作) */
#define UI_W_REC_LOG_ALARM 3u /* 3 号:保护告警(/log/alarm.log,告警型动作) */
#define UI_W_REC_LOG_START 4u /* 4 号:保护启动(/log/start.log,picked 上升沿) */
#define UI_W_REC_LOG_OPER 5u /* 5 号:操作记录(/log/oper.log,人工/远端操作留痕) */
#define UI_W_REC_LOG_YK 6u /* 6 号:遥控记录(/log/yk.log,104 选择/执行/拒绝) */
#define UI_W_REC_LOG_N 7u /* 编号个数(上界;两端映射表的数组长度,不是合法编号) */
/* 读取缓冲容量(UI 侧定义;必须 >= sys_log 契约下限:时间戳 19+NUL、描述 28+NUL。
* sys_log 侧 SYSLOG_TS_LEN/SYSLOG_DESC_MAX 变化时这里同步加宽——容量不足时
* reader 按契约返回负码、页面退化空行,不会读越界) */
#define UI_W_REC_TS_LEN 20u /* "YYYY-MM-DD HH:MM:SS" 19 + NUL */
#define UI_W_REC_DESC_LEN 29u /* 描述 28 + NUL */
/*
* 注入式记录 reader(只读函数表;契约 = UI_数据供给设计说明.md §7.2)
* 实现体在 App / 模拟器侧,uiTask 上下文同步调用——记录页绘制路径上的读盘
* 时序与合并前直调 syslog_* 完全一致,无新增并发面
*/
typedef struct {
/*
* 函数功能:取该日志当前记录条数
* 入口参数:log_id - 不透明记录源编号(UI_W_REC_LOG_*) uint8_t
* 返回值:记录条数(0 = 空态,页面显示伪行"无记录") uint16_t
*/
uint16_t (*count)(uint8_t a_log_id);
/*
* 函数功能:读第 idx 条记录(时间戳 + 描述两字段)
* 入口参数:log_id - 记录源编号 uint8_t
* idx - 记录序号(0 起) uint32_t
* ts - 时间戳缓冲 char *
* ts_len - ts 容量(>= UI_W_REC_TS_LEN) uint32_t
* desc - 描述缓冲 char *
* desc_len - desc 容量(>= UI_W_REC_DESC_LEN)uint32_t
* 返回值:0 = 成功;-1 = 序号/编号越界;-2 = 读失败
* (与 sys_log 契约同值,适配层直通不改码) int
*/
int (*get)(uint8_t a_log_id, uint32_t a_idx,
char *a_ts, uint32_t a_ts_len, char *a_desc, uint32_t a_desc_len);
} ui_rec_reader_t;
/*
* 记录页实例:记录源编号 + 该实例自己的读盘缓存
* 用法:页面文件里 static ui_w_records_t s_rec = { UI_W_REC_LOG_xxx };
* 其余字段自动清零,即"缓存初始无效",与合并前两页的行为一致。
*/
typedef struct {
uint8_t log_id; /* 记录源编号(UI_W_REC_LOG_*,透传给 reader) */
uint8_t cache_valid; /* 缓存有效标志(0 = 无缓存) */
uint32_t last_rec; /* 已缓存的记录序号 */
char ts[UI_W_REC_TS_LEN]; /* 时间戳缓存(含 NUL) */
char desc[UI_W_REC_DESC_LEN];/* 描述缓存(含 NUL) */
} ui_w_records_t;
/*
* 函数功能:注入记录 reader(启动时一次;NULL = 撤销注入,页面回到空态)
* 入口参数:reader - 只读函数表(生命周期由注入方保证,组件只存指针)
* const ui_rec_reader_t *
* 返回值:无
* 限定条件:uiTask 启动期注入(ui_menu_init 之前,UI_数据供给设计说明.md §7.2);
* 未注入时组件按"空态"渲染(伪行"无记录"),不崩不读野
* 函数说明:模块级单例——sys_log 读 API 本就是全局的,两端各只有一份实现;
* 两页共享函数表、独享各自的读盘缓存(缓存才是必须按实例存的那半)
*/
void ui_w_records_bind(const ui_rec_reader_t *a_reader);
/*
* 函数功能:按记录源编号查条数(不经行缓存的裸计数;清除记录页逐行显示用)
* 入口参数:log_id - 记录源编号(UI_W_REC_LOG_*) uint8_t
* 返回值:条数;未注入 reader 或编号未知一律 0,即空态,调用方按"无记录"显示
* uint16_t
* 限定条件:uiTask 上下文(绘制/按键链)
* 函数说明:reader 是本组件私有的注入表,不开放只读入口的话,想按行显示条数的
* 页面只能自己去注第二份 reader——那正好把 task-6 刚削掉的分层反向边
* 接回来(口径 docs/UI设计/UI_数据供给设计.md §7.2/§7.3);
* 本函数不带行缓存(缓存属于"某条记录的字段",与条数无关)
*/
uint16_t ui_w_records_count_of(uint8_t a_log_id);
/*
* 函数功能:总行数(动态;每条记录 2 行,空日志 = 单条伪行"无记录")
* 入口参数:a_inst - 记录页实例 ui_w_records_t *
* 返回值:总行数 uint16_t
*/
uint16_t ui_w_records_count(ui_w_records_t *a_inst);
/*
* 函数功能:逐行取数(偶数行 = 时间戳、奇数行 = 描述;值列恒空)
* 入口参数:a_inst - 记录页实例 ui_w_records_t *
* a_row - 全局行下标 uint16_t
* a_name - 名输出缓冲(框架栈缓冲 UI_BUF_STRLEN=32,含 NUL) char *
* a_value- 值输出缓冲(同上;本组件恒写空串) char *
* 限定条件:页面打开中(框架绘制/按键上下文,uiTask)
*/
void ui_w_records_refresh(ui_w_records_t *a_inst, uint16_t a_row, char *a_name, char *a_value);
#ifdef __cplusplus
}
#endif
#endif /* UI_W_RECORDS_H */