# 模块拆分 - 事件总线与分发管理 (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)
```c
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)` 或后台监测模块。