/******************************************************************************
 * @file    ota_ab.h
 * @brief   APP 侧 OTA 下载接口（写入备份区；切换由 Bootloader 完成）
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.18
 * @version V1.0.0
 * @history
 * - V1.0.0, 2026.08.18, cyWu, 补充接口注释
 ******************************************************************************/

#ifndef __OTA_AB_H
#define __OTA_AB_H

#include <stdint.h>
#include <stdbool.h>
#include "ota_config.h"

/*============================================================================*/
/* 说明                                                                        */
/*============================================================================*/
/*
 * 布局与状态机由 Shared/ota_config.h 唯一配置：
 *   OTA_BAK_ADDR_BASE / OTA_SLOT_MAX_SIZE / ota_param_t / OTA_STATE_*
 *
 * 目标区固定 = OTA_BAK_ADDR_BASE：
 *   单备份 = BAK 下载缓冲；双备份 = B 备份区。APP 不必判断「当前跑的是 A 还是 B」。
 *
 * 状态区读写在 flash.h：ota_param_load / ota_param_store。
 */

/*============================================================================*/
/* 下载流程（协议 0x30 / 0x32 / 0x36）                                         */
/*============================================================================*/

/**
 * @brief  0x30 接受升级后调用：擦备份区，准备收包
 * @param  total_len  固件总字节数（fwLength）
 * @param  fw_crc32   固件 CRC32（fwCrc32）
 * @return 0 成功，-1 长度非法
 */
int ota_start(uint32_t total_len, uint32_t fw_crc32);

/**
 * @brief  0x32 每包调用：写入备份区（内部 256B 页缓冲）
 * @param  data  本包数据
 * @param  len   本包长度
 * @return 0 成功，负值失败
 */
int ota_receive_chunk(const uint8_t *data, uint32_t len);

/**
 * @brief  是否已收满 fwLength（不依赖分片序号从 0 还是 1 起）
 */
bool ota_is_download_complete(void);

/**
 * @brief  收完后调用：核对长度+CRC，通过则写 PENDING
 * @return 0 成功可复位，1 校验失败，-1 未在下载中
 */
int ota_finish(void);

/**
 * @brief  0x36 / 0x38 停止升级：丢弃本次接收，不改运行区
 */
void ota_abort(void);

/*============================================================================*/
/* 新固件确认（仅双备份）                                                      */
/*============================================================================*/

/**
 * @brief  APP 启动自检通过后调用
 * @return true  双备份下刚切到新固件，已确认（主循环可据此回复 OTA 完成）
 *         false 普通启动；单备份恒为 false
 */
bool ota_boot_check_confirm(void);

/**
 * @brief  软件复位（实现在 Protocol/jb_product.c）
 */
void mcuRestart(void);

#endif /* __OTA_AB_H */