mileage-bonus/.claude_plans/quirky-gathering-flame.md

简化账单架构 — 删除3张bill表

Context

当前能源模块有3层架构：原始记录 → energy_bill_detail(统一明细) → 3张bill表(按费用类型拆分的账单)。 实际业务中扣费发生在审核通过创建 bill_detail 时（立即扣），不需要月度账单汇总。 ETC 和电费的 bill 服务是未实现的 stub（throw UnsupportedOperationException），氢费 bill 服务虽然实现了但当前阶段不需要账单汇总、站方确认、提交财务等功能。

简化为：原始记录 → 审核 → energy_bill_detail（终态表，直接扣费）。billing 页面直接查 bill_detail 按 feeType 过滤。

改动范围

删除文件（~30个）

Controller (3):

• modules/energy/controller/EnergyBillController.java
• modules/etc/controller/EtcBillController.java
• modules/electricity/controller/ElectricityBillController.java

Service (4-6):

• modules/energy/service/IEnergyBillService.java + impl/EnergyBillServiceImpl.java
• modules/etc/service/IEtcBillService.java + impl/EtcBillServiceImpl.java（如存在）
• modules/electricity/service/IElectricityBillService.java + impl/ElectricityBillServiceImpl.java（如存在）
• modules/energy/service/IBillAdjustmentService.java + impl/BillAdjustmentServiceImpl.java（如存在）

Mapper (3-4):

• modules/energy/mapper/EnergyHydrogenBillMapper.java
• modules/energy/mapper/EnergyBillAdjustmentMapper.java（如存在）
• modules/etc/mapper/EnergyEtcBillMapper.java
• modules/electricity/mapper/EnergyElectricityBillMapper.java

Entity PO (4):

• modules/energy/entity/bill/po/EnergyHydrogenBill.java
• modules/energy/entity/bill/po/EnergyBillAdjustment.java（如存在）
• modules/etc/entity/bill/po/EnergyEtcBill.java
• modules/electricity/entity/bill/po/EnergyElectricityBill.java

Entity VO/Query/Req（整个 bill 子包）:

• modules/energy/entity/bill/vo/ — 所有 VO（EnergyBillVO, EnergyBillDetailVO, BillPreviewVO, BillStatisticsVO, BillAdjustmentVO）
• modules/energy/entity/bill/query/BillQuery.java
• modules/energy/entity/bill/req/ — 所有 Req（BillGenerateReq, BillReviewReq, AddAdjustmentReq）
• modules/etc/entity/bill/vo/EtcBillVO.java
• modules/etc/entity/bill/req/EtcBillGenerateReq.java
• modules/electricity/entity/bill/vo/ElectricityBillVO.java
• modules/electricity/entity/bill/req/ElectricityBillGenerateReq.java

State Machine（如存在）:

• modules/energy/statemachine/BillStatusMachine.java

Finance 相关（仅删 bill 部分）:

• modules/energy/service/finance/model/BillSubmitRequest.java
• FinanceService 接口中的 submitBill 方法需移除

修改文件

文件	改动
entity/billdetail/po/EnergyBillDetail.java	删除 billId 字段
entity/billdetail/vo/EnergyBillDetailVO.java	删除 billId 字段
service/impl/EnergyBillDetailServiceImpl.java	toVO 中删除 .billId()
entity/detail/po/EnergyHydrogenDetail.java	删除 billId 字段
entity/detail/vo/EnergyDetailVO.java	删除 billId 字段
entity/account/po/EnergyAccountTransaction.java	删除 relatedBillId 字段
entity/account/vo/TransactionVO.java	删除 relatedBillId 字段
service/impl/EnergyAccountTransactionServiceImpl.java	toVO 中删除 .relatedBillId()
service/finance/FinanceService.java	删除 submitBill 方法签名
service/finance/LocalFinanceServiceImpl.java	删除 submitBill 实现

SQL 迁移

新建 db/energy/V3__drop_bill_rollup_tables.sql:

DROP TABLE IF EXISTS energy_bill_adjustment;
DROP TABLE IF EXISTS energy_hydrogen_bill;
DROP TABLE IF EXISTS energy_etc_bill;
DROP TABLE IF EXISTS energy_electricity_bill;

ALTER TABLE energy_bill_detail DROP COLUMN IF EXISTS bill_id;
ALTER TABLE energy_hydrogen_detail DROP COLUMN IF EXISTS bill_id;
ALTER TABLE etc_toll_record DROP COLUMN IF EXISTS bill_id;
ALTER TABLE energy_account_transaction DROP COLUMN IF EXISTS related_bill_id;

执行顺序

1. 删除所有 bill 相关 Java 文件
2. 修改 8 个文件（删除 billId/relatedBillId 字段引用）
3. 编译验证（确保无断裂引用）
4. 提交并推送
5. 部署后执行 SQL 迁移

不动的部分

• energy_bill_detail 表 + Controller + Service（核心，保留）
• 所有原始记录表和相关代码（station/etc/electricity 模块的 record 部分）
• 事件系统和监听器
• 审核流程（RawRecordReviewServiceImpl）
• 扣款服务（DeductionService）
• 前端（用户自行调整 API 路径）

验证

1. 编译通过：mvn compile 无错误
2. 直接访问 GET http://localhost:8702/energy/bill-detail/page?feeType=1 返回数据
3. 原有的 /energy/bill/page、/etc/bill/page、/electricity/bill/page 返回 404（已删除）
4. 审核+扣费流程不受影响