/******************************************************************************
 * @file    app_battery.h
 * @brief   电量算法：电压滤波、充放电基准记录、突变防抖、缓冲平滑显示
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.27
 * @version V1.0.1
 * @history
 * - V1.0.0, 2026.08.26, cyWu, 首次发布，实现电压滤波、充放电基准、突变防抖与缓冲平滑
 * - V1.0.1, 2026.08.27, cyWu, 补充模块说明注释
 *
 * @note    本模块只认识"电压(mV) + 是否在充电"，不碰 ADC/GPIO，电压采样、
 *          USB 在位判定由调用方（app_power）负责，保持单向依赖。
 *          低电告警迟滞（app_power.c 里的 check_low）不受本模块影响：
 *          本模块负责显示电量怎么变得好看；低电红灯仍按原始电压判断，
 *          5% 自动关机则读本模块给出的显示百分比。
 ******************************************************************************/

#ifndef __APP_BATTERY_H__
#define __APP_BATTERY_H__

#include <stdint.h>

/*========================= 功能配置 =========================*/
/** 充电末期自动 +1% 模式：解决充电曲线末期长时间平台期、电量显示卡住的问题；
 *  是否需要取决于实测充电曲线，先关掉，确认卡电量再打开 */
#define APP_BATTERY_AUTO_INCREMENT_EN   0

/**
 * @brief  初始化电量模块状态（含充放电基准，不做持久化，每次重启重新学习）
 * @return 无
 */
void app_battery_init(void);

/**
 * @brief  按最新采样电压推进电量算法
 * @param  dt       距上次调用的毫秒数
 * @param  mv       本次采样均值电压，单位 mV（由调用方滑动平均后传入）
 * @param  charging 1=充电中（USB 在位），0=放电
 * @return 无
 */
void app_battery_tick(uint16_t dt, uint16_t mv, uint8_t charging);

/**
 * @brief  查询当前显示用电量百分比（已做防抖/缓冲平滑，非原始电压换算值）
 * @return 0~100
 */
uint8_t app_battery_get_percent(void);

/**
 * @brief  外部强制刷新电量（例如硬件判定充满后收尾到 100%），立即生效不走缓冲
 * @note   充电场景下曲线拟合可能因基准/温漂等原因走不到 100% 就被充电芯片
 *         判满，靠这个接口兜底，避免显示卡在 98%/99% 不动
 * @param  percent 目标百分比，超过 100 会被钳到 100
 * @return 无
 */
void app_battery_set_percent(uint8_t percent);

#endif /* __APP_BATTERY_H__ */