573f8397a6
输入文件：
- 租赁任务考核_2026年{1,2,3}月.xlsx (考核源数据)
- {1,2}月.xlsx (客户盈亏表)
- 车辆里程考核与奖金发放规则（V.1.2）.docx
输出文件：
- 里程任务考核_{1,2,3}月核算.xlsx (月度核算结果)
- 里程任务考核_Q1汇总.xlsx (含车辆台账)
- 3月客户盈亏表(待填写).xlsx (模版)
.claude_memory: 项目记忆（规则/偏好/架构/测试车辆）
.claude_plans: 历次计划文件
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
193 lines
7.6 KiB
Markdown
193 lines
7.6 KiB
Markdown
# 加氢站对账单功能
|
||
|
||
## Context
|
||
|
||
加氢记录审核通过后，需要定期和加氢站对账结算。当前只有一个 `settlement_status` 字段（0未对账/1已出账/2已付款），但没有对账单实体。需要新建对账单模块，支持：生成对账单 → 查看/下载 → 确认付款 → 状态同步到氢费记录。
|
||
|
||
## 核心概念
|
||
|
||
```
|
||
一张对账单 = 一个加氢站 + 一个时间段内的所有已审核订单
|
||
```
|
||
|
||
- **生成条件**：时间范围内该站所有订单必须已审核（reviewStatus=1）
|
||
- **付款含义**：我们向加氢站付款（成本结算）
|
||
- **状态流转**：生成(已出账) → 付款(已付款) / 删除(回退未对账)
|
||
- **关联订单**：对账单关联的订单 snapshot 快照，生成后订单 settlementStatus 同步为已出账
|
||
- **下载格式**：Excel + PDF
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### 新建表：`hydrogen_settlement_bill`（加氢站对账单）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT PK | 主键 |
|
||
| bill_code | VARCHAR(32) UNIQUE | 对账单编号（SB+日期+序号） |
|
||
| station_id | BIGINT | 加氢站ID |
|
||
| station_name | VARCHAR(128) | 加氢站名称（冗余） |
|
||
| period_start | DATE | 对账起始日期 |
|
||
| period_end | DATE | 对账截止日期 |
|
||
| order_count | INT | 订单笔数 |
|
||
| total_gas_weight | DECIMAL(12,4) | 总加注量(kg) |
|
||
| total_amount | DECIMAL(12,2) | 总金额(元) — 成本金额 |
|
||
| status | TINYINT | 0-已出账 1-已付款 |
|
||
| paid_time | DATETIME | 付款时间 |
|
||
| paid_by | BIGINT | 付款确认人 |
|
||
| remark | VARCHAR(500) | 备注 |
|
||
| create_by/create_time/update_by/update_time/del_flag | | 审计字段 |
|
||
|
||
### 新建表：`hydrogen_settlement_bill_item`（对账单明细快照）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT PK | 主键 |
|
||
| bill_id | BIGINT | 关联对账单ID |
|
||
| order_id | BIGINT | 关联氢费记录ID |
|
||
| order_number | VARCHAR(64) | 订单编号 |
|
||
| plate_number | VARCHAR(16) | 车牌号 |
|
||
| fill_end_time | DATETIME | 加注时间 |
|
||
| gas_weight | DECIMAL(10,4) | 加注重量(kg) |
|
||
| gas_price | DECIMAL(10,4) | 气价(元/kg) |
|
||
| total_amount | DECIMAL(10,2) | 金额(元) |
|
||
| create_time | DATETIME | 创建时间 |
|
||
|
||
> 注：明细快照不含客户/项目信息——加氢站对账只关心站方数据（车牌、时间、重量、气价、金额）。
|
||
|
||
---
|
||
|
||
## API 设计
|
||
|
||
### 后端接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/station/settlement-bill/generate` | 生成对账单（传 stationId, periodStart, periodEnd） |
|
||
| GET | `/station/settlement-bill/page` | 对账单分页列表 |
|
||
| GET | `/station/settlement-bill/{id}` | 对账单详情（含明细） |
|
||
| PUT | `/station/settlement-bill/pay/{id}` | 确认付款 |
|
||
| DELETE | `/station/settlement-bill/{id}` | 删除对账单（仅已出账可删） |
|
||
| GET | `/station/settlement-bill/export-excel/{id}` | 导出 Excel |
|
||
| GET | `/station/settlement-bill/export-pdf/{id}` | 导出 PDF |
|
||
|
||
### 生成对账单逻辑
|
||
|
||
```
|
||
1. 校验：时间范围内该站所有订单 reviewStatus 必须全部为 1（已审核）
|
||
2. 校验：时间范围内该站不能有 settlementStatus != 0（未对账）的订单（避免重复出账）
|
||
3. 查询：该站 + 时间范围 + reviewStatus=1 + settlementStatus=0 的所有订单
|
||
4. 汇总：计算 orderCount, totalGasWeight, totalAmount
|
||
5. 创建：hydrogen_settlement_bill + 逐条 snapshot 到 bill_item
|
||
6. 更新：所有关联订单的 settlementStatus → 1（已出账）
|
||
7. 返回：对账单ID
|
||
```
|
||
|
||
### 确认付款逻辑
|
||
|
||
```
|
||
1. 校验：对账单 status 必须为 0（已出账）
|
||
2. 更新：对账单 status → 1（已付款），记录 paidTime, paidBy
|
||
3. 批量更新：关联订单的 settlementStatus → 2（已付款）
|
||
```
|
||
|
||
### 删除对账单逻辑
|
||
|
||
```
|
||
1. 校验：对账单 status 必须为 0（已出账，未付款才可删）
|
||
2. 批量回退：关联订单的 settlementStatus → 0（未对账）
|
||
3. 删除：对账单 + 明细（逻辑删除）
|
||
```
|
||
|
||
---
|
||
|
||
## 前端设计
|
||
|
||
### 加氢记录页面 — 增加「生成对账单」按钮
|
||
|
||
工具栏新增按钮，点击弹出对话框：
|
||
- 选择加氢站（下拉）
|
||
- 选择对账时间范围（日期区间选择器）
|
||
- 点击「生成」→ 调用后端 → 成功后自动跳转对账单详情页
|
||
|
||
### 对账单页面（/energy/order/settlement-bill/:id）
|
||
|
||
不单独设菜单，通过加氢记录页面跳转。
|
||
|
||
**页面结构：**
|
||
```
|
||
┌─ 对账单详情 ─────────────────────────────┐
|
||
│ │
|
||
│ 对账单号：SB20260325001 │
|
||
│ 加氢站：嘉兴站 状态：[已出账] │
|
||
│ 对账周期：2026-03-01 ~ 2026-03-31 │
|
||
│ │
|
||
│ ┌────────┬────────┬────────┐ │
|
||
│ │ 笔数 │ 总加注量│ 总金额 │ │
|
||
│ │ 25 │ 150 kg │ ¥4,500 │ │
|
||
│ └────────┴────────┴────────┘ │
|
||
│ │
|
||
│ [确认付款] [删除] [导出Excel] [导出PDF] │
|
||
│ │
|
||
│ ── 明细列表 ── │
|
||
│ 订单编号 | 车牌 | 加注时间 | 重量(kg) | 气价(元/kg) | 金额(元) │
|
||
│ ... │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
### 对账单列表页（可选，也可嵌在加氢记录页面作为 Tab）
|
||
|
||
暂不独立列表页，通过加氢记录页面「已出账/已付款」筛选 + 点击跳转查看。
|
||
|
||
---
|
||
|
||
## 文件清单
|
||
|
||
### 后端 — ln-energy
|
||
|
||
| 操作 | 文件 |
|
||
|------|------|
|
||
| Create | `db/station/V6__create_settlement_bill.sql` |
|
||
| Create | `entity/settlement/po/HydrogenSettlementBill.java` |
|
||
| Create | `entity/settlement/po/HydrogenSettlementBillItem.java` |
|
||
| Create | `entity/settlement/vo/SettlementBillVO.java` |
|
||
| Create | `entity/settlement/vo/SettlementBillDetailVO.java` |
|
||
| Create | `entity/settlement/req/GenerateSettlementBillReq.java` |
|
||
| Create | `mapper/HydrogenSettlementBillMapper.java` |
|
||
| Create | `mapper/HydrogenSettlementBillItemMapper.java` |
|
||
| Create | `service/ISettlementBillService.java` |
|
||
| Create | `service/impl/SettlementBillServiceImpl.java` |
|
||
| Create | `controller/SettlementBillController.java` |
|
||
| Modify | `db/init/V1__init_ln_energy.sql` — 补建表语句 |
|
||
|
||
### 前端 — ln-one-os-web
|
||
|
||
| 操作 | 文件 |
|
||
|------|------|
|
||
| Create | `views/station/settlement/bill-detail.vue` — 对账单详情页 |
|
||
| Create | `views/station/settlement/generate-modal.vue` — 生成对账单对话框 |
|
||
| Create | `api/station/settlement/index.ts` — 对账单 API |
|
||
| Modify | `views/station/order/index.vue` — 工具栏加「生成对账单」按钮 |
|
||
| Modify | 后端动态菜单 — 隐藏菜单注册（hideInMenu） |
|
||
|
||
### 数据库
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| Execute DDL | hydrogen_settlement_bill + hydrogen_settlement_bill_item |
|
||
| Menu | 注册隐藏菜单（对账单详情页路由） |
|
||
|
||
---
|
||
|
||
## 验证
|
||
|
||
1. `mvn clean compile` 编译通过
|
||
2. DDL 执行到数据库
|
||
3. 测试：选择加氢站 + 时间范围 → 生成对账单 → 跳转详情
|
||
4. 测试：时间范围内有未审核订单 → 生成失败提示
|
||
5. 测试：确认付款 → 对账单状态+订单状态同步
|
||
6. 测试：删除对账单 → 订单状态回退
|
||
7. 测试：已付款的对账单不可删除
|
||
8. 测试：导出 Excel / PDF
|