/******************************************************************************
 * @file    app_spray.h
 * @brief   喷淋作业引擎：一轮 = 单次时长 × 次数 + 间隔（规格书第 10 章）
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.09.09
 * @version V1.3.0
 * @history
 * - V1.3.0, 2026.09.09, cyWu, P2 轮来源 owner + 计划参数通道 + 轮结束事件
 *******************************************************************************/

#ifndef __APP_SPRAY_H__
#define __APP_SPRAY_H__

#include <stdint.h>

/** 轮来源（规格书 13 章仲裁：手动 > 计划 > 联动） */
typedef enum {
    APP_SPRAY_OWNER_NONE = 0,   /**< 空闲 */
    APP_SPRAY_OWNER_MANUAL,     /**< PB1 / DP1 / DP7 */
    APP_SPRAY_OWNER_PLAN,       /**< 计划到点 */
    APP_SPRAY_OWNER_LINKAGE     /**< 湿度联动循环 */
} AppSprayOwner_t;

typedef enum {
    APP_SPRAY_OK = 0,
    APP_SPRAY_ERR_NOT_INIT
} AppSpray_Ret_t;

/**
 * @brief  初始化作业引擎（泵保持关，参数待起轮时解析）
 * @return APP_SPRAY_OK=成功
 */
AppSpray_Ret_t app_spray_init(void);

/**
 * @brief  请求开一轮：空闲才执行，用 RAM 里最近有效 DP7 配置（手动来源）
 * @note   请求在 20ms tick 消费；幂等：消费时已在作业中则保持当前轮
 *         （规格书 10.5，PB1/DP1 语义）。
 * @return 无
 */
void app_spray_req_start(void);

/**
 * @brief  请求停：消费时立刻两脚拉低、结束作业（间隔等待中也立即停）
 * @return 无
 */
void app_spray_req_stop(void);

/**
 * @brief  请求重开一轮：中止当前轮（若有）并按 RAM 里最新 DP7 参数立刻开新轮
 * @note   APP 写合法 DP7 的专用入口（规格书 10.2：中止旧轮再开新轮）。
 * @return 无
 */
void app_spray_req_restart(void);

/**
 * @brief  请求开一轮（联动循环来源，DP7 参数）
 * @note   规格书 11.3：H<Hmin 时循环开一轮又一轮；计划占用中联动不抢。
 * @return 无
 */
void app_spray_req_start_link(void);

/**
 * @brief  请求开一轮（计划来源，用该条计划自己的参数，规格书 12.3）
 * @param  dur_s  单次时长秒
 * @param  cnt    次数
 * @param  itv_s  间隔秒
 * @param  slot   槽位 0~6（轮结束收口清单次使能用）
 * @return 无
 */
void app_spray_req_start_plan(uint16_t dur_s, uint8_t cnt, uint16_t itv_s, uint8_t slot);

/**
 * @brief  作业节拍：先消费请求，再做时长/间隔倒数与切泵（每 20ms 调用）
 * @param  dt 距上次调用的毫秒数
 * @return 无
 */
void app_spray_poll(uint16_t dt);

/**
 * @brief  查询是否处于作业态（含间隔等待，整轮期间为 1）
 * @return 1=作业中，0=空闲
 */
uint8_t app_spray_is_running(void);

/**
 * @brief  查询当前轮来源（AppSprayOwner_t；空闲=NONE）
 * @return 来源
 */
uint8_t app_spray_owner(void);

/**
 * @brief  当前轮计划槽位（owner==PLAN 时有效）
 * @return 槽位 0~6
 */
uint8_t app_spray_plan_slot(void);

/**
 * @brief  收下轮结束事件（500ms 任务上下文，仲裁收口用）
 * @param  owner 输出：结束轮的来源（AppSprayOwner_t）
 * @param  slot  输出：结束轮的槽位（owner==PLAN 时有效）
 * @return 1=有事件（已收下），0=无
 */
uint8_t app_spray_pop_done(uint8_t *owner, uint8_t *slot);

/**
 * @brief  查询模块是否已初始化
 * @return APP_SPRAY_OK=已初始化，APP_SPRAY_ERR_NOT_INIT=未初始化
 */
AppSpray_Ret_t app_spray_get_status(void);

#endif /* __APP_SPRAY_H__ */