# 加氢站对账单功能

## 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