/******************************************************************************
 * @file    app_arbiter.h
 * @brief   CBR3 模式仲裁器（规格书第 12 章）：手动 > 定时 > 条件
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.31
 * @version V1.0.0，首次发布（P2）
 *
 * @note    把"谁在驱动模式"收成一处，避免 mode/cond/timer 互调成环。
 *          唯一状态源是 owner（NONE/COND/TIMER）+ 条件快照；
 *          条件/定时引擎各自维护占用细节，通过查询 owner 感知被打断：
 *            - 手动动作（短按/APP 写档/mode）→ app_arbiter_manual_intervene()
 *              清 owner；条件引擎感知后作废本轮（RAM），定时引擎感知后本窗
 *              不再抢回（规格书 12 章规则 1/2）。
 *            - 条件自然失效（比较不成立）→ 条件引擎恢复快照后
 *              app_arbiter_cond_release()。
 *            - 定时窗结束 → app_arbiter_timer_release() + 收口。
 *          快照：第一次条件抢权前保存用户 mode+gear（规格书 10.3-3），
 *          后覆盖/手动介入均不更新它（10.3-6），只在条件自然失效恢复后清空。
 ******************************************************************************/

#ifndef __APP_ARBITER_H__
#define __APP_ARBITER_H__

#include <stdint.h>

/** 当前模式占用者 */
typedef enum {
    ARB_OWNER_NONE = 0,   /**< 空闲 / 手动接管 */
    ARB_OWNER_COND = 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   立即释放一切自动化占用；条件/定时引擎下个 tick 感知后各自作废
 * @return 无
 */
void app_arbiter_manual_intervene(void);

/* ═══ 条件引擎接口 ═══ */

/**
 * @brief  条件引擎尝试占用（触发模式前调用）
 * @note   定时占用中返回 0（规格书 12：定时窗 vs 条件 → 定时胜，条件不开）；
 *         占用成功时若尚无快照则保存当前用户 mode+gear（仅第一次）
 * @return 1=占用成功，0=被定时占用拒绝
 */
uint8_t app_arbiter_cond_take(void);

/**
 * @brief  条件是否仍在占用
 * @return 1=owner==COND
 */
uint8_t app_arbiter_cond_active(void);

/**
 * @brief  条件自然失效：恢复快照后调用（清 owner 与快照）
 * @return 无
 */
void app_arbiter_cond_release(void);

/**
 * @brief  取条件快照（恢复用）
 * @param  mode 输出快照模式
 * @param  gear 输出快照档位
 * @return 无
 */
void app_arbiter_cond_get_snapshot(uint8_t *mode, uint8_t *gear);

/**
 * @brief  条件被手动打断：只清快照（快照对应的用户状态已过时），
 *         不恢复、不清 owner（owner 已被 manual_intervene 清掉）
 * @return 无
 */
void app_arbiter_cond_snapshot_clear(void);

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

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

/**
 * @brief  定时窗结束释放
 * @return 无
 */
void app_arbiter_timer_release(void);

#endif /* __APP_ARBITER_H__ */