# flash_file_mgr 模块说明

> 路径：`BSP/flash_file_mgr/`  
> 作用：提供历史故障记录的掉电持久化能力，采用“EEPROM 管理索引 + 外部 Flash 存储内容”的双存储架构。

## 1. 模块文件

- `fault_flash_impl.h`
  - 历史故障持久化对外接口声明
  - `S_HIS_FAULT_MNG` 管理结构定义
- `fault_flash_impl.c`
  - EEPROM 索引读写实现
  - 外部 Flash 记录读写实现
  - 历史记录计数、按“最新N条”读取实现
- `meter_calculate_flash_impl.c`
  - 充电订单记录持久化实现（EEPROM 管理块 + 外部 Flash 订单正文）
  - 提供订单保存/按索引读取/按位置读取、临时订单 EEPROM 缓存接口
  - 支持双枪临时订单标志管理（用于掉电恢复）
- `unsettled_order_mng.c`
  - 未结算订单列表管理（EEPROM 持久化）
  - 支持未结订单添加、移除、查询、清空与 CRC 校验

## 2. 设计目标

- 将高频变化的小数据（计数、索引）放 EEPROM，降低 Flash 管理复杂度；
- 将体积较大的历史故障记录放 externalflash，便于顺序存储与扩展；
- 提供统一接口给 `fault_cheak`、`meter_calculate`，业务层只关心“保存/读取故障或订单记录”。

## 3. 存储布局

### 3.1 EEPROM（索引区）

- 地址：`EEPROM_ADDR_HISALARM_MNG`
- 数据：`S_HIS_FAULT_MNG`
  - `u16_head`：固定头 `0x5AA5`，用于有效性校验
  - `u16_hisFaultCnt`：历史记录数
  - `u16_currIndex`：当前最新逻辑索引（环形）

### 3.2 externalflash（数据区）

- 基址：`DATAFLASH_FAULT_ADDR`
- 扇区大小：`SPI_SECTOR_SIZE`
- 单条记录格式：
  - `1 byte RECORD_HEADER`
  - `sizeof(HIS_FAULT_DATA_T) bytes 数据体`
  - `1 byte CRC`（`u16_crc_checksum` 低 8 位）

## 4. 核心接口说明

- `v_hisFault_save_record(HIS_FAULT_DATA_T *pt_hisFault_data)`
  - 保存一条历史故障
  - 更新环形索引与计数
  - 写 externalflash 记录后更新 EEPROM 管理信息
- `u8_fault_read_his_by_newest(U16_T newest_pos, HIS_FAULT_DATA_T *pt_hisFault)`
  - 按“最新优先”读取历史记录
  - `newest_pos=0` 表示最新一条
- `u16_fault_get_his_count(void)`
  - 返回历史记录数量（带上限保护）
- `v_fault_clear_his_fault(void)`
  - 清空管理信息（不逐条清除 Flash 区内容）

### 4.1 计量订单相关接口（meter_calculate）

- `v_chg_order_flash_init(void)`
  - 初始化充电订单管理信息（读取 EEPROM 管理块，必要时恢复默认）
- `u32_chg_order_save_record(S_LOG_DATA *order_data)`
  - 保存订单到外部 Flash，并返回单调递增订单索引
- `v_read_chg_order_record(S_LOG_DATA *order_data, U32_T index)`
  - 按订单索引读取订单记录
- `v_save_temp_chg_record_to_eeprom(...)` / `v_read_temp_chg_record_from_eeprom(...)`
  - 充电过程临时订单缓存/恢复（EEPROM）
- `u8_add_unsettled_order(U32_T orderIndex)` / `u8_remove_unsettled_order(U32_T orderIndex)`
  - 未结算订单添加/移除
- `u8_check_order_settled(U32_T orderIndex)`
  - 查询订单是否仍处于未结算列表

## 5. 写入策略

- 采用环形索引写入，达到上限后覆盖最老记录；
- 每个扇区的第 1 条记录写入前先擦除该扇区，避免旧数据干扰；
- 记录读取时校验：
  - 头字节必须是 `RECORD_HEADER`
  - CRC 必须匹配
  - 否则判定为无效记录。

## 6. 依赖关系

- EEPROM 驱动：`BSP/eeprom/fm24cl16.c`
- 外部 Flash 驱动：`BSP/externalflash/flash_external_data.c`
- CRC 工具：`app/publicdata/public_func.c` 的 `u16_crc_checksum`
- 故障数据结构：`app/fault_cheak/faultcheck_task.h`
- 计量订单结构：`app/meter_calculate/meter_calculate_impl.h`（`S_LOG_DATA`）

## 7. 注意事项

- 请保证 `DATAFLASH_FAULT_ADDR` 区域不与其他业务区重叠；
- `HIS_FAULT_MAX_CNT` 与扇区分配需协同评估，避免有效容量不足；
- 计量订单区（`DATAFLASH_HIS_RECORD_ADDR`）与故障区地址需避免重叠；
- 未结算订单列表与订单管理块均依赖 EEPROM，建议控制写频率并保留 CRC 校验；
- 该模块默认在任务上下文调用，若多任务并发写入建议增加互斥保护。

## 8. 相关文档

- [主说明 README](../../README.md)
- [fault_cheak 模块说明](../../app/fault_cheak/fault_cheak模块说明.md)
- [eeprom 模块说明](../eeprom/eeprom模块说明.md)
- [externalflash 模块说明](../externalflash/externalflash模块说明.md)