b40f521c03
后端优化： - 创建加氢站表，删除 energy_station_config - 简化事件驱动（7个→3个） - 合并导入流程（自动匹配+生成明细） - 优化审核流程（审核+扣款合并+批量审核） - 修复跨模块依赖（创建 Asset API 接口层） 前端优化： - 简化导入交互（3步→1步） - 批量审核功能 - 快速生成账单（本月/上月） - 批量价格配置（前端完成） 技术改进： - 微服务架构规范（API 优先） - 事务一致性保证 - 用户体验优化
141 lines
5.2 KiB
Markdown
141 lines
5.2 KiB
Markdown
# 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. **边界测试**: 测试价格配置缺失、合同过期等边界情况
|