/******************************************************************************
 * @file    app_power.h
 * @brief   USB / 充电检测、电量采样与低电策略、深睡请求生命周期
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.25
 * @version V1.0.0
 * @history
 * - V1.0.0, 2026.08.25, cyWu, 首次发布，实现 USB/充电检测、电量采样与深睡请求
 *
 * @note    本模块只管“电从哪来、还剩多少、要不要关机”，不认识电机/灯/按键。
 *          需要在 USB 插拔 / 深睡时联动其它模块的地方，一律走 app_power_set_hooks
 *          注册的回调，调用方（usr_jb_main）负责接线，避免本模块反过来依赖别的模块。
 ******************************************************************************/

#ifndef __APP_POWER_H__
#define __APP_POWER_H__

#include <stdint.h>

/** USB 插拔的边沿事件，仅在状态变化那一次返回一次 */
typedef enum {
    APP_POWER_EVT_NONE = 0,
    APP_POWER_EVT_USB_IN,
    APP_POWER_EVT_USB_OUT
} AppPowerEvt_t;

/** 深睡请求的钩子：on_request 用于立即停机（马达/灯），on_finalize 用于真正掉电 */
typedef void (*AppPowerHook_t)(void);

/**
 * @brief  初始化电源模块状态
 * @return 无
 */
void app_power_init(void);

/**
 * @brief  注册深睡请求的两段式回调
 * @param  on_request  刚请求深睡时调用（停电机、灯全灭）
 * @param  on_finalize 50ms 后调用（真正进深睡，不会返回）
 * @return 无
 */
void app_power_set_hooks(AppPowerHook_t on_request, AppPowerHook_t on_finalize);

/**
 * @brief  充电检测 + 电量采样，每个业务 tick 调用一次
 * @param  dt 距上次调用的毫秒数
 * @return USB 插拔边沿事件，多数时候是 APP_POWER_EVT_NONE
 */
AppPowerEvt_t app_power_tick_1ms(uint16_t dt);

/**
 * @brief  查询 USB 是否在位（含正在充电）
 * @return 1=在位，0=未接
 */
uint8_t app_power_usb_online(void);

/**
 * @brief  查询充电灯状态
 * @return 0=无 1=充电中红灯 2=已充满绿灯
 */
uint8_t app_power_charge_led(void);

/**
 * @brief  查询是否处于低电告警
 * @return 1=低电，0=正常
 */
uint8_t app_power_low_bat(void);

/**
 * @brief  请求深睡：立即触发 on_request 钩子，50ms 后触发 on_finalize
 * @return 无
 */
void app_power_request_poweroff(void);

/**
 * @brief  查询深睡请求是否已发起（发起后其它模块应停止响应新操作）
 * @return 1=已发起，0=未发起
 */
uint8_t app_power_poweroff_pending(void);

#endif /* __APP_POWER_H__ */