/*
 * 模块名称：UI 动作确认页（操作页共享实现，ui_page_action）
 * 模块功能：可复用的"确认 -> 二次确认 -> 执行回报"操作页构建器——
 *           强制复归 / 清除记录 / 手动录波等叶子共用同一页实现，
 *           各自以一份实例（标题/问句/结果行/执行回调）开页；
 *           执行回调只投递请求不阻塞（跨任务交接由页面跳板实现），
 *           成功经 done_text 回报后再 ENTER 返回，done_text=NULL 成功即关页；
 *           投递失败显示 ERR，下一次 ENTER 重新走二次确认
 * 适用范围：Drivers/BSP/UI（表单页形态：无浅 V 装饰、无页脚——用户密钥页
 *           跟随实机先例；ESC 恒关页 = 取消，LEFT 亦关页 = 取消）
 * 说明：同一时刻仅一张操作页在用（内容页框架本就全局单页），模块以
 *      static 单例描述符 + 当前实例指针承载钩子上下文；页面跳板
 *      （批 2 各 ui_page_xxx）持 ui_page_action_t 实例并在自己的入口
 *      调 ui_page_action_open()
 * 作者：王建锋
 * 创建日期：2026-10-25
 * 修改记录：
 *     v1.0  2026-10-25  王建锋  创建（道B task-5 三组件之一；规格 =
 *                               页面扩充详细方案.md §3.4 装置维护操作页 +
 *                               §4.2 ui_page_action bind(title, prompt, ok_cb)
 *                               二次确认、ok_cb 只投递不阻塞）
 */
#ifndef UI_PAGE_ACTION_H
#define UI_PAGE_ACTION_H

#ifdef __cplusplus
extern "C" {
#endif

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

#include "bsp_err.h"    /* bsp_err_t（开页结果错误通道——BSP 公开 API 约定） */

/* 执行回调：只投递请求（事件位/消息队列），立即返回；
 * 返回值：true = 投递被接受（页面转成功回报），false = 拒收（页面显示 ERR） */
typedef bool (*ui_page_action_ok_fn)(void);

/* 操作页实例（配置字段 Flash 指针 + 运行态）；
 * 用法：页面跳板 static 一份、花括号初始化配置，开页经 ui_page_action_open */
typedef struct {
    const char *title;          /* Flash：页标题（框架头部居中） */
    const char *prompt;         /* Flash：确认问句（如"确认复归所有保护?"——
                                   问句用字须已入字体子集） */
    const char *done_text;      /* Flash：成功后结果行（如"已请求复归"）；
                                   NULL = 成功后直接关页回菜单 */
    ui_page_action_ok_fn ok_cb; /* 必填：执行投递 */
    uint8_t stage;              /* 运行态：0 一次确认 / 1 二次确认 / 2 完成回报 */
    uint8_t err;                /* 运行态：1 = 上轮投递被拒（显示 ERR） */
} ui_page_action_t;

/*
 * 函数功能：开操作页（装载实例 + 复位确认态 + 经内容页框架开页）
 * 入口参数：inst - 操作页实例（配置字段须已填好；ok_cb 不得为 NULL）
 *                  ui_page_action_t *
 *           perm - 授予权限（ui_perm_t；由跳板决定传什么权限，
 *                  组件不拦权限只拦 ok_cb 为空）
 * 返回值：BSP_OK = 已开页；BSP_ERR_PARAM = 参数无效；
 *                  BSP_ERR_STATE = 已有页面打开（框架单页互斥）；
 *                  BSP_ERR_NO_SPACE = 框架开页失败（池不足等）  bsp_err_t
 * 限定条件：uiTask 上下文；每次进入从一次确认开始（不跨次保留 stage）
 * 函数说明：键语义——ENTER 推进确认链（0->1->执行->2），ESC/LEFT 关页取消；
 *           stage=2 时 ENTER 关页返回
 */
bsp_err_t ui_page_action_open(ui_page_action_t *a_inst, uint8_t a_perm);

#ifdef __cplusplus
}
#endif

#endif /* UI_PAGE_ACTION_H */