/******************************************************************************
 * @file    app_light_life.h
 * @brief   灯泡剩余寿命（规格书 13.2 节，DP2/DP3/DP25；DP4 本版不用）
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.08
 * @version V1.0.1
 *
 * @note    额定工时 2592000s（30 天），按继电器**实际吸合**每秒扣 1；
 *          扣到 0 停住不回绕，置 alarm_code=1（灯泡到期告警，粘住）但**不互锁**，
 *          灯仍可手动/定时/联动再开（第 12 章仲裁不参与）。
 *          APP 换灯：直接写 DP3（通常写 2592000），不走 DP4。
 *          DP3 上报节流：平时满 60s 才同步一次 gDevData；到期 / APP 写 DP3 /
 *          出厂复位走边沿立刻同步 + 落盘（任务上下文，禁止 ISR 写 VM）。
 ******************************************************************************/

#ifndef __APP_LIGHT_LIFE_H__
#define __APP_LIGHT_LIFE_H__

#include <stdint.h>

/**
 * @brief  初始化剩余寿命：RAM 复位为额定值，告警按值推导
 * @note   之后 app_nvm_load 若 VM 有效会调 app_light_life_restore 覆盖
 * @return 无
 */
void app_light_life_init(void);

/**
 * @brief  20ms 业务节拍（中断上下文）：实际吸合才折秒扣减
 * @param  dt 距上次调用的毫秒数
 * @note   ISR 只碰 s_life（RAM）；gDevData 同步 / 落盘 / 上报在 app_light_life_loop
 * @return 无
 */
void app_light_life_tick(uint16_t dt);

/**
 * @brief  500ms 任务上下文：60s 节流同步 DP3、边沿立刻同步 + 落盘、推导告警
 * @return 无
 */
void app_light_life_loop(void);

/**
 * @brief  设置剩余寿命（APP 写 DP3 / 出厂复位，任务上下文）
 * @param  remain 剩余寿命秒，范围 0~0xFFFFFFFF 不封顶
 * @note   立刻生效：同步 gDevData + 推导 alarm_code + 立刻落盘；
 *         remain>0 清到期告警，=0 置告警。上电灌 VM 请用 restore。
 *         APP 换灯：写 DP3=2592000，不要写 DP4。
 * @return 无
 */
void app_light_life_set_remain(uint32_t remain);

/**
 * @brief  上电从 VM 恢复剩余寿命（只改 RAM，不写 flash）
 * @param  remain VM 中的剩余寿命秒
 * @return 无
 */
void app_light_life_restore(uint32_t remain);

/**
 * @brief  寿命回到额定值（仅出厂复位内部调用）
 * @note   APP 换灯请写 DP3，本函数不接 DP4
 * @return 无
 */
void app_light_life_reset(void);

/**
 * @brief  查询剩余寿命
 * @return 剩余寿命秒
 */
uint32_t app_light_life_get_remain(void);

#endif /* __APP_LIGHT_LIFE_H__ */