oneos-backend/yudao-module-energy/IMPLEMENTATION_SUMMARY.md

Energy 模块导入流程优化 - 实现总结

实现完成时间

2026-03-16

核心功能

实现了 Energy 模块的导入流程优化，将原来的 3 步手动流程（上传 → 匹配 → 生成明细）合并为 1 步自动流程。

创建的文件

1. MatchResultVO.java

路径: yudao-module-energy-server/src/main/java/cn/iocoder/yudao/module/energy/service/match/vo/MatchResultVO.java

作用: 单条记录匹配结果值对象

字段:

• vehicleId - 匹配到的车辆ID
• customerId - 匹配到的客户ID
• contractId - 匹配到的合同ID
• matchStatus - 匹配状态（0=完全匹配，1=部分匹配，2=未匹配）
• matchMessage - 匹配说明

2. MatchResultDTO.java

路径: yudao-module-energy-server/src/main/java/cn/iocoder/yudao/module/energy/service/match/dto/MatchResultDTO.java

作用: 批量匹配结果统计对象

字段:

• successCount - 成功数量
• failCount - 失败数量
• successIds - 成功的记录ID列表
• failIds - 失败的记录ID列表

3. HydrogenMatchService.java

路径: yudao-module-energy-server/src/main/java/cn/iocoder/yudao/module/energy/service/match/HydrogenMatchService.java

作用: 加氢记录匹配服务接口

方法:

• batchMatch(List<Long> recordIds) - 批量自动匹配记录
• matchRecord(EnergyHydrogenRecordDO record) - 单条记录匹配

4. HydrogenMatchServiceImpl.java

路径: yudao-module-energy-server/src/main/java/cn/iocoder/yudao/module/energy/service/match/HydrogenMatchServiceImpl.java

作用: 加氢记录匹配服务实现类

核心逻辑:

1. 匹配车辆: 通过车牌号（plateNumber）精确匹配 asset_vehicle_base 表
2. 匹配客户:
   • 如果车辆未匹配，尝试通过客户名称模糊匹配 asset_customer 表
3. 匹配合同:
   • 通过客户ID查询 asset_contract 表
   • 筛选条件：contractStatus=2（进行中）且 endDate > 加氢日期
   • 如果有多个合同，取最新的（按 startDate 降序）
4. 更新记录: 将匹配结果更新到 EnergyHydrogenRecordDO

依赖的 Mapper:

• VehicleBaseMapper (asset 模块)
• CustomerMapper (asset 模块)
• ContractMapper (asset 模块)
• EnergyHydrogenRecordMapper (energy 模块)

修改的文件

5. DetailEventListener.java

路径: yudao-module-energy-server/src/main/java/cn/iocoder/yudao/module/energy/listener/DetailEventListener.java

修改内容: 实现完整的自动匹配和生成明细流程

核心流程:

1. 批量匹配: 调用 hydrogenMatchService.batchMatch() 匹配车辆、客户、合同
2. 生成明细:
   • 只为匹配成功的记录生成明细
   • 从价格配置获取成本价和客户价
   • 计算成本金额和客户金额
   • 设置初始状态（待审核、未扣款、未结算）
3. 自动扣款:
   • 检查站点配置 autoDeduct 字段
   • 如果为 true，生成明细后立即调用 accountService.deduct() 扣款
   • 更新明细的扣款状态

新增依赖:

• HydrogenMatchService
• HydrogenStationService (asset 模块)
• EnergyStationPriceService
• EnergyAccountService

技术要点

1. 跨模块调用

• energy 模块通过 @Resource 直接注入 asset 模块的 Mapper 和 Service
• 同一个应用内，无需 Feign 客户端

2. 事务管理

• 使用 @Transactional 确保匹配、生成明细、扣款在同一事务中
• 使用 @TransactionalEventListener 监听导入事件

3. 错误处理

• 匹配失败的记录不生成明细
• 扣款失败不影响其他记录，使用 try-catch 捕获异常
• 详细的日志记录，便于排查问题

4. 性能优化

• 批量查询而不是循环单条查询
• 使用 MyBatis Plus 的 selectBatchIds() 批量查询
• 批量插入明细（虽然当前实现是循环插入，后续可优化为真正的批量插入）

注意事项

1. 数据库字段映射

• Record 表的 plateNumber 字段对应 Vehicle 表的 plateNo 字段
• 需要确保字段名称一致

2. 匹配规则优化空间

• 当前车辆匹配只取第一辆，后续可优化为提示用户选择
• 客户名称模糊匹配可能不准确，建议增加更多匹配条件

3. 价格配置依赖

• 生成明细依赖价格配置，如果没有配置价格，明细无法生成
• 需要确保每个站点和客户都有有效的价格配置

4. 合同ID获取

• 当前实现中，合同ID通过重新调用 matchRecord() 获取
• 这会导致重复查询，后续可优化为在批量匹配时直接返回合同ID

后续优化建议

1. 批量插入优化: 使用 MyBatis 的 insertBatch 真正实现批量插入
2. 匹配结果缓存: 避免重复查询合同信息
3. 异步处理: 对于大批量导入，可以考虑异步处理匹配和生成明细
4. 匹配规则配置化: 将匹配规则配置到数据库，支持动态调整
5. 匹配失败通知: 对于匹配失败的记录，发送通知给管理员

测试建议

1. 单元测试: 测试匹配服务的各种场景（完全匹配、部分匹配、未匹配）
2. 集成测试: 测试完整的导入流程
3. 性能测试: 测试大批量导入的性能
4. 边界测试: 测试价格配置缺失、合同过期等边界情况