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

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

本模块描述系统事件缓冲队列（Event Queue）、事件分发路由器（Event Dispatcher）以及系统核心事件定义与流转机制。

1. 模块职责说明

• 职责范围：
  1. 事件解耦隔离：作为硬件中断/扫描层（Layer 2 驱动）与应用层（Layer 5 应用业务）的中间桥梁，使得高频的中断产生者和低频的业务逻辑处理器完全解耦。
  2. 事件环形缓冲区 (EventQueue)：实现一个深度为 4 级的环形事件队列。底层按键消抖模块和射频自适应解调模块作为“事件产生者”在任何时候都可以非阻塞地向缓冲区 Push 事件；主循环（或 APP 管理器）作为“事件消费者”从中 Pop 事件。
  3. 事件分发路由 (EventDispatcher)：定时查询事件队列，若队列非空，则弹出首个事件并根据事件类型将其分发给当前活跃应用的前台 active_app->onEvent(evt) 钩子，或者分发给后台守护进程 BgApp 进行处理。

---

2. 核心结构体与事件定义

2.1 系统事件类型枚举 (KeyEvent)

typedef enum {
    KEY_EVENT_NONE,
    KEY_EVENT_UP_CLICK,       // SW1 单击 (Pin 21 / P2.0)
    KEY_EVENT_DOWN_CLICK,     // SW2 单击 (Pin 19 / P3.6)
    KEY_EVENT_SOS_CLICK,      // SW3 单击 (Pin 24 / P2.3)
    KEY_EVENT_UP_LONG,        // SW1 长按 3 秒
    KEY_EVENT_DOWN_LONG,      // SW2 长按 3 秒
    KEY_EVENT_SOS_LONG,       // SW3 长按 3 秒
    KEY_EVENT_UP_DOWN_COMB,   // SW1 + SW2 组合按键
    KEY_SOS_ACTIVE,           // 本地主动触发紧急报警事件
    RF_EVENT_ALARM,           // 射频接收到对码防区传感器触发事件
    RF_EVENT_PAIR             // 射频接收到未对码的传感器配对事件
} KeyEvent;

---

3. 接口与函数说明

• void Event_Queue_Init(void)：初始化环形队列的读写指针（write_ptr = 0, read_ptr = 0）与计数器。
• bit Event_Queue_Push(KeyEvent evt)：向队列尾部推入一个事件，若队列已满则丢弃并返回 0，用于中断或扫描函数回调。
• KeyEvent Event_Queue_Pop(void)：从队列头部弹出一个事件，若队列为空则返回 KEY_EVENT_NONE。
• void Event_Dispatcher_Loop(void)：在主循环中不断被轮询调用，从 Event_Queue_Pop 获取有效事件，分发路由到 active_app->onEvent(evt) 或后台监测模块。