/*
 * OTA 状态管理器
 * 管理OTA更新状态，支持失败回退到上一版本
 * 适用于 WiFi/HTTP OTA、BLE OTA、UART OTA
 */

#ifndef OTA_MANAGER_H
#define OTA_MANAGER_H

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

#ifdef __cplusplus
extern "C" {
#endif

/* OTA 状态 */
typedef enum {
    OTA_STATE_IDLE = 0,           /* 空闲，无OTA进行中 */
    OTA_STATE_IN_PROGRESS,        /* OTA进行中 */
    OTA_STATE_PENDING_VERIFY,     /* OTA完成，等待验证 */
    OTA_STATE_SUCCESS,            /* OTA验证成功 */
    OTA_STATE_FAILED,             /* OTA失败，已回退或需要回退 */
    OTA_STATE_ROLLBACK,           /* 已回退到上一版本 */
} ota_state_t;

/* OTA 类型 */
typedef enum {
    OTA_TYPE_HTTP = 0,            /* WiFi/HTTP OTA */
    OTA_TYPE_BLE,                 /* BLE OTA */
    OTA_TYPE_UART,                /* UART OTA */
} ota_type_t;

/* OTA 会话信息（存储于NVS） */
typedef struct {
    ota_state_t state;            /* 当前状态 */
    ota_type_t type;              /* OTA类型 */
    char target_version[32];        /* 目标版本号 */
    char source_version[32];      /* 升级前版本号 */
    char source_partition[16];    /* 升级前运行分区标签，如 ota_0 */
    uint32_t timestamp;           /* OTA开始时间戳 */
    uint8_t boot_count;         /* 新固件启动计数 */
    uint8_t max_boot_attempts;   /* 最大尝试次数 */
} ota_session_info_t;

/**
 * @brief 初始化OTA管理器
 * 在系统启动时调用，检查OTA状态并决定是否回退
 * @return ESP_OK 正常启动，ESP_FAIL 已触发回退
 */
esp_err_t ota_manager_init(void);

/**
 * @brief 开始OTA会话
 * @param type OTA类型
 * @param target_version 目标版本号
 * @return ESP_OK 成功，其他错误码
 */
esp_err_t ota_manager_begin_session(ota_type_t type, const char *target_version);

/**
 * @brief 结束OTA会话（标记为等待验证）
 * 新固件写入完成后调用，标记状态为PENDING_VERIFY
 * @return ESP_OK 成功
 */
esp_err_t ota_manager_end_session(void);

/**
 * @brief 验证OTA成功
 * 应用层确认固件运行正常后调用
 * @return ESP_OK 成功
 */
esp_err_t ota_manager_mark_success(void);

/**
 * @brief 标记OTA失败并触发回退
 * 在确认新固件有问题时调用，立即回退到上一版本
 * @param reason 失败原因
 * @return ESP_OK 已触发回退，设备将重启
 */
esp_err_t ota_manager_mark_failed_and_rollback(const char *reason);

/**
 * @brief 获取当前OTA状态
 * @return 当前OTA状态
 */
ota_state_t ota_manager_get_state(void);

/**
 * @brief 获取OTA会话信息
 * @param info 输出结构体
 * @return ESP_OK 成功，ESP_ERR_NOT_FOUND 无会话信息
 */
esp_err_t ota_manager_get_session_info(ota_session_info_t *info);

/**
 * @brief 检查是否需要回退
 * 在应用层检测到异常时调用，增加启动计数并决定是否回退
 * @return true 需要回退，false 正常
 */
bool ota_manager_should_rollback(void);

/**
 * @brief 执行回退到上一版本
 * 切换到上一个OTA分区并重启
 * @return ESP_OK 已设置回退，设备将重启
 */
esp_err_t ota_manager_rollback(void);

/**
 * @brief 获取当前运行的OTA分区标签
 * @return "ota_0" 或 "ota_1"，失败返回NULL
 */
const char* ota_manager_get_current_partition_label(void);

/**
 * @brief 获取当前运行的固件版本号（从NVS读取最后一次成功版本）
 * @param buf 输出缓冲区
 * @param len 缓冲区长度
 * @return ESP_OK 成功
 */
esp_err_t ota_manager_get_stored_version(char *buf, size_t len);

/**
 * @brief 更新存储的版本号（OTA成功后调用）
 * @param version 版本号字符串
 * @return ESP_OK 成功
 */
esp_err_t ota_manager_update_stored_version(const char *version);

#ifdef __cplusplus
}
#endif

#endif /* OTA_MANAGER_H */
