/*
 * 模块名称：Volume Idle Sync（写回缓存空闲 flush）
 * 模块功能：随 defaultTask 主循环周期轮询，在存储**空闲**时对 NAND FatFs 卷
 *          补发一次 CTRL_SYNC（FatFs 幂等落盘语义 = FTL 单页写回缓存脏页刷入
 *          + dhara journal 待办收账，见 docs/架构设计/STM32F4-Base存储架构说明.md
 *          §5.5），作为写回缓存持久性的兜底网：
 *            - 正常写事务语义不变：f_close 内部 sync_fs 已同步，本模块零干预；
 *            - 价值在漏网兜底：任何"缓存留脏、之后再无调用触发 sync"的状态
 *              （异常路径中途放锁等）其掉电驻留窗从"无限期，直到下一笔写"
 *              收敛为"不超过本模块周期"；
 *            - 卷不空闲（卷锁被持有：syslog 落盘 / 配置保存 / lftpd
 *              open...close 序列进行中）本轮跳过——不改变文件持有期（如 FTP
 *              STOR 进行中）的既有语义。
 *          clean 态零 NAND 触点（脏标志与 journal 双短路）；脏态成本与一次
 *          f_close 同型。周期 5 s（.c 内 VOL_IDLE_SYNC_PERIOD_MS）。
 *          ⚠ 边界（勿当成掉电保护）：本板无掉电检测硬件，"掉电前强制 flush"
 *          不可行；"单次写事务进行中掉电"的丢失边界也不因本模块改变。
 * 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）；仅 MCU 端，
 *          主机侧纯逻辑单测 test/host/vol_idle_sync/
 * 作者：DTU 项目组
 * 创建日期：2026-10-25（道F 批 2：写回缓存空闲 flush 收口）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：STORAGE_READY 门控 + 周期节流 +
 *                              卷锁 try + disk_ioctl(CTRL_SYNC) + 失败边沿 latch
 */

#ifndef VOL_IDLE_SYNC_H
#define VOL_IDLE_SYNC_H

#ifdef __cplusplus
extern "C" {
#endif

/*
 * 函数功能：存储空闲周期同步的轮询入口（内部自带就绪门控 / 节流 / 非阻塞
 *          try 锁 / clean 短路，调用点每轮无条件调用即可）
 * 入口参数：无  void
 * 返回值：无  void
 * 限定条件：仅 defaultTask 主循环调用（存储属主任务；本函数内部绝不阻塞——
 *          defaultTask 是看门狗喂狗点，见 vol_lock.h 使用约定）；
 *          TEST_SUITE_STORAGE 构建下为空实现（卷由 testTask 独占，后台同步
 *          必须彻底静默）
 */
void vol_idle_sync_poll(void);

#ifdef __cplusplus
}
#endif

#endif /* VOL_IDLE_SYNC_H */