CCU621M/app/ui/ui模块说明.md

UI 模块说明（CCU621_M）

路径：app/ui/
返回主说明：README

1. 模块定位

app/ui 是整机的人机交互中枢，负责把“系统状态”转换为“屏幕可视化结果”，并把“屏幕触控/输入”转换为“系统控制动作”。

核心职责分为四类：

• 通信层：与迪文屏进行串口协议收发；
• 交互层：触控事件解析、输入字符串解析；
• 状态机层：页面跳转、页面生命周期、超时返回；
• 数据适配层：把业务数据统一封装给 UI（ui_interface.c）。

2. 代码结构与职责划分

• ui_task.c/.h

  • UI 主任务入口；
  • 页面状态机（当前页面判断、页面切换触发）；
  • 页面显示刷新调度（按 1s/首次进入/事件触发刷新）；
  • 看门狗喂狗和通信超时检测。

• ui_comm_impl.c/.h

  • 迪文协议封包/解包；
  • 控制寄存器与数据寄存器读写；
  • 字符串显示下发、动画图标下发；
  • 参数区块镜像管理与屏幕写回。

• ui_interface.c/.h

  • 提供统一的“取数/控数”接口；
  • 屏蔽底层模块差异（流程、BMS、计量、平台）；
  • 当前版本承担 CCU621_M 兼容层职能（部分数据默认值策略）。

• ui_info.c/.h

  • 页面文案资源（中文/英文）；
  • 故障文本辅助转换；
  • UI 显示固定字符串资源。

3. UI 主流程（任务周期）

v_ui_task() 一个周期内的关键步骤：

调度信息（来自 app/app_init/app_init.c）：

• UiComm：100ms 周期（任务入口：v_ui_task(void *argument)）

1. 看门狗喂狗；
2. 读取并解包屏幕报文（触控、字符串、变量写入）；
3. 执行页面切换控制（当前页校验 + 目标页下发）；
4. 执行当前页面刷新逻辑（按页面类型调用对应显示函数）；
5. 更新通信超时计数并上报状态；
6. 睡眠等待下个周期。

设计目标是将“通信、状态机、显示逻辑”解耦，便于后续替换业务数据源而不影响页面框架。

4. 多语言界面实现逻辑

多语言由两个层次实现：

• 页面资源映射层（页面ID -> 屏幕图片ID）

  • 每个逻辑页面 E_UI_ID_TYPE 在映射表里有多套语言图片索引；
  • 通过 u8_lalanguage_type 选择对应语言图片并下发；
  • 切语言时不改页面状态机，只改映射结果。

• 动态文本层（实时字符串）

  • 实时流程文案、状态文本通过 ui_info.c 的字符串表输出；
  • 同一个寄存器地址可按语言写入不同字符串；
  • 对于长度变化文本，先清空再写入，防止残留字符。

当前默认使用中/英两套资源，后续可按同一模式扩展第三语言。

5. 页面跳转状态机设计

页面切换由“被动跳转 + 主动跳转”共同驱动：

• 被动跳转（用户输入）

  • 触控按钮（开始、停止、返回、上一页、下一页等）；
  • 字符串输入（维护密码、管理员密码、确认动作密码等）。

• 主动跳转（系统状态变化）

  • 空闲 -> 启动中 -> 充电中 -> 停止中 -> 结算；
  • 故障触发 -> 故障页面；
  • 升级标志触发 -> 升级页面；
  • 空闲超时 -> 屏保/首页。

状态机关键变量：

• e_set_pic_id：目标逻辑页面；
• u8_ret_pic_id：屏幕当前页面ID回读值；
• e_previous_id：上一页面（用于返回）；
• u8_first_jump：首次进入页面标志（用于首次刷新）。

6. 主要页面显示内容（摘要）

• 待机页

  • 二维码、联网图标、枪状态、桩号；
  • 双枪/单枪根据配置和工作状态动态切换页面。

• 启动中页

  • 当前流程阶段文本；
  • 倒计时；
  • 达到充电状态后自动转实时页。

• 充电实时页

  • 电压、电流、电量/功率、金额、时长、SOC；
  • 支持切换到电池信息页和停止操作。

• 电池信息页

  • 电池类型/容量、需求电压电流、额定上限等；
  • 不同语言模式可展示不同字段重点。

• 停止中/结算页

  • 停止倒计时、订单结算信息、停止原因；
  • 支持返回待机。

• 维护相关页

  • 参数分类配置（系统/保护/网络/模块/预留/其他）；
  • 历史告警分页、历史充电记录分页；
  • 操作确认页（保存参数/参数初始化/系统重启）。

7. 参数配置区块设计

参数按寄存器区块管理：

• 0x0200 系统参数；
• 0x0220 保护参数；
• 0x0240 网络参数；
• 0x0260 模块参数；
• 0x0280 预留参数。

读写策略：

• “进入页面”时：从共享配置初始化 UI 参数镜像并下发到屏；
• “屏幕修改”时：回写参数镜像；
• “确认保存”时：镜像写回系统配置并持久化。

字符串参数（桩号、域名、二维码、APN）单独按地址映射回写，避免和数值参数混用。

8. 当前兼容策略（CCU621_M 过渡期）

由于 CCU621_M 业务模块未完全对齐旧项目，ui_interface.c 使用了默认策略：

• 部分运行时数据（流程/BMS/计量/平台状态）临时返回默认值；
• 控制接口先占位（记录启动方式，不直接驱动底层流程）；
• 历史记录接口返回空结果并给固定提示文案；
• 可直接映射的固定参数与字符串（桩号、域名、密码、二维码、APN）已接入共享配置。

该策略目标是“先保障界面框架稳定可联调”，后续逐项替换默认值。

9. 后续对接建议（优先级）

建议按以下顺序接入真实业务能力：

1. 流程状态与启停控制；
2. 电表/计量实时数据与订单结算数据；
3. BMS 数据；
4. 平台在线/升级/禁用状态；
5. 历史故障与历史订单分页读取；
6. 通信超时与故障上报闭环。