/*
 * 模块名称：UI 菜单节点表头文件（自动生成）
 * 模块功能：菜单节点结构、表规模护栏与表查询 API 声明
 * 适用平台：STM32F407ZGTx / PC 模拟器（共用源码）
 * 作者：王建锋
 * 创建日期：2026-09-07
 * 修改记录：
 *     2026-09-13  王建锋  工程约定规范化（文件头），内容由生成器自动更新
 * 自动生成：本文件由 tools/menu_gen/gen_menu.py 从 ui_menu_tree.txt 自动生成，请勿手改。
 *           修改菜单：编辑 ui_menu_tree.txt 后重跑 `python tools/menu_gen/gen_menu.py`。
 */
#ifndef UI_MENU_TAB_H
#define UI_MENU_TAB_H

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

#define MENU_ROOT 0xFFu     /* 根哨兵：仅根节点(主界面)的 parent 取此值；8 位，上限 255 项 */

/* 菜单节点：子项 = parent 等于本下标的所有行（按表序）；有子项=菜单，无=叶子 */
/* 字段序 parent/pwd 在前：32 位下两项 8 位合并 + 4 位指针 = 8 B/项 */
typedef struct {
    uint8_t     parent;     /* 父节点下标(0..254)；根为 MENU_ROOT(0xFF) */
    uint8_t    pwd;         /* 1 = 需密码（密码页按所输密码授权）；0 = 直接进（只读） */
    const char *name;       /* 显示文本（字面量，存 Flash） */
} ui_menu_node_t;

#define UI_MENU_TAB_COUNT 42

/* 护栏：8 位索引上限 255 项（哨兵 0xFF 占用 255）；超界则编译失败（C99 写法，兼容 ARMCC v5） */
typedef char menu_tab_count_check[(UI_MENU_TAB_COUNT <= 255) ? 1 : -1];

extern const ui_menu_node_t g_menu_tab[];

/*
 * 表查询 API（导航逻辑层 ui_menu.c 与显示层 ui_menu_view.c 共用）：
 * 实现随表生成，改菜单（ui_menu_tree.txt）调用方零代码改动。
 */

/*
 * 函数功能：取某节点的直接子项（按表序）
 * 入口参数：node - 节点下标      uint8_t   0 - 表长-1
 *           out  - 子项下标输出  uint8_t[] 长度 >= max，可为 NULL（只数个数时）
 *           max  - 最多写出个数  uint8_t   >= 1
 * 返回值：实际写出的子项个数    uint8_t   0 - max（0 = 叶子节点）
 * 限定条件：node 越界时返回 0，不写 out（与"叶子"同形，调用方需要区分就先用 has_children）
 * 函数说明：不分配内存、不递归，只查一层。
 */
uint8_t ui_menu_tab_children(uint8_t node, uint8_t out[], uint8_t max);

/*
 * 函数功能：判断节点是否为菜单节点（有子项）
 * 入口参数：node - 节点下标  uint8_t  0 - 表长-1
 * 返回值：true - 有子项（显示为菜单，带 ▶）；false - 无子项（叶子，可进内容页）
 * 限定条件：纯查询，无副作用；node 越界返回 false
 * 函数说明：这是**谓词**（bool 合法），不是成败码——S-5 R1 的白名单形态。
 */
bool ui_menu_tab_has_children(uint8_t node);

/*
 * 函数功能：取节点的显示名
 * 入口参数：node - 节点下标  uint8_t  0 - 表长-1
 * 返回值：显示名字符串指针  const char*  指向表内静态存储，**不为 NULL**（越界返回空串）
 * 限定条件：返回的是静态存储地址，调用方不得写、不得 free
 * 函数说明：编码随表来源（ui_menu_tree.txt），显示层直接喂 LVGL。
 */
const char *ui_menu_tab_name(uint8_t node);

/*
 * 函数功能：判断该叶子是否需要密码
 * 入口参数：node - 节点下标  uint8_t  0 - 表长-1
 * 返回值：true - 需密码（先进密码页，按所输密码授权）；false - 直接进（只读）
 * 限定条件：纯查询；node 越界返回 false（保守取"只读"，不放开写权限）
 * 函数说明：授权强度由密码页所输密码决定，本函数只回答"要不要过这一关"。
 */
bool ui_menu_tab_has_pwd(uint8_t node);

/*
 * 函数功能：菜单表启动自检（表与生成器是否自洽）
 * 入口参数：无
 * 返回值：true - 表自洽（非根节点的 parent 下标均有效、pwd 只取 0/1）；
 *         false - 表被手工改坏，调用方应拒绝进入菜单而不是继续用
 * 限定条件：ui_menu_init() 阶段调用一次
 * 函数说明：宁可拒绝显示，也不要按一张错表导航——错表可能把只读叶子指到写页面上。
 */
bool ui_menu_tab_valid(void);

#endif