/**
 * @file meter_calculate_flash_impl.h
 * @brief 充电订单 / 临时订单 EEPROM+SPI Flash 存储接口声明
 *
 * 与 `meter_calculate_flash_impl.c` 配套：管理元数据在 EEPROM，订单记录在 `DATAFLASH_HIS_RECORD_ADDR`
 * 区域；并提供双枪临时订单 EEPROM 备份与恢复接口。具体地址与记录格式见 `public_define.h`、`flash_external_data.h`。
 */

#ifndef METER_CALCULATE_FLASH_IMPL_H
#define METER_CALCULATE_FLASH_IMPL_H

#ifdef __cplusplus /*C++编译环境下兼容C语言*/
extern "C" {
#endif

/*------  Exported includes(头文件) ----------------------*/
#include "main.h"
#include "meter_calculate/meter_calculate_impl.h" /* S_LOG_DATA 等 */
#include "eeprom/fm24cl16.h"
#include "externalflash/flash_external_data.h"

/*------  Exported macro(宏定义) -------------------------*/

// 调试宏定义
// #define DEBUG_FLASH_READ   0  // 启用Flash读取调试
// #define DEBUG_FLASH_WRITE  0  // 启用Flash写入调试

/* 充电订单记录容量相关宏（CHG_ORDER_* / TEMP_CHG_RECORD_SIZE）
 * 统一由 `BSP/spi_Flash/flash_external_data.h` 提供，避免多处重复定义。
 */

// 断电续传标志位定义
typedef enum
{
    TEMP_CHG_FLAG_UNSETTLED = 0x00,     // 未结算状态（充电中）
    TEMP_CHG_FLAG_SETTLED   = 0x01,     // 已结算状态（充电完成）
    TEMP_CHG_FLAG_INVALID   = 0xFF      // 无效状态
} E_TEMP_CHG_FLAG;

/*------  Exported struct(结构体定义) --------------------*/

/**
 * @brief 充电订单管理信息结构体
 * 
 * 存储在EEPROM中，地址：EEPROM_ADDR_CHGRCD_MNG (0x0000)
 * 用于管理充电订单的索引和计数信息
 */
typedef struct
{
    U16_T   u16_head;           // 头标志 (0x5AA5)
    U16_T   u16_chgOrderCnt;    // 充电订单总条数
    U16_T   u16_currIndex;      // 当前索引（循环缓冲区中的位置）
    U32_T   u32_lastIndex;      // 最后分配的索引值（保证索引唯一性递增）
} S_CHG_ORDER_MNG;

/*------  Exported variables(变量定义) -------------------*/

// 充电订单管理信息全局变量
extern S_CHG_ORDER_MNG s_chgOrderMng;

/*------  Exported function prototypes （函数声明） -------*/

/**
 * @brief 初始化充电订单Flash存储模块
 * 
 * 从EEPROM读取管理信息，如果不存在则初始化默认值
 */
void v_chg_order_flash_init(void);

/**
 * @brief 写入充电订单管理信息到EEPROM
 * 
 * @param chgOrderMng 充电订单管理信息指针
 */
void v_write_eeprom_chgOrderMng(S_CHG_ORDER_MNG *chgOrderMng);

/**
 * @brief 从EEPROM读取充电订单管理信息
 * 
 * @param chgOrderMng 充电订单管理信息指针（用于存储读取到的数据）
 */
void v_read_eeprom_chgOrderMng(S_CHG_ORDER_MNG *chgOrderMng);

/**
 * @brief 清除所有充电订单记录
 * 
 * 重置管理信息并清除Flash中的记录
 */
void v_chg_order_clear_all(void);

/**
 * @brief 保存充电订单记录到Flash
 *
 * 自动分配索引并保存记录，更新管理信息
 * 注意：此函数会修改order_data中的u32_index字段
 *
 * @param order_data 充电订单数据指针（会被修改）
 * @return U32_T 分配的索引值（唯一标识）
 */
U32_T u32_chg_order_save_record(S_LOG_DATA *order_data);

/**
 * @brief 从Flash读取指定索引的充电订单记录
 * 
 * @param order_data 充电订单数据指针（用于存储读取到的数据）
 * @param index 要读取的记录索引
 * @return U8_T 读取结果：0-成功，1-失败
 */
U8_T v_read_chg_order_record(S_LOG_DATA *order_data, U32_T index);

/**
 * @brief 获取充电订单记录总数
 * 
 * @return U16_T 充电订单记录总数
 */
U16_T v_get_chg_order_count(void);

/**
 * @brief 获取当前索引位置
 * 
 * @return U16_T 当前索引位置
 */
U16_T v_get_chg_order_curr_index(void);

/**
 * @brief 获取最后分配的索引值
 * 
 * @return U32_T 最后分配的索引值（唯一递增）
 */
U32_T v_get_chg_order_last_index(void);

/**
 * @brief 读取指定位置的充电订单记录（基于循环缓冲区位置）
 *
 * @param order_data 充电订单数据指针（用于存储读取到的数据）
 * @param position 循环缓冲区中的位置（0-based）
 * @return U8_T 读取结果：0-成功，1-失败
 */
U8_T v_read_chg_order_by_position(S_LOG_DATA *order_data, U16_T position);

/**
 * @brief 保存临时充电记录到EEPROM（用于断电续传）
 *
 * 在充电过程中周期更新实时充电信息，第一个字节为断电续传标志位
 *
 * @param gunNo 枪号（0-A枪，1-B枪）
 * @param order_data 充电订单数据指针
 * @param flag 断电续传标志位（0-未结算，1-已结算）
 * @return U8_T 保存结果：0-成功，1-失败
 */
U8_T v_save_temp_chg_record_to_eeprom(U8_T gunNo, const S_LOG_DATA *order_data, E_TEMP_CHG_FLAG flag);

/**
 * @brief 从EEPROM读取临时充电记录（用于断电续传恢复）
 *
 * @param gunNo 枪号（0-A枪，1-B枪）
 * @param order_data 充电订单数据指针（用于存储读取到的数据）
 * @param flag 读取到的断电续传标志位指针（可选）
 * @return U8_T 读取结果：0-成功，1-失败
 */
U8_T v_read_temp_chg_record_from_eeprom(U8_T gunNo, S_LOG_DATA *order_data, E_TEMP_CHG_FLAG *flag);

/**
 * @brief 清除EEPROM中的临时充电记录
 *
 * 将断电续传标志位设置为无效状态
 *
 * @param gunNo 枪号（0-A枪，1-B枪）
 * @return U8_T 清除结果：0-成功，1-失败
 */
U8_T v_clear_temp_chg_record_in_eeprom(U8_T gunNo);

/**
 * @brief 检查EEPROM中是否有有效的临时充电记录
 *
 * @param gunNo 枪号（0-A枪，1-B枪）
 * @return U8_T 检查结果：0-无有效记录，1-有有效记录
 */
U8_T v_check_temp_chg_record_valid(U8_T gunNo);

#ifdef __cplusplus
}
#endif

#endif  /* METER_CALCULATE_FLASH_IMPL_H */