/**
 * @file menu_core.h
 * @brief 菜单组件核心类型定义（用户无需关心）
 */
#ifndef MENU_CORE_H
#define MENU_CORE_H

#include "menu_def.h"
#include <stdint.h>
#include <stdbool.h>

/************************** 核心数据结构 **************************/
/**
 * @brief 菜单事件结构体（事件队列元素）
 */
typedef struct {
    MenuEventType type;  ///< 事件类型
    uint32_t param;      ///< 事件附加参数
    uint32_t timestamp;  ///< 事件产生时间（ms，用于超时处理）
} MenuEvent;

/**
 * @brief 菜单节点结构体（菜单树的基本单元）
 * @note 紧凑设计：使用位域和共用体减少内存占用（工业级嵌入式低内存优化）
 */
typedef struct MenuNode {
    MenuNodeId id;               ///< 节点ID（唯一）
    MenuNodeId parent_id;        ///< 父节点ID（根节点为0）
    const char* name;            ///< 菜单名称（或多语言索引）
    MenuCallback enter_cb;       ///< 进入回调
    MenuCallback exit_cb;        ///< 退出回调
    struct MenuNode* first_child;///< 第一个子节点
    struct MenuNode* next_sibling;///< 下一个兄弟节点
    struct MenuNode* prev_sibling;///< 上一个兄弟节点
    // 位域：减少内存占用（1字节代替多个u8变量）
    struct {
        bool is_registered : 1;  ///< 是否已注册
        bool is_selected : 1;    ///< 是否被选中
        unsigned int reserved : 6; ///< 保留位
    } flags;
#if MENU_CONFIG_ENABLE_PARAM
    uint16_t param_id;           ///< 绑定的参数ID（启用参数时有效）
#endif
} MenuNode;

/**
 * @brief 菜单栈结构体（管理导航层级）
 */
typedef struct {
    MenuNodeId nodes[MENU_CONFIG_STACK_DEPTH];  ///< 栈元素（存储节点ID）
    uint8_t top;                                 ///< 栈顶指针
} MenuStack;

/**
 * @brief 事件队列结构体（环形队列，工业级：避免溢出）
 */
typedef struct {
    MenuEvent buffer[MENU_CONFIG_EVENT_QUEUE_LEN];  ///< 队列缓冲区
    uint8_t head;                                     ///< 入队指针
    uint8_t tail;                                     ///< 出队指针
    uint8_t count;                                    ///< 队列元素数量
} MenuEventQueue;

/**
 * @brief 菜单核心上下文（全局唯一，存储菜单状态）
 */
typedef struct {
    MenuNode nodes[MENU_CONFIG_MAX_NODES];  ///< 静态菜单节点池（无动态分配）
    MenuStack stack;                        ///< 菜单导航栈
    MenuEventQueue event_queue;             ///< 事件队列
    MenuNodeId current_node_id;             ///< 当前选中的节点ID
    uint32_t last_refresh_tick;             ///< 上次刷新时间（ms）
    bool is_initialized;                    ///< 是否已初始化
} MenuCoreCtx;

/************************** 核心内部接口声明 **************************/
/**
 * @brief 查找菜单节点（通过ID）
 * @param node_id 节点ID
 * @return 节点指针（NULL表示未找到）
 */
MenuNode* menu_core_find_node(MenuNodeId node_id);

/**
 * @brief 初始化菜单核心上下文
 * @return 错误码
 */
MenuErrCode menu_core_ctx_init(void);

/**
 * @brief 获取菜单核心上下文（内部唯一访问入口）
 * @return 菜单核心上下文指针
 */
MenuCoreCtx* menu_core_get_ctx(void);

/**
 * @brief 处理单个菜单事件
 * @param event 事件指针
 * @return 错误码
 */
MenuErrCode menu_core_handle_event(const MenuEvent* event);

/**
 * @brief 刷新菜单显示（内部调用，对接port层显示接口）
 */
void menu_core_refresh_display(void);

#endif // MENU_CORE_H