# meter_calculate 模块说明

> 路径：`app/meter_calculate/`  
> 返回主说明：[README](../../README.md)

## 1. 模块职责

- 提供电表采集与计量计费两类任务能力：`meter_coll_task` 负责电表数据采集，`meterfee_task` 负责订单计量与费用累计；
- 维护充电订单生命周期数据（开始、充电中、结束）并对外提供订单读写接口；
- 提供费率查询、周期计量、下周期金额预估能力；
- 对接故障系统，处理计量跳变、费率时间异常等故障置位/恢复；
- 对接 Flash/EEPROM 订单存储与未结算订单管理，支持掉电续传和平台结算确认。

## 2. 关键文件

- `meter_coll_task.c/.h`：电表通信采集任务与底层数据更新；
- `calculate_task.c/.h`：计量计费任务（`v_meterfee_task`）及计费控制结构；
- `meter_calculate_impl.c/.h`：计量对外接口、订单数据接口、故障与结算接口；
- `BSP/flash_file_mgr/meter_calculate_flash_impl.c/.h`：订单正式记录与临时订单 EEPROM/Flash 持久化；
- `BSP/flash_file_mgr/unsettled_order_mng.c/.h`：未结算订单索引管理。

## 3. 功能说明

### 3.1 任务与调度模型

- `v_meterfee_task()` 在系统任务表中按周期运行，流程为：
  - 初始化计量控制对象 `s_metering_ctrl`；
  - 初始化订单存储模块 `v_chg_order_flash_init()` 与未结算模块 `v_unsettled_order_init()`；
  - 循环执行 `v_meterlog_action_cheak()`（计费启停状态机）和 `v_meterlog_ctrl()`（周期计费）；
  - 周期喂狗、日志输出与睡眠调度。
- 计量主循环按 5 秒节拍进行电量与费用更新，充电中每 60 秒刷新一次 EEPROM 临时订单。

### 3.2 计量与计费流程

- 通过 `u64_meterlog_get_meter_data()` 获取电表电量（0.0001kWh 精度）；
- 首次计量记录起始电量，后续计算循环差分电量并累计到：
  - 总电量 `u32_used_energy`
  - 分时段电量 `u32_part_energy[period]`
  - 电费 `u32_used_money`
  - 服务费 `u32_used_service`
- `v_meterlog_real_fee_updata()` 根据当前时间计算 15 分钟时段索引（0~95），并更新充电/放电费率缓存；
- `u32_meterlog_next_cycle_money()` 提供下一周期金额预测（基于当前电压电流和费率）。

### 3.3 订单生命周期管理

- 启动充电：`v_meterlog_set_start_char_log_info()` 清零并写入启动订单关键信息（交易号、用户、VIN、起始电量、起始时间）；
- 充电中：`v_meterlog_log_updata()` 持续更新结束时间、结束电量、SOC、已充时长；
- 停止充电：`v_meterlog_set_stop_char_log_info()` 写入停止原因并更新末态数据；
- 对外接口：
  - `v_meterlog_put_char_log_data()` 读取订单完整结构；
  - `v_meterlog_set_char_log_info()` 按字段更新订单；
  - `u32_meterlog_put_data()` 按枚举提取关键订单字段。

### 3.4 存储与结算接口

- `v_meterlog_flash_save_log(u8_flag, u8_gunNo)`：
  - `u8_flag=0`：充电中更新 EEPROM 临时订单（未结算标志）；
  - `u8_flag=1`：结束后保存正式订单到 Flash，记录 `u32_index`，加入未结算列表，并清除临时订单。
- `u8_platform_settlement_confirm(orderIndex)`：平台确认结算后，从未结算列表移除订单；
- `u8_check_order_settlement_status(orderIndex)`：查询订单是否已结算（0 已结算，1 未结算）。

### 3.5 故障处理

- 计量相关故障由 `v_meterlog_set_fault()` 统一上报：
  - `E_FAULT_17007`：电表跳变异常；
  - `E_FAULT_17008`：电量长时间未更新；
  - `E_FAULT_17009`：费率/时间异常。
- 计费停止后会执行对应恢复逻辑，避免故障状态长期残留。

## 4. 维护建议

- 调整计量周期、临时订单保存周期（当前 60 秒）时，需同步评估 EEPROM 擦写寿命与掉电恢复精度；
- 修改费率来源时，优先保持 `u32_meterlog_get_sys_data()` 作为统一入口，避免业务层直连全局配置；
- 若后续接入平台上送流程，可在 `v_set_plat_log_flag()` 增加上送触发逻辑并和未结算列表闭环验证；
- 建议联动验证三类场景：正常停机、异常掉电恢复、平台延迟结算。

## 5. 关联文档

- `BSP/flash_file_mgr/flash_file_mgr模块说明.md`
- 主索引：[README](../../README.md)