/******************************************************************************
 * @file    app_nvm.h
 * @brief   CBR2 VM 持久化（P1 起）：spray_config(8B) / linkage_config(20B) /
 *          spray_plan_en / spray_plan1 + time_config2~7（各 15B） /
 *          fault_en / alarm_en / 运行记录（规格书第 14 章）
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.09
 * @version V1.0.0，首次发布
 *
 * @note    存：spray_config（含首次默认 10/3/3）、linkage_config 20B、
 *          spray_plan_en、7 条计划、fault_en、alarm_en、run_record。
 *          不存：DP0/2/3/4/5、DP1 作业开关（上电绝不自动喷）、DP6 当前湿度、
 *          联动作废标志、linkage_delete（脉冲）、BLE 三元组（出厂重置不清）。
 *
 *          ⚠ 写 flash 只能在任务上下文（app_nvm_flush / app_nvm_save），
 *          20ms 中断上下文只允许 app_nvm_tick 防抖计时。
 ******************************************************************************/

#ifndef __APP_NVM_H__
#define __APP_NVM_H__

#include <stdint.h>

/**
 * @brief  初始化（校验 VM 有效性，仅日志；数据加载在 app_nvm_load）
 * @return 无
 */
void app_nvm_init(void);

/**
 * @brief  从 VM 加载业务字段回填 gDevData（开机调用，在 userInit 之后）
 * @note   VM 无效（首次上电）保持 gDevData 现值——userInit 已写入 DP7 默认
 *         10s×3+3s。只回填配置，DP1/泵保持关，不恢复作业。
 * @return 无
 */
void app_nvm_load(void);

/**
 * @brief  立即保存全部业务字段到 VM（任务上下文）
 * @return 无
 */
void app_nvm_save(void);

/**
 * @brief  任务上下文落盘：防抖满后真正写 VM（由 usr_timer_loop 500ms 调用）
 * @note   必须且只能在非中断上下文调用（VM 擦写 flash 栈用量大）
 * @return 无
 */
void app_nvm_flush(void);

/**
 * @brief  标记业务字段有变化，防抖计时归零（DP7/计划/plan_en/DP20/22 写入时调用）
 * @return 无
 */
void app_nvm_mark_dirty(void);

/**
 * @brief  立即保存运行记录 item（满 600s / 跨天 / 首次对时调用，任务上下文）
 * @note   与 app_nvm_save 分开：运行记录落盘节奏与配置变化无关，避免把
 *         配置区无谓擦写一遍
 * @return 无
 */
void app_nvm_save_runrec(void);

/**
 * @brief  出厂重置：清全部业务 VM（含运行记录；保留 BLE 配对，规格书 15 章）
 * @note   4 个 item 写全 0 → magic 失效，下次开机走首次上电默认值；
 *         RAM 复位由调用方（app_function）完成
 * @return 无
 */
void app_nvm_reset(void);

#endif /* __APP_NVM_H__ */