/**
 * @file business_protocol.h
 * @brief STM8 业务帧协议接口。
 *
 * 业务帧格式：SRC_H SRC_L | CMD | LEN | DATA | CRC16_H CRC16_L。
 * SRC 为发送方的 Mesh 短地址；CRC 使用 CRC-16/MODBUS，计算范围为
 * SRC、CMD、LEN 和 DATA，线上高字节在前。
 */
#ifndef BUSINESS_PROTOCOL_H
#define BUSINESS_PROTOCOL_H

#include <stdint.h>

/** 业务帧最大 DATA 长度，需为 JDY-28M 外层 20 字节限制预留空间。 */
#define BUSINESS_MAX_DATA_LENGTH  4u

/** 发送方短地址字段长度。 */
#define BUSINESS_SOURCE_ADDRESS_LENGTH 2u

/** 业务命令：继电器控制。 */
#define CMD_RELAY_CONTROL 0x01u

/** 业务命令：查询继电器状态。 */
#define CMD_RELAY_QUERY 0x02u

/** 业务命令：查询实际电流。 */
#define CMD_CURRENT_QUERY 0x03u

/** 业务命令：故障/恢复上报。 */
#define CMD_FAULT_REPORT 0x04u

/** 业务命令：短地址查询。 */
#define CMD_ADDRESS_QUERY 0x05u

/** 业务命令：电流阈值配置。 */
#define CMD_THRESHOLD_CONFIG 0x06u

/** 设备上线广播通知；DATA长度为0，不需要应答。 */
#define CMD_DEVICE_ONLINE 0x07u

/** 主机广播可用固件版本和长度；DATA长度为4，不直接启动OTA。 */
#define CMD_FIRMWARE_ANNOUNCE 0x10u

/** 设备发现自己需要升级后的响应命令；DATA返回当前版本和目标版本。 */
#define CMD_FIRMWARE_ANNOUNCE_RESPONSE \
    (CMD_FIRMWARE_ANNOUNCE | CMD_RESPONSE_FLAG)

/** 查询当前主程序固件版本。 */
#define CMD_FIRMWARE_VERSION_QUERY 0x0Eu

/** 查询固件版本应答。 */
#define CMD_FIRMWARE_VERSION_RESPONSE \
    (CMD_FIRMWARE_VERSION_QUERY | CMD_RESPONSE_FLAG)

/** Bootloader升级结果主动上报。 */
#define CMD_OTA_RESULT_REPORT 0x0Du

/** 应答命令基值，具体应答为请求命令加 0x80。 */
#define CMD_RESPONSE_FLAG 0x80u

/** OTA升级结果上报应答命令。 */
#define CMD_OTA_RESULT_ACK (CMD_OTA_RESULT_REPORT | CMD_RESPONSE_FLAG)

/** 通用错误应答命令。 */
#define CMD_ERROR_RESPONSE 0xE0u

/** CRC 校验失败时静默丢弃，不生成业务错误应答。 */
#define BUSINESS_PARSE_CRC_ERROR 0x01u

/** 业务帧解析结果：没有完整帧。 */
#define BUSINESS_PARSE_INCOMPLETE 0x00u

/** 业务帧解析结果：收到并通过 CRC 校验。 */
#define BUSINESS_PARSE_FRAME_READY 0x01u

/** 业务帧解析器初始化。 */
void BusinessProtocol_Init(void);

/** 处理 UART 输入和待发送业务帧。 */
void BusinessProtocol_Task(void);

/** 强制将业务应答放入随机延时队列，供异步广播应答使用。 */
void BusinessProtocol_QueueDelayedResponse(uint16_t address,
                                           uint8_t command,
                                           const uint8_t *data,
                                           uint8_t length);

/**
 * 向解析器输入一个字节。
 *
 * 该接口只负责解析内层业务帧，不执行继电器动作，也不负责 JDY-28M
 * 外层 Mesh 封装。外层模块应在确认 `F1 DD 09 00 0A ... 0D 0A` 后，
 * 将其中的业务数据逐字节送入本接口。
 *
 * @param value 输入字节。
 * @return 1 表示刚刚形成一帧合法业务帧，0 表示尚未形成完整帧。
 */
uint8_t BusinessProtocol_InputByte(uint8_t value);

/** 读取最近一帧合法业务帧的命令字。 */
uint8_t BusinessProtocol_GetCommand(void);

/** 读取最近一帧合法业务帧的数据长度。 */
uint8_t BusinessProtocol_GetDataLength(void);

/** 读取最近一帧合法业务帧携带的发送方 Mesh 短地址。 */
uint16_t BusinessProtocol_GetSourceAddress(void);

/** 执行最近一帧已经通过校验的业务命令，并向源地址返回应答。 */
void BusinessProtocol_HandleFrame(void);

/** CRC-16/MODBUS 计算函数，输入范围包含发送方地址字段。 */
uint16_t BusinessProtocol_Crc16Modbus(const uint8_t *data, uint16_t length);

#endif