stc32g128k/Docs/50_module-breakdown/mod-event.md

# 模块拆分 - 事件采集与总线分发管理 (Docs/50_module-breakdown/mod-event.md)

本模块描述系统输入事件采集（按键移位消抖滤波与 RF 自适应解调解码）、事件环形队列（EventQueue）缓冲以及事件输出分配（EventDispatcher）的整体流转规格。

## 1. 模块职责说明

*   **职责范围**：
    1. **事件采集（按键输入）**：
       * 在 Timer1 中断 (10ms 时基) 中以移位方式读取物理引脚 `KEY_UP` (P0.1), `KEY_CONFIRM` (P0.2), `KEY_DOWN` (P0.3), `KEY_SOS` (P2.6) 的电平状态，连续 3 次检测一致确立电平。
       * 物理确认键长按 3 秒生成 `KEY_EVENT_SOS_LONG`，下移键长按 2 秒生成 `KEY_EVENT_DOWN_LONG`，SOS键按下即刻产生最高优先级的 `KEY_SOS_ACTIVE` 求救事件。
    2. **事件采集（射频接收）**：
       * 当射频输入引脚 `RF_RX_DATA` (Pin 22 / `P2.1`) 发生电平沿变化时触发外部中断，定时器捕获高低电平比值。
       * 解调自适应基准 T。连续采集 24 个数据位并组合还原 20 位物理 ID 及 4 位状态码。解密通过后打包为无线对码事件 `RF_EVENT_PAIR` 或报警事件 `RF_EVENT_ALARM`。
    3. **多事件环形队列缓冲 (EventQueue)**：
       * 维护一个深度为 4 级的软件环形事件队列。按键和射频中断作为“事件产生者”非阻塞地向其中 Push 事件，隔离高频中断和低频业务交互。
    4. **事件输出路由分发 (EventDispatcher)**：
       * 在主循环轮询中，若检测到队列非空，从中 Pop 弹出第一个有效事件。
       * 优先分发给物理强占型 APP（如 `KEY_SOS_ACTIVE` 强制启动 SOSApp）；或分发给后台守护进程 `BgApp` 匹对防区决定是否唤醒 `AlarmApp`；其余常规交互事件分发给当前前台应用 `active_app->onEvent(evt)` 钩子。

---

## 2. 接口与函数说明

*   `void Event_Queue_Init(void)`：复位环形队列读写指针与总计数器。
*   `bit Event_Queue_Push(KeyEvent evt)`：非阻塞将物理采集的事件推入队列尾部，成功返回 1。
*   `KeyEvent Event_Queue_Pop(void)`：从队列头部弹出一个事件并返回，若空返回 `KEY_EVENT_NONE`。
*   `void Key_Scan_Process(void)`：Timer1 (10ms) 滴答调度。扫描物理引脚 P0.1-P0.3 / P2.6 并判定长短按逻辑，调用 `Event_Queue_Push` 产生输入源。
*   `bit EV1527_Decode(u32 *out_addr, u8 *out_type)`：无线引脚 `P2.1` 边沿触发，捕获解密数据，解密成功后由主轮询捕获并 Push 对应的射频事件。
*   `void Event_Dispatcher_Loop(void)`：主循环轮询总线路由器，调用 `Event_Queue_Pop()` 并分发路由。