/**
 * @file    app_controller.h
 * @brief   应用控制器 — 层级状态机 (HSM)
 *
 * 将 Button FSM 的事件映射到 LED Driver 的控制指令
 * 使用 OOPC 不透明指针封装应用状态
 *
 * HSM 层级状态图:
 * ┌─────────────────────────────────────────────────────────┐
 * │                    POWERED                              │
 * │  ┌──────────────────────────────────────────────────┐   │
 * │  │                  ACTIVE                          │   │
 * │  │                                                  │   │
 * │  │   ┌────────┐  single_click  ┌────────┐          │   │
 * │  │   │  OFF   │───────────────→│   ON   │          │   │
 * │  │   └────────┘←───────────────└────────┘          │   │
 * │  │       ↑          single_click                    │   │
 * │  │       │                                          │   │
 * │  │       │ double_click                             │   │
 * │  │   ┌────────┐←─────────────┐                     │   │
 * │  │   │ BLINK  │              │ double_click         │   │
 * │  │   │ (SLOW) │─────────────→│ BLINK(FAST) │        │   │
 * │  │   └────────┘              └─────────────┘        │   │
 * │  │       ↑                        ↑                │   │
 * │  │       │ long_press             │ long_press      │   │
 * │  │   ┌────────┐                                    │   │
 * │  │   │BREATHING│←──────────────────────────────────┘   │   │
 * │  │   └────────┘   long_press(退出→OFF)                │   │
 * │  └──────────────────────────────────────────────────┘   │
 * └─────────────────────────────────────────────────────────┘
 *
 * 事件映射表:
 *   当前状态      │ 事件              │ 下一状态     │ 动作
 *   ─────────────┼──────────────────┼─────────────┼──────────────
 *   OFF          │ SINGLE_CLICK     │ ON          │ Led_On()
 *   ON           │ SINGLE_CLICK     │ OFF         │ Led_Off()
 *   ON           │ DOUBLE_CLICK     │ BLINK_SLOW  │ Led_SetBlink(1000)
 *   BLINK_SLOW   │ DOUBLE_CLICK     │ BLINK_FAST  │ Led_SetBlink(200)
 *   BLINK_FAST   │ DOUBLE_CLICK     │ OFF         │ Led_Off()
 *   任意状态      │ LONG_PRESS_START │ BREATHING   │ Led_SetBreathing()
 *   BREATHING    │ LONG_PRESS_START │ OFF         │ Led_Off()
 */
#ifndef APP_CONTROLLER_H
#define APP_CONTROLLER_H

#include <stdint.h>
#include "led_driver.h"
#include "btn_fsm.h"

/* ======== 前向声明 ======== */
typedef struct AppCtrl_S AppCtrl_S;

/* ======== 应用状态枚举 ======== */
typedef enum {
    APP_STATE_OFF = 0,
    APP_STATE_ON,
    APP_STATE_BLINK_SLOW,
    APP_STATE_BLINK_FAST,
    APP_STATE_BREATHING,
    APP_STATE_COUNT
} AppState_E;

/* ======== 公开 API ======== */

/**
 * @brief  创建应用控制器
 * @param  led   LED 驱动实例（不透明指针）
 * @param  btn   按键 FSM 实例（开放结构体指针）
 * @return AppCtrl_S* 控制器实例
 */
AppCtrl_S* AppCtrl_Create(LedDriver_S* led, Btn_FSM* btn);

/**
 * @brief  销毁应用控制器
 */
void AppCtrl_Destroy(AppCtrl_S* me);

/**
 * @brief  初始化：注册按键回调，设置初始状态
 */
void AppCtrl_Init(AppCtrl_S* me);

/**
 * @brief  主循环轮询（非阻塞）
 * @param  now_ms  系统时间戳
 */
void AppCtrl_Poll(AppCtrl_S* me, uint32_t now_ms);

/**
 * @brief  获取当前应用状态
 */
AppState_E AppCtrl_GetState(const AppCtrl_S* me);

/**
 * @brief  状态名称字符串（调试用）
 */
const char* AppCtrl_StateName(AppState_E state);

/* ======== 配置宏 ======== */
#define APP_MAX_INSTANCES   2

#endif /* APP_CONTROLLER_H */