/******************************************************************************
 * @file    app_linkage.h
 * @brief   CBR3 联动引擎（替换原 7 组条件）：DP5 删除 + DP6 20B 配置，
 *          按实时温湿度回差开 1 档 / 关 0 档
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.02
 * @version V3.0.0，随规格书 V3.0.0 新建（删除 app_cond）
 *
 * @note    规格书第 10 章（行为）+ 第 12 章（仲裁）。与条件引擎的关键差别：
 *            - 只有 **1 条** 20B 配置（无 cond_en 总开关）；
 *            - **不改 mode**：开只写 fan_gear=1，关只写 0，不切通风/强力；
 *            - **不恢复档位快照**（原条件引擎的快照语义整段作废）；
 *            - 手动作废标志是 RAM，不写 VM，需走到「关」条件才再武装。
 *          字节布局（规格书 10.2，以本文为准，不看 JSON 摘要）：
 *            Byte0-1 缸体编号 uint16 大端（≠0 才有效，只存不用）
 *            Byte2 Tmin int8 ℃   Byte3 Tmax int8 ℃
 *            Byte4 Hmin uint8 %  Byte5 Hmax uint8 %
 *            Byte6 配置版本（只存不用）  Byte7-19 预留（只存不用）
 *          温度比较用设备内部 0.1℃（temp_x10），**没有等于比较**：
 *          T==Tmax 不算超最高，也不算低于最低。
 *
 *          ⚠ app_linkage_run / app_linkage_reeval 只能在 usr_timer_loop
 *          （500ms，任务上下文）调用；20ms usr_timer_tick 是中断上下文，
 *          本模块没有任何 tick 接口，不要在中断里调。
 ******************************************************************************/

#ifndef __APP_LINKAGE_H__
#define __APP_LINKAGE_H__

#include <stdint.h>

/**
 * @brief  初始化联动引擎（清 RAM 状态与数码管告警标志）
 * @return 无
 */
void app_linkage_init(void);

/**
 * @brief  推进联动引擎（500ms，任务上下文，由 usr_timer_loop 调用）
 * @param  dt 距上次调用的毫秒数（本模块不计时，仅透传）
 * @return 无
 */
void app_linkage_run(uint16_t dt);

/**
 * @brief  立刻按第 10.3 节重判一次（不是手动作废）
 * @note   供定时窗结束收口后调用（规格书 11.3：窗结束仍超最高 → 联动接手
 *         开 1 档）。本函数是 app_linkage_run 的核心，幂等。
 * @return 无
 */
void app_linkage_reeval(void);

/**
 * @brief  DP5 linkage_delete 写 1：清 RAM + VM 的 20B 配置
 * @note   联动若正占着风扇 → fan_gear=0；作废标志一并清掉（配置已不存在）。
 *         调用方（jb_product）负责把 linkage_delete 清回 0 再上报（脉冲）
 * @return 无
 */
void app_linkage_delete(void);

/**
 * @brief  DP6 linkage_config 重写完成：存 VM + 清手动作废 + 立刻重判
 * @note   数据已由 jb_product memcpy 进 gDevData.linkage_config。
 *         BOARD_LINKAGE_ENABLE=0 时仍 mark_dirty 落盘，只是不跑开停。
 * @return 无
 */
void app_linkage_set_config(void);

/**
 * @brief  手动作废本轮联动（短按 / APP 写 mode / APP 写 fan_gear）
 * @note   RAM 标志，不写 VM（规格书 12 章）。作废期间数码管仍按 8.2 闪。
 *         再武装只能靠走到第 10.3 节的「关」条件（没有一侧超最高，
 *         且至少一侧 < min），然后重新出现超最高。
 * @return 无
 */
void app_linkage_void(void);

/**
 * @brief  当前 20B 配置是否为有效联动配置（第 10.1 节）
 * @return 1=有效（缸体号≠0 且 Tmin≤Tmax 且 Hmin≤Hmax）
 */
uint8_t app_linkage_is_valid(void);

#endif /* __APP_LINKAGE_H__ */