/**
 **********************************************************************************************************************
 * @file    menu_api.h
 * @brief   菜单组件对外API接口定义
 * @author  menu_component
 * @date    2025-12-19
 **********************************************************************************************************************
 */

#ifndef MENU_API_H
#define MENU_API_H

/* Includes ----------------------------------------------------------------------------------------------------------*/
#include "../src/core/menu_config.h"
#include "../src/core/menu_types.h"

/* 宏定义 -----------------------------------------------------------------------------------------------------------*/
#define MENU_API_VERSION "1.0.1"

/* 函数声明 ---------------------------------------------------------------------------------------------------------*/

/* 菜单初始化与反初始化 ---------------------------------------------------------------------------------------------*/

/**
 * @brief 初始化菜单组件
 * @return 错误码
 */
MenuErrCode menu_init(void);

/**
 * @brief 反初始化菜单组件
 * @return 错误码
 */
MenuErrCode menu_deinit(void);

/* 菜单节点管理 -----------------------------------------------------------------------------------------------------*/

/**
 * @brief 注册菜单节点
 * @param node_id 节点ID（0表示自动分配）
 * @param parent_id 父节点ID
 * @param name 节点名称
 * @param enter_cb 进入回调
 * @param exit_cb 退出回调
 * @return 实际分配的节点ID
 */
MenuNodeId menu_register_node(MenuNodeId node_id, MenuNodeId parent_id, const char* name, MenuCallback enter_cb, MenuCallback exit_cb);

/**
 * @brief 批量注册菜单节点
 * @param nodes 节点数组
 * @param count 节点数量
 * @return 错误码
 */
MenuErrCode menu_register_nodes(const struct MenuNode* nodes, uint16_t count);

/**
 * @brief 注销菜单节点
 * @param node_id 节点ID
 * @return 错误码
 */
MenuErrCode menu_unregister_node(MenuNodeId node_id);

/**
 * @brief 更新菜单节点
 * @param node_id 节点ID
 * @param name 节点名称（NULL表示不更新）
 * @param enter_cb 进入回调（NULL表示不更新）
 * @param exit_cb 退出回调（NULL表示不更新）
 * @return 错误码
 */
MenuErrCode menu_update_node(MenuNodeId node_id, const char* name, MenuCallback enter_cb, MenuCallback exit_cb);

/**
 * @brief 查找菜单节点
 * @param node_id 节点ID
 * @return 节点指针，未找到返回NULL
 */
const struct MenuNode* menu_find_node(MenuNodeId node_id);

/* 菜单事件处理 -----------------------------------------------------------------------------------------------------*/

/**
 * @brief 发送菜单事件
 * @param event_type 事件类型
 * @param priority 事件优先级（0-3，0最高）
 * @return 错误码
 */
MenuErrCode menu_post_event(MenuEventType event_type, uint8_t priority);

/**
 * @brief 发送带数据的菜单事件
 * @param event_type 事件类型
 * @param priority 事件优先级（0-3，0最高）
 * @param data 事件数据
 * @return 错误码
 */
MenuErrCode menu_post_event_with_data(MenuEventType event_type, uint8_t priority, void* data);

/* 菜单导航操作 -----------------------------------------------------------------------------------------------------*/

/**
 * @brief 菜单主循环，处理事件和刷新显示
 * @param tick 当前系统时间（ms）
 * @return 错误码
 */
MenuErrCode menu_main_loop(uint32_t tick);

/**
 * @brief 进入菜单
 * @return 错误码
 */
MenuErrCode menu_enter(void);

/**
 * @brief 退出菜单
 * @return 错误码
 */
MenuErrCode menu_exit(void);

/**
 * @brief 上移菜单项
 * @return 错误码
 */
MenuErrCode menu_up(void);

/**
 * @brief 下移菜单项
 * @return 错误码
 */
MenuErrCode menu_down(void);

/**
 * @brief 选择菜单项
 * @param node_id 节点ID
 * @return 错误码
 */
MenuErrCode menu_select(MenuNodeId node_id);

/**
 * @brief 重置菜单，回到主菜单
 * @return 错误码
 */
MenuErrCode menu_reset(void);

/* 菜单状态查询 -----------------------------------------------------------------------------------------------------*/

/**
 * @brief 获取当前菜单状态
 * @return 当前菜单状态
 */
MenuState menu_get_state(void);

/**
 * @brief 获取当前选中的节点ID
 * @return 当前节点ID
 */
MenuNodeId menu_get_current_node(void);

/**
 * @brief 获取导航深度
 * @return 导航深度
 */
uint8_t menu_get_nav_depth(void);

/**
 * @brief 获取导航路径
 * @param path 用于存储导航路径的数组
 * @param max_depth 数组最大深度
 * @return 实际获取的深度
 */
uint8_t menu_get_nav_path(MenuNodeId* path, uint8_t max_depth);

/* 状态机扩展接口 ---------------------------------------------------------------------------------------------------*/

#if MENU_CONFIG_ENABLE_STATE_MACHINE_EXT
/**
 * @brief 注册自定义状态转换规则
 * @param transition 状态转换规则
 * @return 错误码
 */
MenuErrCode menu_state_register_transition(const MenuStateTransition* transition);

/**
 * @brief 注销自定义状态转换规则
 * @param current_state 当前状态
 * @param event 触发事件
 * @return 错误码
 */
MenuErrCode menu_state_unregister_transition(MenuState current_state, MenuEventType event);

/**
 * @brief 切换到指定状态
 * @param state 目标状态
 * @return 错误码
 */
MenuErrCode menu_state_switch(MenuState state);
#endif

/* 内存监控接口 -----------------------------------------------------------------------------------------------------*/

#if MENU_CONFIG_ENABLE_MEM_MONITOR
/**
 * @brief 获取已使用节点数量
 * @return 已使用节点数量
 */
uint16_t menu_mem_get_used_nodes(void);

/**
 * @brief 获取空闲节点数量
 * @return 空闲节点数量
 */
uint16_t menu_mem_get_free_nodes(void);

/**
 * @brief 获取最大节点数量
 * @return 最大节点数量
 */
uint16_t menu_mem_get_max_nodes(void);
#endif

/* 权限管理接口 -----------------------------------------------------------------------------------------------------*/

#if MENU_CONFIG_ENABLE_PERMISSION
/**
 * @brief 注册角色
 * @param role 角色结构体指针
 * @return 错误码
 */
MenuErrCode menu_permission_register_role(const MenuRole* role);

/**
 * @brief 注销角色
 * @param role_id 角色ID
 * @return 错误码
 */
MenuErrCode menu_permission_unregister_role(MenuRoleId role_id);

/**
 * @brief 设置当前角色
 * @param role_id 角色ID
 * @return 错误码
 */
MenuErrCode menu_permission_set_current_role(MenuRoleId role_id);

/**
 * @brief 获取当前角色
 * @return 当前角色ID
 */
MenuRoleId menu_permission_get_current_role(void);

/**
 * @brief 更新节点权限级别
 * @param node_id 节点ID
 * @param permission_level 权限级别
 * @return 错误码
 */
MenuErrCode menu_permission_update_node_level(MenuNodeId node_id, MenuPermissionLevel permission_level);

/**
 * @brief 获取节点权限级别
 * @param node_id 节点ID
 * @return 节点权限级别
 */
MenuPermissionLevel menu_permission_get_node_level(MenuNodeId node_id);

/**
 * @brief 检查节点是否可访问
 * @param node_id 节点ID
 * @return true表示可访问，false表示不可访问
 */
bool menu_permission_check_node_access(MenuNodeId node_id);

/**
 * @brief 获取角色信息
 * @param role_id 角色ID
 * @return 角色结构体指针，NULL表示角色不存在
 */
const MenuRole* menu_permission_get_role(MenuRoleId role_id);
#endif

/* 状态持久化接口 ---------------------------------------------------------------------------------------------------*/

#if MENU_CONFIG_ENABLE_PERSISTENCE
/**
 * @brief 注册持久化回调函数
 * @param save_cb 保存回调函数
 * @param restore_cb 恢复回调函数
 * @return 错误码
 */
MenuErrCode menu_persistence_register_callback(MenuPersistenceCallback save_cb, MenuRestoreCallback restore_cb);

/**
 * @brief 启用或禁用自动保存
 * @param enable true表示启用，false表示禁用
 * @return 错误码
 */
MenuErrCode menu_persistence_set_auto_save(bool enable);

/**
 * @brief 获取自动保存状态
 * @return true表示启用，false表示禁用
 */
bool menu_persistence_get_auto_save(void);

/**
 * @brief 设置自动保存间隔
 * @param interval 自动保存间隔（ms）
 * @return 错误码
 */
MenuErrCode menu_persistence_set_auto_save_interval(uint32_t interval);

/**
 * @brief 获取自动保存间隔
 * @return 自动保存间隔（ms）
 */
uint32_t menu_persistence_get_auto_save_interval(void);

/**
 * @brief 手动保存菜单状态
 * @return 错误码
 */
MenuErrCode menu_persistence_save(void);

/**
 * @brief 恢复菜单状态
 * @return 错误码
 */
MenuErrCode menu_persistence_restore(void);
#endif

#endif /* MENU_API_H */