/******************************************************************************
 * @file    app_arbiter.h
 * @brief   CBR3 模式仲裁器（规格书第 12 章）：手动 > 定时 > 联动
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.02
 * @version V2.0.0（规格书 V3.0.0）：owner COND → LINKAGE；**删除档位快照**
 *
 * @note    把"谁在驱动风扇"收成一处，避免 mode/linkage/timer 互调成环。
 *          唯一状态源是 owner（NONE/LINKAGE/TIMER）。
 *            - 手动动作（短按/APP 写档/写 mode）→ app_arbiter_manual_intervene()：
 *              清 owner 并转调 app_linkage_void() 作废本轮联动（RAM，不写 VM）；
 *              定时引擎下个 tick 感知 owner 后本窗剩余时间不再抢回。
 *            - 定时窗开始 → app_arbiter_timer_take()（定时 > 联动）；
 *            - 联动触发 → app_arbiter_linkage_take()；定时占用中返回 0。
 *            - 联动自然失效（关条件成立）→ app_arbiter_linkage_release()。
 *
 *          ⚠ V2.0.0 与旧条件引擎的关键差别（规格书 12 章）：
 *          **联动不恢复档位快照**——开只写 fan_gear=1，关只写 0，不存也不恢复
 *          进入联动前的 mode/gear。原 cond_get_snapshot / snapshot_clear
 *          一组接口整段删除，不要再加回来。
 *          作废标志是 RAM、不写 VM，再武装要靠走到第 10.3 节的「关」条件。
 ******************************************************************************/

#ifndef __APP_ARBITER_H__
#define __APP_ARBITER_H__

#include <stdint.h>

/** 当前风扇占用者 */
typedef enum {
    ARB_OWNER_NONE = 0,     /**< 空闲 / 手动接管 */
    ARB_OWNER_LINKAGE = 1,  /**< 联动引擎占用 */
    ARB_OWNER_TIMER = 2     /**< 定时引擎占用 */
} ArbOwner_t;

/**
 * @brief  初始化仲裁器
 * @return 无
 */
void app_arbiter_init(void);

/**
 * @brief  当前风扇占用者
 * @return ArbOwner_t
 */
uint8_t app_arbiter_get_owner(void);

/**
 * @brief  手动动作统一入口（短按 / APP 写 fan_gear / APP 写 mode）
 * @note   立即释放一切自动化占用，并作废本轮联动（12 章规则 1）。
 *         定时引擎下个 tick 感知 owner 后本窗剩余时间不再抢回（规则 2）
 * @return 无
 */
void app_arbiter_manual_intervene(void);

/* ═══ 联动引擎接口 ═══ */

/**
 * @brief  联动引擎尝试占用（超最高要开 1 档前调用）
 * @note   定时占用中返回 0（12 章：定时窗 vs 联动 → 定时胜，窗内联动不插嘴）；
 *         占用成功时**不保存任何档位快照**（联动不恢复快照）
 * @return 1=占用成功，0=被定时占用拒绝
 */
uint8_t app_arbiter_linkage_take(void);

/**
 * @brief  联动是否仍在占用
 * @return 1=owner==LINKAGE
 */
uint8_t app_arbiter_linkage_active(void);

/**
 * @brief  联动自然失效：让出风扇（只清 owner，档位由调用方写）
 * @return 无
 */
void app_arbiter_linkage_release(void);

/* ═══ 定时引擎接口 ═══ */

/**
 * @brief  定时引擎窗开始占用
 * @return 1=成功（恒成功，定时优先级高于联动）
 */
uint8_t app_arbiter_timer_take(void);

/**
 * @brief  定时窗结束释放
 * @note   调用方负责收口（风扇 0、mode 0），并按 11.3 调
 *         app_linkage_reeval() 让联动立刻重判
 * @return 无
 */
void app_arbiter_timer_release(void);

#endif /* __APP_ARBITER_H__ */