#ifndef __EVENT_H__
#define __EVENT_H__

#include "config.h"

/* ====== 事件环形缓冲区 (队列) 接口 ====== */

/**
 * @brief 初始化事件队列
 * @details 将队列的头指针、尾指针以及当前事件计数器全部归零，清空缓冲区。
 */
void EventQueue_Init(void);

/**
 * @brief 将一个普通事件压入队列的末尾 (入队)
 * @param evt 要入队的系统事件实例
 * @return bit 1-入队成功，0-队列已满 (入队失败，丢弃事件)
 * @note 此函数操作时会自动禁用全局中断 (EA = 0)，操作完成后恢复以防止重入冲突。
 */
bit EventQueue_Push(SystemEvent evt);

/**
 * @brief 将一个紧急/高优先级事件强行插入到队列的首部 (插队)
 * @param evt 要优先处理的系统事件
 * @return bit 1-插队成功，0-队列已满 (插队失败)
 * @note 用于处理如 SOS 紧急求救和无线防区报警等需要立即响应的事件。操作受全局中断屏蔽保护。
 */
bit EventQueue_InsertFront(SystemEvent evt);

/**
 * @brief 从队列首部弹出一个事件 (出队)
 * @return SystemEvent 被取出的系统事件。如果队列为空，将返回一个 key_event 为 KEY_EVENT_NONE 的空事件。
 * @note 操作时受全局中断屏蔽保护。
 */
SystemEvent EventQueue_Pop(void);

/**
 * @brief 检测事件队列当前是否为空
 * @return bit 1-队列为空，0-队列中仍有事件未处理
 */
bit EventQueue_IsEmpty(void);

/**
 * @brief 检测事件队列当前是否已满 (即达到最大深度 8)
 * @return bit 1-队列已满，0-队列仍有剩余空闲槽位
 */
bit EventQueue_IsFull(void);

/**
 * @brief 获取事件队列中当前已缓冲的事件总个数
 * @return u8 当前事件的缓存个数
 */
u8 EventQueue_GetCount(void);


/* ====== 事件分发环与定时器驱动初始化 ====== */

/**
 * @brief 事件分发轮询主处理程序
 * @details 负责从事件队列中弹出当前最优先的事件，解析其内容，处理全局重置逻辑（如重置闲置休眠计时器），
 *          并根据事件的类型与当前活跃的前台 APP 状态将事件分发到具体的应用程序中去处理。
 */
void Event_Dispatcher_Loop(void);

/**
 * @brief 初始化 Timer1 定时器，生成系统基准时钟 (1ms 中断)
 * @details 配置定时器 1 为 16 位自动重装载模式，设定中断周期为 1.0 毫秒，开启 Timer1 中断并启动计数。
 */
void Timer1_Init(void);

// 主循环按键扫描定时标志 (由 1ms 中断置 1，主循环响应清除)
extern volatile bit key_scan_flag;

/**
 * @brief 主循环按键扫描与消抖处理函数
 * @details 将按键检测逻辑从中断搬移至此，在主线程执行，避免 ADC 多重采样冲突死锁
 */
void Event_KeyScan_Poll(void);

#endif // __EVENT_H__