/**
 * @file service_version_info.h
 * @brief 版本信息服务层头文件
 *
 * 本模块为版本信息界面提供业务逻辑处理，属于MVVM架构中的Service层（ViewModel）。
 *
 * == 功能说明 ==
 * - 接收Data层提供的原始数据
 * - 进行数据格式化、字符串拼接等业务处理
 * - 组装页面配置结构体供UI层使用
 *
 * == 架构位置 ==
 * - 上游：Data层（data_version_info.h）
 * - 下游：UI层（ui_version_info_page.h）
 *
 * == 与传统设计的区别 ==
 * - 传统设计：UI层直接处理数据拼接和格式化
 * - 新设计：数据处理逻辑下沉到Service层，UI层仅负责展示
 */

#ifndef _SERVICE_VERSION_INFO_H_
#define _SERVICE_VERSION_INFO_H_

#include "data/data_version_info.h"
#include "ui/ui_config.h"

/* ============================ 界面布局常量 ============================= */

/**
 * @brief 标签文本最大长度
 * @note 用于存储标签名和值的组合文本，考虑超长边界情况
 */
#define VI_LABEL_TEXT_MAX_LEN       64

/**
 * @brief 最大标签项数量
 * @note 版本信息页面共显示6项信息：设备名称、设备型号、硬件版本、
 *       软件版本、启动版本、制造商
 */
#define VI_MAX_LABEL_COUNT          6

/**
 * @brief 标签起始X坐标
 * @note 页面左侧留出一定边距，确保显示美观
 */
#define VI_LABEL_START_X            15

/**
 * @brief 标签起始Y坐标
 * @note 页面顶部留出空间用于显示路径信息
 */
#define VI_LABEL_START_Y            45

/**
 * @brief 标签行间距
 * @note 每行标签之间保持30像素间距，确保文字不重叠
 */
#define VI_LABEL_SPACING_Y          30

/* ============================ 数据结构定义 ============================= */

/**
 * @brief 版本信息标签项结构体
 *
 * 用于存储单个标签的显示内容，包括标签名称和对应的值。
 * 标签名称如"设备名称:"，值如"CSP6000"。
 */
typedef struct {
    char label_text[VI_LABEL_TEXT_MAX_LEN];  /**< 标签文本，如"设备名称: " */
    char value_text[VI_LABEL_TEXT_MAX_LEN];  /**< 值文本，如"CSP6000" */
} VersionInfoLabelItem;

/**
 * @brief 版本信息页面配置结构体
 *
 * 该结构体封装了版本信息页面所需的所有配置数据，
 * 由Service层组装完成后传递给UI层进行渲染。
 *
 * @note 这是MVVM架构中的"ViewModel"概念的具体实现
 *       UI层通过此配置进行页面渲染，无需关心数据来源
 */
typedef struct {
    char path_text[64];                       /**< 路径文本，如"/主菜单/版本信息" */
    VersionInfoLabelItem items[VI_MAX_LABEL_COUNT]; /**< 标签项数组 */
    uint8_t item_count;                      /**< 实际标签数量 */
} VersionInfoPageConfig;

/* ============================ 接口函数声明 ============================= */

/**
 * @brief 获取版本信息页面配置
 *
 * 该函数是Service层的核心接口，调用Data层获取原始数据，
 * 然后进行格式化处理，最终组装成UI层可直接使用的页面配置。
 *
 * @param[out] config 输出参数，指向页面配置结构体的指针
 * @return true-获取成功，false-获取失败
 *
 * @retval true  成功获取页面配置，config已填充完整
 * @retval false 获取失败，可能原因：config为NULL或Data层获取失败
 *
 * @note 调用流程：
 *       1. 参数合法性检查
 *       2. 调用Data层获取原始版本信息
 *       3. 清空配置结构体
 *       4. 组装路径文本
 *       5. 拼接标签名称和值
 *       6. 设置标签数量
 */
bool version_info_service_get_page_config(VersionInfoPageConfig *config);

/**
 * @brief 初始化版本信息服务层
 *
 * 系统启动时调用的初始化函数。
 * 用于初始化Service层的内部状态。
 *
 * @note 当前主要用于标记初始化状态，确保Service层在被正确初始化后才使用
 */
void version_info_service_init(void);

#endif /* _SERVICE_VERSION_INFO_H_ */
