#ifndef PAGE_H
#define PAGE_H

#include "types.h"
/* -------------------------------------------------------------------------
 * 枚举名: page_id_t
 * 作用:
 *   定义系统内可导航页面的逻辑标识（Page ID）。
 *
 * 取值说明:
 *   PAGE_ID_NONE     - 无效页面 ID / 未初始化占位值
 *   PAGE_ID_MENU     - 菜单页 ID（当前主运行页）
 *   PAGE_ID_APP_INFO - 装置信息页 ID（在 main 中与菜单页一并注册）
 *   PAGE_ID_YC       - 遥测页 ID
 *   PAGE_ID_MAX      - 上界哨兵，不可作为有效页面 ID 使用
 *
 * 使用约束:
 *   - PageManager_Register() 会校验 page_id，PAGE_ID_NONE 与 >= PAGE_ID_MAX
 *     均视为非法值。
 * ------------------------------------------------------------------------- */
typedef enum
{
    PAGE_ID_NONE = 0,
    PAGE_ID_MENU = 1,
    PAGE_ID_APP_INFO = 2, /* 装置信息页：AppInfoPage_GetInstance */
    PAGE_ID_YC = 3,       /* 遥测页：YCPage_GetInstance */
    PAGE_ID_MAX
} page_id_t;

/* -------------------------------------------------------------------------
 * 枚举名: page_event_type_t
 * 作用:
 *   定义页面层可分发的事件类型。
 *
 * 当前约定:
 *   PAGE_EVENT_KEY - 按键输入事件
 *
 * 扩展说明:
 *   - 后续可按需扩展触摸、定时器、通信消息等事件类型。
 * ------------------------------------------------------------------------- */
typedef enum
{
    PAGE_EVENT_KEY = 1
} page_event_type_t;

/* -------------------------------------------------------------------------
 * 结构体名: input_event_t
 * 作用:
 *   页面事件分发的数据载体，由 PageManager_DispatchEvent() 传入页面 on_event。
 *
 * 字段说明:
 *   type   - 事件类型，取值来自 page_event_type_t
 *   keyVal - 按键值（当 type 为 PAGE_EVENT_KEY 时有效）
 *
 * 使用约束:
 *   - 调用方应保证 type/keyVal 与事件来源一致；
 *   - 页面 on_event 可基于该结构返回 EVENT_HANDLED / EVENT_UNHANDLED。
 * ------------------------------------------------------------------------- */
typedef struct
{
    uint8_t type;
    uint8_t keyVal;
} input_event_t;

/* -------------------------------------------------------------------------
 * 枚举名: event_result_t
 * 作用:
 *   定义页面事件处理结果，用于控制事件链是否继续兜底处理。
 *
 * 取值说明:
 *   EVENT_UNHANDLED - 页面未消费事件；允许交由管理器执行全局兜底逻辑
 *   EVENT_HANDLED   - 页面已消费事件；事件链终止
 * ------------------------------------------------------------------------- */
typedef enum
{
    EVENT_UNHANDLED = 0,
    EVENT_HANDLED = 1
} event_result_t;

/* 前置声明：支持在回调签名中使用 page_t* */
typedef struct page_t page_t;

/* -------------------------------------------------------------------------
 * 结构体名: page_t
 * 作用:
 *   页面抽象基元，描述“一个可被 PageManager 管理的页面实例”。
 *
 * 字段分组:
 *   1) 基础元信息
 *      page_id    - 页面逻辑标识
 *      is_cached  - 是否缓存页（1: Pop 后不销毁；0: Pop 后可销毁）
 *      is_created - 是否已执行过 on_create（由管理器维护）
 *
 *   2) 生命周期与事件回调
 *      on_create  - 首次创建时调用
 *      on_enter   - 页面进入前台时调用
 *      on_exit    - 页面离开前台时调用
 *      on_destroy - 页面销毁时调用（常用于非缓存页）
 *      on_event   - 输入事件处理回调
 *      on_loop    - 周期循环回调
 *
 *   3) 三层对象挂载指针（MVP）
 *      presenter / view / model - 页面内部层对象地址（可为空，按页面实现决定）
 *
 * 生命周期约定（由 PageManager 驱动）:
 *   - Push 到新页面时：旧页 on_exit -> 新页（必要时 on_create）-> 新页 on_enter
 *   - Pop 回退时：当前页 on_exit ->（非缓存页可 on_destroy）-> 新栈顶 on_enter
 * ------------------------------------------------------------------------- */
struct page_t
{
    page_id_t page_id;
    uint8_t is_cached;
    uint8_t is_created;

    void (*on_create)(page_t *page);
    void (*on_enter)(page_t *page);
    void (*on_exit)(page_t *page);
    void (*on_destroy)(page_t *page);
    event_result_t (*on_event)(page_t *page, input_event_t *event);
    void (*on_loop)(page_t *page);

    void *presenter;
    void *view;
    void *model;
};

#endif
