# UI 模块说明（CCU621_M）

> 路径：`app/ui/`  
> 返回主说明：[README](../../README.md)

## 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. 通信超时与故障上报闭环。