CCU621M/BSP/flash_file_mgr/flash_file_mgr_说明.md

flash_file_mgr 模块说明

本文档用于说明 BSP/flash_file_mgr 目录下各文件职责、数据落盘位置与调用关系，便于定位问题和后续扩展。

目录内文件与功能

1) fault_flash_impl.h / fault_flash_impl.c

• 功能：历史故障记录持久化（EEPROM 管理信息 + SPI Flash 记录体）。
• 管理信息：S_HIS_FAULT_MNG，存放在 EEPROM EEPROM_ADDR_HISALARM_MNG。
• 记录数据：从 DATAFLASH_FAULT_ADDR 开始，单条记录格式：
  • RECORD_HEADER(1B) + HIS_FAULT_DATA_T + CRC低8位(1B)。
• 核心接口：
  • v_hisFault_save_record()：保存一条故障记录。
  • v_read_hisFault_record()：按逻辑索引读取记录。
  • v_fault_clear_his_fault()：清空故障管理信息。

2) card_flash_impl.h / card_flash_impl.c

• 功能：卡号白名单持久化（替代 CSV/FAT 文件实现），由 fatfs_card.h 对外暴露业务接口。
• 管理信息：S_CARD_MNG，存放在 EEPROM EEPROM_ADDR_CARD_MNG。
• 记录数据：从 DATAFLASH_CARD_ADDR 开始，单槽格式：
  • RECORD_HEADER(1B) + CARD_FLASH_BODY_T + CRC低8位(1B)。
• 关键特性：
  • 按卡号查重/查找。
  • 写入采用“读扇区 -> 合并 -> 擦除 -> 整扇区回写”策略，避免 NOR Flash 原地改写问题。
• 对外接口（由 fatfs_card.h 声明）：
  • card_init/card_add/card_update/card_delete/card_find/...。

3) meter_calculate_flash_impl.h / meter_calculate_flash_impl.c

• 功能：充电订单历史记录 + 临时订单（断电续传）持久化。
• 管理信息：S_CHG_ORDER_MNG，存放在 EEPROM EEPROM_ADDR_CHGRCD_MNG。
• 历史订单数据：从 DATAFLASH_HIS_RECORD_ADDR 开始，记录体为 S_LOG_DATA，单条格式：
  • RECORD_HEADER(1B) + S_LOG_DATA + CRC低8位(1B)。
• 临时订单数据：A/B 枪分别存放在 EEPROM EEPROM_ADDR_A_LOG_DATA / EEPROM_ADDR_B_LOG_DATA。
• 核心接口：
  • u32_chg_order_save_record()：保存并分配唯一索引。
  • v_read_chg_order_record()：按索引读取。
  • v_temp_chg_data_save/v_temp_chg_data_read/...：临时订单保存/恢复。

4) unsettled_order_mng.h / unsettled_order_mng.c

• 功能：未结算订单索引列表管理（仅存索引，不存订单正文）。
• 存储位置：EEPROM EEPROM_ADDR_UNSETTLED_MNG。
• 数据结构：S_UNSETTLED_ORDER_MNG，包含头标志、数量、CRC 和 3 字节压缩索引数组。
• 核心接口：
  • u8_add_unsettled_order()：新增未结订单索引。
  • u8_remove_unsettled_order()：删除已结索引。
  • u8_check_order_settled()：检查是否仍未结。

5) ocpp_mv_offline_flash_impl.h / ocpp_mv_offline_flash_impl.c

• 功能：平台离线时周期缓存 MeterValues；Flash 为 整池定长帧数组（仿 fault_flash_impl：帧头+32B 负载+CRC），全局序号与物理槽 seq % POOL_MAX 一一对应；FRAM 存 u32_next_seq 与 流水号→(seq_start,count) 映射表（最多 6 笔并发），上送时按序号直接读 Flash。
• 容量：OCPP_MV_OFFLINE_POOL_MAX = 每扇区 floor(4096/帧长) × DATAFLASH_OCPP_MV_OFFLINE_SECTOR_CNT（扇区尾截断不用）。
• 滚动：u32_next_seq 递增写满池后自然覆盖最旧物理槽；映射行上送后应 u8_ocpp_mv_offline_map_remove。
• 核心接口：v_ocpp_mv_offline_init、u32_ocpp_mv_offline_pool_max、u8_ocpp_mv_offline_mv_save、u8_ocpp_mv_offline_mv_read_by_seq、u8_ocpp_mv_offline_map_get、u8_ocpp_mv_offline_map_remove、v_ocpp_mv_offline_flash_erase_pool、u8_ocpp_mv_offline_fram_read / u8_ocpp_mv_offline_fram_write。
• RAM 镜像：s_ocppMvOfflineFramMng；上电 v_ocpp_mv_offline_init()（兼容宏 v_ocpp_mv_offline_flash_init()）。

地址与容量宏来源

flash_file_mgr 模块统一依赖 BSP/spi_Flash/flash_external_data.h 中定义的地址与容量宏（如 DATAFLASH_FAULT_ADDR、DATAFLASH_CARD_ADDR、DATAFLASH_HIS_RECORD_ADDR、DATAFLASH_OCPP_MV_OFFLINE_ADDR、CHG_ORDER_* 等）。

建议后续若调整分区地址，仅修改 flash_external_data.h，并回归验证：

• 故障记录读写；
• 卡号增删查；
• 订单保存与按索引回读；
• 未结算订单索引增删。

模块关系（简版）

• faultcheck_task -> fault_flash_impl：故障历史。
• fatfs_init / bs_public_impl -> fatfs_card.h -> card_flash_impl：本地卡鉴权与白名单。
• meter_calculate_impl -> meter_calculate_flash_impl：订单持久化。
• meter_calculate_flash_impl + bs_public_impl -> unsettled_order_mng：未结算订单索引维护。
• （规划）BS_ocpp_ctrl / OCPP 离线路径 -> ocpp_mv_offline_flash_impl：离线 MeterValues 采样落盘与联网后补发。