docs: 根据架构.odg重新设计重构手环系统的分层事件驱动APP框架设计文档

Docs/50_module-breakdown/mod-key.md

@@ -1,49 +1,26 @@
-# 模块拆分 - 按键输入消抖与判定 (Docs/50_module-breakdown/mod-key.md)
+# 模块拆分 - 按键输入与事件产生 (Docs/50_module-breakdown/mod-key.md)
 
-本模块描述物理按键输入的检测、电平消抖、长按计时以及多事件防丢处理。
+本模块描述物理按键输入引脚的检测、消抖、长短按事件封包，以及其作为事件产生者向事件队列投递的过程。
 
 ## 1. 模块职责说明
 
 *   **职责范围**：
-    1. 在系统上电时，将按键引脚 `P0.1~P0.5` 配置为**高阻输入且开启内部上拉电阻**（STC32G P0M0/P0M1/P0PU 寄存器配置）。
-    2. 实现每 10ms 一次的硬件消抖滤波（采用 3 次扫描连续一致判定法，滤波时间约 20-30ms）。
-    3. 支持侧边 ▲/▼ 键、确认键 ■，以及上部双并联 SOS 键的独立状态判定。
-    4. 对上部双 SOS 按键进行逻辑并联处理：只要任意一个按键拉低，即视为 SOS 触发。
-    5. **长按计时判定**：
-        *   长按 **确认键 (■)** 达 3 秒（300 个时基单位）触发主菜单切换或子页面放弃退出。
-        *   长按 **▼ 键** 达 2 秒（200 个时基单位）触发报警清除或 IPC 绑定退出。
-    6. **防丢事件缓冲队列 (Ring Buffer)**：
-        *   为了防止高频按键或同时按下时发生丢键，本模块维护一个深度为 4 级的环形事件队列。按键扫描判定出的 `KeyEvent` 压入队列，主循环通过出队机制依次消费。
+    1. **事件产生者 (Event Producer)**：物理按键 `KEY_UP` (P2.0), `KEY_DOWN` (P3.6), `KEY_CONFIRM` (P3.7), `KEY_SOS` (P2.3) 被按下触发低电平，按键模块负责将物理信号翻译为 `KeyEvent` 事件，并**推送到事件队列**中。
+    2. **移位消抖**：在 Timer1 10ms 中断分频中读取 IO 状态，连续 3 次检测一致则确认电平状态，滤波滤除物理抖动。
+    3. **多事件防丢缓冲**：维护一个深度为 4 级的环形事件队列。当主循环繁忙（例如正在处理复杂的 SPI 显示或 RF 编解码）时，后续到达的按键事件被压入队列保存，避免丢键。
+    4. **长短按时序**：确认键长按 3 秒产生 `KEY_CONFIRM_LONG`，▼ 键长按 2 秒产生 `KEY_DOWN_LONG`，SOS 键按下即刻产生最高优先级的 `KEY_SOS_ACTIVE` 抢占求救事件。
 
 ---
 
-## 2. 数据结构定义
+## 2. 接口与函数说明
 
-### 2.1 按键事件枚举 (KeyEvent)
-```c
-typedef enum {
-    KEY_EVENT_NONE,
-    KEY_UP_SHORT,       // ▲ 键短按
-    KEY_DOWN_SHORT,     // ▼ 键短按
-    KEY_DOWN_LONG,      // ▼ 键长按 2 秒 (清除报警/退出)
-    KEY_CONFIRM_CLICK,  // ■ 确认键短按
-    KEY_CONFIRM_LONG,   // ■ 确认键长按 3 秒 (菜单切换)
-    KEY_SOS_ACTIVE      // SOS 键触发 (不分长短按，秒级响应)
-} KeyEvent;
-```
-
----
-
-## 3. 接口与函数说明
-
-*   `void Key_Init(void)`：配置 `P0.1~P0.5` 的 `P0M1=0x00`, `P0M0=0x00`（高阻模式），并设置 `P0PU = 0x3E` 使能上拉电阻。
+*   `void Key_Init(void)`：将 Pin 19, 20, 21, 24 配置为高阻输入并开启内部上拉电阻 (`P3PU |= 0xC0`, `P2PU |= 0x09`)。
 *   `void Key_Scan_Process(void)`：
-    在 Timer 1 10ms 中断分频中调用。
-    *   读取引脚逻辑状态，并利用移位寄存器滤波判定。
-    *   并联 SOS 状态：`sos_pressed = (KEY_SOS1 == 0) || (KEY_SOS2 == 0)`。
-    *   累加各按键的计数器：`key_up_hold`, `key_down_hold`, `key_confirm_hold`, `key_sos_hold`。
-    *   达到长按阈值时将对应事件写入环形队列。
-*   `bit Key_Push_Event(KeyEvent evt)`：将事件压入环形事件队列。若满则丢弃，返回 0。
-*   `KeyEvent Key_Pop_Event(void)`：主循环调用，从事件队列中读取未消费的事件。若空返回 `KEY_EVENT_NONE`。
+    在 Timer1 的 10ms 定时周期中回调。
+    *   读取 `KEY_UP`, `KEY_DOWN`, `KEY_CONFIRM`, `KEY_SOS` 引脚。
+    *   累加按键维持计数器以判定长按与短按。
+    *   将结果转换为 `KeyEvent` 传入事件队列。
+*   `bit Key_Push_Event(KeyEvent evt)`：将产生的事件压入事件环形队列（Event Queue）。若溢出返回 0。
+*   `KeyEvent Key_Pop_Event(void)`：主循环调用该接口，读出排队事件。若空返回 `KEY_EVENT_NONE`。
 
 <!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V2 -->