stc32g128k/App/app_manager.h

#ifndef __APP_MANAGER_H__
#define __APP_MANAGER_H__

#include "config.h"

/* ====== 应用程序管理器 (AppManager) 核心接口 ====== */

/**
 * @brief 初始化应用程序管理器
 * @details 负责将应用管理器的系统注册表清零，随后逐一注册系统支持的五个前台应用：
 *          ClockApp (待机时钟), MenuApp (主菜单), PairApp (传感器对码), 
 *          AlarmApp (传感器警报), SOSApp (主动求救呼叫)。最后默认加载并启动 ClockApp。
 */
void AppManager_Init(void);

/**
 * @brief 启动指定的应用程序
 * @param app_id 待启动应用的目标 ID (如 APP_ID_MENU, APP_ID_PAIR)
 * @details 会执行完整的切应用生命周期流转：
 *          1. 检查目标是否合法且包含有效的 OnStart 启动回调。
 *          2. 对当前正在活跃运行的前台应用调用其 onClose()，以关闭该应用的屏幕内容、马达振动或射频特定模式。
 *          3. 将活跃应用指针指向新应用，将其 is_active 和 is_running 标志位置 1。
 *          4. 调用新应用的 OnStart() 初始化回调以绘制新页面。
 */
void AppManager_StartApp(AppID app_id);

/**
 * @brief 向当前活跃的前台应用程序派发事件
 * @param evt 要分发派送的系统事件
 */
void AppManager_DispatchEvent(SystemEvent evt);

/**
 * @brief 在系统主循环中持续轮询运行活跃应用
 * @details 负责从全局注册表中定位到 active_app，并轮询执行其 onRun() 周期回调。
 *          该接口同时集成了【CPU占用率限制机制】：如果在调用 onRun 前后，检测到应用
 *          占用 CPU 时间超过了 APP_ONRUN_MAX_TICKS (5ms)，它将在下一次循环中暂时挂起
 *          该应用，强制释放本次 CPU 占用以防止界面卡死或影响底层射频解调。
 */
void AppManager_RunActiveApp(void);

/**
 * @brief 获取当前前台活跃应用的唯一应用程序 ID
 * @return AppID 当前活跃前台应用的枚举ID
 */
AppID AppManager_GetActiveAppID(void);


/* ====== 时间编辑状态机交互接口 ====== */

/**
 * @brief 启动时钟数值调整编辑状态机
 * @details 由 MenuApp 的 "HORLOGE" 项被确认点击后触发。用于直接将系统运行状态切入
 *          STATE_SET_TIME，控制灯条常亮蓝色，马达短振反馈，并进入时间参数微调页。
 */
void Start_Time_Edit(void);

#endif // __APP_MANAGER_H__