jsowell-charger-web/docs/feature-tracker-无交易记录自动结算.md

# 功能开发追踪：无交易记录时按实时检测数据自动结算

**功能编号**: TBD
**版本**: v0.2
**日期**: 2026-08-11
**项目**: 万车充运营管理平台
**状态**: 方案已确认，开发中
**负责模块**: jsowell-pile / jsowell-netty / jsowell-quartz

---

## 变更记录

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| v0.1 | 2026-08-11 | 初稿：需求分析、风险点、实现方案、开发进度追踪框架 |
| v0.2 | 2026-08-11 | 确认决策：金额以桩端 chargingAmount 为准；双依据判定都启用；特定站点灰度 |

---

## 一、背景与目标

### 背景

当前自动结算**唯一入口**是收到交易记录帧。充电桩在线、充电已停止，但**若未收到交易记录**（桩端漏发、网络丢帧、交易记录帧异常等），订单将永远停留在「待结算」状态，无法自动结算，导致：
- 用户预付资金长期冻结，体验差
- 后台需要人工介入结算，运维成本高

### 目标

充电桩**在线**且**停止充电超过 10 分钟**仍未收到交易记录时，平台**按最后一条实时检测记录中的耗电量（充电度数）自动结算**，替代人工结算，缩短资金冻结周期。

### 非目标（本期不做）

- 桩离线场景的自动结算（离线时数据不可信，需人工确认）
- 尖峰平谷分时明细的补全（实时数据本身不含分时信息）

---

## 二、需求分析

### 2.1 当前逻辑（现状）

| 环节 | 现状 | 代码位置 |
|------|------|---------|
| 结算触发 | 仅收到交易记录帧时触发 `settleOrder` | `TransactionRecordsRequestHandler.processOrder()` → jsowell-netty/.../TransactionRecordsRequestHandler.java:683 |
| 结算数据来源 | 交易记录 `TransactionRecordsData`（含尖峰平谷分时电量、单价、金额） | 同上 |
| 无交易记录时 | 订单停在「待结算」，不自动结算 | — |
| 桩离线 | 订单置为异常 `updateOrderStatusAsAbnormal` | YKCBusinessServiceImpl.java:166 |
| 人工结算 | 已支持「无交易记录 → 用最后一条实时数据构造结算数据」 | `OrderService.manualSettlementOrder()` → jsowell-admin/.../OrderService.java:1008-1027 |

### 2.2 目标逻辑

```
定时任务（周期可配，默认如每 10 分钟）扫描待结算订单：
  ├─ 条件 1：订单状态 = 待结算 (STAY_SETTLEMENT)
  ├─ 条件 2：充电桩在线（connector status ≠ "0" 离线）
  ├─ 条件 3：充电已停止超过 10 分钟
  │     ├─ 优先依据：chargeEndTime 非空 且 距当前 > 10 分钟（桩上报过 0x19 充电结束）
  │     └─ 兜底依据：最后一条实时检测数据 dateTime 距当前 > 10 分钟（桩未上报结束/交易记录）
  └─ 条件 4：存在实时检测数据（chargingDegree > 0）

命中后：
  1. 复用人工结算逻辑，从最后一条实时检测数据构造 TransactionRecordsData
  2. 走 orderLogic.settleOrder(data, orderBasicInfo)
```

### 2.3 关键数据来源

| 数据 | 字段 | 说明 |
|------|------|------|
| 累计充电度数 | `RealTimeMonitorData.chargingDegree` | 精确到 4 位小数，待机置零 |
| 已充金额 | `RealTimeMonitorData.chargingAmount` | 桩端计算（电费+服务费）*计损度数 |
| 实时数据落库 | `order_monitor_data` 表 / redis `PILE_REAL_TIME_MONITOR_DATA` | 充电中每 10s 上报一次，按分钟保留最后一条 |
| 桩在线状态 | `PileConnectorDataBaseStatusEnum` | `"0"`=离线，`1/2/3/4`=在线 |
| 充电结束信号 | `ChargeEndHandler` (0x19) | 更新 `chargeEndTime`、`endSoc` |

---

## 三、风险点与应对

| # | 风险 | 等级 | 说明 | 应对 |
|---|------|------|------|------|
| R1 | **金额准确性依赖桩端上报** | 高 | 实时数据无尖峰平谷分时明细，结算走「以交易记录金额为准」分支，即完全信任桩端 `chargingAmount`。若桩端该值有误（充电中途拔枪、数据异常），直接导致扣费/退款不准确 | **已决策：以桩端 `chargingAmount` 为准**（与人工结算一致）。降低影响：① 异常金额阈值（chargingAmount 远超 payAmount）时跳过并告警；② 特定站点灰度上线，逐步观察 |
| R2 | **退款联动** | 中 | `chargingAmount` < 预付款 `payAmount` 时走退款流程，金额不准会连带退款不准 | 结算金额以 `chargingAmount` 为准，与人工结算一致；金额异常（远超 payAmount）时跳过并告警 |
| R3 | **幂等 / 并发** | 中 | 定时扫描与「交易记录恰好到达」可能并发重复结算 | 复用现有 `settle_order_`+transactionCode redis 锁（TransactionRecordsRequestHandler.java:602）；结算前校验订单状态与结算时间 |
| R4 | **判「停止」时间点模糊** | 中 | 桩只拔枪不上报 0x19 时，`chargeEndTime` 为空，只能依赖实时数据 `dateTime` 判定；若桩同时离线则数据停更 | **已决策：双依据都启用**（chargeEndTime 优先，最后实时数据 dateTime 兜底）。条件 2（在线）为安全底线，离线订单不结算 |
| R5 | **影响面扩散** | 中 | 该逻辑影响所有待结算订单，改动结算主链路风险高 | 不修改结算核心 `settleOrder`，仅新增定时扫描入口，复用人工结算构造逻辑 |
| R6 | **灰度与回滚** | 中 | 新逻辑上线初期存在未覆盖场景 | **已决策：特定站点灰度**（`auto-settle.grayscale-station-ids`）。开关关闭即回退到现有行为 |

---

## 四、实现方案

### 4.1 总体思路

不修改现有结算核心链路，新增**定时扫描任务**，命中条件后复用人工结算的「实时数据 → TransactionRecordsData」构造逻辑，再走既有的 `settleOrder`。

### 4.2 实现步骤

| # | 步骤 | 说明 | 模块 |
|---|------|------|------|
| 1 | 配置开关 | 新增自动结算开关 + 站点灰度白名单：`auto-settle.enabled`、`auto-settle.timeout-minutes=10`、`auto-settle.interval`、`auto-settle.grayscale-station-ids`（特定站点灰度）。默认关闭或仅灰度站点开启 | jsowell-pile / application.yml |
| 2 | 构造结算数据方法 | 在 `OrderService`（或抽到 pile 的公共 Service）新增「从最后一条实时数据构造 TransactionRecordsData」方法，与人工结算复用同一逻辑 | jsowell-admin / jsowell-pile |
| 3 | 查询待结算订单 | 新增 mapper 查询：状态=待结算 + 桩在线 + 满足停止条件（chargeEndTime/最后实时数据时间 < 当前-10min）的订单列表 | jsowell-pile |
| 4 | 定时任务 | 新增 Quartz Job，周期执行扫描+结算，含 redis 分布式锁防并发 | jsowell-quartz |
| 5 | 结算执行 | 循环命中订单，构造数据 → `orderLogic.settleOrder`，异常单独捕获不影响整体 | jsowell-pile |
| 6 | 幂等保护 | 结算前校验订单状态未变更、`settle_order_` 锁未占用 | jsowell-pile |
| 7 | 告警日志 | 结算异常、金额异常（chargingAmount 远大于 payAmount）时输出 ERROR 日志/告警 | 各模块 |

### 4.3 涉及文件清单（预估）

| 文件 | 变更 |
|------|------|
| `jsowell-pile/.../OrderBasicInfoService.java` | 新增查询待结算订单方法 |
| `jsowell-pile/.../OrderBasicInfoServiceImpl.java` | 实现查询逻辑 |
| `jsowell-pile/.../OrderBasicInfoMapper.xml` | 新增 SQL |
| `jsowell-admin/.../OrderService.java` | 抽取「实时数据→结算数据」构造方法（或下沉到 pile） |
| `jsowell-quartz/.../RyTask.java` 或新增 Task | 新增自动结算定时任务 |
| `jsowell-admin/src/main/resources/application*.yml` | 新增配置项 |

---

## 五、开发进度追踪

> 状态：`⬜ 未开始` / `🟡 进行中` / `✅ 已完成` / `🔴 阻塞`

| # | 任务 | 模块 | 负责人 | 状态 | 备注 |
|---|------|------|--------|------|------|
| 1 | 需求评审确认（含 R1/R4 决策） | - | | ✅ 已完成 | 2026-08-11 确认：金额以桩端 chargingAmount 为准；双依据判定；特定站点灰度 |
| 2 | 配置开关 | jsowell-pile | | ⬜ 未开始 | |
| 3 | 实时数据→结算数据构造方法 | jsowell-admin/pile | | ⬜ 未开始 | |
| 4 | 待结算订单查询 SQL | jsowell-pile | | ⬜ 未开始 | |
| 5 | 定时任务 | jsowell-quartz | | ⬜ 未开始 | |
| 6 | 幂等保护 | jsowell-pile | | ⬜ 未开始 | |
| 7 | 告警日志 | 各模块 | | ⬜ 未开始 | |
| 8 | 单元测试 / 集成测试 | jsowell-admin | | ⬜ 未开始 | |
| 9 | 灰度上线（特定站点） | - | | ⬜ 未开始 | 先对灰度站点开启，观察稳定后逐步放开 |
| 10 | 上线后监控与复盘 | - | | ⬜ 未开始 | |

### 已决策问题

| # | 问题 | 决策 | 决策日期 |
|---|------|------|---------|
| 1 | 金额策略 | **以桩端 `chargingAmount` 为准**（与人工结算一致） | 2026-08-11 |
| 2 | 停止判定依据 | **双依据都启用**：chargeEndTime 优先，最后实时数据 dateTime 兜底 | 2026-08-11 |
| 3 | 灰度范围 | **特定站点灰度**，先对指定站点开启，观察稳定后再逐步放开 | 2026-08-11 |

---

## 六、测试计划

| # | 场景 | 预期 |
|---|------|------|
| 1 | 桩在线 + 有 chargeEndTime + 停止>10min + 有实时数据 | 自动结算成功，金额=实时数据 chargingAmount |
| 2 | 桩在线 + 无 chargeEndTime + 最后实时数据>10min + 有实时数据 | 兜底依据触发，自动结算 |
| 3 | 桩离线 | 不触发（条件 2 拦截） |
| 4 | 停止 < 10min | 不触发 |
| 5 | 无实时检测数据（chargingDegree=0） | 不触发 |
| 6 | 扫描期间交易记录到达 | 不重复结算（幂等） |
| 7 | chargingAmount > payAmount 异常值 | 跳过并告警 |
| 8 | 配置开关关闭 | 保持现有行为（不自动结算） |