zouhaitao/stc32g128k
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现事件驱动应用框架，支持前台/后台分离、事件优先级和CPU占用控制

Browse Source
This commit is contained in:
zouhaitao
2026-07-10 11:30:48 +08:00
parent 00c00fb60e
commit b4fabf85b5
11 changed files with 2487 additions and 541 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
Docs/30_architecture/main.md
View File

@@ -1,166 +1,341 @@
# 架构设计说明书 (Docs/30_architecture/main.md)
本章节定义手环的系统软硬件架构设计，包括引脚分配、基于事件驱动的 APP 框架微内核设计、事件生命周期流转机制以及持久化数据存储结构。
---
## 1. 硬件原理图与引脚分配架构
手环的完整电路连接设计参见以下 KiCad 硬件工程文件：
* **硬件原理图**：[text.kicad_sch](file:///c:/workfile/105/stc32g12k128/Hardware/text.kicad_sch)
* **PCB 布局图**：[text.kicad_pcb](file:///c:/workfile/105/stc32g12k128/Hardware/text.kicad_pcb)
主控芯片采用 **STC32G12K128**（工作频率 24.0 MHz，单周期 8051 内核，32位乘除法器）。
显示端采用 **Truly 0.95寸 AMOLED 屏幕**，物理分辨率为 **120x240 像素**，控制芯片为 **RM69310**。
### 1.1 GPIO 物理映射表
| 芯片引脚号 | 引脚名称 | 逻辑网络标号 | IO 模式 | 连接外设与功能描述 |
| :--- | :--- | :--- | :--- | :--- |
| **Pin 1** | `P1.0` | `DIS_RST` | 推挽输出 | Truly AMOLED 屏幕复位控制脚 (RESET) |
| **Pin 2** | `P1.1` | `SPI_DCX` | 推挽输出 | Truly AMOLED 屏幕 SPI 数据/指令选择脚 (D/C) |
| **Pin 3** | `P1.4` | `SPI_SDI` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行数据输入 (MOSI/SDA) |
| **Pin 4** | `P1.5` |`SPI_CLK` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行时钟信号 (SCL) |
| **Pin 5** | `P1.6` | `SPI_CS` | 推挽输出 | Truly AMOLED 屏幕 SPI 片选信号 (CS) |
| **Pin 6** | `P1.7` | `SPI_SDO` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行数据输出 (MISO) |
| **Pin 10** | `Vcc` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 11** | `VREF+` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 12** | `GND` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 13** |`P3.1` |`RXD` | 高阻输入 | 串口 1 (UART1) 接收脚 |
| **Pin 14** | `P3.0` | `TXD` | 推挽输出 | 串口 1 (UART1) 发送脚 |
| **Pin 19** | `P3.6` | `RF_TX_DAT` | 推挽输出 | LR690L 射频芯片发射调制数据输入引脚 |
| **Pin 20** | `P3.7` | `RF_RX` | 推挽输出 | LR690L 射频芯片接收使能控制引脚
| **Pin 21** | `P2.0` | `RF_TX` | 推挽输出 | LR690L 射频芯片发射使能控制引脚 |
| **Pin 22** | `P2.1` | `RF_RX_DATA` | 输入中断 | LR690L 433MHz 射频接收芯片数据输出脚
| **Pin 23** | `P2.2` |`SHUT` | 推挽输出 | OLED 供电芯片 SGM3833 控制引脚。高电平开启供电
| **Pin 24** | `P2.3` | `LED_RGB` | SPI MOSI | WS2812B 级联双幻彩灯珠 DIN 控制信号
| **Pin 26** | `P2.5` | `MOTOR_PWM` | 推挽输出 | 连接振动马达驱动电路。高电平震动，低电平静止 |
| **Pin 27** | `P2.6` | `KEY_SOS` | 高阻输入 + 上拉 | 上部并联 SOS 求救按键，按下为低电平 |
| **Pin 28** | `P2.7` | `DET` | 高阻输入 | USB 插入充电检测引脚，高电平代表正在充电 |
| **Pin 29** | `P0.0` | `BAT_ADC` |ADC 输入 | 电池电压采集
| **Pin 30** | `P0.1` | `KEY_UP` | 高阻输入 + 上拉 | 侧边按键 ▲ (上移)，按下为低电平 |
| **Pin 31** | `P0.2` | `KEY_CONFIRM` | 高阻输入 + 上拉 | 侧边按键 ■ (确认/菜单)，按下为低电平 |
| **Pin 32** | `P0.3` | `KEY_DOWN` | 高阻输入 + 上拉 | 侧边按键 ▼ (下移)，按下为低电平 |
---
## 2. 软件事件驱动 APP 框架 (Event-Driven App-Framework)
手环软件系统摒弃了传统的单线程前后台大循环设计，采用分层明确的 **事件驱动式 APP 框架** 架构。
### 2.1 五层软件架构模型
```mermaid
graph BT
%% 自下而上的 5 层软件依赖拓扑
subgraph Layer5 ["5. 应用业务层 Applications"]
ActiveApp["当前活跃应用 Foreground App"]
BgApp["后台监测应用 Background App"]
end
subgraph Layer4 ["4. 应用管理层 APP Management"]
AppManager["APP 管理器 StartApp / CloseApp"]
Lifecycle["生命周期调度机"]
end
subgraph Layer3 ["3. 事件管理与总线层 Event Layer"]
EventDispatcher["事件分配器 Event Dispatcher"]
EventQueue["事件环形缓冲区 EventQueue"]
end
subgraph Layer2 ["2. 中断与驱动层 Drivers"]
ExtInt["外部中断 KEY按键扫描 / RF解码"]
TimeInt["时钟中断 Timer1 1ms时基"]
ADC_Drv["ADC 电量采集"]
LCD_Drv["LCD 屏幕绘制驱动"]
end
subgraph Layer1 ["1. 硬件实体层 STC32 HW"]
MCU["STC32G 单片机核心"]
end
%% 单向数据与控制交互 (自下而上)
MCU ===> Layer2
Layer2 ===>|异步推送事件| Layer3
Layer3 ===>|事件分发路由| Layer4
Layer4 ===>|生命周期回调与分发| Layer5
Layer5 ===>|调用显示/报警动作| Layer2
```
---
## 3. 应用生命周期机制 (APP Lifecycle)
手环中运行的各个子功能页面（如时钟、菜单、对码、布防）均被抽象为独立的 **App 实例**。每个 App 必须注册并实现以下生命周期回调接口：
```c
typedef struct {
u8 app_id; // 应用程序 ID
void (*OnStart)(void); // 启动回调：应用切入前台，加载资源、初始化显示
void (*onRun)(void); // 循环回调：主循环轮询轮空调用，执行非阻塞业务逻辑
void (*onClose)(void); // 关闭回调：应用退出前台，保存状态、清理外设
void (*onEvent)(KeyEvent evt); // 事件回调：接收并消耗来自事件层的系统事件
} WristbandApp;
```
### 3.1 活跃应用切换逻辑 (APP Switch)
1. 当调用 `StartApp(target_app_id)` 时：
* 触发当前活跃应用的 `onClose()` 接口，执行现场保存及关屏/停振等外设清理。
* 更新活跃应用指针指向新 App。
* 触发新活跃应用的 `OnStart()` 接口，执行初始画面的绘制（置 `Redraw = 1`）。
2. 在主循环中，系统不断执行当前活跃应用的 `onRun()` 接口，以维护非阻塞的页面动画或等待超时逻辑。
---
## 4. 事件采集、缓冲与流转机制 (Event Bus)
事件总线层是实现前后台解耦的核心。
```mermaid
graph LR
%% 事件的产生与消耗流转
HW_Sig["物理引脚状态跳变"] -->|电平变化中断| Driver["驱动中断 ISR"]
Driver -->|消抖/自适应解调| Packer["封装统一事件 KeyEvent"]
Packer -->|Key_Push_Event| Queue["Event Ring Buffer 环形队列"]
Queue -->|Key_Pop_Event| MainLoop["MainLoop 轮询读取"]
MainLoop -->|事件分发| AppMgr["APP 管理器"]
AppMgr -->|onEvent 回调| ActiveApp["当前活跃 App 实例"]
```
### 4.1 环形事件缓冲区 (EventQueue)
为防止高速按键或多输入源并发导致事件丢失，系统建立一个深度为 4 级的环形事件队列。按键消抖模块与 RF 模块作为 **事件产生者** 将数据推送至队列：
* **按键事件产生**：Timer1 定时器每 10ms 中断扫描物理引脚，判定有效按键后执行 `Key_Push_Event(KEY_UP_SHORT)`。
* **RF 事件产生**：LR690L 接收中断触发，解码线程还原 24 位载波包，识别到配对传感器动作，推送对应防区事件。
* **事件路由**：主循环轮询事件队列，若队列非空，`Key_Pop_Event()` 读出事件并分配给当前活跃应用的 `onEvent(evt)` 执行特异化响应。
---
## 5. 持久化配置数据库架构
手环配对防区数据存储在 STC32G 内置 Flash 的第 254 扇区：
* **物理存储地址**：`0xFE0000` (末尾 512 字节)。
* **数据库容量**：共 16 组传感器配置槽位。
* **存储结构定义**：
```c
typedef struct {
u8 flags_suffix; // 属性字节：Bit 7 代表有效标志 (1: 有效, 0: 空闲)；Bit 0~6 代表法语防区名称的后缀序号 (01~99)
u8 addr[3]; // 24位射频物理地址 (EV1527 地址 + 4位状态数据码)
} Sensor_Slot;
```
---
## 6. 核心业务事件输入输出 (I/O) 架构明细表
手环核心事件在整个框架中的端到端流动及消耗链路如下：
| 事件名称 | 输入源 (触发条件与参数) | 事件总线流转 (产生端 -> 分发端) | 活跃 APP 消费处理 (逻辑响应与动作) |
| :--- | :--- | :--- | :--- |
| **按键操作事件**<br>`KEY_EVENT` | **源**：Pin 30/31/32 (Port 0) 下降沿中断。<br>**参数**：▲/▼/■ (短按/长按)。 | **产生**：`KEY` 驱动 10ms 中断消抖扫描包装。<br>**分发**：`Event_Queue_Push` 压入队列，主循环调用 `Event_Dispatcher_Loop` 传入活跃 App。 | **待机应用**：长按确认键 3 秒，调用 `StartApp(APP_MENU)`；<br>**菜单应用**：短按 ▲/▼ 键移动高亮焦点；短按确认键调用 `StartApp` 进入对应子设置应用。 |
| **主动求救事件**<br>`SOS_ACTIVE_EVENT` | **源**：Pin 27 (`P2.6`) SOS 物理键拉低。 | **产生**：检测到低电平，直接压入事件队列 `KEY_SOS_ACTIVE`。<br>**分发**：主循环捕获，APP 管理器强制抢占调用 `StartApp(APP_SOS)`。 | **SOS报警应用**：<br>1. 显示： OEL 屏亮起 `SOS EMIS`；<br>2. 灯效：WS2812B 红色交替闪烁 (50ms)；<br>3. 马达：开启间歇长振 (振1000ms，停200ms)；<br>4. 射频：启动发送线程周期性（2s）发射手环 Factory ID 及 `0x08` (SOS) 包。 |
| **无线对码捕获事件**<br>`RF_PAIR_RECV_EVENT` | **源**：Pin 22 (`P2.1`) 沿变化中断。<br>**参数**：EV1527 24位对码信号。 | **产生**：RF 驱动解调同步头并还原二进制码字。<br>**分发**：包装为 `RF_EVENT_PAIR` 传入事件队列，主循环分发。 | **配对应用**：<br>1. 状态：跳转进入 `STATE_PAIR_CONFIRM` (微调保存页)；<br>2. 显示：只读显示自动识别 of 传感器类型及大图标；<br>3. 马达：短振 300ms 提醒成功；<br>4. 交互：通过按键微调序号并写入 Flash 数据库。 |
| **传感器入侵警报事件**<br>`RF_ALARM_RECV_EVENT` | **源**：Pin 22 (`P2.1`) 沿变化中断。<br>**参数**：传感器物理地址 + 4位状态码。 | **产生**：RF 驱动还原码字。<br>**分发**：主循环比对 Flash 数据库匹配槽位成功，触发防区报警事件。 | **警报应用**：若该防区为 ZONE 0 (24h) 或处于已布防，APP管理器启动 `StartApp(APP_ALARM)`。<br>1. 显示：OLED 刷红边框与对应大图标，显示入侵警报文字；<br>2. 灯效：同步闪烁该防区专属色彩；<br>3. 马达：输出对应防区的特定异步振动波形。 |
| **系统自动休眠事件**<br>`AUTO_SLEEP_EVENT` | **源**：软件时钟计时 `inactivity_timer >= 1000` (10s)。 | **产生**：Timer1 中断秒分频累加。<br>**分发**：触发超时休眠事件，分发至当前应用。 | **所有非警报应用**：执行 `onClose()` $
ightarrow$ 调用 PM 模块拉低 `SHUT=0`（Pin 23）彻底切断屏幕供电 $
ightarrow$ 配置 GPIO 变化中断和无线唤醒源 $
ightarrow$ 执行 `PCON|=0x02` 进入停机休眠。 |
# 架构设计说明书 (Docs/30_architecture/main.md)
本章节定义手环的系统软硬件架构设计，包括引脚分配、基于事件驱动的 APP 框架微内核设计、事件生命周期流转机制以及持久化数据存储结构。
---
## 1. 硬件原理图与引脚分配架构
手环的完整电路连接设计参见以下 KiCad 硬件工程文件：
* **硬件原理图**：[text.kicad_sch](file:///c:/workfile/105/stc32g12k128/Hardware/text.kicad_sch)
* **PCB 布局图**：[text.kicad_pcb](file:///c:/workfile/105/stc32g12k128/Hardware/text.kicad_pcb)
主控芯片采用 **STC32G12K128**（工作频率 24.0 MHz，单周期 8051 内核，32位乘除法器）。
显示端采用 **Truly 0.95寸 AMOLED 屏幕**，物理分辨率为 **120x240 像素**，控制芯片为 **RM69310**。
### 1.1 GPIO 物理映射表
| 芯片引脚号 | 引脚名称 | 逻辑网络标号 | IO 模式 | 连接外设与功能描述 |
| :--- | :--- | :--- | :--- | :--- |
| **Pin 1** | `P1.0` | `DIS_RST` | 推挽输出 | Truly AMOLED 屏幕复位控制脚 (RESET) |
| **Pin 2** | `P1.1` | `SPI_DCX` | 推挽输出 | Truly AMOLED 屏幕 SPI 数据/指令选择脚 (D/C) |
| **Pin 3** | `P1.4` | `SPI_SDI` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行数据输入 (MOSI/SDA) |
| **Pin 4** | `P1.5` |`SPI_CLK` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行时钟信号 (SCL) |
| **Pin 5** | `P1.6` | `SPI_CS` | 推挽输出 | Truly AMOLED 屏幕 SPI 片选信号 (CS) |
| **Pin 6** | `P1.7` | `SPI_SDO` | 推挽输出 | Truly AMOLED 屏幕 SPI 串行数据输出 (MISO) |
| **Pin 10** | `Vcc` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 11** | `VREF+` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 12** | `GND` | `+3.3V` | 电源 | 屏幕/系统 3.3V 逻辑供电 |
| **Pin 13** |`P3.1` |`RXD` | 高阻输入 | 串口 1 (UART1) 接收脚 |
| **Pin 14** | `P3.0` | `TXD` | 推挽输出 | 串口 1 (UART1) 发送脚 |
| **Pin 19** | `P3.6` | `RF_TX_DAT` | 推挽输出 | LR690L 射频芯片发射调制数据输入引脚 |
| **Pin 20** | `P3.7` | `RF_RX` | 推挽输出 | LR690L 射频芯片接收使能控制引脚 |
| **Pin 21** | `P2.0` | `RF_TX` | 推挽输出 | LR690L 射频芯片发射使能控制引脚 |
| **Pin 22** | `P2.1` | `RF_RX_DATA` | 输入中断 | LR690L 433MHz 射频接收芯片数据输出脚 |
| **Pin 23** | `P2.2` |`SHUT` | 推挽输出 | OLED 供电芯片 SGM3833 控制引脚。高电平开启供电 |
| **Pin 24** | `P2.3` | `LED_RGB` | SPI MOSI | WS2812B 级联双幻彩灯珠 DIN 控制信号 |
| **Pin 26** | `P2.5` | `MOTOR_PWM` | 推挽输出 | 连接振动马达驱动电路。高电平震动，低电平静止 |
| **Pin 27** | `P2.6` | `KEY_SOS` | 高阻输入 + 上拉 | 上部并联 SOS 求救按键，按下为低电平 |
| **Pin 28** | `P2.7` | `DET` | 高阻输入 | USB 插入充电检测引脚，高电平代表正在充电 |
| **Pin 29** | `P0.0` | `BAT_ADC` | ADC 输入 | 电池电压采集 |
| **Pin 30** | `P0.1` | `KEY_UP` | 高阻输入 + 上拉 | 侧边按键 ▲ (上移)，按下为低电平 |
| **Pin 31** | `P0.2` | `KEY_CONFIRM` | 高阻输入 + 上拉 | 侧边按键 ■ (确认/菜单)，按下为低电平 |
| **Pin 32** | `P0.3` | `KEY_DOWN` | 高阻输入 + 上拉 | 侧边按键 ▼ (下移)，按下为低电平 |
---
## 2. 软件事件驱动 APP 框架 (Event-Driven App-Framework)
手环软件系统摒弃了传统的单线程前后台大循环设计，采用分层明确的 **事件驱动式 APP 框架** 架构。
### 2.1 五层软件架构模型
```mermaid
graph BT
%% 自下而上的 5 层软件依赖拓扑
subgraph Layer5 ["5. 应用业务层 Applications"]
subgraph FG_Apps ["前台应用 Foreground Apps"]
ClockApp["时钟应用 ClockApp"]
MenuApp["菜单应用 MenuApp"]
PairApp["配对应用 PairApp"]
AlarmApp["报警应用 AlarmApp"]
SOSApp["求救应用 SOSApp"]
end
subgraph BG_Apps ["后台应用 Background Apps"]
BgMonitor["后台监测 BgMonitor"]
end
ActiveApp["当前活跃应用 ActiveApp"]
end
subgraph Layer4 ["4. 应用管理层 APP Management"]
AppManager["APP 管理器 AppManager"]
Lifecycle["生命周期调度机 Lifecycle"]
EventRouter["事件路由器 EventRouter"]
end
subgraph Layer3 ["3. 事件管理与总线层 Event Layer"]
EventDispatcher["事件分配器 EventDispatcher"]
EventQueue["事件环形缓冲区 EventQueue (深度8)"]
EmergencyPath["紧急事件直通路径 EmergencyBypass"]
end
subgraph Layer2 ["2. 中断与驱动层 Drivers"]
ExtInt["外部中断 KEY/RF"]
TimeInt["时钟中断 Timer1 1ms"]
ADC_Drv["ADC 电量采集"]
LCD_Drv["LCD 屏幕绘制"]
end
subgraph Layer1 ["1. 硬件实体层 STC32 HW"]
MCU["STC32G 单片机核心"]
end
%% 单向数据与控制交互 (自下而上)
MCU ===> Layer2
Layer2 ===>|异步推送事件| Layer3
Layer3 ===>|事件分发路由| Layer4
Layer4 ===>|生命周期回调与事件分发| FG_Apps
Layer4 ===>|事件广播| BG_Apps
Layer5 ===>|调用显示/报警动作| Layer2
%% 紧急事件直通路径
Layer2 -.->|紧急事件| EmergencyPath
EmergencyPath -.->|直接调用| AppManager
```
### 2.2 应用类型划分
系统将应用分为两大类：
| 应用类型 | 标识 | 特性 | 典型应用 |
| :--- | :--- | :--- | :--- |
| **前台应用** | `APP_TYPE_FOREGROUND` | 独占屏幕显示，响应用户交互，一次只有一个活跃 | 时钟、菜单、配对、报警、SOS |
| **后台应用** | `APP_TYPE_BACKGROUND` | 无屏幕显示，持续运行监听特定事件 | 射频监测、系统守护 |
### 2.3 事件优先级体系
系统定义四级事件优先级，支持紧急事件跳过队列直接处理：
| 优先级 | 标识 | 描述 | 处理方式 | 典型事件 |
| :--- | :--- | :--- | :--- | :--- |
| **低** | `EVENT_PRIORITY_LOW` | 系统内部事件，如定时更新 | 入队等待处理 | 时钟分钟更新 |
| **正常** | `EVENT_PRIORITY_NORMAL` | 普通用户交互事件 | 入队等待处理 | 按键单击、菜单导航 |
| **高** | `EVENT_PRIORITY_HIGH` | 报警相关事件 | 入队优先处理 | 传感器入侵警报 |
| **紧急** | `EVENT_PRIORITY_URGENT` | 最高优先级事件 | **跳过队列直接分发** | SOS求救、紧急按键 |
---
## 3. 应用生命周期机制 (APP Lifecycle)
手环中运行的各个子功能页面（如时钟、菜单、对码、布防）均被抽象为独立的 **App 实例**。每个 App 必须注册并实现以下生命周期回调接口：
### 3.1 应用描述符结构
```c
typedef struct {
AppID app_id; // 应用程序 ID (APP_ID_CLOCK/MENU/PAIR/ALARM/SOS)
AppType app_type; // 应用类型 (前台 APP_TYPE_FOREGROUND / 后台 APP_TYPE_BACKGROUND)
char *app_name; // 应用名称（用于调试日志）
AppStartFunc OnStart; // 启动回调：应用切入前台，加载资源、初始化显示
AppRunFunc onRun; // 循环回调：主循环轮询调用，执行非阻塞业务逻辑
AppCloseFunc onClose; // 关闭回调：应用退出前台，保存状态、清理外设
AppEventFunc onEvent; // 事件回调：接收并处理来自事件层的系统事件，返回 EVENT_HANDLED/IGNORED
bit is_active; // 当前是否活跃（仅对前台应用有效）
bit is_running; // 应用是否处于运行状态（用于CPU占用控制）
} WristbandApp;
```
### 3.2 事件处理返回值
```c
typedef enum {
EVENT_HANDLED, // 事件已处理，停止分发
EVENT_IGNORED // 事件未处理，继续传递给下一个应用
} EventResult;
```
### 3.3 活跃应用切换逻辑 (APP Switch)
1. 当调用 `AppManager_StartApp(target_app_id)` 时：
* 触发当前活跃应用的 `onClose()` 接口，执行现场保存及关屏/停振等外设清理。
* 更新活跃应用指针 `active_app` 指向新 App。
* 触发新活跃应用的 `OnStart()` 接口，执行初始画面的绘制。
2. 在主循环中，系统不断执行当前活跃应用的 `onRun()` 接口，以维护非阻塞的页面动画或等待超时逻辑。
### 3.4 CPU 占用控制机制
为防止单个应用长时间占用 CPU 导致系统响应迟钝，框架引入 **onRun 执行时间限制**：
* **时间阈值**：`APP_ONRUN_MAX_TICKS`（默认 5ms，可配置）
* **监控机制**：每次调用 `onRun()` 前记录当前 `ms_tick`，返回后计算执行耗时
* **超时处理**：若执行时间超过阈值，将应用的 `is_running` 标记为 0，暂停其 `onRun()` 调用，允许下一次循环恢复
```
onRun() 执行流程：
1. 记录开始时间 start_tick = ms_tick
2. 执行应用的 onRun() 回调
3. 计算耗时 elapsed = ms_tick - start_tick
4. 若 elapsed > APP_ONRUN_MAX_TICKS → 设置 is_running = 0（暂停）
5. 否则保持 is_running = 1（继续）
```
---
## 4. 事件采集、缓冲与流转机制 (Event Bus)
事件总线层是实现前后台解耦的核心，支持多级优先级、紧急直通和事件丢弃机制。
### 4.1 事件流转完整架构
```mermaid
graph TD
%% 事件产生层
HW_Sig["物理引脚状态跳变"] -->|电平变化中断| Driver["驱动中断 ISR"]
Driver -->|消抖/解调| Packer["封装统一事件 SystemEvent"]
%% 优先级判断与分流
Packer -->|判断优先级| PriorityJudge{"优先级判断"}
%% 紧急事件直通路径
PriorityJudge -->|URGENT| EmergencyDispatch["EventQueue_EmergencyDispatch()"]
EmergencyDispatch -->|直接调用| AppMgr["APP 管理器"]
%% 普通事件队列路径
PriorityJudge -->|非URGENT| Queue["EventQueue 环形缓冲区 (深度8)"]
Queue -->|主循环轮询| MainLoop["MainLoop 轮询读取"]
MainLoop -->|事件分发| AppMgr
%% 应用层处理
AppMgr -->|步骤1: 前台优先| FG_App["当前活跃前台应用 active_app"]
FG_App -->|返回 EVENT_IGNORED| BG_Check{"后台应用检查"}
FG_App -->|返回 EVENT_HANDLED| Done["事件处理完成"]
BG_Check -->|存在后台应用| BG_Apps["遍历所有后台应用"]
BG_Check -->|无后台应用| Discard["事件丢弃"]
BG_Apps -->|某后台返回 EVENT_HANDLED| Done
BG_Apps -->|所有后台返回 EVENT_IGNORED| Discard
```
### 4.2 事件分发优先级规则
事件在应用层的分发遵循以下严格顺序：
```
事件分发流程：
┌─────────────────────────────────────────────────────────────┐
│ 1. 优先分发给当前活跃的前台应用 (active_app->onEvent()) │
│ ├── 返回 EVENT_HANDLED → 事件处理完成，结束分发 │
│ └── 返回 EVENT_IGNORED → 继续下一步 │
├─────────────────────────────────────────────────────────────┤
│ 2. 分发给所有后台应用 (遍历 app_registry) │
│ ├── 跳过非后台应用和未注册应用 │
│ ├── 逐个调用 bg_app->onEvent() │
│ ├── 某后台返回 EVENT_HANDLED → 事件处理完成，结束分发 │
│ └── 所有后台返回 EVENT_IGNORED → 继续下一步 │
├─────────────────────────────────────────────────────────────┤
│ 3. 事件被丢弃（无应用处理该事件） │
└─────────────────────────────────────────────────────────────┘
```
### 4.3 扩展事件结构体
```c
typedef struct {
KeyEvent key_event; // 原始按键事件
EventPriority priority; // 事件优先级 (LOW/NORMAL/HIGH/URGENT)
u32 extra_data; // 额外数据（如射频地址、时间信息等）
u8 extra_size; // 额外数据有效字节数
} SystemEvent;
```
### 4.4 环形事件缓冲区 (EventQueue)
为防止高速按键或多输入源并发导致事件丢失，系统建立一个深度为 **8 级** 的环形事件队列：
* **队列深度**：`EVENT_QUEUE_DEPTH = 8`
* **入队操作**：`EventQueue_Push(evt)` — 非阻塞，队列满时返回 0（丢弃事件）
* **出队操作**：`EventQueue_Pop()` — 返回队首事件，队空时返回空事件
* **中断保护**：队列操作时禁用全局中断 (`EA=0`)，操作完成后恢复 (`EA=1`)，确保原子性
* **紧急直通**：`EventQueue_EmergencyDispatch(evt)` — 跳过队列，直接调用 `AppManager_DispatchEvent()`
#### 队列内部结构
```c
static SystemEvent event_queue[EVENT_QUEUE_DEPTH]; // 环形缓冲区存储
static u8 queue_head = 0; // 读指针：指向即将读取的位置
static u8 queue_tail = 0; // 写指针：指向即将写入的位置
static u8 queue_count = 0; // 当前队列中的事件数量
```
#### 队列操作流程
```
入队 (Push):
1. 检查队列是否已满 → 满则返回失败
2. 禁用中断 (EA=0)
3. event_queue[queue_tail] = evt
4. queue_tail = (queue_tail + 1) % EVENT_QUEUE_DEPTH
5. queue_count++
6. 恢复中断 (EA=1)
7. 返回成功
出队 (Pop):
1. 检查队列是否为空 → 空则返回空事件
2. 禁用中断 (EA=0)
3. evt = event_queue[queue_head]
4. queue_head = (queue_head + 1) % EVENT_QUEUE_DEPTH
5. queue_count--
6. 恢复中断 (EA=1)
7. 返回事件
```
### 4.5 事件产生机制
#### 按键事件产生
* Timer1 定时器每 10ms 中断扫描物理引脚
* 判定有效按键后执行 `EventQueue_Push()` 或 `EventQueue_EmergencyDispatch()`（SOS事件）
#### RF 事件产生
* LR690L 接收中断触发，解码线程还原 24 位载波包
* 识别到配对传感器动作，推送对应防区事件
#### 系统事件产生
* 定时器分钟变化时推送时钟更新事件（低优先级）
---
## 5. 持久化配置数据库架构
手环配对防区数据存储在 STC32G 内置 Flash 的第 254 扇区：
* **物理存储地址**：`0xFE0000` (末尾 512 字节)。
* **数据库容量**：共 16 组传感器配置槽位。
* **存储结构定义**：
```c
typedef struct {
u8 flags_suffix; // 属性字节：Bit 7 代表有效标志 (1: 有效, 0: 空闲)；Bit 0~6 代表法语防区名称的后缀序号 (01~99)
u8 addr[3]; // 24位射频物理地址 (EV1527 地址 + 4位状态数据码)
} Sensor_Slot;
```
---
## 6. 核心业务事件输入输出 (I/O) 架构明细表
手环核心事件在整个框架中的端到端流动及消耗链路如下：
| 事件名称 | 输入源 (触发条件与参数) | 事件优先级 | 流转方式 | 活跃 APP 消费处理 (逻辑响应与动作) |
| :--- | :--- | :--- | :--- | :--- |
| **按键操作事件**<br>`KEY_EVENT` | **源**：Pin 30/31/32 (Port 0) 下降沿中断。<br>**参数**：▲/▼/■ (短按/长按)。 | NORMAL | **入队**：`EventQueue_Push` 压入队列 | **待机应用**：长按确认键 3 秒，调用 `StartApp(APP_MENU)`；<br>**菜单应用**：短按 ▲/▼ 键移动高亮焦点；短按确认键调用 `StartApp` 进入对应子设置应用。 |
| **主动求救事件**<br>`KEY_EVENT_SOS_CLICK` / `KEY_EVENT_SOS_LONG` | **源**：Pin 27 (`P2.6`) SOS 物理键拉低。<br>**参数**：短按触发 `KEY_EVENT_SOS_CLICK`，长按触发 `KEY_EVENT_SOS_LONG`。 | **URGENT** | **直通**：`EventQueue_EmergencyDispatch` 跳过队列直接分发 | **SOS报警应用**：<br>1. 显示：OLED 屏亮起 `SOS EMIS`；<br>2. 灯效：WS2812B 红色交替闪烁 (50ms)；<br>3. 马达：开启间歇长振 (振1000ms，停200ms)；<br>4. 射频：启动发送线程周期性（2s）发射手环 Factory ID 及 `0x08` (SOS) 包。 |
| **无线对码捕获事件**<br>`RF_PAIR_RECV_EVENT` | **源**：Pin 22 (`P2.1`) 沿变化中断。<br>**参数**：EV1527 24位对码信号。 | NORMAL | **入队**：`EventQueue_Push` 压入队列 | **配对应用**：<br>1. 状态：跳转进入 `STATE_PAIR_CONFIRM` (微调保存页)；<br>2. 显示：只读显示自动识别传感器类型及大图标；<br>3. 马达：短振 300ms 提醒成功；<br>4. 交互：通过按键微调序号并写入 Flash 数据库。 |
| **传感器入侵警报事件**<br>`RF_ALARM_RECV_EVENT` | **源**：Pin 22 (`P2.1`) 沿变化中断。<br>**参数**：传感器物理地址 + 4位状态码。 | HIGH | **入队**：`EventQueue_Push` 压入队列 | **警报应用**：若该防区为 ZONE 0 (24h) 或处于已布防，APP管理器启动 `StartApp(APP_ALARM)`。<br>1. 显示：OLED 刷红边框与对应大图标，显示入侵警报文字；<br>2. 灯效：同步闪烁该防区专属色彩；<br>3. 马达：输出对应防区的特定异步振动波形。 |
| **系统自动休眠事件**<br>`AUTO_SLEEP_EVENT` | **源**：软件时钟计时 `inactivity_timer >= 1000` (10s)。 | LOW | **入队**：`EventQueue_Push` 压入队列 | **所有非警报应用**：执行 `onClose()` → 调用 PM 模块拉低 `SHUT=0`（Pin 23）彻底切断屏幕供电 → 配置 GPIO 变化中断和无线唤醒源 → 执行 `PCON|=0x02` 进入停机休眠。 |
| **中断唤醒系统事件**<br>`SYSTEM_WAKEUP_EVENT` | **源**：GPIO 按键下降沿或无线信号变化触发硬件唤醒。 | HIGH | **入队**：`EventQueue_Push` 压入队列 | **系统底层**：优先拉高 `SHUT=1` 重新开启 SGM3833 供电 → **阻塞强延时 50ms 避开浪涌** → 完整重新配置 RM69310 屏幕控制器 → 调用 `StartApp(APP_CLOCK)` 恢复时钟显示状态。 |
<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V3 -->
<!-- Updated with foreground/background app separation, event priority system, emergency dispatch, and CPU occupancy control -->