docs: optimize all module breakdown files with architect-level details

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

@@ -1,47 +1,49 @@
-# 模块拆分 - 按键扫描与事件判定 (Docs/50_module-breakdown/mod-key.md)
+# 模块拆分 - 按键输入消抖与判定 (Docs/50_module-breakdown/mod-key.md)
 
-本模块描述按键状态消抖、长按和短按计时判定。支持 5 个物理按键到手环事件的映射。
+本模块描述物理按键输入的检测、电平消抖、长按计时以及多事件防丢处理。
 
 ## 1. 模块职责说明
 
 *   **职责范围**：
-    1. 在 1ms 定时器中断中建立 10ms 扫描计时周期。
-    2. 对 5 个物理按键进行引脚电平扫描：
-       * 侧边：`KEY_UP` SW1 (▲), `KEY_DOWN` SW2 (▼), `KEY_CONFIRM` (■)
-       * 上部：`KEY_SOS1` (SOS 1), `KEY_SOS2` (SOS 2)
-    3. 实现消抖检测（连续 20ms 检测到电平稳定才认定按键动作）。
-    4. 对上部双 SOS 按键进行逻辑并联处理，保证按下任意一个均能触发求救。
-    5. 对按住不放的行为进行计时累加，判定长按：
-       * 长按 **确认键 (CONFIRM / ■)** 达 3 秒触发主菜单选择界面或退出当前页面。
-       * 侧边 **▼ 键** 长按达 2 秒产生长按退出/消除警报事件。
-       * SOS 按键（SOS1 / SOS2）长按或短按，只要是非报警状态，一律触发 `KEY_SOS_ACTIVE` 本地报警呼救事件。
-    6. 将按键判定结果转换为 `KeyEvent` 并注入按键事件缓冲区 `key_event_buf`。
+    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` 压入队列，主循环通过出队机制依次消费。
+
+---
 
 ## 2. 数据结构定义
 
-### 按键事件枚举 (KeyEvent)
+### 2.1 按键事件枚举 (KeyEvent)
 ```c
 typedef enum {
     KEY_EVENT_NONE,
-    KEY_UP_SHORT,
-    KEY_DOWN_SHORT,
-    KEY_DOWN_LONG,      // 长按 ▼ 2 秒解除警报/退出绑定
+    KEY_UP_SHORT,       // ▲ 键短按
+    KEY_DOWN_SHORT,     // ▼ 键短按
+    KEY_DOWN_LONG,      // ▼ 键长按 2 秒 (清除报警/退出)
     KEY_CONFIRM_CLICK,  // ■ 确认键短按
-    KEY_CONFIRM_LONG,   // ■ 确认键长按（3秒进入/退出菜单/退出绑定）
-    KEY_SOS_ACTIVE      // SOS键活动 (短按或长按，跳转至发送 SOS 报警)
+    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_Scan_Process(void)`：
-    在 Timer 1 ISR 中每 10ms 调度一次。
-    *   读取 `KEY_UP`, `KEY_DOWN`, `KEY_CONFIRM`, `KEY_SOS1`, `KEY_SOS2` 的 GPIO 逻辑电平。
-    *   计算并联 SOS 状态：`is_sos_pressed = (KEY_SOS1 == 0) || (KEY_SOS2 == 0)`。
-    *   如果发现按键电平状态改变，进行计数消抖。
-    *   如果按住不放，累加计时计数器（`key_up_hold`, `key_down_hold`, `key_confirm_hold`, `key_sos_hold`）。
-    *   检测到 `key_confirm_hold >= 300` 达 3 秒时，注入 `KEY_CONFIRM_LONG` 中断事件。
-    *   检测到 `key_down_hold >= 200` 达 2 秒时，注入 `KEY_DOWN_LONG` 中断事件。
-    *   检测到并联 SOS 被按下时，注入 `KEY_SOS_ACTIVE` 事件。
+    在 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`。
 
 <!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V2 -->