mirror of
https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git
synced 2026-05-08 20:10:16 +08:00
update
This commit is contained in:
jsowell
11
docs/2022年11月17日逻辑改动.md
Normal file
11
docs/2022年11月17日逻辑改动.md
Normal file
@@ -0,0 +1,11 @@
|
||||
充电桩
|
||||
|
||||
1. 充电桩桩类型全部都是运营桩
|
||||
2. 充电桩必须绑定计费模板才能使用
|
||||
3. 充电桩桩对白名单用户免费
|
||||
4. 创建订单时，判断是否为白名单用户
|
||||
|
||||
站点白名单
|
||||
|
||||
|
||||
|
||||
322
docs/JCPP_JSON消息分区消费方案.md
Normal file
322
docs/JCPP_JSON消息分区消费方案.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# JCPP JSON 消息分区消费方案
|
||||
|
||||
## 概述
|
||||
|
||||
本方案实现了基于 JSON 格式的 JCPP 消息分区消费，确保同一充电桩（相同 pileCode）的消息按顺序处理，避免并发导致的消息乱序问题。
|
||||
|
||||
## 核心特性
|
||||
|
||||
1. **消息顺序保证**：同一充电桩的消息按顺序处理
|
||||
2. **分区消费**：10 个分区，基于 pileCode 的 Hash 分区
|
||||
3. **单线程消费**：每个分区单线程消费，保证顺序
|
||||
4. **JSON 格式**：保持原有 JSON 格式，无需 Protobuf
|
||||
5. **统一处理**：整合所有消息类型的处理逻辑
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 1. 分区策略
|
||||
|
||||
- **分区数量**：默认 10 个分区（可配置）
|
||||
- **分区算法**：MurmurHash3_128（与 JCPP 保持一致）
|
||||
- **分区键**：pileCode（充电桩编码）
|
||||
- **消费模式**：每个分区单线程消费，保证顺序
|
||||
|
||||
### 2. 核心组件
|
||||
|
||||
```
|
||||
jsowell-pile/src/main/java/com/jsowell/pile/jcpp/
|
||||
├── config/
|
||||
│ └── JcppPartitionQueueConfig.java # 分区队列配置
|
||||
├── consumer/
|
||||
│ └── JcppJsonPartitionConsumer.java # JSON 消息消费者
|
||||
├── service/
|
||||
│ ├── IJcppJsonMessageHandler.java # 消息处理器接口
|
||||
│ └── impl/
|
||||
│ └── JcppJsonMessageHandlerImpl.java # 消息处理器实现
|
||||
└── util/
|
||||
└── JcppPartitionCalculator.java # 分区计算器
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
### 1. 配置文件
|
||||
|
||||
在 `application-{env}.yml` 中添加：
|
||||
|
||||
```yaml
|
||||
# JCPP 配置
|
||||
jcpp:
|
||||
rabbitmq:
|
||||
# 分区数量（与 JCPP 保持一致）
|
||||
partition-count: 10
|
||||
# Exchange 名称
|
||||
exchange: jcpp.uplink.exchange
|
||||
# 队列前缀
|
||||
queue-prefix: jcpp.uplink.partition
|
||||
```
|
||||
|
||||
### 2. RabbitMQ 队列
|
||||
|
||||
启动应用时会自动创建以下队列：
|
||||
|
||||
```
|
||||
jcpp.uplink.partition.0
|
||||
jcpp.uplink.partition.1
|
||||
jcpp.uplink.partition.2
|
||||
...
|
||||
jcpp.uplink.partition.9
|
||||
```
|
||||
|
||||
每个队列绑定到 `jcpp.uplink.exchange`，routing key 为 `jcpp.uplink.#`
|
||||
|
||||
### 3. 消息格式
|
||||
|
||||
消息体为 JSON 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"messageType": "LOGIN",
|
||||
"data": "{\"pileCode\":\"20231212000010\",\"remoteAddress\":\"192.168.1.100\"}"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**：
|
||||
- `pileCode`：充电桩编码（用于分区计算）
|
||||
- `messageType`：消息类型（LOGIN, HEARTBEAT, GUN_STATUS, REAL_TIME_DATA, TRANSACTION_RECORD 等）
|
||||
- `data`：具体消息内容（JSON 字符串）
|
||||
|
||||
### 4. 支持的消息类型
|
||||
|
||||
| 消息类型 | messageType 值 | 说明 |
|
||||
|---------|---------------|------|
|
||||
| 登录请求 | LOGIN | 充电桩登录 |
|
||||
| 心跳请求 | HEARTBEAT | 心跳保活 |
|
||||
| 枪状态上报 | GUN_STATUS | 充电枪状态变化 |
|
||||
| 充电进度 | REAL_TIME_DATA | 实时充电数据 |
|
||||
| 交易记录 | TRANSACTION_RECORD | 充电完成记录 |
|
||||
| 启动充电 | START_CHARGE | 刷卡启动充电 |
|
||||
| 查询计费 | QUERY_PRICING | 查询计费模板 |
|
||||
| 校验计费 | VERIFY_PRICING | 校验计费模板 |
|
||||
| 会话关闭 | SESSION_CLOSE | 会话关闭事件 |
|
||||
| 远程启动结果 | REMOTE_START_RESULT | 远程启动结果 |
|
||||
| 远程停止结果 | REMOTE_STOP_RESULT | 远程停止结果 |
|
||||
|
||||
## 消息流程
|
||||
|
||||
### 1. JCPP 发送消息
|
||||
|
||||
JCPP 在发送消息时需要：
|
||||
|
||||
1. 将消息序列化为 JSON 格式
|
||||
2. 根据 pileCode 计算分区编号
|
||||
3. 将消息发送到对应的分区队列
|
||||
|
||||
```java
|
||||
// JCPP 端示例代码
|
||||
String pileCode = "20231212000010";
|
||||
int partition = JcppPartitionCalculator.getPartition(pileCode);
|
||||
String queueName = "jcpp.uplink.partition." + partition;
|
||||
|
||||
// 构建消息
|
||||
JcppUplinkMessage message = new JcppUplinkMessage();
|
||||
message.setPileCode(pileCode);
|
||||
message.setMessageType("LOGIN");
|
||||
message.setData("{...}");
|
||||
|
||||
// 发送到指定队列
|
||||
rabbitTemplate.convertAndSend("jcpp.uplink.exchange", queueName, message);
|
||||
```
|
||||
|
||||
### 2. Web 项目消费消息
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class JcppJsonPartitionConsumer {
|
||||
|
||||
@RabbitListener(
|
||||
queues = {
|
||||
"jcpp.uplink.partition.0",
|
||||
"jcpp.uplink.partition.1",
|
||||
// ... 其他分区
|
||||
},
|
||||
concurrency = "1" // 单线程消费保证顺序
|
||||
)
|
||||
public void consumeMessage(JcppUplinkMessage uplinkMessage) {
|
||||
// 处理消息
|
||||
messageHandler.handleUplinkMessage(uplinkMessage);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 消息处理
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class JcppJsonMessageHandlerImpl implements IJcppJsonMessageHandler {
|
||||
|
||||
@Override
|
||||
public void handleUplinkMessage(JcppUplinkMessage message) {
|
||||
// 根据消息类型分发处理
|
||||
switch (message.getMessageType()) {
|
||||
case "LOGIN":
|
||||
handleLogin(message);
|
||||
break;
|
||||
case "HEARTBEAT":
|
||||
handleHeartbeat(message);
|
||||
break;
|
||||
// ... 其他消息类型
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 分区算法
|
||||
|
||||
### Hash 计算
|
||||
|
||||
使用 MurmurHash3_128 算法计算分区：
|
||||
|
||||
```java
|
||||
public static int getPartition(String pileCode) {
|
||||
// 使用 MurmurHash3_128 算法
|
||||
long hash = Hashing.murmur3_128()
|
||||
.hashString(pileCode, StandardCharsets.UTF_8)
|
||||
.asLong();
|
||||
|
||||
// 取绝对值并对分区数取模
|
||||
return Math.abs((int) (hash % partitionCount));
|
||||
}
|
||||
```
|
||||
|
||||
### 分区示例
|
||||
|
||||
假设 `partitionCount = 10`：
|
||||
|
||||
| pileCode | Hash 值 | 分区编号 |
|
||||
|----------|---------|---------|
|
||||
| 20231212000010 | 123456789 | 9 |
|
||||
| 20231212000011 | 987654321 | 1 |
|
||||
| 20231212000012 | 456789123 | 3 |
|
||||
|
||||
同一个 pileCode 的所有消息都会路由到同一个分区，由单线程顺序处理。
|
||||
|
||||
## 与原有方案的对比
|
||||
|
||||
### 原有方案（无分区）
|
||||
|
||||
- ❌ 多个消费者并发消费，可能导致消息乱序
|
||||
- ❌ 同一充电桩的消息可能被不同消费者处理
|
||||
- ✅ 实现简单，无需额外配置
|
||||
|
||||
### 新方案（分区消费）
|
||||
|
||||
- ✅ 同一充电桩的消息保证顺序处理
|
||||
- ✅ 每个分区单线程消费，避免并发问题
|
||||
- ✅ 支持水平扩展（增加分区数量）
|
||||
- ⚠️ 需要 JCPP 端配合实现分区路由
|
||||
|
||||
## 监控与运维
|
||||
|
||||
### 1. 日志监控
|
||||
|
||||
```
|
||||
[分区0] 收到消息: pileCode=20231212000010, messageType=LOGIN
|
||||
[分区0] 消息处理完成: pileCode=20231212000010
|
||||
```
|
||||
|
||||
### 2. 性能指标
|
||||
|
||||
- 消息处理延迟
|
||||
- 队列堆积数量
|
||||
- 消费速率
|
||||
- 错误率
|
||||
|
||||
### 3. 告警规则
|
||||
|
||||
- 队列堆积超过阈值
|
||||
- 消息处理失败率超过阈值
|
||||
- 消费延迟超过阈值
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. 分区数量
|
||||
|
||||
- 分区数量必须与 JCPP 保持一致
|
||||
- 修改分区数量需要重新创建队列
|
||||
- 建议在系统初始化时确定分区数量，后续不要修改
|
||||
|
||||
### 2. 消息顺序
|
||||
|
||||
- 每个分区单线程消费（`concurrency=1`）
|
||||
- 同一 pileCode 的消息保证顺序
|
||||
- 不同 pileCode 的消息可能并发处理
|
||||
|
||||
### 3. 异常处理
|
||||
|
||||
- JSON 解析失败：记录日志并抛出异常
|
||||
- 业务处理失败：根据业务需求决定是否重试
|
||||
- 建议配置死信队列处理失败消息
|
||||
|
||||
### 4. 性能优化
|
||||
|
||||
- 合理设置分区数量（建议 10-20）
|
||||
- 避免在消息处理中执行耗时操作
|
||||
- 使用 Redis 缓存减少数据库压力
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 1. 消息无法消费
|
||||
|
||||
- 检查队列是否创建成功
|
||||
- 检查队列绑定是否正确
|
||||
- 检查 RabbitMQ 连接是否正常
|
||||
|
||||
### 2. 消息分区错误
|
||||
|
||||
- 检查 Hash 算法是否与 JCPP 一致
|
||||
- 检查分区数量配置是否一致
|
||||
- 查看日志中的分区不匹配警告
|
||||
|
||||
### 3. 消息处理失败
|
||||
|
||||
- 查看异常堆栈信息
|
||||
- 检查业务逻辑是否正确
|
||||
- 检查数据库连接是否正常
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 1. 更新配置
|
||||
|
||||
在 `application-{env}.yml` 中添加 JCPP 配置
|
||||
|
||||
### 2. 启动应用
|
||||
|
||||
```bash
|
||||
mvn clean package -DskipTests
|
||||
java -jar jsowell-admin/target/jsowell-admin.jar --spring.profiles.active=sit
|
||||
```
|
||||
|
||||
### 3. 验证队列创建
|
||||
|
||||
登录 RabbitMQ 管理界面，检查是否创建了 10 个分区队列
|
||||
|
||||
### 4. 发送测试消息
|
||||
|
||||
使用 JCPP 发送测试消息，验证分区路由是否正确
|
||||
|
||||
### 5. 监控运行状态
|
||||
|
||||
查看日志，确认消息正常消费
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Spring AMQP 文档](https://docs.spring.io/spring-amqp/reference/)
|
||||
- [RabbitMQ 分区队列](https://www.rabbitmq.com/partitions.html)
|
||||
- [Guava Hashing](https://github.com/google/guava/wiki/HashingExplained)
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v2.1（JSON 格式）
|
||||
**最后更新**：2025-12-30
|
||||
**维护人员**：jsowell 团队
|
||||
710
docs/JCPP对接进度文档.md
Normal file
710
docs/JCPP对接进度文档.md
Normal file
@@ -0,0 +1,710 @@
|
||||
# JCPP 充电桩平台对接进度文档
|
||||
|
||||
> 文档创建时间：2025-12-30
|
||||
> 最后更新时间：2025-12-30
|
||||
> 对接平台：JCPP（Java Charging Pile Platform）
|
||||
|
||||
---
|
||||
|
||||
## 一、项目概述
|
||||
|
||||
### 1.1 对接目标
|
||||
将万车充运营管理平台与 JCPP 充电桩平台进行对接，实现充电桩设备的统一管理和充电业务的互联互通。
|
||||
|
||||
### 1.2 技术架构
|
||||
- **通信方式**：RabbitMQ 消息队列
|
||||
- **消息格式**：JSON
|
||||
- **协议版本**：yunkuaichongV150
|
||||
- **Exchange**：`jcpp.uplink.exchange`（上行消息）、`jcpp.downlink.exchange`（下行消息）
|
||||
|
||||
### 1.3 模块位置
|
||||
- **核心代码**：`jsowell-pile` 模块
|
||||
- **包路径**：`com.jsowell.pile.jcpp`
|
||||
- **配置类**：`JcppConfig`、`JcppRabbitConfig`
|
||||
|
||||
---
|
||||
|
||||
## 二、已完成功能
|
||||
|
||||
### 2.1 基础架构搭建 ✅
|
||||
|
||||
#### 2.1.1 RabbitMQ 配置
|
||||
- [x] 创建 `JcppRabbitConfig` 配置类
|
||||
- [x] 定义上行消息 Exchange：`jcpp.uplink.exchange`
|
||||
- [x] 定义 9 个消息队列和对应的 Routing Key
|
||||
- [x] 配置队列绑定关系
|
||||
|
||||
**队列列表**：
|
||||
| 队列名称 | Routing Key | 用途 |
|
||||
|---------|-------------|------|
|
||||
| `jcpp.uplink.login` | `jcpp.uplink.login` | 充电桩登录 |
|
||||
| `jcpp.uplink.heartbeat` | `jcpp.uplink.heartbeat` | 心跳消息 |
|
||||
| `jcpp.uplink.startCharge` | `jcpp.uplink.startCharge` | 刷卡启动充电 |
|
||||
| `jcpp.uplink.realTimeData` | `jcpp.uplink.realTimeData` | 实时充电数据 |
|
||||
| `jcpp.uplink.transaction` | `jcpp.uplink.transaction` | 交易记录 |
|
||||
| `jcpp.uplink.gunStatus` | `jcpp.uplink.gunStatus` | 枪状态上报 |
|
||||
| `jcpp.uplink.pricing` | `jcpp.uplink.pricing.#` | 计费模板查询 |
|
||||
| `jcpp.uplink.remoteResult` | `jcpp.uplink.remoteResult.#` | 远程操作结果 |
|
||||
| `jcpp.uplink.sessionClose` | `jcpp.uplink.sessionClose` | 会话关闭 |
|
||||
|
||||
#### 2.1.2 DTO 数据传输对象
|
||||
- [x] `JcppUplinkMessage`：上行消息统一封装
|
||||
- [x] `JcppDownlinkRequest`：下行请求封装
|
||||
- [x] `JcppDownlinkCommand`：下行命令封装
|
||||
- [x] `JcppLoginData`：登录数据
|
||||
- [x] `JcppStartChargeData`：启动充电数据
|
||||
- [x] `JcppRealTimeData`：实时数据
|
||||
- [x] `JcppTransactionData`：交易记录数据
|
||||
- [x] `JcppPricingModel`：计费模板数据
|
||||
- [x] `JcppRemoteStartResultData`：远程启动结果数据
|
||||
- [x] `JcppSessionInfo`：会话信息
|
||||
|
||||
#### 2.1.3 常量定义
|
||||
- [x] `JcppConstants`：定义队列名称、Routing Key、消息类型等常量
|
||||
|
||||
---
|
||||
|
||||
### 2.2 上行消息处理（JCPP → 万车充）✅
|
||||
|
||||
#### 2.2.1 充电桩登录 ✅
|
||||
**消费者**：`JcppLoginConsumer`
|
||||
**队列**：`jcpp.uplink.login`
|
||||
**功能**：
|
||||
- [x] 接收充电桩登录消息
|
||||
- [x] 验证充电桩是否存在于系统中
|
||||
- [x] 发送登录应答（通过 `IJcppDownlinkService.sendLoginAck()`）
|
||||
- [x] 更新充电桩在线状态（已注释，待确认业务逻辑）
|
||||
|
||||
**状态**：✅ 已完成基础功能
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.2 心跳消息 ✅
|
||||
**消费者**：`JcppHeartbeatConsumer`
|
||||
**队列**：`jcpp.uplink.heartbeat`
|
||||
**功能**：
|
||||
- [x] 接收充电桩心跳消息
|
||||
- [x] 更新充电桩最后活跃时间到 Redis（避免频繁写数据库）
|
||||
- [x] 设置 Redis 过期时间为 180 秒
|
||||
|
||||
**状态**：✅ 已完成
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.3 刷卡启动充电 ✅
|
||||
**消费者**：`JcppStartChargeConsumer`
|
||||
**队列**：`jcpp.uplink.startCharge`
|
||||
**功能**：
|
||||
- [x] 接收刷卡启动充电请求
|
||||
- [x] 验证充电桩状态
|
||||
- [x] 查询授权卡信息（`PileAuthCard`）
|
||||
- [x] 验证卡状态和密码（密码验证已注释）
|
||||
- [x] 查询会员钱包余额
|
||||
- [x] 检查白名单（免费充电）
|
||||
- [x] 验证余额是否充足
|
||||
- [x] 生成交易流水号（`tradeNo`）
|
||||
- [x] 创建充电订单（`OrderBasicInfo`）
|
||||
- [x] 发送鉴权结果应答
|
||||
|
||||
**状态**：✅ 已完成核心功能
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.4 实时充电数据 ✅
|
||||
**消费者**：`JcppRealTimeDataConsumer`
|
||||
**队列**：`jcpp.uplink.realTimeData`
|
||||
**功能**：
|
||||
- [x] 接收实时充电数据（电压、电流、SOC、充电量、充电金额等）
|
||||
- [x] 将实时数据缓存到 Redis（5 分钟过期）
|
||||
- [x] 根据 `tradeNo` 查询订单
|
||||
- [x] 更新订单实时数据（充电量、金额、时长）
|
||||
- [x] 更新枪状态为充电中
|
||||
|
||||
**状态**：✅ 已完成
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.5 交易记录（订单结算）✅
|
||||
**消费者**：`JcppTransactionConsumer`
|
||||
**队列**：`jcpp.uplink.transaction`
|
||||
**功能**：
|
||||
- [x] 接收充电完成的交易记录
|
||||
- [x] 根据 `tradeNo` 查询订单
|
||||
- [x] 幂等性检查（避免重复处理）
|
||||
- [x] 更新订单状态为"充电完成"
|
||||
- [x] 更新订单充电数据（开始时间、结束时间、充电量、金额、停止原因）
|
||||
- [x] 更新枪状态为空闲
|
||||
- [x] 发送交易记录应答
|
||||
- [ ] 触发结算流程（已注释，待实现）
|
||||
|
||||
**状态**：✅ 基础功能已完成，⚠️ 结算流程待对接
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.6 枪状态上报 ✅
|
||||
**消费者**：`JcppGunStatusConsumer`
|
||||
**队列**：`jcpp.uplink.gunStatus`
|
||||
**功能**：
|
||||
- [x] 接收充电枪状态变化消息
|
||||
- [x] 状态映射（JCPP 状态 → 系统状态）
|
||||
- `IDLE` → `1`（空闲）
|
||||
- `INSERTED` → `2`（占用未充电）
|
||||
- `CHARGING` → `3`（充电中）
|
||||
- `CHARGE_COMPLETE` → `2`（充电完成未拔枪）
|
||||
- `FAULT` → `255`（故障）
|
||||
- `UNKNOWN` → `0`（离网）
|
||||
- [x] 更新枪状态到数据库
|
||||
- [x] 记录故障信息（日志）
|
||||
|
||||
**状态**：✅ 已完成
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.7 计费模板查询 ✅
|
||||
**消费者**：`JcppPricingConsumer`
|
||||
**队列**：`jcpp.uplink.pricing`
|
||||
**功能**：
|
||||
- [x] 处理计费模板查询请求（`QUERY_PRICING`）
|
||||
- [x] 根据充电桩编码查询关联的计费模板
|
||||
- [x] 将计费模板转换为 JCPP 格式（`PricingModelConverter`）
|
||||
- [x] 发送计费模板查询应答
|
||||
- [x] 处理计费模板校验请求（`VERIFY_PRICING`）
|
||||
- [x] 发送计费模板校验应答
|
||||
|
||||
**状态**：✅ 已完成
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.8 远程操作结果 ✅
|
||||
**消费者**：`JcppRemoteResultConsumer`
|
||||
**队列**：`jcpp.uplink.remoteResult`
|
||||
**功能**：
|
||||
- [x] 处理远程启动结果（`REMOTE_START_RESULT`）
|
||||
- 启动成功：更新订单状态为"充电中"，更新枪状态
|
||||
- 启动失败：更新订单状态为"已取消"，记录失败原因
|
||||
- [x] 处理远程停止结果（`REMOTE_STOP_RESULT`）
|
||||
- 记录停止结果日志
|
||||
- 等待交易记录消息进行最终结算
|
||||
- [ ] 启动失败时触发退款流程（已注释，待实现）
|
||||
|
||||
**状态**：✅ 基础功能已完成，⚠️ 退款流程待实现
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.9 会话关闭 ✅
|
||||
**消费者**：`JcppSessionCloseConsumer`
|
||||
**队列**：`jcpp.uplink.sessionClose`
|
||||
**功能**：
|
||||
- [x] 接收充电桩会话关闭消息
|
||||
- [x] 更新充电桩离线状态（已注释）
|
||||
- [x] 更新所有枪状态为离线
|
||||
- [ ] 查询正在充电的订单并标记为异常（待实现）
|
||||
|
||||
**状态**：✅ 基础功能已完成，⚠️ 异常订单处理待实现
|
||||
|
||||
---
|
||||
|
||||
### 2.3 下行消息发送（万车充 → JCPP）✅
|
||||
|
||||
#### 2.3.1 下行服务接口
|
||||
**服务接口**：`IJcppDownlinkService`
|
||||
**实现类**：`JcppDownlinkServiceImpl`
|
||||
|
||||
**已实现方法**：
|
||||
- [x] `sendLoginAck()`：发送登录应答
|
||||
- [x] `sendStartChargeAck()`：发送启动充电鉴权应答
|
||||
- [x] `sendTransactionRecordAck()`：发送交易记录应答
|
||||
- [x] `sendQueryPricingAck()`：发送计费模板查询应答
|
||||
- [x] `sendVerifyPricingAck()`：发送计费模板校验应答
|
||||
- [x] `sendRemoteStart()`：发送远程启动充电命令
|
||||
- [x] `sendRemoteStop()`：发送远程停止充电命令
|
||||
|
||||
**状态**：✅ 已完成核心下行命令
|
||||
|
||||
---
|
||||
|
||||
### 2.4 远程充电控制 ✅
|
||||
|
||||
#### 2.4.1 远程充电服务
|
||||
**服务接口**：`IJcppRemoteChargeService`
|
||||
**实现类**：`JcppRemoteChargeServiceImpl`
|
||||
**Controller**：`JcppRemoteChargeController`（路径：`/jcpp/remote`）
|
||||
|
||||
**功能**：
|
||||
- [x] 远程启动充电（`POST /jcpp/remote/start`）
|
||||
- 验证充电桩和枪状态
|
||||
- 验证会员余额
|
||||
- 创建充电订单
|
||||
- 发送远程启动命令到 JCPP
|
||||
- [x] 远程停止充电（`POST /jcpp/remote/stop`）
|
||||
- 查询订单状态
|
||||
- 发送远程停止命令到 JCPP
|
||||
|
||||
**状态**：✅ 已完成
|
||||
|
||||
---
|
||||
|
||||
### 2.5 工具类 ✅
|
||||
|
||||
#### 2.5.1 计费模板转换器
|
||||
**类名**：`PricingModelConverter`
|
||||
**功能**：
|
||||
- [x] 将系统计费模板（`PileBillingTemplate`）转换为 JCPP 格式（`JcppPricingModel`）
|
||||
- [x] 支持分时电价和服务费配置
|
||||
- [x] 单元测试：`PricingModelConverterTest`
|
||||
|
||||
**状态**：✅ 已完成并测试
|
||||
|
||||
---
|
||||
|
||||
## 三、已修复的问题
|
||||
|
||||
### 3.1 消息反序列化错误（第一次修复）✅
|
||||
|
||||
**问题描述**：
|
||||
消费 JCPP 发来的消息时报错：
|
||||
```
|
||||
Caused by: com.fasterxml.jackson.databind.exc.MismatchedInputException:
|
||||
Cannot deserialize value of type `java.lang.String` from Object value (token `JsonToken.START_OBJECT`)
|
||||
```
|
||||
|
||||
**原因分析**：
|
||||
JCPP 发送的消息中，`data` 字段是一个 **JSON 字符串**，而不是 JSON 对象。但在 `JcppUplinkMessage` 中定义为 `Object` 类型，导致 Jackson 反序列化时尝试将 JSON 字符串解析为对象，从而失败。
|
||||
|
||||
**解决方案**：
|
||||
1. 修改 `JcppUplinkMessage.data` 字段类型从 `Object` 改为 `String`
|
||||
2. 修改所有消费者中的数据解析逻辑：
|
||||
- 原代码：`JSONObject data = JSON.parseObject(JSON.toJSONString(uplinkMessage.getData()));`
|
||||
- 修改后：`JSONObject data = JSON.parseObject(uplinkMessage.getData());`
|
||||
|
||||
**修复时间**：2025-12-30
|
||||
**状态**：✅ 已修复
|
||||
|
||||
---
|
||||
|
||||
### 3.2 RabbitMQ 消息转换器冲突（第二次修复）✅
|
||||
|
||||
**问题描述**：
|
||||
修复第一个问题后，仍然出现反序列化错误：
|
||||
```
|
||||
Caused by: com.fasterxml.jackson.databind.exc.MismatchedInputException:
|
||||
Cannot deserialize value of type `java.lang.String` from Object value (token `JsonToken.START_OBJECT`)
|
||||
at [Source: (String)"{"pileCode":"20231212000010","messageType":"LOGIN","data":"{\n \"messageIdMSB\": ...
|
||||
```
|
||||
|
||||
**原因分析**：
|
||||
消费者方法签名是 `public void handleLogin(String message)`，但 RabbitMQ 配置了 `Jackson2JsonMessageConverter`。当 RabbitMQ 接收到 JSON 对象消息时：
|
||||
1. `Jackson2JsonMessageConverter` 尝试将 JSON 对象反序列化为 `String` 类型
|
||||
2. Jackson 无法将 JSON 对象转换为 String，导致 `MismatchedInputException`
|
||||
|
||||
**根本原因**：
|
||||
- 消费者期望接收 `String` 类型参数
|
||||
- RabbitMQ 配置了 `Jackson2JsonMessageConverter`，会自动进行 JSON 反序列化
|
||||
- 两者冲突导致反序列化失败
|
||||
|
||||
**解决方案**：
|
||||
将所有消费者的方法参数从 `String message` 改为 `JcppUplinkMessage uplinkMessage`，让 Jackson 自动反序列化为对象。
|
||||
|
||||
**修改内容**：
|
||||
1. 修改所有消费者的方法签名：
|
||||
- 原代码：`public void handleXxx(String message)`
|
||||
- 修改后：`public void handleXxx(JcppUplinkMessage uplinkMessage)`
|
||||
|
||||
2. 简化消息解析逻辑：
|
||||
- 删除：`JcppUplinkMessage uplinkMessage = JSON.parseObject(message, JcppUplinkMessage.class);`
|
||||
- 直接使用：`uplinkMessage` 参数
|
||||
|
||||
3. 优化日志输出：
|
||||
- 原代码：`log.info("收到 JCPP 登录消息: {}", message);`
|
||||
- 修改后：`log.info("收到 JCPP 登录消息: pileCode={}, messageType={}", uplinkMessage.getPileCode(), uplinkMessage.getMessageType());`
|
||||
|
||||
**修改文件**：
|
||||
- [x] `JcppLoginConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppHeartbeatConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppStartChargeConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppRealTimeDataConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppTransactionConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppGunStatusConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppPricingConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppRemoteResultConsumer.java`：修改方法签名和日志
|
||||
- [x] `JcppSessionCloseConsumer.java`：修改方法签名和日志
|
||||
|
||||
**优势**：
|
||||
1. 代码更简洁：不需要手动解析 JSON 字符串
|
||||
2. 性能更好：减少一次 JSON 解析操作
|
||||
3. 类型安全：编译时就能发现类型错误
|
||||
4. 符合 Spring AMQP 最佳实践：利用消息转换器自动反序列化
|
||||
|
||||
**修复时间**：2025-12-30
|
||||
**状态**：✅ 已修复
|
||||
|
||||
---
|
||||
|
||||
## 四、待完成功能
|
||||
|
||||
### 4.1 订单结算流程 ⚠️
|
||||
|
||||
**优先级**：高
|
||||
**描述**：
|
||||
在 `JcppTransactionConsumer` 中，交易记录处理完成后需要触发订单结算流程，包括：
|
||||
- 计算实际费用（电费 + 服务费）
|
||||
- 扣除会员余额或赠金
|
||||
- 执行分账（商户、平台、站点等）
|
||||
- 发放积分奖励
|
||||
- 生成清算账单
|
||||
|
||||
**待实现**：
|
||||
```java
|
||||
// TODO: 触发结算流程
|
||||
// orderBasicInfoService.realTimeOrderSplit(order.getId());
|
||||
```
|
||||
|
||||
**相关类**：
|
||||
- `OrderBasicInfoServiceImpl.realTimeOrderSplit()`
|
||||
- `StationSplitConfigService`
|
||||
- `OrderSplitRecordService`
|
||||
- `PointsRewardProducer`
|
||||
|
||||
---
|
||||
|
||||
### 4.2 远程启动失败退款 ⚠️
|
||||
|
||||
**优先级**：中
|
||||
**描述**：
|
||||
在 `JcppRemoteResultConsumer` 中，如果远程启动失败且用户已预付费，需要触发退款流程。
|
||||
|
||||
**待实现**：
|
||||
```java
|
||||
// TODO: 如果已预付费，触发退款流程
|
||||
```
|
||||
|
||||
**相关类**：
|
||||
- `MemberWalletInfoService`
|
||||
- `MemberWalletLogService`
|
||||
- 第三方支付退款接口（微信、支付宝）
|
||||
|
||||
---
|
||||
|
||||
### 4.3 会话关闭异常订单处理 ⚠️
|
||||
|
||||
**优先级**：中
|
||||
**描述**：
|
||||
在 `JcppSessionCloseConsumer` 中，当充电桩会话关闭时，需要查询是否有正在充电的订单，如果有则标记为异常结束。
|
||||
|
||||
**待实现**：
|
||||
```java
|
||||
// TODO: 查询是否有正在充电的订单，如果有则标记为异常
|
||||
// 可以调用 OrderBasicInfoService 查询并处理
|
||||
```
|
||||
|
||||
**相关类**：
|
||||
- `OrderBasicInfoService`
|
||||
- `OrderAbnormalRecordService`
|
||||
|
||||
---
|
||||
|
||||
### 4.4 充电桩在线状态管理 ⚠️
|
||||
|
||||
**优先级**：低
|
||||
**描述**：
|
||||
目前在登录和会话关闭时更新充电桩在线状态的代码已注释，需要确认业务逻辑后启用。
|
||||
|
||||
**待确认**：
|
||||
- 是否需要实时更新充电桩在线状态到数据库？
|
||||
- 还是仅通过 Redis 心跳判断在线状态？
|
||||
|
||||
**相关代码**：
|
||||
- `JcppLoginConsumer.java:56-59`（已注释）
|
||||
- `JcppSessionCloseConsumer.java:59`（已注释）
|
||||
|
||||
---
|
||||
|
||||
### 4.5 枪故障信息持久化 ⚠️
|
||||
|
||||
**优先级**：低
|
||||
**描述**：
|
||||
在 `JcppGunStatusConsumer` 中，当接收到枪故障信息时，目前仅记录日志，需要将故障信息保存到数据库或发送告警。
|
||||
|
||||
**待实现**：
|
||||
```java
|
||||
// TODO: 可以将故障信息保存到数据库或发送告警
|
||||
```
|
||||
|
||||
**相关表**：
|
||||
- `pile_connector_info`（可能需要添加故障信息字段）
|
||||
- 或创建新表 `pile_connector_fault_record`
|
||||
|
||||
---
|
||||
|
||||
### 4.6 消息服务接口 ⚠️
|
||||
|
||||
**优先级**：低
|
||||
**描述**：
|
||||
`IJcppMessageService` 和 `JcppMessageServiceImpl` 已创建但功能未完善，可能用于消息查询、重发等功能。
|
||||
|
||||
**待实现**：
|
||||
- 消息历史查询
|
||||
- 消息重发机制
|
||||
- 消息统计分析
|
||||
|
||||
---
|
||||
|
||||
## 五、测试情况
|
||||
|
||||
### 5.1 单元测试
|
||||
- [x] `PricingModelConverterTest`：计费模板转换器测试
|
||||
- [ ] 其他消费者单元测试（待补充）
|
||||
|
||||
### 5.2 集成测试
|
||||
- [ ] 充电桩登录流程测试
|
||||
- [ ] 刷卡启动充电流程测试
|
||||
- [ ] 远程启动充电流程测试
|
||||
- [ ] 充电过程实时数据测试
|
||||
- [ ] 充电完成结算流程测试
|
||||
- [ ] 异常场景测试（网络断开、超时等）
|
||||
|
||||
---
|
||||
|
||||
## 六、部署配置
|
||||
|
||||
### 6.1 RabbitMQ 配置
|
||||
|
||||
**配置文件**：`application-{env}.yml`
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
rabbitmq:
|
||||
host: ${RABBITMQ_HOST}
|
||||
port: 5672
|
||||
username: ${RABBITMQ_USERNAME}
|
||||
password: ${RABBITMQ_PASSWORD}
|
||||
virtual-host: /
|
||||
listener:
|
||||
simple:
|
||||
acknowledge-mode: auto # 自动应答模式
|
||||
concurrency: 1
|
||||
max-concurrency: 20
|
||||
prefetch: 1
|
||||
retry:
|
||||
enabled: true
|
||||
max-attempts: 3
|
||||
initial-interval: 1s
|
||||
max-interval: 10s
|
||||
multiplier: 2.0
|
||||
```
|
||||
|
||||
### 6.2 JCPP 配置
|
||||
|
||||
**配置类**：`JcppConfig`
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class JcppConfig {
|
||||
// JCPP 平台相关配置
|
||||
// 如：API 地址、认证信息等
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、注意事项
|
||||
|
||||
### 7.1 消息幂等性
|
||||
- 所有消费者都需要做幂等性检查，避免重复处理
|
||||
- 目前 `JcppTransactionConsumer` 已实现幂等性检查
|
||||
- 其他消费者需要根据业务场景补充
|
||||
|
||||
### 7.2 事务管理
|
||||
- 涉及数据库操作的消费者需要添加 `@Transactional` 注解
|
||||
- 目前 `JcppStartChargeConsumer`、`JcppTransactionConsumer`、`JcppRemoteResultConsumer` 已添加
|
||||
|
||||
### 7.3 异常处理
|
||||
- 所有消费者都需要捕获异常并记录日志
|
||||
- 避免异常导致消息丢失或重复消费
|
||||
|
||||
### 7.4 性能优化
|
||||
- 实时数据和心跳消息使用 Redis 缓存，避免频繁写数据库
|
||||
- 考虑使用批量更新减少数据库压力
|
||||
|
||||
---
|
||||
|
||||
## 八、后续计划
|
||||
|
||||
### 8.1 短期计划（1-2 周）
|
||||
1. 完成订单结算流程对接
|
||||
2. 实现远程启动失败退款功能
|
||||
3. 完善会话关闭异常订单处理
|
||||
4. 补充单元测试和集成测试
|
||||
|
||||
### 8.2 中期计划（1 个月）
|
||||
1. 优化消息处理性能
|
||||
2. 完善监控和告警机制
|
||||
3. 补充故障信息持久化功能
|
||||
4. 完善消息服务接口
|
||||
|
||||
### 8.3 长期计划（3 个月）
|
||||
1. 支持更多 JCPP 协议功能
|
||||
2. 实现消息重发和补偿机制
|
||||
3. 优化数据统计和报表功能
|
||||
4. 完善运维工具和管理界面
|
||||
|
||||
---
|
||||
|
||||
## 九、联系人
|
||||
|
||||
- **开发负责人**：待补充
|
||||
- **测试负责人**：待补充
|
||||
- **运维负责人**：待补充
|
||||
|
||||
---
|
||||
|
||||
## 十、变更记录
|
||||
|
||||
| 日期 | 版本 | 修改人 | 修改内容 |
|
||||
|------|------|--------|----------|
|
||||
| 2025-12-30 | v1.0 | Claude | 创建文档，记录当前对接进度 |
|
||||
| 2025-12-30 | v1.1 | Claude | 修复消息反序列化错误（第一次） |
|
||||
| 2025-12-30 | v1.2 | Claude | 修复 RabbitMQ 消息转换器冲突（第二次） |
|
||||
| 2025-12-30 | v2.1 | Claude | 实现 JSON 消息分区消费方案 |
|
||||
|
||||
---
|
||||
|
||||
## 十一、JSON 消息分区消费方案（v2.1 新增）
|
||||
|
||||
### 11.1 方案概述
|
||||
|
||||
为了确保同一充电桩的消息按顺序处理，实现了基于 JSON 格式的分区消费方案：
|
||||
|
||||
- **消息格式**：保持原有 JSON 格式，无需 Protobuf
|
||||
- **分区策略**：基于 pileCode 的 Hash 分区
|
||||
- **分区数量**：10 个分区（可配置）
|
||||
- **Hash 算法**：MurmurHash3_128（与 JCPP 保持一致）
|
||||
- **消费模式**：每个分区单线程消费，保证顺序
|
||||
|
||||
### 11.2 核心组件
|
||||
|
||||
#### 11.2.1 分区计算器
|
||||
|
||||
**类名**：`JcppPartitionCalculator`
|
||||
**功能**：
|
||||
- 使用 MurmurHash3_128 算法计算分区
|
||||
- 根据 pileCode 计算分区编号（0 到 partitionCount-1）
|
||||
- 提供队列名称生成方法
|
||||
|
||||
**核心代码**：
|
||||
```java
|
||||
public static int getPartition(String pileCode) {
|
||||
long hash = Hashing.murmur3_128()
|
||||
.hashString(pileCode, StandardCharsets.UTF_8)
|
||||
.asLong();
|
||||
return Math.abs((int) (hash % partitionCount));
|
||||
}
|
||||
```
|
||||
|
||||
#### 11.2.2 分区队列配置
|
||||
|
||||
**类名**：`JcppPartitionQueueConfig`
|
||||
**功能**：
|
||||
- 创建 10 个分区队列（`jcpp.uplink.partition.0` ~ `jcpp.uplink.partition.9`）
|
||||
- 创建 Topic Exchange（`jcpp.uplink.exchange`）
|
||||
- 绑定队列到 Exchange（routing key: `jcpp.uplink.#`）
|
||||
|
||||
#### 11.2.3 JSON 消息消费者
|
||||
|
||||
**类名**：`JcppJsonPartitionConsumer`
|
||||
**功能**：
|
||||
- 监听所有分区队列
|
||||
- 单线程消费（`concurrency=1`）保证顺序
|
||||
- 自动反序列化 JSON 消息为 `JcppUplinkMessage` 对象
|
||||
- 验证分区是否正确
|
||||
- 调用消息处理器处理消息
|
||||
|
||||
#### 11.2.4 消息处理器
|
||||
|
||||
**接口**：`IJcppJsonMessageHandler`
|
||||
**实现类**：`JcppJsonMessageHandlerImpl`
|
||||
**功能**：
|
||||
- 根据消息类型分发处理
|
||||
- 整合原有所有消费者的处理逻辑
|
||||
- 处理登录、心跳、枪状态、充电进度、交易记录、刷卡启动、计费查询、会话关闭、远程操作结果等消息
|
||||
- 复用原有业务逻辑（`PileBasicInfoService`、`OrderBasicInfoService` 等）
|
||||
|
||||
### 11.3 技术栈
|
||||
|
||||
- **Guava**：33.0.0-jre（提供 MurmurHash3_128）
|
||||
- **Spring AMQP**：2.5.14
|
||||
- **RabbitMQ**：5672
|
||||
- **FastJSON2**：2.0.23
|
||||
|
||||
### 11.4 配置说明
|
||||
|
||||
**配置文件**：`application-{env}.yml`
|
||||
|
||||
```yaml
|
||||
# JCPP 配置
|
||||
jcpp:
|
||||
rabbitmq:
|
||||
# 分区数量（与 JCPP 保持一致）
|
||||
partition-count: 10
|
||||
# Exchange 名称
|
||||
exchange: jcpp.uplink.exchange
|
||||
# 队列前缀
|
||||
queue-prefix: jcpp.uplink.partition
|
||||
```
|
||||
|
||||
### 11.5 消息格式
|
||||
|
||||
```json
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"messageType": "LOGIN",
|
||||
"data": "{\"pileCode\":\"20231212000010\",\"remoteAddress\":\"192.168.1.100\"}"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**：
|
||||
- `pileCode`：充电桩编码（用于分区计算）
|
||||
- `messageType`：消息类型
|
||||
- `data`：具体消息内容（JSON 字符串）
|
||||
|
||||
### 11.6 优势
|
||||
|
||||
1. **消息顺序保证**：同一充电桩的消息按顺序处理
|
||||
2. **简单易用**：保持原有 JSON 格式，无需 Protobuf
|
||||
3. **统一处理**：整合所有消息类型的处理逻辑到一个处理器
|
||||
4. **易于调试**：JSON 格式可读性强，便于排查问题
|
||||
5. **可扩展性**：支持动态调整分区数量
|
||||
|
||||
### 11.7 与原有方案的对比
|
||||
|
||||
| 特性 | 原有方案（无分区） | 新方案（分区消费） |
|
||||
|------|------------------|------------------|
|
||||
| 消息格式 | JSON 字符串 | JSON 字符串 |
|
||||
| 消息顺序 | 不保证 | 保证同一 pileCode 顺序 |
|
||||
| 分区消费 | 不支持 | 支持 |
|
||||
| 并发处理 | 多消费者并发 | 每个分区单线程 |
|
||||
| 代码复杂度 | 多个独立消费者 | 统一消息处理器 |
|
||||
| 易于调试 | 较难 | 较易 |
|
||||
|
||||
### 11.8 部署步骤
|
||||
|
||||
1. **更新配置**：在 `application-{env}.yml` 中添加 JCPP 配置
|
||||
2. **启动应用**：应用会自动创建 10 个分区队列
|
||||
3. **JCPP 端配置**：确保 JCPP 使用相同的 Hash 算法和分区数量
|
||||
4. **验证测试**：发送测试消息，验证分区路由和消息处理
|
||||
|
||||
### 11.9 注意事项
|
||||
|
||||
1. **分区数量**：必须与 JCPP 保持一致，建议在系统初始化时确定，后续不要修改
|
||||
2. **Hash 算法**：必须使用 MurmurHash3_128，与 JCPP 保持一致
|
||||
3. **消息顺序**：每个分区单线程消费（`concurrency=1`），不要修改此配置
|
||||
4. **异常处理**：JSON 解析失败会抛出异常，建议配置死信队列
|
||||
5. **性能监控**：监控队列堆积、消费延迟、错误率等指标
|
||||
|
||||
### 11.10 相关文档
|
||||
|
||||
详细使用说明请参考：[JCPP JSON 消息分区消费方案](JCPP_JSON消息分区消费方案.md)
|
||||
|
||||
---
|
||||
|
||||
## 十、变更记录
|
||||
402
docs/JCPP项目配合实现Prompt.md
Normal file
402
docs/JCPP项目配合实现Prompt.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# JCPP 项目充电桩数据同步接口实现 Prompt
|
||||
|
||||
> 请将以下内容复制给 JCPP 项目的 Claude Code 执行
|
||||
|
||||
---
|
||||
|
||||
## 任务概述
|
||||
|
||||
需要在 JCPP 项目中实现充电桩数据同步接口，用于接收来自 Web 项目的充电桩和充电枪数据。
|
||||
|
||||
## 背景说明
|
||||
|
||||
Web 项目（MySQL）中维护了充电桩的主数据，现在需要将这些数据同步到 JCPP 项目（PostgreSQL）中，用于登录鉴权等操作。
|
||||
|
||||
### 数据流向
|
||||
```
|
||||
Web 项目 (MySQL) → HTTP API → JCPP 项目 (PostgreSQL)
|
||||
```
|
||||
|
||||
### 关键差异
|
||||
1. **主键类型**：Web 使用 int，JCPP 使用 uuid
|
||||
2. **station_id 类型**：Web 是 int，JCPP 是 uuid（需要映射）
|
||||
3. **字段名称**：sn → pile_code, name → pile_name
|
||||
|
||||
---
|
||||
|
||||
## 需要实现的功能
|
||||
|
||||
### 1. 认证接口
|
||||
|
||||
**接口路径**：`POST /api/auth/login`
|
||||
|
||||
**请求格式**：
|
||||
```json
|
||||
{
|
||||
"username": "sanbing",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应格式**：
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"expiresIn": 1800
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- 用于 Web 项目获取访问令牌
|
||||
- token 有效期 30 分钟
|
||||
- Web 项目会将 token 缓存在 Redis 中
|
||||
|
||||
---
|
||||
|
||||
### 2. 充电桩同步接口
|
||||
|
||||
**接口路径**：`POST /api/sync/piles`
|
||||
|
||||
**认证方式**：Bearer Token（在请求头中添加 `Authorization: Bearer {token}`）
|
||||
|
||||
**重要说明**：
|
||||
- ✅ 所有充电桩的 `station_id` 统一使用固定值：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- Web 项目的原始 station_id 保存在 `additionalInfo.webStationId` 中便于追溯
|
||||
|
||||
**请求格式**：
|
||||
```json
|
||||
{
|
||||
"piles": [
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"pileName": "1号充电桩",
|
||||
"protocol": "yunkuaichongV150",
|
||||
"brand": "特来电",
|
||||
"model": "AC-7KW",
|
||||
"manufacturer": "特来电",
|
||||
"type": "OPERATION",
|
||||
"additionalInfo": {
|
||||
"webPileId": 6844,
|
||||
"webStationId": 123,
|
||||
"businessType": "1",
|
||||
"secretKey": "abc123",
|
||||
"longitude": "116.404",
|
||||
"latitude": "39.915",
|
||||
"iccid": "89860123456789012345"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**：
|
||||
- `pileCode`：充电桩编码（对应 Web 的 sn），唯一标识
|
||||
- `pileName`：充电桩名称（对应 Web 的 name）
|
||||
- `protocol`：软件协议（对应 Web 的 software_protocol）
|
||||
- `brand`：品牌（可为空）
|
||||
- `model`：型号（可为空）
|
||||
- `manufacturer`：制造商（可为空）
|
||||
- `type`：类型，枚举值：
|
||||
- `OPERATION`：运营桩（对应 Web 的 business_type = "1"）
|
||||
- `PERSONAL`：个人桩（对应 Web 的 business_type = "2"）
|
||||
- `additionalInfo`：附加信息（JSON 格式），包含：
|
||||
- `webPileId`：Web 项目的充电桩 ID
|
||||
- `webStationId`：Web 项目的充电站 ID（原始 int 值）
|
||||
- 其他 Web 项目的字段
|
||||
|
||||
**响应格式**：
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "同步成功",
|
||||
"results": [
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"pileId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"success": true,
|
||||
"message": "创建成功"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**处理逻辑**：
|
||||
1. 遍历 `piles` 数组
|
||||
2. 对于每个充电桩：
|
||||
- 根据 `pileCode` 查询 `t_pile` 表，判断是否已存在
|
||||
- **station_id 统一使用固定值**：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 如果充电桩已存在，执行 UPDATE 操作
|
||||
- 如果充电桩不存在，执行 INSERT 操作（生成新的 uuid）
|
||||
- 将 `additionalInfo` 存储为 jsonb 类型
|
||||
3. 返回每个充电桩的处理结果
|
||||
|
||||
**注意事项**：
|
||||
- 使用事务保证数据一致性
|
||||
- pile_code 必须唯一（已有唯一索引）
|
||||
- 所有充电桩的 station_id 都使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- **需要验证 Authorization 请求头中的 token**
|
||||
- token 无效时返回 401 Unauthorized
|
||||
|
||||
---
|
||||
|
||||
### 3. 充电枪同步接口
|
||||
|
||||
**接口路径**：`POST /api/sync/guns`
|
||||
|
||||
**认证方式**：Bearer Token（在请求头中添加 `Authorization: Bearer {token}`）
|
||||
|
||||
**重要说明**：
|
||||
- ✅ 所有充电枪的 `station_id` 统一使用固定值：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
|
||||
**请求格式**：
|
||||
```json
|
||||
{
|
||||
"guns": [
|
||||
{
|
||||
"gunCode": "2023121200001001",
|
||||
"gunName": "1号枪",
|
||||
"gunNo": "01",
|
||||
"pileCode": "20231212000010",
|
||||
"additionalInfo": {
|
||||
"webGunId": 30060,
|
||||
"status": "1",
|
||||
"parkNo": "A01"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**：
|
||||
- `gunCode`：充电枪编码（对应 Web 的 pile_connector_code），唯一标识
|
||||
- `gunName`：充电枪名称（对应 Web 的 name）
|
||||
- `gunNo`：枪号（从 gunCode 提取最后 2 位）
|
||||
- `pileCode`：所属充电桩编码（对应 Web 的 pile_sn）
|
||||
- `additionalInfo`：附加信息（JSON 格式），包含 Web 项目的其他字段
|
||||
|
||||
**响应格式**：
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "同步成功",
|
||||
"results": [
|
||||
{
|
||||
"gunCode": "2023121200001001",
|
||||
"gunId": "660e8400-e29b-41d4-a716-446655440000",
|
||||
"success": true,
|
||||
"message": "创建成功"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**处理逻辑**：
|
||||
1. 遍历 `guns` 数组
|
||||
2. 对于每个充电枪：
|
||||
- 根据 `gunCode` 查询 `t_gun` 表，判断是否已存在
|
||||
- 根据 `pileCode` 查询 `t_pile` 表，获取 `pile_id` (uuid)
|
||||
- 如果充电桩不存在，记录错误并跳过该充电枪
|
||||
- **station_id 统一使用固定值**：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 如果充电枪已存在，执行 UPDATE 操作
|
||||
- 如果充电枪不存在，执行 INSERT 操作（生成新的 uuid）
|
||||
3. 返回每个充电枪的处理结果
|
||||
|
||||
**注意事项**：
|
||||
- 充电桩必须先于充电枪同步
|
||||
- gun_code 必须唯一（已有唯一索引）
|
||||
- (pile_id, gun_no) 组合必须唯一（已有唯一索引）
|
||||
- 所有充电枪的 station_id 都使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- **需要验证 Authorization 请求头中的 token**
|
||||
- token 无效时返回 401 Unauthorized
|
||||
|
||||
---
|
||||
|
||||
## 实现建议
|
||||
|
||||
### 技术栈
|
||||
- **框架**：Spring Boot
|
||||
- **数据库**：PostgreSQL 17
|
||||
- **ORM**：JPA / MyBatis
|
||||
- **JSON 处理**：Jackson / Gson
|
||||
|
||||
### 代码结构建议
|
||||
|
||||
```
|
||||
src/main/java/com/jcpp/
|
||||
├── controller/
|
||||
│ ├── AuthController.java # 认证接口 Controller
|
||||
│ └── SyncController.java # 同步接口 Controller
|
||||
├── service/
|
||||
│ ├── AuthService.java # 认证服务接口
|
||||
│ ├── PileSyncService.java # 充电桩同步服务接口
|
||||
│ └── GunSyncService.java # 充电枪同步服务接口
|
||||
├── service/impl/
|
||||
│ ├── AuthServiceImpl.java
|
||||
│ ├── PileSyncServiceImpl.java
|
||||
│ └── GunSyncServiceImpl.java
|
||||
├── entity/
|
||||
│ ├── Pile.java # t_pile 实体
|
||||
│ └── Gun.java # t_gun 实体
|
||||
├── repository/
|
||||
│ ├── PileRepository.java
|
||||
│ └── GunRepository.java
|
||||
├── dto/
|
||||
│ ├── LoginRequest.java # 登录请求
|
||||
│ ├── LoginResponse.java # 登录响应
|
||||
│ ├── PileSyncDTO.java # 充电桩同步 DTO
|
||||
│ ├── GunSyncDTO.java # 充电枪同步 DTO
|
||||
│ ├── SyncRequest.java # 同步请求
|
||||
│ └── SyncResponse.java # 同步响应
|
||||
└── security/
|
||||
└── JwtTokenProvider.java # JWT Token 生成和验证
|
||||
```
|
||||
|
||||
### 关键代码示例
|
||||
|
||||
**PileSyncService 接口**：
|
||||
```java
|
||||
public interface PileSyncService {
|
||||
/**
|
||||
* 同步充电桩数据
|
||||
* @param piles 充电桩列表
|
||||
* @return 同步结果
|
||||
*/
|
||||
SyncResponse syncPiles(List<PileSyncDTO> piles);
|
||||
}
|
||||
```
|
||||
|
||||
**处理逻辑伪代码**：
|
||||
```java
|
||||
@Transactional
|
||||
public SyncResponse syncPiles(List<PileSyncDTO> piles) {
|
||||
List<SyncResult> results = new ArrayList<>();
|
||||
|
||||
// 固定的 station_id
|
||||
UUID FIXED_STATION_ID = UUID.fromString("88bca8da-cdbf-6587-aecc-75784838c501");
|
||||
|
||||
for (PileSyncDTO dto : piles) {
|
||||
try {
|
||||
// 1. 查询充电桩是否存在
|
||||
Pile existingPile = pileRepository.findByPileCode(dto.getPileCode());
|
||||
|
||||
if (existingPile != null) {
|
||||
// 更新
|
||||
existingPile.setPileName(dto.getPileName());
|
||||
existingPile.setProtocol(dto.getProtocol());
|
||||
existingPile.setStationId(FIXED_STATION_ID); // 使用固定值
|
||||
existingPile.setBrand(dto.getBrand());
|
||||
existingPile.setModel(dto.getModel());
|
||||
existingPile.setManufacturer(dto.getManufacturer());
|
||||
existingPile.setType(dto.getType());
|
||||
existingPile.setAdditionalInfo(dto.getAdditionalInfo());
|
||||
existingPile.setUpdatedTime(new Date());
|
||||
pileRepository.save(existingPile);
|
||||
results.add(SyncResult.success(dto.getPileCode(), existingPile.getId(), "更新成功"));
|
||||
} else {
|
||||
// 创建
|
||||
Pile newPile = new Pile();
|
||||
newPile.setId(UUID.randomUUID());
|
||||
newPile.setPileCode(dto.getPileCode());
|
||||
newPile.setPileName(dto.getPileName());
|
||||
newPile.setProtocol(dto.getProtocol());
|
||||
newPile.setStationId(FIXED_STATION_ID); // 使用固定值
|
||||
newPile.setBrand(dto.getBrand());
|
||||
newPile.setModel(dto.getModel());
|
||||
newPile.setManufacturer(dto.getManufacturer());
|
||||
newPile.setType(dto.getType());
|
||||
newPile.setAdditionalInfo(dto.getAdditionalInfo());
|
||||
newPile.setCreatedTime(new Date());
|
||||
pileRepository.save(newPile);
|
||||
results.add(SyncResult.success(dto.getPileCode(), newPile.getId(), "创建成功"));
|
||||
}
|
||||
} catch (Exception e) {
|
||||
results.add(SyncResult.fail(dto.getPileCode(), e.getMessage()));
|
||||
}
|
||||
}
|
||||
|
||||
return SyncResponse.build(results);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 1. 单元测试
|
||||
- 测试 station_id 映射查询
|
||||
- 测试充电桩创建
|
||||
- 测试充电桩更新
|
||||
- 测试充电枪创建
|
||||
- 测试充电枪更新
|
||||
|
||||
### 2. 集成测试
|
||||
- 测试完整的同步流程
|
||||
- 测试异常场景（映射不存在、充电桩不存在等）
|
||||
- 测试并发同步
|
||||
|
||||
### 3. 性能测试
|
||||
- 测试批量同步性能（100、500、1000 条数据）
|
||||
- 测试数据库连接池配置
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **事务处理**
|
||||
- 每批数据使用一个事务
|
||||
- 单个充电桩失败不影响其他充电桩
|
||||
|
||||
2. **错误处理**
|
||||
- 记录详细的错误信息
|
||||
- 返回明确的错误原因
|
||||
|
||||
3. **日志记录**
|
||||
- 记录同步开始和结束时间
|
||||
- 记录成功和失败的数量
|
||||
- 记录详细的错误日志
|
||||
|
||||
4. **性能优化**
|
||||
- 使用批量查询减少数据库访问
|
||||
- 合理设置数据库连接池大小
|
||||
- 考虑使用缓存优化映射查询
|
||||
|
||||
5. **安全性**
|
||||
- 添加接口鉴权（JWT Token）
|
||||
- 验证请求数据的合法性
|
||||
- 防止 SQL 注入
|
||||
- token 有效期 30 分钟
|
||||
|
||||
---
|
||||
|
||||
## 交付物
|
||||
|
||||
1. **代码**
|
||||
- Controller、Service、Repository、Entity、DTO 等完整代码
|
||||
- 单元测试代码
|
||||
|
||||
2. **接口文档**
|
||||
- Swagger / OpenAPI 文档
|
||||
- 接口调用示例
|
||||
|
||||
3. **部署说明**
|
||||
- 配置项说明
|
||||
- 部署步骤
|
||||
|
||||
---
|
||||
|
||||
## 联调准备
|
||||
|
||||
完成实现后，请提供：
|
||||
1. 接口地址（如：http://jcpp-server:8080/api/sync）
|
||||
2. 测试账号（如果需要鉴权）
|
||||
3. 测试数据示例
|
||||
|
||||
**重要提醒**：
|
||||
- 确保 JCPP 数据库中已存在 station_id 为 `88bca8da-cdbf-6587-aecc-75784838c501` 的充电站记录
|
||||
- 如果不存在，需要先创建该充电站记录
|
||||
|
||||
---
|
||||
|
||||
## 问题反馈
|
||||
|
||||
如有任何问题或需要澄清的地方，请及时反馈。
|
||||
272
docs/Web项目充电桩同步功能实现总结.md
Normal file
272
docs/Web项目充电桩同步功能实现总结.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Web 项目充电桩数据同步功能实现总结
|
||||
|
||||
> 完成时间：2025-12-30
|
||||
> 状态：✅ Web 项目部分已完成，等待 JCPP 项目配合
|
||||
|
||||
---
|
||||
|
||||
## 一、已完成功能
|
||||
|
||||
### 1. DTO 数据传输对象 ✅
|
||||
|
||||
**位置**：`jsowell-pile/src/main/java/com/jsowell/pile/jcpp/dto/sync/`
|
||||
|
||||
| 文件名 | 说明 |
|
||||
|--------|------|
|
||||
| `JcppPileSyncDTO.java` | 充电桩同步数据 DTO |
|
||||
| `JcppGunSyncDTO.java` | 充电枪同步数据 DTO |
|
||||
| `JcppSyncRequest.java` | 同步请求 DTO |
|
||||
| `JcppSyncResponse.java` | 同步响应 DTO |
|
||||
| `JcppSyncResult.java` | 单个同步结果 DTO |
|
||||
|
||||
### 2. 数据库表和 Mapper ✅
|
||||
|
||||
**建表 SQL**：`sql/jcpp_sync_record.sql`
|
||||
|
||||
**Domain 实体**：`jsowell-pile/src/main/java/com/jsowell/pile/domain/JcppSyncRecord.java`
|
||||
|
||||
**Mapper 接口**：`jsowell-pile/src/main/java/com/jsowell/pile/mapper/JcppSyncRecordMapper.java`
|
||||
|
||||
**Mapper XML**：`jsowell-pile/src/main/resources/mapper/pile/JcppSyncRecordMapper.xml`
|
||||
|
||||
### 3. 同步服务 ✅
|
||||
|
||||
**服务接口**：`jsowell-pile/src/main/java/com/jsowell/pile/jcpp/service/IJcppPileSyncService.java`
|
||||
|
||||
**服务实现**：`jsowell-pile/src/main/java/com/jsowell/pile/jcpp/service/impl/JcppPileSyncServiceImpl.java`
|
||||
|
||||
**核心功能**：
|
||||
- ✅ 全量同步充电桩数据
|
||||
- ✅ 增量同步充电桩数据（基于 update_time）
|
||||
- ✅ 单个充电桩同步
|
||||
- ✅ 数据格式转换（Web → JCPP）
|
||||
- ✅ 调用 JCPP 同步接口
|
||||
- ✅ 同步记录管理
|
||||
|
||||
### 4. Controller 接口 ✅
|
||||
|
||||
**控制器**：`jsowell-admin/src/main/java/com/jsowell/web/controller/jcpp/JcppPileSyncController.java`
|
||||
|
||||
**API 接口**：
|
||||
|
||||
| 方法 | 路径 | 说明 | 权限 |
|
||||
|------|------|------|------|
|
||||
| POST | `/jcpp/sync/full` | 全量同步 | `jcpp:sync:full` |
|
||||
| POST | `/jcpp/sync/incremental` | 增量同步 | `jcpp:sync:incremental` |
|
||||
| POST | `/jcpp/sync/pile/{pileSn}` | 单个充电桩同步 | `jcpp:sync:single` |
|
||||
| GET | `/jcpp/sync/records` | 查询同步记录列表 | `jcpp:sync:list` |
|
||||
| GET | `/jcpp/sync/records/{id}` | 查询同步记录详情 | `jcpp:sync:query` |
|
||||
|
||||
### 5. 配置项 ✅
|
||||
|
||||
**配置文件**：`jsowell-admin/src/main/resources/application-sit.yml`
|
||||
|
||||
```yaml
|
||||
jcpp:
|
||||
sync:
|
||||
# JCPP 同步接口地址
|
||||
api-url: http://localhost:8080/api/sync
|
||||
# 批量同步大小
|
||||
batch-size: 100
|
||||
# 超时时间（毫秒）
|
||||
timeout: 60000
|
||||
# 是否启用自动增量同步
|
||||
auto-sync-enabled: false
|
||||
# 自动同步间隔（分钟）
|
||||
auto-sync-interval: 30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、核心实现逻辑
|
||||
|
||||
### 1. 数据转换逻辑
|
||||
|
||||
#### 充电桩数据转换
|
||||
```java
|
||||
Web (pile_basic_info) → JCPP (t_pile)
|
||||
- sn → pileCode
|
||||
- name → pileName
|
||||
- software_protocol → protocol
|
||||
- business_type → type (1→OPERATION, 2→PERSONAL)
|
||||
- 其他字段 → additionalInfo (JSON)
|
||||
- station_id → 固定值 '88bca8da-cdbf-6587-aecc-75784838c501'
|
||||
```
|
||||
|
||||
#### 充电枪数据转换
|
||||
```java
|
||||
Web (pile_connector_info) → JCPP (t_gun)
|
||||
- pile_connector_code → gunCode
|
||||
- name → gunName
|
||||
- pile_sn → pileCode
|
||||
- 最后2位 → gunNo
|
||||
- 其他字段 → additionalInfo (JSON)
|
||||
- station_id → 固定值 '88bca8da-cdbf-6587-aecc-75784838c501'
|
||||
```
|
||||
|
||||
### 2. 同步流程
|
||||
|
||||
#### 全量同步
|
||||
1. 创建同步记录（状态：RUNNING）
|
||||
2. 查询所有未删除的充电桩和充电枪
|
||||
3. 转换数据格式
|
||||
4. 调用 JCPP 同步接口
|
||||
- 先同步充电桩（POST /api/sync/piles）
|
||||
- 再同步充电枪（POST /api/sync/guns）
|
||||
5. 更新同步记录（状态：SUCCESS/FAILED）
|
||||
|
||||
#### 增量同步
|
||||
1. 获取上次同步时间（参数或查询最后一次成功记录）
|
||||
2. 查询 update_time > lastSyncTime 的数据
|
||||
3. 其他步骤同全量同步
|
||||
|
||||
#### 单个充电桩同步
|
||||
1. 查询指定充电桩及其所有充电枪
|
||||
2. 转换数据格式
|
||||
3. 调用 JCPP 同步接口
|
||||
|
||||
### 3. 错误处理
|
||||
|
||||
- ✅ 接口调用异常捕获
|
||||
- ✅ 单个数据失败不影响其他数据
|
||||
- ✅ 详细的错误信息记录
|
||||
- ✅ 同步记录状态管理
|
||||
|
||||
---
|
||||
|
||||
## 三、使用说明
|
||||
|
||||
### 1. 数据库初始化
|
||||
|
||||
执行建表 SQL：
|
||||
```bash
|
||||
mysql -u username -p database_name < sql/jcpp_sync_record.sql
|
||||
```
|
||||
|
||||
### 2. 配置 JCPP 接口地址
|
||||
|
||||
修改 `application-sit.yml`：
|
||||
```yaml
|
||||
jcpp:
|
||||
sync:
|
||||
api-url: http://jcpp-server:8080/api/sync # 修改为实际地址
|
||||
```
|
||||
|
||||
### 3. API 调用示例
|
||||
|
||||
#### 全量同步
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/jcpp/sync/full \
|
||||
-H "Authorization: Bearer {token}"
|
||||
```
|
||||
|
||||
#### 增量同步
|
||||
```bash
|
||||
curl -X POST "http://localhost:8080/jcpp/sync/incremental?lastSyncTime=2025-12-30 10:00:00" \
|
||||
-H "Authorization: Bearer {token}"
|
||||
```
|
||||
|
||||
#### 单个充电桩同步
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/jcpp/sync/pile/20231212000010 \
|
||||
-H "Authorization: Bearer {token}"
|
||||
```
|
||||
|
||||
#### 查询同步记录
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/jcpp/sync/records?pageNum=1&pageSize=10" \
|
||||
-H "Authorization: Bearer {token}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、待完成事项
|
||||
|
||||
### 1. JCPP 项目需要实现 ⏳
|
||||
|
||||
请参考文档：`doc/JCPP项目配合实现Prompt.md`
|
||||
|
||||
需要实现的接口：
|
||||
- [ ] POST /api/sync/piles - 充电桩同步接口
|
||||
- [ ] POST /api/sync/guns - 充电枪同步接口
|
||||
|
||||
**重要提醒**：
|
||||
- 所有充电桩和充电枪的 station_id 统一使用固定值：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 确保 JCPP 数据库中已存在该 station_id 的充电站记录
|
||||
|
||||
### 2. 联调测试 ⏳
|
||||
|
||||
- [ ] 测试全量同步功能
|
||||
- [ ] 测试增量同步功能
|
||||
- [ ] 测试单个充电桩同步
|
||||
- [ ] 测试异常场景（网络异常、数据异常等）
|
||||
- [ ] 性能测试（大批量数据同步）
|
||||
|
||||
### 3. 优化项（可选）
|
||||
|
||||
- [ ] 添加按 update_time 查询的 Mapper 方法（提升增量同步性能）
|
||||
- [ ] 添加重试机制（网络异常时自动重试）
|
||||
- [ ] 添加同步进度查询（异步任务）
|
||||
- [ ] 添加定时自动同步（基于配置）
|
||||
- [ ] 添加同步数据校验（数据完整性检查）
|
||||
|
||||
---
|
||||
|
||||
## 五、技术要点
|
||||
|
||||
### 1. 固定 station_id 方案
|
||||
|
||||
**优势**：
|
||||
- ✅ 简化实现，无需维护映射表
|
||||
- ✅ 减少接口调用次数
|
||||
- ✅ 降低系统复杂度
|
||||
|
||||
**注意事项**：
|
||||
- Web 的原始 station_id 保存在 additionalInfo.webStationId 中
|
||||
- 便于后续追溯和数据分析
|
||||
|
||||
### 2. 数据转换
|
||||
|
||||
**business_type 映射**：
|
||||
- "1" → "OPERATION"（运营桩）
|
||||
- "2" → "PERSONAL"（个人桩）
|
||||
|
||||
**gun_no 提取**：
|
||||
- pile_connector_code: "2023121200001001"
|
||||
- gun_no: "01"（最后 2 位）
|
||||
|
||||
### 3. 同步记录
|
||||
|
||||
**状态**：
|
||||
- RUNNING：进行中
|
||||
- SUCCESS：成功
|
||||
- FAILED：失败
|
||||
|
||||
**统计信息**：
|
||||
- 总数、成功数、失败数（充电桩和充电枪分别统计）
|
||||
- 错误信息列表
|
||||
|
||||
---
|
||||
|
||||
## 六、相关文档
|
||||
|
||||
- [充电桩数据同步需求.md](充电桩数据同步需求.md) - 原始需求
|
||||
- [充电桩数据同步实现计划.md](充电桩数据同步实现计划.md) - 详细实现计划
|
||||
- [JCPP项目配合实现Prompt.md](JCPP项目配合实现Prompt.md) - 给 JCPP 项目的实现指南
|
||||
- [JCPP对接进度文档.md](JCPP对接进度文档.md) - JCPP 整体对接进度
|
||||
|
||||
---
|
||||
|
||||
## 七、问题反馈
|
||||
|
||||
如有任何问题，请及时反馈：
|
||||
1. 接口调用异常
|
||||
2. 数据转换错误
|
||||
3. 性能问题
|
||||
4. 其他技术问题
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v1.0
|
||||
**最后更新**：2025-12-30
|
||||
**维护人员**：jsowell 团队
|
||||
266
docs/improve_record.md
Normal file
266
docs/improve_record.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# 充电桩频繁登录问题优化记录
|
||||
|
||||
## 问题背景
|
||||
|
||||
**发生时间**: 2026-03-21 06:00 左右
|
||||
|
||||
**问题描述**: 充电桩出现频繁登录的情况
|
||||
|
||||
**初步原因**: 项目没有及时回复桩端的心跳消息，未及时回复超过 3 次后桩端会发起重连
|
||||
|
||||
---
|
||||
|
||||
## 问题分析
|
||||
|
||||
### 问题 1: Pipeline 配置存在潜在阻塞点（最关键）
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java:41`
|
||||
|
||||
**问题描述**:
|
||||
- `nettyServerHandler` 绑定到 `businessGroup` 线程池（32 线程）
|
||||
- 但 `echoServerHandler` **没有绑定到任何 EventExecutorGroup**，它会在 **IO 线程**（Worker 线程）中执行
|
||||
- 如果 IO 线程被其他任务阻塞，心跳回复就无法及时发送
|
||||
|
||||
**影响**: 这是导致心跳回复不及时的最主要原因！
|
||||
|
||||
---
|
||||
|
||||
### 问题 2: 心跳处理中存在阻塞的数据库操作
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/HeartbeatRequestHandler.java:54`
|
||||
|
||||
**问题描述**:
|
||||
- `saveLastTimeAndCheckChannel()` 是**同步**执行的，包含 Redis 写操作
|
||||
- 如果 Redis 响应慢，会阻塞心跳响应
|
||||
|
||||
---
|
||||
|
||||
### 问题 3: `PileChannelEntity.checkChannel()` 使用同步阻塞遍历
|
||||
|
||||
**文件**: `jsowell-common/src/main/java/com/jsowell/common/enums/ykc/PileChannelEntity.java:108-115`
|
||||
|
||||
**问题描述**:
|
||||
- `getPileSnByChannelId()` 使用线性遍历整个 `manager.entrySet()`
|
||||
- 当连接数很多时，这个遍历操作会很慢，并且会阻塞执行线程
|
||||
|
||||
---
|
||||
|
||||
### 问题 4: 线程池配置可能导致任务堆积
|
||||
|
||||
**文件**: `jsowell-framework/src/main/java/com/jsowell/framework/config/ThreadPoolConfig.java:63`
|
||||
|
||||
**问题描述**:
|
||||
- 使用 `CallerRunsPolicy` 拒绝策略，当队列满时，任务会在调用者线程中执行
|
||||
- 如果 Netty 的 IO 线程或 businessGroup 线程作为调用者，会**阻塞这些关键线程**！
|
||||
|
||||
---
|
||||
|
||||
## 优化方案
|
||||
|
||||
### 优化 1: 修复 Pipeline 配置（优先级：P0）✅ 已完成
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java:41`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
// 修改前
|
||||
pipeline.addLast(businessGroup, nettyServerHandler);
|
||||
pipeline.addLast(echoServerHandler);
|
||||
|
||||
// 修改后
|
||||
pipeline.addLast(businessGroup, nettyServerHandler);
|
||||
pipeline.addLast(businessGroup, echoServerHandler); // 回复Handler也绑定到业务线程池
|
||||
```
|
||||
|
||||
**效果**: 避免心跳回复被 IO 线程阻塞
|
||||
|
||||
---
|
||||
|
||||
### 优化 2: 优化 PileChannelEntity 使用双向映射（优先级：P0）✅ 已完成
|
||||
|
||||
**文件**: `jsowell-common/src/main/java/com/jsowell/common/enums/ykc/PileChannelEntity.java`
|
||||
|
||||
**修改内容**:
|
||||
1. 新增反向映射 `channelIdToPileSnMap`
|
||||
2. `getPileSnByChannelId()` 从 O(n) 优化到 O(1)
|
||||
3. 同步维护反向映射（checkChannel、removeByPileSn、removeByChannelId）
|
||||
4. 新增 `removeByPileSnAndChannelId()` 安全删除方法
|
||||
|
||||
**效果**: 当连接数多时，查询性能大幅提升
|
||||
|
||||
---
|
||||
|
||||
### 优化 3: 修改线程池拒绝策略（优先级：P1）✅ 已完成
|
||||
|
||||
**文件**: `jsowell-framework/src/main/java/com/jsowell/framework/config/ThreadPoolConfig.java`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
// 修改前
|
||||
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
|
||||
private final int queueCapacity = 2000;
|
||||
|
||||
// 修改后
|
||||
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.DiscardOldestPolicy());
|
||||
private final int queueCapacity = 5000; // 增大队列容量
|
||||
```
|
||||
|
||||
**效果**: 避免阻塞关键线程（Netty IO 线程、业务线程池）
|
||||
|
||||
---
|
||||
|
||||
### 优化 4: 心跳处理完全异步化（优先级：P1）✅ 已完成
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/HeartbeatRequestHandler.java:67-85`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
// 修改前：saveLastTimeAndCheckChannel 同步执行
|
||||
saveLastTimeAndCheckChannel(pileSn, channel);
|
||||
CompletableFuture.runAsync(() -> updateStatus(...), executor);
|
||||
|
||||
// 修改后：先返回心跳应答，再异步处理
|
||||
byte[] response = getResult(ykcDataProtocol, messageBody);
|
||||
CompletableFuture.runAsync(() -> {
|
||||
saveLastTimeAndCheckChannel(pileSn, channel);
|
||||
pileBasicInfoService.updateStatus(...);
|
||||
}, executor);
|
||||
return response;
|
||||
```
|
||||
|
||||
**效果**: 心跳回复不受 Redis/数据库操作影响
|
||||
|
||||
---
|
||||
|
||||
### 优化 5: 增加心跳处理耗时监控（优先级：P2）✅ 已完成
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java:81-127`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
@Override
|
||||
public void channelRead(ChannelHandlerContext ctx, Object message) throws Exception {
|
||||
long startTime = System.currentTimeMillis();
|
||||
|
||||
try {
|
||||
// ... 原有代码 ...
|
||||
} finally {
|
||||
ReferenceCountUtil.release(message);
|
||||
|
||||
// 性能监控：记录消息处理耗时
|
||||
long elapsed = System.currentTimeMillis() - startTime;
|
||||
String frameType = ctx.channel().attr(LAST_FRAME_TYPE).get();
|
||||
// 心跳帧(0x03)处理超过50ms警告，其他帧超过200ms警告
|
||||
int warnThreshold = "0x03".equals(frameType) ? 50 : 200;
|
||||
if (elapsed > warnThreshold) {
|
||||
log.warn("【性能警告】消息处理耗时: {}ms, 帧类型: {}, channelId: {}",
|
||||
elapsed, frameType, ctx.channel().id().asLongText());
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**效果**: 便于后续排查性能问题
|
||||
|
||||
---
|
||||
|
||||
## 额外优化（团队完成）
|
||||
|
||||
### 优化 6: IdleStateHandler 超时调整
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java:38`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
// 修改前
|
||||
pipeline.addLast(new IdleStateHandler(30, 0, 0, TimeUnit.SECONDS));
|
||||
|
||||
// 修改后
|
||||
pipeline.addLast(new IdleStateHandler(15, 0, 0, TimeUnit.SECONDS)); // 读空闲tick设置为15s，连续3次空闲后再由handler执行关闭
|
||||
```
|
||||
|
||||
**效果**: 更快检测到心跳超时，及时处理连接异常
|
||||
|
||||
---
|
||||
|
||||
### 优化 7: 新增连接管理 AttributeKey
|
||||
|
||||
**文件**: `jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java:40-48`
|
||||
|
||||
**修改内容**:
|
||||
```java
|
||||
public static final AttributeKey<Integer> IDLE_COUNT = AttributeKey.valueOf("ykc_idle_count");
|
||||
public static final AttributeKey<String> LAST_FRAME_TYPE = AttributeKey.valueOf("ykc_last_frame_type");
|
||||
public static final AttributeKey<String> LAST_RECEIVE_AT = AttributeKey.valueOf("ykc_last_receive_at");
|
||||
public static final AttributeKey<String> LAST_SERIAL_NUMBER = AttributeKey.valueOf("ykc_last_serial_number");
|
||||
public static final AttributeKey<String> DISCONNECT_REASON = AttributeKey.valueOf("ykc_disconnect_reason");
|
||||
```
|
||||
|
||||
**效果**: 更精细的连接管理和断开原因追踪
|
||||
|
||||
---
|
||||
|
||||
## 修改文件清单
|
||||
|
||||
| 序号 | 文件路径 | 修改内容 | 状态 |
|
||||
|------|----------|----------|------|
|
||||
| 1 | `jsowell-netty/.../NettyServerChannelInitializer.java` | EchoServerHandler 绑定到业务线程池<br>IdleStateHandler 从 30s 调整为 15s | ✅ 完成 |
|
||||
| 2 | `jsowell-common/.../PileChannelEntity.java` | 新增反向映射，优化查询性能<br>新增 removeByPileSnAndChannelId 方法 | ✅ 完成 |
|
||||
| 3 | `jsowell-framework/.../ThreadPoolConfig.java` | 修改拒绝策略，增大队列容量 | ✅ 完成 |
|
||||
| 4 | `jsowell-netty/.../HeartbeatRequestHandler.java` | 心跳处理完全异步化 | ✅ 完成 |
|
||||
| 5 | `jsowell-netty/.../NettyServerHandler.java` | 增加消息处理耗时监控<br>新增 AttributeKey 用于连接管理 | ✅ 完成 |
|
||||
|
||||
---
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 1. 编译打包
|
||||
```bash
|
||||
mvn clean package -DskipTests
|
||||
```
|
||||
|
||||
### 2. 部署后观察日志
|
||||
关注以下指标：
|
||||
- 是否还有桩频繁登录的情况
|
||||
- 心跳处理耗时是否降低
|
||||
- 是否出现 `【性能警告】` 日志
|
||||
|
||||
### 3. 监控 Redis 和数据库性能
|
||||
- Redis 响应时间应 < 5ms
|
||||
- 数据库连接池应充足
|
||||
- 检查 Redis 服务性能
|
||||
|
||||
### 4. 持续监控
|
||||
部署后持续观察 24 小时，确认问题是否彻底解决
|
||||
|
||||
---
|
||||
|
||||
## 预期效果
|
||||
|
||||
| 指标 | 优化前 | 优化后 |
|
||||
|------|--------|--------|
|
||||
| 心跳回复延迟 | 可能被阻塞 | < 10ms |
|
||||
| 桩频繁登录 | 存在 | 消除 |
|
||||
| 连接查询性能 | O(n) | O(1) |
|
||||
| 线程阻塞风险 | 高 | 低 |
|
||||
| 超时检测响应 | 30s | 15s（更快）|
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `CLAUDE.md` - 项目架构文档
|
||||
- `jsowell-netty/CLAUDE.md` - Netty 模块文档
|
||||
- `jsowell-common/CLAUDE.md` - 通用模块文档
|
||||
|
||||
---
|
||||
|
||||
## 记录信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 记录人 | Claude Code + 开发团队 |
|
||||
| 记录时间 | 2026-03-21 |
|
||||
| Git 分支 | dev |
|
||||
| 提交建议 | 建议创建新分支提交，便于回滚 |
|
||||
| 状态 | ✅ 全部优化已完成 |
|
||||
@@ -0,0 +1,7 @@
|
||||
"id","priority","phase","area","title","description","acceptance_criteria","test_mcp","review_initial_requirements","review_regression_requirements","dev_state","review_initial_state","review_regression_state","git_state","owner","refs","notes"
|
||||
"WLOS-010","P0","1","backend","澄清白名单修正规则与验收口径","明确白名单支付订单的判定字段与状态修正边界，形成可实现/可测试的规则清单。","明确并在PR/变更说明中写清：1) 白名单判定字段（order_basic_info.pay_mode 是否足够，是否需校验 order_pay_record.pay_mode）；2) 仅当 payMode=3 且订单状态为 ABNORMAL(4) 或 STAY_SETTLEMENT(2) 才允许修正；3) 修正为 ORDER_COMPLETE(6) 时需要同步的字段列表（settlement_time/金额字段/pay_status 等）与缺失数据的默认策略。","AUTOSERVER","Review过程中持续检查：规则是否与枚举一致；字段同步是否会影响分账/退款/通知/解锁等后续链路；是否需要审计/日志记录原状态。","完成后复核：规则与验收口径在代码/测试/接口行为三者一致；对非白名单/非目标状态无副作用。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:16; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:17; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:18; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:20; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayRecordEnum.java:8; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:12; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:14; jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java:1244; jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java:5618; jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java:5693","picked_reason:define concrete rule set before wiring behavior in WLOS-040; done_at:2026-01-28; evidence:documented executable rule set in plan/2026-01-23_16-45-56-whitelist-order-status-complete.md; risk:low doc-only"
|
||||
"WLOS-020","P0","2","backend","定位异常/待结算状态写入点并梳理影响面","确认订单进入 ABNORMAL/待结算/完成 的关键写入路径，决定修正应放在写入点还是补偿点，并列出受影响链路。","输出可审计的影响面清单（写在PR描述或变更说明中）：至少包含白名单批量入口、订单标记异常位置、结算后落库完成位置；明确最终选择的修正插入点（例如统一补偿方法 + 入口调用）。","AUTOSERVER","检查是否存在并发/重复调用场景；是否有事务边界；是否会触发远程停机/拉取交易记录等外部依赖；异常原因字段/审计日志是否保留。","回归时覆盖：修正路径不会破坏正常结算完成流程；不会将真实异常订单误判为完成。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:20; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:22; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:42; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:51; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:528; jsowell-netty/src/main/java/com/jsowell/netty/strategy/ykc/RemoteStopChargingStrategy.java:85; jsowell-netty/src/main/java/com/jsowell/netty/strategy/ykc/TransactionRecordsStrategy.java:617; jsowell-netty/src/main/java/com/jsowell/netty/strategy/ykc/TransactionRecordsStrategy.java:642; jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java:247","picked_reason:map status write paths before changing TempService入口逻辑; done_at:2026-01-28; evidence:documented status write paths + insertion point decision in plan/2026-01-23_16-45-56-whitelist-order-status-complete.md; risk:low doc-only"
|
||||
"WLOS-030","P0","3","backend","设计并落地统一的白名单订单完成补偿方法","在订单领域服务中新增可复用且幂等的补偿方法，专门用于白名单订单从异常/待结算修正为完成，并补齐必要字段。","新增补偿方法（如 completeWhitelistOrderIfNeeded(orderCode) 或等价实现）：1) 判定 payMode=3 且状态在 {ABNORMAL, STAY_SETTLEMENT}；2) 幂等（重复调用不产生额外副作用）；3) 更新为 ORDER_COMPLETE 并处理 settlement_time（为空则置当前时间）及约定的金额/状态字段默认值；4) 记录可追溯日志（至少包含订单号、原状态、新状态）。","AUTOSERVER","检查金额字段默认策略是否会影响对账；时间字段是否符合既有语义；方法是否避免不必要的外部调用（如远程停机/拉交易）。","回归验证：在真实/模拟数据上重复调用、并发调用无异常；下游依赖（通知/解锁/MQ/分账退款）要么保持一致，要么明确不触发并有说明。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:27; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:30; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:54; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:14; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:1629; jsowell-admin/src/main/java/com/jsowell/service/WhitelistOrderCompletionDefaults.java:17; jsowell-admin/src/test/java/com/jsowell/service/WhitelistOrderCompletionDefaultsTest.java:1","picked_reason:unblocks core capability for WLOS-040/WLOS-050; done_at:2026-01-28; evidence:added completeWhitelistOrderIfNeeded + defaults helper + unit test; validation_limited:jsowell-admin module compilation fails due to missing types (e.g., CarNumberBindDTO, com.jsowell.pile.jcpp.*), tests not runnable until fixed; manual_test:mvn -pl jsowell-admin test -Dtest=WhitelistOrderCompletionDefaultsTest; risk:low additive method not yet wired into flows"
|
||||
"WLOS-040","P0","4","backend","改造白名单结算入口以支持异常/待结算并复用补偿逻辑","调整 TempService.whiteListSettlement 及对应接口，使其支持 ABNORMAL/待结算两种状态并调用统一补偿方法，避免硬编码与不必要外部依赖。","1) TempService.whiteListSettlement 支持状态=ABNORMAL 或 STAY_SETTLEMENT；2) payMode 判断改为使用 OrderPayModeEnum.PAYMENT_OF_WHITELIST.getValue()；3) 默认走统一补偿方法完成状态修正；4) 若保留 manualSettlementOrder 调用，需明确触发条件与降级策略（避免依赖外部设备/交易服务导致批量失败）。","AUTOSERVER","Review时重点：权限/入参校验是否合理；批量处理时的错误隔离与日志；是否需要对调用方预期做兼容（原先只允许异常）。","回归时验证：接口对非白名单/非目标状态不改动；批量输入中单个失败不影响其他（如有此需求则实现并说明）。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:35; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:39; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1516; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1525; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:1629; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11","picked_reason:wire whitelist入口 to unified compensation method; done_at:2026-01-28; evidence:whiteListSettlement now allows ABNORMAL/STAY_SETTLEMENT + uses OrderPayModeEnum + delegates to completeWhitelistOrderIfNeeded; validation_limited:jsowell-admin module compilation fails due to missing types (e.g., CarNumberBindDTO, com.jsowell.pile.jcpp.*), tests not runnable until fixed; manual_test:POST /whiteListSettlement with whitelist orders in status 4/2 then verify order_basic_info.order_status=6 and settlement_time set when null; risk:medium endpoint behavior changed (no longer calls manualSettlementOrder/remote stop)"
|
||||
"WLOS-050","P0","5","backend","补齐白名单状态修正的单测/集成测试与回归场景","为白名单订单状态修正逻辑新增测试用例，确保异常/待结算均可修正且非白名单不会被误改。","新增/更新测试并通过：1) 白名单+异常(4) -> 完成(6)；2) 白名单+待结算(2) -> 完成(6)；3) 非白名单订单不变；4) 关键字段（如 settlement_time）按约定填充；执行 `mvn -pl jsowell-admin test` 通过。","AUTOSERVER","Review时关注：测试数据构造是否贴近真实（金额/时间/状态）；是否覆盖幂等与边界输入（空字段、重复调用）。","完成后回归：全量后端测试通过；若有接口层变化，补充接口测试或Mock验证。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:41; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:46; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1525; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:1629; jsowell-admin/src/test/java/com/jsowell/service/OrderServiceWhitelistCompletionTest.java:1; jsowell-admin/src/test/java/com/jsowell/service/WhitelistOrderCompletionDefaultsTest.java:1","picked_reason:add tests for whitelist compensation + rerun mvn with -am; done_at:2026-01-28; evidence:added unit tests covering whitelist ABNORMAL/STAY_SETTLEMENT -> COMPLETE and non-whitelist no-op; validation_limited:mvn build fails in jsowell-common with javac NoSuchFieldError (JDK/toolchain mismatch), cannot run tests in this environment; manual_test:set JAVA_HOME to JDK8 then run mvn -pl jsowell-admin -am test; risk:low tests only"
|
||||
"WLOS-060","P0","6","backend","测试环境演练与上线前数据校验/回滚预案","在测试环境按订单号列表演练修正接口，校验DB字段变化，并准备可执行的回滚/审计方案。","1) 在测试环境对选定订单号列表调用 /whiteListSettlement（或等价入口）成功；2) DB 校验：order_basic_info.order_status=6 且 settlement_time/金额字段符合约定；3) 形成可执行回滚步骤（SQL/脚本/手工流程）并记录在PR描述或运维文档中；4) 日志中可追溯到修正前后状态。","AUTOE2E","Review过程中确认：是否需要灰度/限流；批量处理失败的可观测性（日志/告警）；是否保留原状态用于追溯。","上线前回归：随机抽样多笔订单复测；验证不会导致下游不一致（通知/解锁/MQ/分账退款）或已明确不会触发并可接受。","已完成","已完成","已完成","已提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:77; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:88; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:54; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:1673","picked_reason:write executable manual runbook + rollback plan for test/prod; done_at:2026-01-28; evidence:added runnable rehearsal + rollback runbook in plan/2026-01-23_16-45-56-whitelist-order-status-complete.md; validation_limited:no access to test environment/DB/logs from this session to execute rehearsal; manual_test:follow plan runbook (snapshot DB -> POST /temp/whiteListSettlement -> verify SQL/logs -> rollback if needed); risk:medium rehearsal not executed yet"
|
||||
|
104
docs/plan/2026-01-23_16-45-56-whitelist-order-status-complete.md
Normal file
104
docs/plan/2026-01-23_16-45-56-whitelist-order-status-complete.md
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
mode: plan
|
||||
cwd: D:\jsowell\IdeaProjects\jsowell-charger-web
|
||||
task: 白名单支付订单在异常/待结算时自动修正为订单完成
|
||||
complexity: medium
|
||||
planning_method: builtin
|
||||
created_at: 2026-01-23T16:45:56.6767838+08:00
|
||||
---
|
||||
|
||||
# Plan: 白名单支付订单状态修正（异常/待结算 -> 完成）
|
||||
|
||||
🎯 任务概述
|
||||
当前系统中存在白名单支付（payMode=3）的订单，在某些场景下可能停留在“异常(4)”或“待结算(2)”状态。目标是在满足白名单支付条件时，将这些订单状态修正为“订单完成(6)”，并确保必要的结算时间/金额字段与后续流程（通知、解锁、分账/退款）保持一致或可控。
|
||||
|
||||
📋 执行计划
|
||||
1. 需求澄清与验收口径
|
||||
- 明确“白名单支付”的判定字段：`order_basic_info.pay_mode` 是否恒为 `3`（参考 `OrderPayModeEnum.PAYMENT_OF_WHITELIST`），以及是否需要同时检查支付流水 `order_pay_record.pay_mode`。
|
||||
- 定义修正规则：仅对白名单支付订单，且当前状态 ∈ {`ABNORMAL(4)`, `STAY_SETTLEMENT(2)`} 时修正为 `ORDER_COMPLETE(6)`；确认是否需要同步设置 `settlement_time`、`order_amount`、`refund_amount`、`virtual_amount`、`settle_amount`、`pay_status` 等字段。
|
||||
|
||||
✅ 规则清单（可实现/可测试）
|
||||
- 白名单判定：以 `order_basic_info.pay_mode == OrderPayModeEnum.PAYMENT_OF_WHITELIST(3)` 为主（系统业务字段）；若存在支付流水，可选做一致性校验 `order_pay_record.pay_mode == OrderPayRecordEnum.WHITELIST_PAYMENT(3)`，不一致时仅记录告警日志，不阻断补偿。
|
||||
- 修正边界：仅当订单状态 ∈ {`ABNORMAL(4)`, `STAY_SETTLEMENT(2)`} 才允许修正为 `ORDER_COMPLETE(6)`；其余状态必须保持不变。
|
||||
- 字段同步（补偿落库时）：
|
||||
- `order_status`：置为 `ORDER_COMPLETE(6)`
|
||||
- `settlement_time`：为空则置当前时间；非空保持原值
|
||||
- 金额字段默认策略（尽量沿用既有结算逻辑的语义）：
|
||||
- `order_amount`：优先保留已有值；为空则使用 `pay_amount`，仍为空则置 0；若 `order_amount > pay_amount` 则以 `pay_amount` 为准
|
||||
- `virtual_amount`：白名单支付场景置为 `order_amount`（不参与结算对账）
|
||||
- `settle_amount` / `actual_received_amount`：置为 `order_amount - virtual_amount`（白名单场景为 0）
|
||||
- `refund_amount`：为空则置为 `max(pay_amount - order_amount, 0)`
|
||||
- `pay_status`：优先保留原值；为空则置 `OrderPayStatusEnum.pay_nothing(2)`
|
||||
- 副作用约束：补偿方法为 DB/缓存层修正，不应触发远程停机、拉交易记录、MQ 推送、解锁等额外链路（如需触发，应另起规则与验收）。
|
||||
- 审计日志：至少记录 `orderCode`、原状态、目标状态（必要时补充关键字段快照）。
|
||||
|
||||
2. 代码定位与影响面梳理
|
||||
- 定位现有白名单异常订单批量处理入口：`jsowell-admin/src/main/java/com/jsowell/service/TempService.java` 的 `whiteListSettlement` 与 `jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java` 的 `/whiteListSettlement`。
|
||||
- 查找订单状态被设置为异常/待结算的路径，确认修正应放在“状态写入点”还是“事后补偿点”。重点关注：
|
||||
- `jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java`
|
||||
- `jsowell-admin/src/main/java/com/jsowell/service/OrderService.java`（存在将充电中订单标记为异常的逻辑）
|
||||
- `jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java`、`jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java`（结算后会落库为完成）
|
||||
|
||||
📌 影响面清单（可审计）
|
||||
- 白名单批量入口（人工/管理接口）：`TempController#/whiteListSettlement` → `TempService#whiteListSettlement`（当前仅允许异常订单、且硬编码 payMode=3，并调用 `OrderService#manualSettlementOrder`，会触发远程停机/拉交易记录等外部依赖）。
|
||||
- 订单标记异常（后管查询触发）：`OrderService#getOrderDetail` 在“充电中”但实时数据缺失/超时场景会将订单置为 `ABNORMAL(4)` 并落库。
|
||||
- 待结算写入点（设备/交易链路）：
|
||||
- `RemoteStopChargingStrategy`：停机成功→`STAY_SETTLEMENT(2)`；停机失败→`ABNORMAL(4)`。
|
||||
- `TransactionRecordsStrategy`：收到交易记录后，若订单为 `ABNORMAL(4)` 会先改为 `STAY_SETTLEMENT(2)`，随后进入 `ProgramLogicFactory#getProgramLogic(...).settleOrder(...)` 完成结算落库。
|
||||
- 其他协议/平台（同类写入点）：`jsowell-netty` 的 yunkuaichong handlers、`jsowell-thirdparty` 的 Huawei 等也存在将订单置为 `STAY_SETTLEMENT(2)` 的路径（需避免在这些写入点引入“白名单直接完成”造成副作用扩散）。
|
||||
- 结算后落库完成（核心）：`AbstractProgramLogic#returnUpdateOrderBasicInfo` 会设置 `ORDER_COMPLETE(6)` 并写入结算时间/金额字段（及可能补 SOC）。
|
||||
|
||||
🧭 修正插入点选择（结论）
|
||||
- 选择“事后补偿点”而不是在各类“状态写入点”分散修正：以统一补偿方法 + 白名单批量入口调用为主（后续可扩展定时任务/管理按钮复用该方法）。
|
||||
- 理由：避免侵入设备协议/交易记录链路（风险大、场景多）；补偿方法可控、幂等、日志可追溯，且明确不触发远程停机/拉交易/MQ/解锁等外部副作用。
|
||||
|
||||
3. 设计修正策略（推荐“统一补偿方法”）
|
||||
- 在订单领域服务中新增一个可复用的方法（命名示例：`completeWhitelistOrderIfNeeded(orderCode)`），封装：
|
||||
- 判定：payMode=3 且状态为异常/待结算。
|
||||
- 修正：更新为 `ORDER_COMPLETE`，补齐 `settlement_time`（无则置当前时间），并根据现有数据填充金额字段（缺失时以 0 或合理默认值），确保幂等。
|
||||
- 选择调用点：
|
||||
- 扩展现有 `/whiteListSettlement`：允许处理 `ABNORMAL` 与 `STAY_SETTLEMENT` 两种状态；内部改为调用统一补偿方法。
|
||||
- 视业务需要补充一个定时任务/管理端按钮做批量修复（避免仅靠人工接口）。
|
||||
|
||||
4. 实现细节落地
|
||||
- 调整 `TempService.whiteListSettlement`：
|
||||
- 将“只允许异常订单”的校验扩展为“异常或待结算”。
|
||||
- 将硬编码 `payMode == "3"` 改为使用枚举 `OrderPayModeEnum.PAYMENT_OF_WHITELIST.getValue()`。
|
||||
- 明确是否继续调用 `orderService.manualSettlementOrder(...)`（它会尝试远程停机、拉取交易记录）；若目标仅是状态修正，优先走新的补偿方法，避免不必要的外部依赖。
|
||||
|
||||
5. 测试与回归
|
||||
- 增加单元/集成测试覆盖：
|
||||
- 白名单订单 + 状态=异常 -> 修正为完成。
|
||||
- 白名单订单 + 状态=待结算 -> 修正为完成。
|
||||
- 非白名单订单不应被修正。
|
||||
- 运行验证命令：`mvn -pl jsowell-admin test`（必要时指定测试类）。
|
||||
|
||||
6. 数据校验与上线准备
|
||||
- 演练入口：`POST /temp/whiteListSettlement`
|
||||
- body（示例）：`{"orderCodeList":["O1","O2"]}`
|
||||
- 演练前（务必留存快照，用于回滚/审计）：
|
||||
- DB 快照（示例 SQL）：
|
||||
- `SELECT order_code,pay_mode,order_status,pay_status,settlement_time,order_amount,virtual_amount,settle_amount,actual_received_amount,refund_amount,reason FROM order_basic_info WHERE order_code IN ('O1','O2');`
|
||||
- 将查询结果保存到工单/PR/运维记录（CSV/截图均可）。
|
||||
- 演练后（校验点）：
|
||||
- `order_basic_info.order_status = 6`
|
||||
- `settlement_time`：原为空则已填充；原非空保持不变
|
||||
- 金额字段符合“规则清单”默认策略（白名单虚拟金额/结算金额等）
|
||||
- 日志可追溯：搜索 `completeWhitelistOrderIfNeeded updated orderCode:`，应包含订单号与状态变更前后值
|
||||
- 回滚预案（可执行）：
|
||||
- 原则：以“演练前快照”为准逐单回退（避免盲目回退影响正常订单）。
|
||||
- 回滚 SQL（模板，按快照逐单生成）：
|
||||
- `UPDATE order_basic_info SET order_status='<before_status>', settlement_time='<before_settlement_time>', order_amount=<before_order_amount>, virtual_amount=<before_virtual_amount>, settle_amount=<before_settle_amount>, actual_received_amount=<before_actual_received_amount>, refund_amount=<before_refund_amount>, pay_status='<before_pay_status>' WHERE order_code='<order_code>';`
|
||||
|
||||
⚠️ 风险与注意事项
|
||||
- 业务风险：将异常/待结算直接置为完成可能掩盖真实设备/交易异常；需确认是否仍需要保留异常原因字段或额外审计。
|
||||
- 技术风险：如果修正流程绕过了“解锁卡/VIN、推送MQ、实时数据落库”等步骤，可能导致下游状态不一致；应明确是否需要补做这些副作用。
|
||||
- 兼容性：`TempService.whiteListSettlement` 当前只允许异常订单，放宽后需确认调用方预期与权限控制。
|
||||
|
||||
📎 参考
|
||||
- `jsowell-admin/src/main/java/com/jsowell/service/TempService.java`
|
||||
- `jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java`
|
||||
- `jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java`
|
||||
- `jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java`
|
||||
- `jsowell-admin/src/main/java/com/jsowell/service/OrderService.java`
|
||||
- `jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java`
|
||||
@@ -0,0 +1,433 @@
|
||||
---
|
||||
mode: plan
|
||||
cwd: /Users/guoqiusi/Workspace/jsowell-charger-web
|
||||
task: 云快充1.6协议凌晨离线问题修复与协议对齐
|
||||
complexity: high
|
||||
planning_method: builtin
|
||||
created_at: 2026-03-21T08:48:24+08:00
|
||||
---
|
||||
|
||||
# Plan: 云快充1.6凌晨离线修复跟踪
|
||||
|
||||
## 任务概述
|
||||
|
||||
当前项目中，云快充 1.6 协议设备在凌晨时段存在离线现象。经代码与协议文档对照，未发现明确的“凌晨主动断链”定时任务，更可能是夜间网络/SIM 抖动触发了当前偏激进的离线判定逻辑，导致短时弱网被放大为设备离线。
|
||||
|
||||
本计划用于跟踪以下三类工作：
|
||||
|
||||
1. 先止血：降低“短时抖动即离线”的敏感度。
|
||||
2. 再纠偏：按协议修正登录、心跳、费率、对时流程。
|
||||
3. 最后收敛：统一实现入口，减少后续维护风险。
|
||||
|
||||
## 关键结论
|
||||
|
||||
- 协议要求：
|
||||
- `0x03` 心跳为 10 秒周期上送，连续 3 次未收到才视为网络异常并重新登录。
|
||||
- `0x13` 实时监测数据周期上送，待机 5 分钟、充电 15 秒。
|
||||
- `0x05 -> 0x06 -> 0x09 -> 0x0A` 为费率模型校验与拉取闭环。
|
||||
- `0x56` 对时为 1 天周期发送。
|
||||
- 当前实现中的高风险点：
|
||||
- Netty 读空闲 30 秒即触发关闭连接。
|
||||
- 断链后立即将枪口置离线，并将充电中订单改异常。
|
||||
- 桩状态按“任意枪口离线即整桩离线”计算。
|
||||
- `0x05` 校验请求当前固定返回“一致”，未真正校验费率模型。
|
||||
- 登录后主动下发 `0x58`，与协议标准流程不完全一致。
|
||||
- 对时仅在登录后发送一次，未发现每日自动对时任务。
|
||||
- 线上实际走老 Handler 链路，新 Strategy 链路当前不生效。
|
||||
|
||||
## 目标与验收口径
|
||||
|
||||
### 业务目标
|
||||
|
||||
- 凌晨 `00:00-06:00` 时段，短时网络抖动不再导致桩状态频繁离线。
|
||||
- 单次 `30-40s` 的弱网抖动不应直接把充电中订单改为异常。
|
||||
- 桩在线状态与真实链路状态更一致，减少前端“在线/离线闪断”。
|
||||
|
||||
### 协议目标
|
||||
|
||||
- `0x03` 按协议节奏与容错逻辑处理。
|
||||
- `0x05/0x06/0x09/0x0A` 恢复为真实校验与请求链路。
|
||||
- `0x56/0x55` 具备每日自动对时能力和执行记录。
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 短时网络抖动：
|
||||
- 30-40 秒无上行数据后恢复，不直接离线。
|
||||
- 宽限期内重连成功，不产生订单异常。
|
||||
- 长时网络中断：
|
||||
- 超出配置阈值后，设备进入离线状态。
|
||||
- 若有正在充电订单，按规则进入异常处理。
|
||||
- 协议链路：
|
||||
- 桩上报旧费率模型时，平台能正确返回不一致并等待 `0x09` 请求。
|
||||
- 每日自动对时后，可看到 `0x55` 应答记录。
|
||||
- 排障能力：
|
||||
- 日志能够还原“最后正常通信 -> 空闲超时 -> 关闭连接 -> 是否重连成功”的完整链路。
|
||||
|
||||
## 执行批次
|
||||
|
||||
### 第一批：先止血
|
||||
|
||||
- 调整 Netty 空闲断链策略。
|
||||
- 引入断链宽限期，避免瞬断即离线。
|
||||
- 补连接生命周期日志。
|
||||
- 修复 channel 映射清理。
|
||||
|
||||
### 第二批：协议纠偏
|
||||
|
||||
- 修复费率模型校验与拉取闭环。
|
||||
- 新增每日自动对时。
|
||||
- 将关键阈值配置化。
|
||||
|
||||
### 第三批：实现收敛
|
||||
|
||||
- 收敛云快充双实现，只保留一条实际生效链路。
|
||||
- 补齐专项回归验证与联调记录。
|
||||
|
||||
## 任务清单
|
||||
|
||||
### YKC-001
|
||||
|
||||
- 优先级：P0
|
||||
- 状态：done
|
||||
- 目标：将云快充连接保活从“30 秒空闲直接断开”改为“允许短时抖动，按连续丢心跳或宽限期判定断链”。
|
||||
- 当前进展：
|
||||
- 已按第一批止血方案落地为 `15s tick + 连续 3 次 READER_IDLE 才关闭`。
|
||||
- 已补 `idleCount / lastFrameType / lastReceiveAt / lastSerialNumber / disconnectReason` 连接属性。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java`
|
||||
- 设计要点：
|
||||
- `IdleStateHandler` 读空闲阈值调整为 `40-45s` 或等效容错值。
|
||||
- `userEventTriggered` 不再第一次超时就 `close()`。
|
||||
- 结合最近通信时间和连续空闲次数处理。
|
||||
- 验收标准：
|
||||
- 单次 `30-40s` 无上行数据不直接断链。
|
||||
- 凌晨弱网时连接不会频繁抖动为离线。
|
||||
- 风险：
|
||||
- 阈值过宽会延迟真实离线发现，需要与业务确认容忍度。
|
||||
|
||||
### YKC-002
|
||||
|
||||
- 优先级：P0
|
||||
- 状态：done
|
||||
- 目标：增加“断链宽限期”，避免瞬断立刻将枪口置离线、订单置异常。
|
||||
- 当前进展：
|
||||
- 已落地 `60s` 离线确认宽限期。
|
||||
- 已引入 `pile_pending_disconnect` 和 `pile_offline_confirmed` 标记，并在恢复通信后自动清理。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java`
|
||||
- 设计要点：
|
||||
- `exit()` 中先记录“断链待确认”状态。
|
||||
- 宽限期结束且未恢复登录时，才正式落离线和订单异常。
|
||||
- 若宽限期内重连，取消离线确认。
|
||||
- 验收标准：
|
||||
- 短时断链后在宽限期内重连，不产生订单异常。
|
||||
- 真正长断链后仍能正确离线。
|
||||
- 风险：
|
||||
- 需防止宽限期任务重复执行或状态竞争。
|
||||
|
||||
### YKC-003
|
||||
|
||||
- 优先级：P0
|
||||
- 状态：in_progress
|
||||
- 目标：补齐连接生命周期日志，支持“凌晨离线”专项排查。
|
||||
- 当前进展：
|
||||
- 已补空闲告警、连续空闲关闭、异常断链、宽限恢复、正式离线确认等主链路日志。
|
||||
- `LoginRequestHandler` / `UploadRealTimeMonitorHandler` 维度的专项日志尚未单独补齐。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/HeartbeatRequestHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/LoginRequestHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/UploadRealTimeMonitorHandler.java`
|
||||
- 设计要点：
|
||||
- 统一打印 `pileSn`、`channelId`、远端 IP、最后一帧类型、最后上报时间、IdleState 类型、重连耗时。
|
||||
- 对凌晨时段日志加清晰关键词，便于筛查。
|
||||
- 验收标准：
|
||||
- 一次离线事件能从日志完整还原链路。
|
||||
- 风险：
|
||||
- 需控制日志量，避免高频心跳刷爆日志。
|
||||
|
||||
### YKC-004
|
||||
|
||||
- 优先级：P0
|
||||
- 状态：done
|
||||
- 目标：修复 channel 映射清理不完整的问题，避免旧连接残留。
|
||||
- 当前进展：
|
||||
- 已补 `removeByPileSnAndChannelId()` 安全删除。
|
||||
- 已补 `channelId -> pileSn` 反向映射维护，并修复删除时的脏映射残留问题。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-common/src/main/java/com/jsowell/common/enums/ykc/PileChannelEntity.java`
|
||||
- 设计要点：
|
||||
- 恢复 `removeByPileSn/removeByChannelId` 的正常调用。
|
||||
- 确保断链、异常、重连时旧 `channel` 被清理。
|
||||
- 验收标准：
|
||||
- 同一桩重连后只保留一个有效 `channel`。
|
||||
- 下行命令不会打到死连接。
|
||||
- 风险：
|
||||
- 需避免误删新连接。
|
||||
|
||||
### YKC-005
|
||||
|
||||
- 优先级：P1
|
||||
- 状态：in_progress
|
||||
- 目标：将桩离线判定从“任意枪状态为离线即整桩离线”改为“最近通信时间 + 枪状态 + 宽限期”的综合判定。
|
||||
- 当前进展：
|
||||
- 已完成 `checkPileOffLine()` 优先识别 `PILE_OFFLINE_CONFIRMED` 标记。
|
||||
- 仍未重写 `getPileStatus/getPileStatusV2` 的整桩聚合规则，暂按第一批止血范围保留现状。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/PileConnectorInfoServiceImpl.java`
|
||||
- 设计要点：
|
||||
- `getPileStatus/getPileStatusV2/checkPileOffLine` 使用统一判定逻辑。
|
||||
- 将固定 3 分钟阈值改为可配置。
|
||||
- 验收标准：
|
||||
- 前端在线状态与真实通信状态一致。
|
||||
- 短时抖动不出现整桩离线闪断。
|
||||
- 风险：
|
||||
- 旧缓存与新判定逻辑可能短期不一致，需要同步清理策略。
|
||||
|
||||
### YKC-006
|
||||
|
||||
- 优先级：P1
|
||||
- 状态：todo
|
||||
- 目标：按协议修正费率模型交互，去掉“固定返回一致”的实现。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/BillingTemplateValidateRequestHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/BillingTemplateRequestHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/LoginRequestHandler.java`
|
||||
- 设计要点：
|
||||
- `0x05` 真比较平台模型号与桩上报模型号。
|
||||
- 不一致返回 `0x01`。
|
||||
- 由桩继续发 `0x09`，平台回 `0x0A`。
|
||||
- 登录后主动 `0x58` 改为开关控制或移除。
|
||||
- 验收标准：
|
||||
- 费率模型链路符合协议。
|
||||
- 跨天费率切换时行为可解释、可追踪。
|
||||
- 风险：
|
||||
- 需确认现网桩程序是否依赖“登录后强推模板”的兼容行为。
|
||||
|
||||
### YKC-007
|
||||
|
||||
- 优先级：P1
|
||||
- 状态：done
|
||||
- 目标：补每日自动对时，降低跨天时钟漂移的影响。
|
||||
- 当前进展：
|
||||
- 已新增 `jsowellTask.dailyProofreadTimeForYkcV160()`。
|
||||
- 已补 `0x56` 下发记录和 `0x55` 应答记录。
|
||||
- 待上线时补 Quartz 任务配置。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/YKCPushCommandServiceImpl.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/TimeCheckSettingResponseHandler.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-quartz/src/main/java/com/jsowell/quartz/task/JsowellTask.java`
|
||||
- 设计要点：
|
||||
- 每日定时给在线桩批量发 `0x56`。
|
||||
- 记录 `0x55` 应答结果与桩回传时间。
|
||||
- 验收标准：
|
||||
- 每日有自动对时执行记录。
|
||||
- 对时失败可重试，可观测。
|
||||
- 风险：
|
||||
- 大批量对时可能集中打到凌晨，需控制任务节奏。
|
||||
|
||||
### YKC-008
|
||||
|
||||
- 优先级：P1
|
||||
- 状态：todo
|
||||
- 目标：将关键超时和离线参数配置化，避免硬编码。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/PileConnectorInfoServiceImpl.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application.yml`
|
||||
- 设计要点：
|
||||
- 至少抽出：
|
||||
- `readerIdleSeconds`
|
||||
- `offlineConfirmSeconds`
|
||||
- `lastConnectionOfflineMinutes`
|
||||
- `dailyTimeSyncCron`
|
||||
- 验收标准：
|
||||
- 不改代码即可在环境配置中调整离线策略。
|
||||
- 风险：
|
||||
- 需注意各环境默认值兼容。
|
||||
|
||||
### YKC-009
|
||||
|
||||
- 优先级：P2
|
||||
- 状态：todo
|
||||
- 目标：收敛云快充双实现，避免后续修错入口。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong`
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/strategy/ykc`
|
||||
- 设计要点：
|
||||
- 确认唯一线上入口。
|
||||
- 如果保留老 Handler，则冻结或移除 Strategy。
|
||||
- 如果迁移到 Strategy，则需一次性迁完。
|
||||
- 验收标准：
|
||||
- 线上只存在一套实际生效的云快充处理链路。
|
||||
- 风险：
|
||||
- 涉及面较大，需单独回归。
|
||||
|
||||
### YKC-010
|
||||
|
||||
- 优先级：P1
|
||||
- 状态：todo
|
||||
- 目标：补专项回归验证和凌晨专项验证脚本或测试用例。
|
||||
- 修改文件：
|
||||
- `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-admin/src/test/java`
|
||||
- 设计要点：
|
||||
- 覆盖场景：
|
||||
- `30-40s` 无心跳但恢复。
|
||||
- 宽限期内重连。
|
||||
- 费率模型不一致重新请求。
|
||||
- 每日对时成功和失败。
|
||||
- 验收标准：
|
||||
- 每个修复点至少有一条可复现、可回归的验证路径。
|
||||
- 风险：
|
||||
- 若缺真实协议模拟器，需先补测试桩或伪报文能力。
|
||||
|
||||
## 推荐执行顺序
|
||||
|
||||
1. YKC-001
|
||||
2. YKC-002
|
||||
3. YKC-003
|
||||
4. YKC-004
|
||||
5. YKC-005
|
||||
6. YKC-008
|
||||
7. YKC-006
|
||||
8. YKC-007
|
||||
9. YKC-010
|
||||
10. YKC-009
|
||||
|
||||
## 文件级改造备注
|
||||
|
||||
### 连接与断链主链路
|
||||
|
||||
- `NettyServerChannelInitializer`
|
||||
- 负责 IdleState 参数配置。
|
||||
- `NettyServerHandler`
|
||||
- 负责空闲事件、异常事件、连接关闭事件的断链控制。
|
||||
- `YKCBusinessServiceImpl`
|
||||
- 负责断链后离线和订单状态变更逻辑。
|
||||
|
||||
### 在线状态与业务影响主链路
|
||||
|
||||
- `PileChannelEntity`
|
||||
- 管理桩与 channel 的映射。
|
||||
- `PileConnectorInfoServiceImpl`
|
||||
- 管理枪口状态、桩状态聚合与前端在线判断。
|
||||
- `OrderBasicInfoServiceImpl`
|
||||
- 管理充电订单异常状态的最终落库。
|
||||
|
||||
### 协议对齐主链路
|
||||
|
||||
- `LoginRequestHandler`
|
||||
- 登录后当前有对时和费率主动推送逻辑。
|
||||
- `HeartbeatRequestHandler`
|
||||
- 心跳包处理与最后通信时间刷新。
|
||||
- `BillingTemplateValidateRequestHandler`
|
||||
- 当前实现与协议偏差最大。
|
||||
- `BillingTemplateRequestHandler`
|
||||
- 负责 `0x09 -> 0x0A`。
|
||||
- `TimeCheckSettingResponseHandler`
|
||||
- 用于记录 `0x55` 对时应答。
|
||||
|
||||
## 风险清单
|
||||
|
||||
- 现网桩程序可能已适配当前“非标准但可用”的平台行为，协议纠偏前需确认兼容性。
|
||||
- 离线判定放宽后，真实离线的发现速度会变慢，需要平衡运维体验。
|
||||
- 订单异常处理若改为延迟确认，需防止漏处理真正断电或断网导致的异常订单。
|
||||
- 双实现收敛前，所有改动应明确打在老 Handler 链路上，避免误改新 Strategy 无法生效。
|
||||
|
||||
## 当前进度快照
|
||||
|
||||
- 更新时间：2026-03-21 11:14:17 +0800
|
||||
- `done`：
|
||||
- `YKC-001`
|
||||
- `YKC-002`
|
||||
- `YKC-004`
|
||||
- `YKC-007`
|
||||
- `in_progress`：
|
||||
- `YKC-003`
|
||||
- `YKC-005`
|
||||
- `todo`：
|
||||
- `YKC-006`
|
||||
- `YKC-008`
|
||||
- `YKC-009`
|
||||
- `YKC-010`
|
||||
|
||||
## 进度记录模板
|
||||
|
||||
```md
|
||||
### 进度记录
|
||||
|
||||
- 任务ID: YKC-001
|
||||
- 优先级: P0
|
||||
- 状态: todo
|
||||
- 负责人:
|
||||
- 开始时间:
|
||||
- 完成时间:
|
||||
- 目标: 调整 Netty 空闲断链策略，避免 30 秒无上行直接断链
|
||||
- 修改文件:
|
||||
- /Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java
|
||||
- /Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java
|
||||
- 验收结果:
|
||||
- 备注/风险:
|
||||
```
|
||||
|
||||
## 最终上线注意项
|
||||
|
||||
- 本次建议作为一个整体上线，包含：
|
||||
- 第一批凌晨离线止血。
|
||||
- `YKC-007` 云快充 1.6 每日自动对时。
|
||||
- 当前最终基线以“离线判定正确性优先”为准，同时保留必要性能优化：
|
||||
- 保留 `EchoServerHandler` 绑定 `businessGroup`。
|
||||
- 保留 `PileChannelEntity` 的 `channelId -> pileSn` 反向映射。
|
||||
- 保留 `NettyServerHandler` 的消息处理耗时监控。
|
||||
- 不采用“心跳全异步 + 公共线程池 DiscardOldestPolicy”组合。
|
||||
- 已确认的最终收口原则：
|
||||
- `HeartbeatRequestHandler` 中 `saveLastTimeAndCheckChannel()` 必须同步执行，保证任意上行立即刷新 `PILE_LAST_CONNECTION`，并立即清除 `PILE_PENDING_DISCONNECT / PILE_OFFLINE_CONFIRMED`。
|
||||
- `HeartbeatRequestHandler` 中 `updateStatus()` 继续异步执行，避免数据库操作拖长心跳回包链路。
|
||||
- `ThreadPoolConfig.threadPoolTaskExecutor` 保持 `CallerRunsPolicy`，避免关键任务被静默丢弃。
|
||||
- `PileChannelEntity.removeByPileSnAndChannelId()` 必须同步清理反向映射，避免旧连接脏数据残留。
|
||||
|
||||
### Quartz 配置建议
|
||||
|
||||
- 新增每日对时任务：
|
||||
- `invokeTarget`: `jsowellTask.dailyProofreadTimeForYkcV160()`
|
||||
- 不建议把任务压在 `00:00` 整点，建议放到低峰时段，例如 `03:15`。
|
||||
- 每日对时任务默认只扫描“当前有活连接的云快充 1.6 桩”，并按小间隔逐台发送，避免凌晨集中打满链路。
|
||||
|
||||
### 上线后重点观察
|
||||
|
||||
- 是否还出现“凌晨批量掉线后立刻落离线”的情况。
|
||||
- 是否能看到 `pile_pending_disconnect` 在恢复通信后于宽限期内被清除。
|
||||
- 是否出现“正式离线确认”日志明显下降。
|
||||
- 是否能看到 `0x56` 下发记录与 `0x55` 应答记录。
|
||||
- 是否持续出现 `【性能警告】` 日志堆积。
|
||||
|
||||
### 建议回归项
|
||||
|
||||
- 连续触发 1 次、2 次、3 次 `READER_IDLE`：
|
||||
- 预期仅第 3 次关闭连接。
|
||||
- 第 3 次空闲关闭后 60 秒内重连：
|
||||
- 预期不落 `OFF_NETWORK`，不改订单异常。
|
||||
- 第 3 次空闲关闭后 60 秒内未恢复：
|
||||
- 预期才正式落离线。
|
||||
- 手工执行一次 `jsowellTask.dailyProofreadTimeForYkcV160()`：
|
||||
- 预期仅对在线云快充 1.6 桩发对时。
|
||||
- 检查 `TimeCheckSettingResponseHandler`：
|
||||
- 预期能记录 `0x55` 对时应答及桩端回传时间。
|
||||
|
||||
### 编译验证记录
|
||||
|
||||
- 已执行：
|
||||
- `mvn -pl jsowell-quartz,jsowell-netty -am -DskipTests compile`
|
||||
- `mvn -pl jsowell-netty,jsowell-framework,jsowell-common -am -DskipTests compile`
|
||||
- 结果：
|
||||
- 通过。
|
||||
|
||||
## 当前建议
|
||||
|
||||
- 先以第一批任务为本周主线，尽快止住凌晨离线误判。
|
||||
- 第二批在止血完成后推进，避免协议纠偏与连接策略变更叠加，增加联调复杂度。
|
||||
- 第三批收敛放在前两批稳定后执行。
|
||||
21
docs/sql/jcpp_sync_record.sql
Normal file
21
docs/sql/jcpp_sync_record.sql
Normal file
@@ -0,0 +1,21 @@
|
||||
-- JCPP 充电桩同步记录表
|
||||
CREATE TABLE `jcpp_sync_record` (
|
||||
`id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`sync_type` varchar(20) NOT NULL COMMENT '同步类型（FULL-全量；INCREMENTAL-增量）',
|
||||
`sync_status` varchar(20) NOT NULL COMMENT '同步状态（RUNNING-进行中；SUCCESS-成功；FAILED-失败）',
|
||||
`start_time` datetime NOT NULL COMMENT '开始时间',
|
||||
`end_time` datetime DEFAULT NULL COMMENT '结束时间',
|
||||
`total_piles` int(11) DEFAULT 0 COMMENT '总充电桩数',
|
||||
`success_piles` int(11) DEFAULT 0 COMMENT '成功充电桩数',
|
||||
`failed_piles` int(11) DEFAULT 0 COMMENT '失败充电桩数',
|
||||
`total_guns` int(11) DEFAULT 0 COMMENT '总充电枪数',
|
||||
`success_guns` int(11) DEFAULT 0 COMMENT '成功充电枪数',
|
||||
`failed_guns` int(11) DEFAULT 0 COMMENT '失败充电枪数',
|
||||
`error_message` text COMMENT '错误信息',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (`id`) USING BTREE,
|
||||
KEY `idx_sync_type` (`sync_type`) USING BTREE,
|
||||
KEY `idx_start_time` (`start_time`) USING BTREE,
|
||||
KEY `idx_sync_status` (`sync_status`) USING BTREE
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='JCPP 充电桩同步记录表';
|
||||
BIN
docs/万车充小程序-未分账明细.xlsx
Normal file
BIN
docs/万车充小程序-未分账明细.xlsx
Normal file
Binary file not shown.
305
docs/万车充小程序未分账补分账SOP.md
Normal file
305
docs/万车充小程序未分账补分账SOP.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 万车充小程序未分账补分账 SOP（adapayMemberId=0）
|
||||
|
||||
## 1. 目标与背景
|
||||
|
||||
- 目标：将未分账订单批量向汇付发起 `PaymentConfirm` 请求，分账对象固定为 `adapayMemberId=0`（平台默认账户）。
|
||||
- 数据来源：`doc/万车充小程序-未分账明细.xlsx`。
|
||||
- 编写日期：2026-03-11（Asia/Shanghai）。
|
||||
|
||||
说明：本 SOP 面向“拿到一份未分账明细文件后，批量补分账”的场景。文档中的流程可复用于后续同类任务。
|
||||
|
||||
## 2. 本次文件分析结论
|
||||
|
||||
对 `doc/万车充小程序-未分账明细.xlsx` 的 `Sheet1` 统计结果如下：
|
||||
|
||||
- 总记录数：`42,225`
|
||||
- `paymentId` 去重后重复数：`0`
|
||||
- `app_id`：全部为 `app_d0c80cb1-ffc8-48cb-a030-fe9bec823aaa`
|
||||
- 支付时间范围：`2024-09-07 19:29:00` ~ `2026-03-06 00:11:20`
|
||||
- 未分账金额（列“剩余未分账金额”）
|
||||
- 合计：`171,710.73`
|
||||
- 最小：`0.01`
|
||||
- 中位数：`0.50`
|
||||
- P90：`8.45`
|
||||
- 最大：`268.39`
|
||||
- 金额分布：
|
||||
- `0.01~1`: `34,367`
|
||||
- `1~10`: `4,018`
|
||||
- `10~50`: `3,061`
|
||||
- `50~100`: `507`
|
||||
- `>=100`: `272`
|
||||
- 交易订单号格式：`42,223/42,225` 包含下划线（通常为 `orderCode_时间戳`）
|
||||
|
||||
关键结论：
|
||||
|
||||
1. 量大（4.2 万+），必须批处理+可重试+可追踪。
|
||||
2. 文件最晚数据到 `2026-03-06`，执行时必须先查汇付最新状态，不能盲目按文件金额直发。
|
||||
3. 小额单非常多（0.01~1 占比高），要考虑接口速率与批次执行时长。
|
||||
|
||||
## 3. 现有代码落点（可复用）
|
||||
|
||||
- 发起汇付分账请求：
|
||||
- `jsowell-pile/src/main/java/com/jsowell/adapay/service/AdapayService.java`
|
||||
- 方法：`createPaymentConfirmRequest(PaymentConfirmParam param)`
|
||||
- 查询支付确认列表：
|
||||
- 同上 `queryPaymentConfirmList(QueryPaymentConfirmDTO dto)`
|
||||
- 分账对象模型：
|
||||
- `DivMember.memberId` 设为 `0`，`feeFlag` 设为 `Y`
|
||||
- 已有“未分账处理”参考（测试代码）：
|
||||
- `jsowell-admin/src/test/java/PaymentTestController.java`
|
||||
- 方法：`processUnSettledOrder()`
|
||||
|
||||
注意：
|
||||
|
||||
- `jsowell-quartz` 里的 `processUnSettledOrder()` 当前版本（V2）主要是“查汇付确认信息”，不是生产可直接执行的补分账任务。
|
||||
|
||||
## 4. 推荐执行方案（生产可落地）
|
||||
|
||||
## 4.1 方案总览
|
||||
|
||||
分三阶段执行：
|
||||
|
||||
1. 任务清单准备
|
||||
2. 批量补分账执行
|
||||
3. 结果复核与失败重试
|
||||
|
||||
建议新增一个“一次性批处理工具（仅本次任务分支）”，不要直接依赖手工接口逐条处理。
|
||||
|
||||
## 4.2 任务清单准备
|
||||
|
||||
从 Excel 抽取以下字段形成任务清单（CSV/临时表均可）：
|
||||
|
||||
- `payment_id` ← 交易流水号
|
||||
- `source_order_no` ← 交易订单号
|
||||
- `order_code` ← `source_order_no` 按 `_` 分割取前半段；若无 `_` 则回退原值
|
||||
- `pay_amt` ← 交易订单金额
|
||||
- `file_confirmed_amt` ← 已确认分账金额
|
||||
- `file_reserved_amt` ← 支付确认撤销金额
|
||||
- `file_remaining_amt` ← 剩余未分账金额
|
||||
- `pay_time` ← 支付时间
|
||||
|
||||
过滤条件：
|
||||
|
||||
- `file_remaining_amt > 0`
|
||||
- `payment_id` 非空
|
||||
|
||||
## 4.3 批量补分账执行（核心）
|
||||
|
||||
单条任务处理逻辑（必须幂等）：
|
||||
|
||||
1. 用 `payment_id` 调 `queryPaymentConfirmList` 查询汇付最新确认信息。
|
||||
2. 计算“执行时最新可分账金额” `latest_remaining_amt`：
|
||||
- 基线金额使用文件中的 `file_remaining_amt`。
|
||||
- 若汇付返回了确认信息，使用 `pay_amt - confirmed_amt - reserved_amt` 再算一遍，取两者较小值（且不小于 0）。
|
||||
3. 若 `latest_remaining_amt <= 0`：跳过（记为 `SKIPPED_NO_REMAINING`）。
|
||||
4. 构造分账请求：
|
||||
- `paymentId = payment_id`
|
||||
- `confirmAmt = latest_remaining_amt`
|
||||
- `divMemberList = [{ memberId: "0", amount: latest_remaining_amt, feeFlag: "Y" }]`
|
||||
- `orderCode = order_code`
|
||||
- `wechatAppId = 对应 appId`
|
||||
5. 调用 `createPaymentConfirmRequest(param)`。
|
||||
6. 按响应记录结果：
|
||||
- 成功：记录 `payment_confirm_id`、`confirm_amt`、`fee_amt`
|
||||
- 失败：记录 `error_code`、`error_msg`
|
||||
|
||||
建议执行参数：
|
||||
|
||||
- 批次：每批 `500`（或 `200` 起步）
|
||||
- QPS：`3~5`（每笔 sleep `200~300ms`）
|
||||
- 失败重试：对可重试错误最多 `2` 次
|
||||
|
||||
建议错误处理：
|
||||
|
||||
- `confirm_amt_over_limit`：立即重查汇付最新金额，按新金额重试一次。
|
||||
- `payment_over_time_doing` / `refund_repeate_request`：放入重试队列，延迟重跑。
|
||||
- 其他错误：记录失败，人工复核。
|
||||
|
||||
## 4.4 结果复核与验收
|
||||
|
||||
必须输出三类结果文件（CSV）：
|
||||
|
||||
- `success.csv`：成功明细（含 paymentConfirmId）
|
||||
- `skipped.csv`：跳过明细（无剩余可分账）
|
||||
- `failed.csv`：失败明细（含错误码）
|
||||
|
||||
验收标准：
|
||||
|
||||
1. `success + skipped + failed = 总任务数`
|
||||
2. 对 `success` 样本抽查 `queryPaymentConfirmList`，确认 `div_members` 包含 `memberId=0`
|
||||
3. `failed` 有明确可重试策略或人工处理结论
|
||||
|
||||
## 4.5 回滚预案（必要时）
|
||||
|
||||
如果误分账到错误对象或金额错误：
|
||||
|
||||
1. 从 `success.csv` 取 `payment_confirm_id`
|
||||
2. 调用 `createConfirmReverse(paymentConfirmId, wechatAppId)` 撤销支付确认
|
||||
3. 撤销后重新按正确参数执行补分账
|
||||
|
||||
代码参考：
|
||||
|
||||
- `AdapayService.createConfirmReverse(...)`
|
||||
|
||||
## 5. 下次同类任务复用清单
|
||||
|
||||
执行前 Checklist：
|
||||
|
||||
1. 明细文件是否包含 `payment_id`、`remaining_amt`、`pay_amt`
|
||||
2. 是否确认目标账户（本 SOP 为 `memberId=0`）
|
||||
3. 是否先做 100 条小批次试跑
|
||||
4. 是否有完整执行日志与 `success/skipped/failed` 三份结果
|
||||
5. 是否准备了 `payment_confirm_id` 级别回滚能力
|
||||
|
||||
执行后 Checklist：
|
||||
|
||||
1. 失败项是否重试完毕
|
||||
2. 关键样本是否验证到汇付侧最新状态
|
||||
3. 本次任务结果文件是否归档到 `doc/` 或运维归档目录
|
||||
|
||||
## 6. 当前已落地入口
|
||||
|
||||
已新增任务方法（`JsowellTask`）：
|
||||
|
||||
- `importAdapayUnsplitRecordAndCompleteFields()`
|
||||
- `importAdapayUnsplitRecordAndCompleteFields(String filePath)`
|
||||
|
||||
实现位置：
|
||||
|
||||
- `jsowell-quartz/src/main/java/com/jsowell/quartz/task/JsowellTask.java`
|
||||
|
||||
方法职责：
|
||||
|
||||
1. 从 Excel 导入 `adapay_unsplit_record`（按 `insertOrUpdateSelective`，支持重复执行）
|
||||
2. 自动补齐 `order_code / due_refund_amount / settle_amount / pile_type` 等缺失字段
|
||||
3. 输出导入与补齐统计日志
|
||||
|
||||
执行示例：
|
||||
|
||||
- 使用默认路径：`jsowellTask.importAdapayUnsplitRecordAndCompleteFields()`
|
||||
- 指定路径：`jsowellTask.importAdapayUnsplitRecordAndCompleteFields('doc/万车充小程序-未分账明细.xlsx')`
|
||||
|
||||
## 7. 完整执行流程（落地版）
|
||||
|
||||
以下流程是当前代码已支持、可直接按顺序执行的标准操作。
|
||||
|
||||
### 7.1 执行前检查
|
||||
|
||||
1. 使用 JDK8。
|
||||
2. 编译通过：
|
||||
|
||||
```bash
|
||||
mvn -pl jsowell-quartz -am -DskipTests compile
|
||||
```
|
||||
|
||||
3. 确认 Excel 文件就绪：
|
||||
|
||||
- 默认路径：`doc/万车充小程序-未分账明细.xlsx`
|
||||
- 或你自己的绝对路径/相对路径
|
||||
|
||||
### 7.2 第一步：导入并补齐缺失字段
|
||||
|
||||
执行任务方法（任选其一）：
|
||||
|
||||
1. 默认路径：
|
||||
|
||||
```text
|
||||
jsowellTask.importAdapayUnsplitRecordAndCompleteFields()
|
||||
```
|
||||
|
||||
2. 指定路径：
|
||||
|
||||
```text
|
||||
jsowellTask.importAdapayUnsplitRecordAndCompleteFields('doc/万车充小程序-未分账明细.xlsx')
|
||||
```
|
||||
|
||||
本步骤会自动完成：
|
||||
|
||||
1. Excel -> `adapay_unsplit_record` 导入（`insertOrUpdateSelective`，可重复执行）
|
||||
2. 自动补齐 `order_code / due_refund_amount / settle_amount / pile_type`
|
||||
3. 输出导入统计与补齐统计日志
|
||||
|
||||
### 7.3 第二步：导入后校验
|
||||
|
||||
建议执行以下 SQL：
|
||||
|
||||
```sql
|
||||
-- 总量
|
||||
SELECT COUNT(*) AS total_cnt
|
||||
FROM adapay_unsplit_record;
|
||||
|
||||
-- 核心补齐字段缺失情况
|
||||
SELECT COUNT(*) AS missing_cnt
|
||||
FROM adapay_unsplit_record
|
||||
WHERE order_code IS NULL
|
||||
OR settle_amount IS NULL
|
||||
OR due_refund_amount IS NULL
|
||||
OR pile_type IS NULL;
|
||||
```
|
||||
|
||||
`missing_cnt` 理想结果应接近 `0`（少量异常数据可人工排查）。
|
||||
|
||||
### 7.4 第三步：执行未分账处理（分账到 memberId=0）
|
||||
|
||||
执行任务方法（任选其一）：
|
||||
|
||||
1. 使用默认 appId（`Constants.DEFAULT_APP_ID`）+ pageSize=500：
|
||||
|
||||
```text
|
||||
jsowellTask.processUnsplitRecordToDefaultMember()
|
||||
```
|
||||
|
||||
2. 指定 appId 和分页大小：
|
||||
|
||||
```text
|
||||
jsowellTask.processUnsplitRecordToDefaultMember('你的wechatAppId', 200)
|
||||
```
|
||||
|
||||
建议先用 `200` 小批量试跑，再提升到 `500`。
|
||||
|
||||
本步骤会自动完成：
|
||||
|
||||
1. 分页读取 `queryList()` 的待分账记录
|
||||
2. 先查汇付最新确认信息，计算实时剩余可分账金额
|
||||
3. 取 `min(数据库待分账金额, 汇付实时剩余金额)` 作为本次 `confirmAmt`
|
||||
4. 调 `PaymentConfirm` 分账，分账对象固定 `memberId=0`
|
||||
5. 回写结果：
|
||||
- 成功：更新 `confirmed_split_amount`，`split_flag=SUCCESS`
|
||||
- 失败：`split_flag=FAILED`
|
||||
|
||||
### 7.5 第四步：循环执行直到待分账清零
|
||||
|
||||
每轮执行后，建议跑以下 SQL：
|
||||
|
||||
```sql
|
||||
-- 按当前业务口径，仍待处理数量
|
||||
SELECT COUNT(*) AS remain_cnt
|
||||
FROM adapay_unsplit_record
|
||||
WHERE (settle_amount > confirmed_split_amount - payment_revoke_amount)
|
||||
OR (due_refund_amount > refund_amount);
|
||||
|
||||
-- 分账结果分布
|
||||
SELECT split_flag, COUNT(*) AS cnt
|
||||
FROM adapay_unsplit_record
|
||||
GROUP BY split_flag;
|
||||
```
|
||||
|
||||
当 `remain_cnt = 0` 可视为本次补分账完成。
|
||||
|
||||
### 7.6 失败重试与回滚
|
||||
|
||||
1. 失败重试：重新执行 `processUnsplitRecordToDefaultMember(...)` 即可。
|
||||
2. 回滚（如金额或目标账户异常）：
|
||||
- 按 `paymentId` 查询对应 `payment_confirm_id`
|
||||
- 调 `createConfirmReverse(paymentConfirmId, wechatAppId)` 撤销
|
||||
- 重新执行正确参数的分账流程
|
||||
|
||||
## 8. 一键操作建议（便于下次复用）
|
||||
|
||||
按下面顺序执行，基本可覆盖同类任务：
|
||||
|
||||
1. `jsowellTask.importAdapayUnsplitRecordAndCompleteFields('文件路径')`
|
||||
2. 校验 `missing_cnt`
|
||||
3. `jsowellTask.processUnsplitRecordToDefaultMember('appId', 200)`
|
||||
4. 查看 `remain_cnt`
|
||||
5. 若 `remain_cnt > 0`，重复第 3-4 步，最后切 `pageSize=500` 提速
|
||||
111
docs/万车充接口补充.md
Normal file
111
docs/万车充接口补充.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 首页站点筛选
|
||||
|
||||
```
|
||||
接口地址：/uniapp/pile/queryStationInfosV2
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------- | ------ | -------- | ---------------------- |
|
||||
| sortType | String | N | 1-低价优先；2-距离最近 |
|
||||
| chargeMode | String | N | 1-直流；2-交流 |
|
||||
| chargeSpeed | String | N | 1-快充；2-慢充；3-超充 |
|
||||
| canopyFlag | String | N | 是否有雨棚 |
|
||||
| barrierFlag | String | N | 是否有道闸 |
|
||||
| parkingLockFlag | String | N | 是否有地锁 |
|
||||
| myCollectionFlag | String | N | 我的收藏 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ---- |
|
||||
| | | | |
|
||||
|
||||
# 首页站点列表
|
||||
|
||||
```
|
||||
接口地址：/uniapp/pile/queryStationInfos
|
||||
```
|
||||
|
||||
**加字段：**当前站点最近充电的一次时间
|
||||
|
||||
**加字段：**异常设备数量
|
||||
|
||||
# 站点详情枪口信息
|
||||
|
||||
```
|
||||
接口地址：uniapp/pile/selectStationConnectorList
|
||||
```
|
||||
|
||||
**实现：**根据前端传入的枪口状态参数，动态返回匹配的实时数据信息，实现状态与数据的精准响应。
|
||||
|
||||
# 查询站点收藏
|
||||
|
||||
```
|
||||
接口地址：/uniapp/member/getCollectedStationIdList
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------ | -------- | ------------ |
|
||||
| memberId | String | Y | 存在Header中 |
|
||||
| stationLng | String | Y | 当前位置经度 |
|
||||
| stationLat | String | N | 当前位置纬度 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ---- |
|
||||
| | | | |
|
||||
|
||||
# （添加/删除） 站点收藏
|
||||
|
||||
```
|
||||
接口地址：/uniapp/member/updateCollectedStation
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------ | ------- | -------- | ----------------------------------------- |
|
||||
| memberId | String | Y | 存在Header中 |
|
||||
| stationId | String | Y | 站点id |
|
||||
| operatorType | Boolean | Y | 操作类型（true-添加收藏；false-取消收藏） |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ---- |
|
||||
| | | | |
|
||||
|
||||
# 查询用户常去站点（最近半年）
|
||||
|
||||
```text
|
||||
接口地址：/uniapp/member/getUserFrequentedStationList
|
||||
请求方式：GET
|
||||
```
|
||||
|
||||
### **入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------- | ------ | -------- | ------ |
|
||||
| memberId | String | Y | 会员id |
|
||||
|
||||
### **反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------------------- | ------------------------- | -------- | ------------------------ |
|
||||
| List<UserFrequentedStationInfo> | UserFrequentedStationInfo | Y | 按照充电次数从高到低排序 |
|
||||
|
||||
#### UserFrequentedStationInfo
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | -------- |
|
||||
| stationId | String | Y | 站点id |
|
||||
| stationName | String | Y | 站点名称 |
|
||||
| chargeNum | int | Y | 充电次数 |
|
||||
111
docs/充电桩数据同步.md
Normal file
111
docs/充电桩数据同步.md
Normal file
@@ -0,0 +1,111 @@
|
||||
充电桩数据首先是在web项目生成的，现在需要把web项目生成的充电桩数据同步到JCPP项目中，用于登录鉴权等操作
|
||||
|
||||
下面是web项目中充电桩相关表结构（注意使用的是mysql 5.7）
|
||||
|
||||
~~~mysql
|
||||
CREATE TABLE `pile_basic_info` (
|
||||
`id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`name` varchar(32) DEFAULT NULL COMMENT '别名',
|
||||
`sn` varchar(20) DEFAULT NULL COMMENT '桩号',
|
||||
`business_type` char(5) DEFAULT NULL COMMENT '经营类型（1-运营桩；2-个人桩）',
|
||||
`secret_key` varchar(10) DEFAULT NULL COMMENT '个人桩密钥',
|
||||
`software_protocol` varchar(20) DEFAULT NULL COMMENT '软件协议（yunkuaichongV150--云快充V1.5；yunkuaichongV160--云快充V1.6；yonglianV1--永联；youdianV1--友电）',
|
||||
`production_date` datetime DEFAULT NULL COMMENT '生产日期',
|
||||
`licence_id` int(11) DEFAULT NULL COMMENT '证书编号',
|
||||
`model_id` int(11) DEFAULT NULL COMMENT '充电桩型号',
|
||||
`sim_id` int(11) DEFAULT NULL COMMENT 'sim卡id',
|
||||
`iccid` varchar(50) DEFAULT NULL COMMENT 'sim卡iccid',
|
||||
`merchant_id` int(11) DEFAULT NULL COMMENT '运营商id',
|
||||
`station_id` int(11) DEFAULT NULL COMMENT '充电站id',
|
||||
`longitude` varchar(30) DEFAULT NULL COMMENT '经度',
|
||||
`latitude` varchar(30) DEFAULT NULL COMMENT '纬度',
|
||||
`vin_flag` char(5) DEFAULT NULL COMMENT '是否支持汽车VIN码识别',
|
||||
`fault_reason` varchar(255) DEFAULT NULL COMMENT '故障原因',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(20) DEFAULT NULL COMMENT '更新人',
|
||||
`update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` char(5) DEFAULT '0' COMMENT '删除标识（0-正常；1-删除）',
|
||||
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
|
||||
PRIMARY KEY (`id`) USING BTREE,
|
||||
KEY `idx_sn` (`sn`) USING BTREE,
|
||||
KEY `idx_station_id` (`station_id`) USING BTREE,
|
||||
KEY `idx_iccid` (`iccid`) USING BTREE
|
||||
) ENGINE=InnoDB AUTO_INCREMENT=6845 DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='充电桩基本信息表';
|
||||
|
||||
CREATE TABLE `pile_connector_info` (
|
||||
`id` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`name` varchar(20) DEFAULT NULL COMMENT '名称',
|
||||
`pile_sn` varchar(20) DEFAULT NULL COMMENT '所属充电桩sn',
|
||||
`pile_connector_code` varchar(20) DEFAULT NULL COMMENT '充电枪编号，由充电桩SN+01生成',
|
||||
`status` varchar(5) DEFAULT '0' COMMENT '状态 0：离网 (默认)；1：空闲；2：占用（未充电）；3：占用（充电中）；4：占用（预约锁定） ；255：故障 ',
|
||||
`park_no` varchar(5) DEFAULT NULL COMMENT '车位号（推送联联平台所用字段）',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(20) DEFAULT NULL COMMENT '更新人',
|
||||
`update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` char(1) DEFAULT '0' COMMENT '删除标识（0-正常；1-删除）',
|
||||
PRIMARY KEY (`id`) USING BTREE,
|
||||
KEY `idx_pile_sn` (`pile_sn`) USING BTREE,
|
||||
KEY `idx_code` (`pile_connector_code`) USING BTREE
|
||||
) ENGINE=InnoDB AUTO_INCREMENT=30061 DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='充电桩枪口信息表';
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
下面是JCPP项目充电桩相关表结构(注意使用的是postgreSQL 17)
|
||||
|
||||
~~~
|
||||
CREATE TABLE "public"."t_pile" (
|
||||
"id" uuid NOT NULL,
|
||||
"created_time" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updated_time" timestamp(6),
|
||||
"additional_info" jsonb,
|
||||
"pile_name" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"pile_code" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"protocol" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"station_id" uuid NOT NULL,
|
||||
"brand" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"model" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"manufacturer" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"type" varchar(16) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"version" int4 DEFAULT 1,
|
||||
CONSTRAINT "pile_pkey" PRIMARY KEY ("id")
|
||||
)
|
||||
;
|
||||
|
||||
ALTER TABLE "public"."t_pile"
|
||||
OWNER TO "postgres";
|
||||
|
||||
CREATE UNIQUE INDEX "uni_pile_code" ON "public"."t_pile" USING btree (
|
||||
"pile_code" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
|
||||
CREATE TABLE "public"."t_gun" (
|
||||
"id" uuid NOT NULL,
|
||||
"created_time" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updated_time" timestamp(6),
|
||||
"additional_info" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"gun_no" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"gun_name" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"gun_code" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"station_id" uuid NOT NULL,
|
||||
"pile_id" uuid NOT NULL,
|
||||
"version" int4 DEFAULT 1,
|
||||
CONSTRAINT "t_gun_pkey" PRIMARY KEY ("id")
|
||||
)
|
||||
;
|
||||
|
||||
ALTER TABLE "public"."t_gun"
|
||||
OWNER TO "postgres";
|
||||
|
||||
CREATE UNIQUE INDEX "uni_gun_code" ON "public"."t_gun" USING btree (
|
||||
"gun_code" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX "uni_gun_pile_gun_no" ON "public"."t_gun" USING btree (
|
||||
"pile_id" "pg_catalog"."uuid_ops" ASC NULLS LAST,
|
||||
"gun_no" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
~~~
|
||||
|
||||
464
docs/充电桩数据同步实现计划.md
Normal file
464
docs/充电桩数据同步实现计划.md
Normal file
@@ -0,0 +1,464 @@
|
||||
# 充电桩数据同步实现计划
|
||||
|
||||
> 创建时间：2025-12-30
|
||||
> 任务状态：规划中
|
||||
|
||||
---
|
||||
|
||||
## 一、需求概述
|
||||
|
||||
将 Web 项目（MySQL）中的充电桩数据同步到 JCPP 项目（PostgreSQL）中，用于登录鉴权等操作。
|
||||
|
||||
### 1.1 数据流向
|
||||
```
|
||||
Web 项目 (MySQL) → JCPP 项目 (PostgreSQL)
|
||||
```
|
||||
|
||||
### 1.2 同步方式
|
||||
- **全量同步**：同步所有充电桩和充电枪数据
|
||||
- **增量同步**：只同步新增或修改的数据（基于 update_time）
|
||||
|
||||
---
|
||||
|
||||
## 二、表结构映射分析
|
||||
|
||||
### 2.1 充电桩表映射
|
||||
|
||||
| Web 字段 (pile_basic_info) | JCPP 字段 (t_pile) | 映射说明 |
|
||||
|---------------------------|-------------------|---------|
|
||||
| id (int) | - | Web 主键，不同步 |
|
||||
| sn (varchar(20)) | pile_code (varchar(255)) | 充电桩编码，唯一标识 |
|
||||
| name (varchar(32)) | pile_name (varchar(255)) | 充电桩名称 |
|
||||
| software_protocol (varchar(20)) | protocol (varchar(255)) | 软件协议 |
|
||||
| station_id (int) | station_id (uuid) | ✅ 统一使用固定值 '88bca8da-cdbf-6587-aecc-75784838c501' |
|
||||
| model_id (int) | model (varchar(255)) | 型号，需要查询转换 |
|
||||
| - | brand (varchar(255)) | 品牌，可为空 |
|
||||
| - | manufacturer (varchar(255)) | 制造商，可为空 |
|
||||
| business_type (char(5)) | type (varchar(16)) | 经营类型映射 |
|
||||
| 其他字段 | additional_info (jsonb) | 存储为 JSON |
|
||||
|
||||
### 2.2 充电枪表映射
|
||||
|
||||
| Web 字段 (pile_connector_info) | JCPP 字段 (t_gun) | 映射说明 |
|
||||
|-------------------------------|------------------|---------|
|
||||
| id (int) | - | Web 主键，不同步 |
|
||||
| pile_connector_code (varchar(20)) | gun_code (varchar(255)) | 充电枪编码，唯一标识 |
|
||||
| name (varchar(20)) | gun_name (varchar(255)) | 充电枪名称 |
|
||||
| pile_sn (varchar(20)) | pile_id (uuid) | ⚠️ 需要通过 pile_code 查询 pile_id |
|
||||
| - | gun_no (varchar(255)) | 枪号，从 pile_connector_code 提取 |
|
||||
| - | station_id (uuid) | ✅ 统一使用固定值 '88bca8da-cdbf-6587-aecc-75784838c501' |
|
||||
|
||||
### 2.3 关键问题
|
||||
|
||||
#### 问题1：station_id 类型映射（int → uuid）
|
||||
**解决方案**：
|
||||
- ✅ 统一使用固定的 UUID 值：`88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 所有充电桩都使用这个固定的 station_id
|
||||
- Web 的原始 station_id 保存在 additional_info 中便于追溯
|
||||
|
||||
#### 问题2：pile_id 获取
|
||||
**解决方案**：
|
||||
- 先同步充电桩，获取返回的 pile_id
|
||||
- 再同步充电枪时，通过 pile_code 查询 pile_id
|
||||
|
||||
#### 问题3：gun_no 提取
|
||||
**解决方案**：
|
||||
- pile_connector_code 格式为 "桩号+枪号"（如：20231212000010**01**）
|
||||
- 提取最后 2 位作为 gun_no
|
||||
|
||||
---
|
||||
|
||||
## 三、实现方案
|
||||
|
||||
### 3.1 Web 项目实现（本项目）
|
||||
|
||||
#### 3.1.1 数据传输对象（DTO）
|
||||
|
||||
**文件位置**：`jsowell-pile/src/main/java/com/jsowell/pile/jcpp/dto/sync/`
|
||||
|
||||
1. **JcppPileSyncDTO** - 充电桩同步数据
|
||||
```java
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"pileName": "1号充电桩",
|
||||
"protocol": "yunkuaichongV150",
|
||||
"brand": "特来电",
|
||||
"model": "AC-7KW",
|
||||
"manufacturer": "特来电",
|
||||
"type": "OPERATION", // OPERATION-运营桩, PERSONAL-个人桩
|
||||
"additionalInfo": {
|
||||
"webPileId": 6844,
|
||||
"webStationId": 123, // 保存 Web 的原始 station_id
|
||||
"businessType": "1",
|
||||
"secretKey": "abc123",
|
||||
"longitude": "116.404",
|
||||
"latitude": "39.915",
|
||||
"iccid": "89860123456789012345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：所有充电桩的 station_id 统一使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
|
||||
2. **JcppGunSyncDTO** - 充电枪同步数据
|
||||
```java
|
||||
{
|
||||
"gunCode": "2023121200001001",
|
||||
"gunName": "1号枪",
|
||||
"gunNo": "01",
|
||||
"pileCode": "20231212000010",
|
||||
"additionalInfo": {
|
||||
"webGunId": 30060,
|
||||
"status": "1",
|
||||
"parkNo": "A01"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **JcppSyncRequest** - 同步请求
|
||||
```java
|
||||
{
|
||||
"syncType": "FULL", // FULL-全量, INCREMENTAL-增量
|
||||
"lastSyncTime": "2025-12-30 10:00:00", // 增量同步时使用
|
||||
"piles": [...],
|
||||
"guns": [...]
|
||||
}
|
||||
```
|
||||
|
||||
4. **JcppSyncResponse** - 同步响应
|
||||
```java
|
||||
{
|
||||
"success": true,
|
||||
"message": "同步成功",
|
||||
"totalPiles": 100,
|
||||
"successPiles": 98,
|
||||
"failedPiles": 2,
|
||||
"totalGuns": 200,
|
||||
"successGuns": 195,
|
||||
"failedGuns": 5,
|
||||
"errors": [...]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.1.2 服务接口
|
||||
|
||||
**文件位置**：`jsowell-pile/src/main/java/com/jsowell/pile/jcpp/service/`
|
||||
|
||||
1. **IJcppPileSyncService** - 充电桩同步服务接口
|
||||
```java
|
||||
public interface IJcppPileSyncService {
|
||||
/**
|
||||
* 全量同步充电桩数据到 JCPP
|
||||
*/
|
||||
JcppSyncResponse syncAllPiles();
|
||||
|
||||
/**
|
||||
* 增量同步充电桩数据到 JCPP
|
||||
* @param lastSyncTime 上次同步时间
|
||||
*/
|
||||
JcppSyncResponse syncIncrementalPiles(Date lastSyncTime);
|
||||
|
||||
/**
|
||||
* 同步单个充电桩
|
||||
*/
|
||||
boolean syncSinglePile(String pileSn);
|
||||
}
|
||||
```
|
||||
|
||||
2. **JcppPileSyncServiceImpl** - 实现类
|
||||
- 查询 Web 数据库
|
||||
- 转换数据格式
|
||||
- 调用 JCPP 接口发送数据
|
||||
- 处理同步结果
|
||||
|
||||
#### 3.1.3 Controller 接口
|
||||
|
||||
**文件位置**：`jsowell-admin/src/main/java/com/jsowell/web/controller/jcpp/`
|
||||
|
||||
**JcppPileSyncController**
|
||||
```java
|
||||
@RestController
|
||||
@RequestMapping("/jcpp/sync")
|
||||
public class JcppPileSyncController {
|
||||
|
||||
/**
|
||||
* 全量同步充电桩数据
|
||||
* POST /jcpp/sync/full
|
||||
*/
|
||||
@PostMapping("/full")
|
||||
public AjaxResult syncFull();
|
||||
|
||||
/**
|
||||
* 增量同步充电桩数据
|
||||
* POST /jcpp/sync/incremental
|
||||
* @param lastSyncTime 上次同步时间（可选，默认取上次记录）
|
||||
*/
|
||||
@PostMapping("/incremental")
|
||||
public AjaxResult syncIncremental(@RequestParam(required = false) Date lastSyncTime);
|
||||
|
||||
/**
|
||||
* 同步单个充电桩
|
||||
* POST /jcpp/sync/pile/{pileSn}
|
||||
*/
|
||||
@PostMapping("/pile/{pileSn}")
|
||||
public AjaxResult syncSinglePile(@PathVariable String pileSn);
|
||||
|
||||
/**
|
||||
* 查询同步记录
|
||||
* GET /jcpp/sync/records
|
||||
*/
|
||||
@GetMapping("/records")
|
||||
public TableDataInfo getSyncRecords();
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.1.4 同步记录表
|
||||
|
||||
**表名**：`jcpp_sync_record`
|
||||
```sql
|
||||
CREATE TABLE `jcpp_sync_record` (
|
||||
`id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`sync_type` varchar(20) NOT NULL COMMENT '同步类型（FULL-全量；INCREMENTAL-增量）',
|
||||
`sync_status` varchar(20) NOT NULL COMMENT '同步状态（RUNNING-进行中；SUCCESS-成功；FAILED-失败）',
|
||||
`start_time` datetime NOT NULL COMMENT '开始时间',
|
||||
`end_time` datetime DEFAULT NULL COMMENT '结束时间',
|
||||
`total_piles` int(11) DEFAULT 0 COMMENT '总充电桩数',
|
||||
`success_piles` int(11) DEFAULT 0 COMMENT '成功充电桩数',
|
||||
`failed_piles` int(11) DEFAULT 0 COMMENT '失败充电桩数',
|
||||
`total_guns` int(11) DEFAULT 0 COMMENT '总充电枪数',
|
||||
`success_guns` int(11) DEFAULT 0 COMMENT '成功充电枪数',
|
||||
`failed_guns` int(11) DEFAULT 0 COMMENT '失败充电枪数',
|
||||
`error_message` text COMMENT '错误信息',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
PRIMARY KEY (`id`),
|
||||
KEY `idx_sync_type` (`sync_type`),
|
||||
KEY `idx_start_time` (`start_time`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='JCPP 充电桩同步记录表';
|
||||
```
|
||||
|
||||
#### 3.1.5 配置项
|
||||
|
||||
**配置文件**：`application-{env}.yml`
|
||||
```yaml
|
||||
jcpp:
|
||||
sync:
|
||||
# JCPP 同步接口地址
|
||||
api-url: http://jcpp-server:8080/api/sync
|
||||
# 批量同步大小
|
||||
batch-size: 100
|
||||
# 超时时间（秒）
|
||||
timeout: 60
|
||||
# 是否启用自动增量同步
|
||||
auto-sync-enabled: false
|
||||
# 自动同步间隔（分钟）
|
||||
auto-sync-interval: 30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 JCPP 项目实现（需要配合）
|
||||
|
||||
#### 3.2.1 需要实现的接口
|
||||
|
||||
**接口1：接收充电桩同步数据**
|
||||
```
|
||||
POST /api/sync/piles
|
||||
Content-Type: application/json
|
||||
|
||||
Request Body:
|
||||
{
|
||||
"piles": [
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"pileName": "1号充电桩",
|
||||
"protocol": "yunkuaichongV150",
|
||||
"brand": "特来电",
|
||||
"model": "AC-7KW",
|
||||
"manufacturer": "特来电",
|
||||
"type": "OPERATION",
|
||||
"additionalInfo": {
|
||||
"webStationId": 123 // Web 的原始 station_id
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"success": true,
|
||||
"message": "同步成功",
|
||||
"results": [
|
||||
{
|
||||
"pileCode": "20231212000010",
|
||||
"pileId": "uuid",
|
||||
"success": true,
|
||||
"message": "创建成功"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：所有充电桩的 station_id 统一使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
|
||||
**接口2：接收充电枪同步数据**
|
||||
```
|
||||
POST /api/sync/guns
|
||||
Content-Type: application/json
|
||||
|
||||
Request Body:
|
||||
{
|
||||
"guns": [
|
||||
{
|
||||
"gunCode": "2023121200001001",
|
||||
"gunName": "1号枪",
|
||||
"gunNo": "01",
|
||||
"pileCode": "20231212000010",
|
||||
"additionalInfo": {...}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"success": true,
|
||||
"message": "同步成功",
|
||||
"results": [...]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.2 数据处理逻辑
|
||||
|
||||
1. **充电桩同步逻辑**
|
||||
- 根据 pile_code 判断是否已存在
|
||||
- 存在则更新，不存在则创建
|
||||
- station_id 统一使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 返回 pile_id (uuid)
|
||||
|
||||
2. **充电枪同步逻辑**
|
||||
- 根据 gun_code 判断是否已存在
|
||||
- 通过 pile_code 查询 pile_id
|
||||
- station_id 统一使用固定值 `88bca8da-cdbf-6587-aecc-75784838c501`
|
||||
- 存在则更新，不存在则创建
|
||||
|
||||
---
|
||||
|
||||
## 四、实现步骤
|
||||
|
||||
### 阶段一：Web 项目基础实现 ✅
|
||||
|
||||
- [x] 1. 创建 DTO 类（JcppPileSyncDTO、JcppGunSyncDTO、JcppSyncRequest、JcppSyncResponse、JcppSyncResult）
|
||||
- [x] 2. 创建同步记录表（jcpp_sync_record）及 Mapper
|
||||
- [x] 3. 创建 Service 接口和实现类（IJcppPileSyncService、JcppPileSyncServiceImpl）
|
||||
- [x] 4. 创建 Controller 接口（JcppPileSyncController）
|
||||
- [x] 5. 添加配置项（application-sit.yml）
|
||||
|
||||
**已完成文件**：
|
||||
- DTO: `JcppPileSyncDTO.java`, `JcppGunSyncDTO.java`, `JcppSyncRequest.java`, `JcppSyncResponse.java`, `JcppSyncResult.java`
|
||||
- Domain: `JcppSyncRecord.java`
|
||||
- Mapper: `JcppSyncRecordMapper.java`, `JcppSyncRecordMapper.xml`
|
||||
- Service: `IJcppPileSyncService.java`, `JcppPileSyncServiceImpl.java`
|
||||
- Controller: `JcppPileSyncController.java`
|
||||
- SQL: `sql/jcpp_sync_record.sql`
|
||||
- Config: `application-sit.yml` (已添加 jcpp.sync 配置)
|
||||
|
||||
### 阶段二：JCPP 项目配合实现 ⏳
|
||||
|
||||
- [ ] 1. 实现充电桩同步接口（使用固定 station_id）
|
||||
- [ ] 2. 实现充电枪同步接口（使用固定 station_id）
|
||||
|
||||
### 阶段三：联调测试 ⏳
|
||||
|
||||
- [ ] 1. 测试全量同步
|
||||
- [ ] 2. 测试增量同步
|
||||
- [ ] 3. 测试单个充电桩同步
|
||||
- [ ] 4. 测试异常场景
|
||||
- [ ] 5. 性能测试
|
||||
|
||||
### 阶段四：优化完善 ⏳
|
||||
|
||||
- [ ] 1. 添加重试机制
|
||||
- [ ] 2. 添加同步进度查询
|
||||
- [ ] 3. 添加定时自动同步
|
||||
- [ ] 4. 完善错误处理和日志
|
||||
|
||||
---
|
||||
|
||||
## 五、技术要点
|
||||
|
||||
### 5.1 数据转换
|
||||
|
||||
1. **business_type 映射**
|
||||
- Web: "1"-运营桩, "2"-个人桩
|
||||
- JCPP: "OPERATION"-运营桩, "PERSONAL"-个人桩
|
||||
|
||||
2. **gun_no 提取**
|
||||
- pile_connector_code: "2023121200001001"
|
||||
- gun_no: "01" (最后2位)
|
||||
|
||||
3. **additional_info 构建**
|
||||
- 将 Web 的其他字段存储为 JSON
|
||||
- 保留原始 ID 便于追溯
|
||||
|
||||
### 5.2 性能优化
|
||||
|
||||
1. **批量同步**
|
||||
- 每批 100 条数据
|
||||
- 避免一次性加载所有数据
|
||||
|
||||
2. **异步处理**
|
||||
- 全量同步使用异步任务
|
||||
- 返回任务 ID，可查询进度
|
||||
|
||||
3. **增量同步**
|
||||
- 基于 update_time 字段
|
||||
- 记录上次同步时间
|
||||
|
||||
### 5.3 异常处理
|
||||
|
||||
1. **网络异常**
|
||||
- 重试机制（最多3次）
|
||||
- 指数退避策略
|
||||
|
||||
2. **数据异常**
|
||||
- 记录失败数据
|
||||
- 继续处理其他数据
|
||||
|
||||
3. **事务处理**
|
||||
- JCPP 端保证事务一致性
|
||||
- Web 端记录同步状态
|
||||
|
||||
---
|
||||
|
||||
## 六、注意事项
|
||||
|
||||
1. **数据一致性**
|
||||
- 充电桩必须先于充电枪同步
|
||||
- 确保 pile_code 唯一性
|
||||
|
||||
2. **性能考虑**
|
||||
- 全量同步可能耗时较长
|
||||
- 建议在业务低峰期执行
|
||||
|
||||
3. **安全性**
|
||||
- 同步接口需要鉴权
|
||||
- 敏感数据加密传输
|
||||
|
||||
4. **监控告警**
|
||||
- 同步失败告警
|
||||
- 同步耗时监控
|
||||
|
||||
---
|
||||
|
||||
## 七、变更记录
|
||||
|
||||
| 日期 | 版本 | 修改人 | 修改内容 |
|
||||
|------|------|--------|----------|
|
||||
| 2025-12-30 | v1.0 | Claude | 创建文档，制定实现计划 |
|
||||
|
||||
---
|
||||
|
||||
## 八、相关文档
|
||||
|
||||
- [充电桩数据同步需求.md](充电桩数据同步需求.md)
|
||||
- [JCPP对接进度文档.md](JCPP对接进度文档.md)
|
||||
111
docs/充电桩数据同步需求.md
Normal file
111
docs/充电桩数据同步需求.md
Normal file
@@ -0,0 +1,111 @@
|
||||
充电桩数据首先是在web项目生成的，现在需要把web项目生成的充电桩数据同步到JCPP项目中，用于登录鉴权等操作
|
||||
|
||||
下面是web项目中充电桩相关表结构（注意使用的是mysql 5.7）
|
||||
|
||||
~~~mysql
|
||||
CREATE TABLE `pile_basic_info` (
|
||||
`id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`name` varchar(32) DEFAULT NULL COMMENT '别名',
|
||||
`sn` varchar(20) DEFAULT NULL COMMENT '桩号',
|
||||
`business_type` char(5) DEFAULT NULL COMMENT '经营类型（1-运营桩；2-个人桩）',
|
||||
`secret_key` varchar(10) DEFAULT NULL COMMENT '个人桩密钥',
|
||||
`software_protocol` varchar(20) DEFAULT NULL COMMENT '软件协议（yunkuaichongV150--云快充V1.5；yunkuaichongV160--云快充V1.6；yonglianV1--永联；youdianV1--友电）',
|
||||
`production_date` datetime DEFAULT NULL COMMENT '生产日期',
|
||||
`licence_id` int(11) DEFAULT NULL COMMENT '证书编号',
|
||||
`model_id` int(11) DEFAULT NULL COMMENT '充电桩型号',
|
||||
`sim_id` int(11) DEFAULT NULL COMMENT 'sim卡id',
|
||||
`iccid` varchar(50) DEFAULT NULL COMMENT 'sim卡iccid',
|
||||
`merchant_id` int(11) DEFAULT NULL COMMENT '运营商id',
|
||||
`station_id` int(11) DEFAULT NULL COMMENT '充电站id',
|
||||
`longitude` varchar(30) DEFAULT NULL COMMENT '经度',
|
||||
`latitude` varchar(30) DEFAULT NULL COMMENT '纬度',
|
||||
`vin_flag` char(5) DEFAULT NULL COMMENT '是否支持汽车VIN码识别',
|
||||
`fault_reason` varchar(255) DEFAULT NULL COMMENT '故障原因',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(20) DEFAULT NULL COMMENT '更新人',
|
||||
`update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` char(5) DEFAULT '0' COMMENT '删除标识（0-正常；1-删除）',
|
||||
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
|
||||
PRIMARY KEY (`id`) USING BTREE,
|
||||
KEY `idx_sn` (`sn`) USING BTREE,
|
||||
KEY `idx_station_id` (`station_id`) USING BTREE,
|
||||
KEY `idx_iccid` (`iccid`) USING BTREE
|
||||
) ENGINE=InnoDB AUTO_INCREMENT=6845 DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='充电桩基本信息表';
|
||||
|
||||
CREATE TABLE `pile_connector_info` (
|
||||
`id` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||||
`name` varchar(20) DEFAULT NULL COMMENT '名称',
|
||||
`pile_sn` varchar(20) DEFAULT NULL COMMENT '所属充电桩sn',
|
||||
`pile_connector_code` varchar(20) DEFAULT NULL COMMENT '充电枪编号，由充电桩SN+01生成',
|
||||
`status` varchar(5) DEFAULT '0' COMMENT '状态 0：离网 (默认)；1：空闲；2：占用（未充电）；3：占用（充电中）；4：占用（预约锁定） ；255：故障 ',
|
||||
`park_no` varchar(5) DEFAULT NULL COMMENT '车位号（推送联联平台所用字段）',
|
||||
`create_by` varchar(20) DEFAULT NULL COMMENT '创建人',
|
||||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||||
`update_by` varchar(20) DEFAULT NULL COMMENT '更新人',
|
||||
`update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||||
`del_flag` char(1) DEFAULT '0' COMMENT '删除标识（0-正常；1-删除）',
|
||||
PRIMARY KEY (`id`) USING BTREE,
|
||||
KEY `idx_pile_sn` (`pile_sn`) USING BTREE,
|
||||
KEY `idx_code` (`pile_connector_code`) USING BTREE
|
||||
) ENGINE=InnoDB AUTO_INCREMENT=30061 DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='充电桩枪口信息表';
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
下面是JCPP项目充电桩相关表结构(注意使用的是postgreSQL 17)
|
||||
|
||||
~~~
|
||||
CREATE TABLE "public"."t_pile" (
|
||||
"id" uuid NOT NULL,
|
||||
"created_time" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updated_time" timestamp(6),
|
||||
"additional_info" jsonb,
|
||||
"pile_name" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"pile_code" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"protocol" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"station_id" uuid NOT NULL,
|
||||
"brand" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"model" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"manufacturer" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"type" varchar(16) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"version" int4 DEFAULT 1,
|
||||
CONSTRAINT "pile_pkey" PRIMARY KEY ("id")
|
||||
)
|
||||
;
|
||||
|
||||
ALTER TABLE "public"."t_pile"
|
||||
OWNER TO "postgres";
|
||||
|
||||
CREATE UNIQUE INDEX "uni_pile_code" ON "public"."t_pile" USING btree (
|
||||
"pile_code" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
|
||||
CREATE TABLE "public"."t_gun" (
|
||||
"id" uuid NOT NULL,
|
||||
"created_time" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updated_time" timestamp(6),
|
||||
"additional_info" varchar(255) COLLATE "pg_catalog"."default",
|
||||
"gun_no" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"gun_name" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"gun_code" varchar(255) COLLATE "pg_catalog"."default" NOT NULL,
|
||||
"station_id" uuid NOT NULL,
|
||||
"pile_id" uuid NOT NULL,
|
||||
"version" int4 DEFAULT 1,
|
||||
CONSTRAINT "t_gun_pkey" PRIMARY KEY ("id")
|
||||
)
|
||||
;
|
||||
|
||||
ALTER TABLE "public"."t_gun"
|
||||
OWNER TO "postgres";
|
||||
|
||||
CREATE UNIQUE INDEX "uni_gun_code" ON "public"."t_gun" USING btree (
|
||||
"gun_code" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX "uni_gun_pile_gun_no" ON "public"."t_gun" USING btree (
|
||||
"pile_id" "pg_catalog"."uuid_ops" ASC NULLS LAST,
|
||||
"gun_no" COLLATE "pg_catalog"."default" "pg_catalog"."text_ops" ASC NULLS LAST
|
||||
);
|
||||
~~~
|
||||
|
||||
806
docs/小程序接口文档.md
Normal file
806
docs/小程序接口文档.md
Normal file
@@ -0,0 +1,806 @@
|
||||
# 小程序接口
|
||||
|
||||
## 接口返回格式
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------- | ------ | -------- | ---------- |
|
||||
| resCode | String | Y | 返回码 |
|
||||
| msg | String | Y | 返回信息 |
|
||||
| obj | Object | Y | 返回的数据 |
|
||||
|
||||
以下接口反参，指的是obj中的数据，接口返回都有resCode，msg，obj这三个字段。
|
||||
|
||||
**示例**
|
||||
|
||||
~~~json
|
||||
# 入参
|
||||
{
|
||||
"pageSize": "10",
|
||||
"pageNum": "1",
|
||||
"stationLng": "55.96",
|
||||
"stationLat": "155.77"
|
||||
}
|
||||
|
||||
# 反参
|
||||
{
|
||||
"resCode": "00100000",
|
||||
"msg": "操作成功",
|
||||
"obj": {
|
||||
"pageNum": 1,
|
||||
"pageSize": 10,
|
||||
"list": [
|
||||
{
|
||||
"stationId": "2",
|
||||
"stationName": "测试仓库",
|
||||
"stationAddress": "华新镇华隆路1777号6幢D座",
|
||||
"distance": "10745.74",
|
||||
"electricityPrice": null,
|
||||
"servicePrice": null,
|
||||
"fastTotal": 0,
|
||||
"fastFree": 0,
|
||||
"slowTotal": 3,
|
||||
"slowFree": 0
|
||||
},
|
||||
{
|
||||
"stationId": "1",
|
||||
"stationName": "测试",
|
||||
"stationAddress": "黄埔江南路278号举视新能源",
|
||||
"distance": "10762.94",
|
||||
"electricityPrice": null,
|
||||
"servicePrice": null,
|
||||
"fastTotal": 0,
|
||||
"fastFree": 0,
|
||||
"slowTotal": 0,
|
||||
"slowFree": 0
|
||||
}
|
||||
],
|
||||
"total": 2,
|
||||
"pages": 1
|
||||
}
|
||||
}
|
||||
|
||||
# 错误反参
|
||||
{
|
||||
"resCode": "00100010",
|
||||
"msg": "查询充电站信息列表异常",
|
||||
"obj": null
|
||||
}
|
||||
~~~
|
||||
|
||||
# 会员接口
|
||||
|
||||
## 1001 登录注册接口
|
||||
|
||||
## 1002 查询会员信息
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/member/getMemberInfo
|
||||
>
|
||||
> 请求方式：GET
|
||||
|
||||
**入参**
|
||||
|
||||
null，在Header中需传Authorization
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------- | ------ | -------- | ------------ |
|
||||
| MemberVO | Object | Y | 用户信息对象 |
|
||||
|
||||
**MemberVO**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------ | ------ | -------- | --------------------------- |
|
||||
| memberId | String | Y | 会员Id |
|
||||
| status | String | Y | 状态(1-正常;0-停用) |
|
||||
| nickName | String | Y | 用户昵称 |
|
||||
| mobileNumber | String | Y | 手机号码 |
|
||||
| principalPrice | Number | Y | 本金金额 |
|
||||
| giftPrice | Number | Y | 赠送金额 |
|
||||
| totalAccountAmount | Number | Y | 总金额(本金金额 + 赠送金额) |
|
||||
|
||||
|
||||
|
||||
## 1003 修改会员信息
|
||||
|
||||
## 1004 新增会员发票抬头
|
||||
> 接口地址：http://localhost:8080/uniapp/member/createMemberInvoiceTitle
|
||||
>
|
||||
> 请求方式：POST
|
||||
>
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | ---------------- |
|
||||
| titleType | String | Y | 抬头类型（1-单位；2-个人）|
|
||||
| name | Number | Y | 单位名称 |
|
||||
| taxId | Number | Y | 税号 |
|
||||
| unitAddress | String | N | 单位地址 |
|
||||
| phoneNumber | String | N | 电话号码 |
|
||||
| bankName | String | N | 开户银行 |
|
||||
| bankAccountNumber | String | N | 银行账户 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| titleId | String | Y | 发票抬头id |
|
||||
|
||||
|
||||
|
||||
## 1005 查询会员发票抬头列表
|
||||
> 接口地址：http://localhost:8080/uniapp/member/queryMemberInvoiceTitles
|
||||
>
|
||||
> 请求方式：GET
|
||||
>
|
||||
|
||||
**入参**
|
||||
|
||||
null，在Header中需传Authorization
|
||||
|
||||
**反参**
|
||||
|
||||
取obj中的list, 下面是list中对象字段信息
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| titleId | String | Y | 发票抬头id |
|
||||
| titleName | String | Y | 抬头名称 |
|
||||
| titleType | String | Y | 抬头类型 （单位或个人） |
|
||||
|
||||
|
||||
|
||||
## 1006 查询余额明细
|
||||
|
||||
> 请求地址： http://localhost:8080/uniapp/member/getMemberBalanceChanges
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | ------------------------ |
|
||||
| memberToken | String | Y | 会员令牌 |
|
||||
| type | String | Y | 交易类型 1-进账；2-出账 |
|
||||
| pageSize | | | |
|
||||
| pageNum | | | |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------ | ------ | -------- | -------------------------- |
|
||||
| memberId | String | Y | 会员Id |
|
||||
| principalBalance | Number | Y | 当前账户本金余额 |
|
||||
| giftBalance | Number | Y | 当前账户赠送余额 |
|
||||
| totalAccountAmount | Number | Y | 账户总余额 |
|
||||
| type | String | Y | 交易类型 1-进账；2-出账 |
|
||||
| subType | String | Y | 子类型 |
|
||||
| amount | String | Y | 出账/入账金额 |
|
||||
| transactionTime | String | Y | 交易时间 |
|
||||
| category | String | Y | 余额类型（1-本金，2-赠送） |
|
||||
|
||||
|
||||
|
||||
## 1007 通过 memberId 查询用户个人基本信息(查询用户是否已绑定车牌号)
|
||||
|
||||
> 请求地址： http://localhost:8080/uniapp/member/getMemberCarNoInfo
|
||||
>
|
||||
> 请求方式：GET
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------ | ------ | -------- | -------- |
|
||||
| memberId | String | Y | 会员id |
|
||||
| phoneNumber | String | Y | 手机号码 |
|
||||
| licensePlateNumber | String | Y | 车牌号 |
|
||||
| createTime | String | Y | 创建时间 |
|
||||
|
||||
|
||||
|
||||
## 1008 用户绑定车牌号
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/member/memberBindingCarNo
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------- | ------ | -------- | ---------- |
|
||||
| phoneNumber | String | Y | 手机号码 |
|
||||
| verificationCode | String | Y | 短信验证码 |
|
||||
| carNo | String | Y | 车牌号 |
|
||||
|
||||
|
||||
|
||||
## 1009 用户（批量）解绑车牌号
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/member/memberUnbindCarNo
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ------------- | -------- | -------------- |
|
||||
| id | List<Integer> | Y | 要删除的Id集合 |
|
||||
|
||||
**反参**
|
||||
|
||||
会在 “obj” 中返回解绑的条数
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# 充电站接口
|
||||
|
||||
## 2001 根据经纬度查询充电站列表（分页排序）
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/pile/queryStationInfos
|
||||
>
|
||||
> 请求类型：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | ---------------- |
|
||||
| stationLng | String | N | 经度 |
|
||||
| stationLat | String | N | 纬度 |
|
||||
| pageNum | Number | Y | 页码 |
|
||||
| pageSize | Number | Y | 每页数量 |
|
||||
| stationName | String | y | 站点名称（搜索） |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------- | ---------------- | -------- | ---------- |
|
||||
| pageNum | Number | Y | 页码 |
|
||||
| pageSize | Number | Y | 每页数量 |
|
||||
| list | Array<StationVO> | Y | 充电站列表 |
|
||||
| total | Number | Y | 总数 |
|
||||
| pages | Number | Y | 总页数 |
|
||||
|
||||
StationVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------- | ------------- | -------- | --------------------- |
|
||||
| stationId | String | Y | 站点id |
|
||||
| stationName | String | Y | 站点名称 |
|
||||
| stationAddress | String | Y | 站点地址 |
|
||||
| stationImgList | Array<String> | N | 站点图片 |
|
||||
| distance | String | N | 距离 单位千米 |
|
||||
| electricityPrice | String | Y | 电费 每度单价 |
|
||||
| servicePrice | String | Y | 服务费 每度单价 |
|
||||
| totalPrice | String | Y | 总金额（电费+服务费） |
|
||||
| fastTotal | Number | Y | 快充枪口总数 |
|
||||
| fastFree | Number | Y | 快充枪口空闲数 |
|
||||
| slowTotal | Number | Y | 慢充枪口总数 |
|
||||
| slowFree | Number | Y | 慢充枪口空闲数 |
|
||||
| stationLng | String | Y | 经度 |
|
||||
| stationLat | String | Y | 纬度 |
|
||||
|
||||
# 充电桩接口
|
||||
|
||||
|
||||
|
||||
## 3001 查询充电桩详情
|
||||
|
||||
|
||||
|
||||
## 3002 查询充电桩枪口详情
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/pile/selectConnectorListByParams
|
||||
>
|
||||
> 请求类型：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------------- | -------- | --------------------------- |
|
||||
| pageNum | Number | Y | 页码 |
|
||||
| pageSize | Number | Y | 每页数量 |
|
||||
| merchantId | String | N | 运营商id ==接口暂未支持== |
|
||||
| stationIdList | Array<Long> | N | 站点id列表 |
|
||||
| pileIds | Array<Long> | N | 充电桩id列表 |
|
||||
| connectorIdList | Array<Long> | N | 枪口id列表 |
|
||||
| connectorCodeList | Array<String> | N | 枪口号列表 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------- | -------------------------- | -------- | ------------ |
|
||||
| pageNum | Number | Y | 页码 |
|
||||
| pageSize | Number | Y | 每页数量 |
|
||||
| list | Array<PileConnectorInfoVO> | Y | 充电枪口对象 |
|
||||
| total | Number | Y | 总数 |
|
||||
| pages | Number | Y | 总页数 |
|
||||
|
||||
**PileConnectorInfoVO**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------ | ---------- | :------: | ------------------------------------------------------------ |
|
||||
| connectorId | String | Y | 充电枪口id |
|
||||
| connectorCode | String | Y | 枪口编号 |
|
||||
| connectorQrCodeUrl | String | Y | 枪口二维码 |
|
||||
| status | Number | Y | 状态 0：离网 (默认)；1：空闲；2：占用（未充电）；3：占用（充电中）；4：占用（预约锁定） ；255：故障 |
|
||||
| stationId | String | Y | 站点id |
|
||||
| merchantId | String | Y | 运营商id |
|
||||
| merchantName | String | Y | 运营商名称 |
|
||||
| pileSn | String | Y | 充电桩编号 |
|
||||
| type | String | Y | 类型 1-直流接口 汽车桩+快充 2-交流接口 汽车桩+慢充 3-插座接口 电单车桩 |
|
||||
| instantPower | BigDecimal | Y | 即时功率 |
|
||||
| electricity | BigDecimal | Y | 电量 |
|
||||
| equipmentOrderNum | String | Y | 设备订单号 |
|
||||
| platformOrderNum | String | Y | 平台订单 |
|
||||
| chargingTime | String | Y | 充电时长 |
|
||||
| voltage | BigDecimal | Y | 电压 |
|
||||
| current | BigDecimal | Y | 电流 |
|
||||
| gunLineTemperature | String | Y | 枪线温度 |
|
||||
| userInfo | String | Y | 用户信息 |
|
||||
| orderId | String | Y | 订单id |
|
||||
| carNo | String | Y | 车牌号 |
|
||||
| soc | String | Y | SOC |
|
||||
| chargingAmount | BigDecimal | Y | 充电金额 |
|
||||
| chargingDegree | BigDecimal | Y | 充电度数 |
|
||||
| businessType | | y | 经营类型（1-运营桩；2-个人桩） |
|
||||
|
||||
**示例：**
|
||||
|
||||
```json
|
||||
#入参：
|
||||
{
|
||||
"pageNum": 1,
|
||||
"pageSize":10,
|
||||
"connectorIdList":[1]
|
||||
}
|
||||
|
||||
#反参：
|
||||
{
|
||||
"resCode": "00100000",
|
||||
"msg": "操作成功",
|
||||
"obj": {
|
||||
"pageNum": 1,
|
||||
"pageSize": 10,
|
||||
"list": [
|
||||
{
|
||||
"connectorId": "1",
|
||||
"connectorCode": "8800000000000101",
|
||||
"connectorQrCodeUrl": "http://localhost/pileConnectorInfo&code=8800000000000101",
|
||||
"status": 0,
|
||||
"stationId": "2",
|
||||
"merchantId": "5",
|
||||
"merchantName": "举视(上海)新能源科技有限公司",
|
||||
"pileSn": "88000000000001",
|
||||
"type": "2",
|
||||
"instantPower": 0.00,
|
||||
"electricity": null,
|
||||
"equipmentOrderNum": null,
|
||||
"platformOrderNum": null,
|
||||
"chargingTime": null,
|
||||
"voltage": 0.0,
|
||||
"current": 0.0,
|
||||
"gunLineTemperature": "0",
|
||||
"userInfo": null,
|
||||
"orderId": null,
|
||||
"carNo": null,
|
||||
"chargingAmount": 0.00,
|
||||
"chargingDegree": 0.00,
|
||||
"soc": "0"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"pages": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 3003 站点详情页面
|
||||
|
||||
接口地址：
|
||||
|
||||
请求方式：
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ---- | -------- | ------ |
|
||||
| stationId | | | 站点id |
|
||||
| | | | |
|
||||
| | | | |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------- | ---- | -------- | -------- |
|
||||
| stationName | | | 站点名称 |
|
||||
| stationAddress | | | 站点地址 |
|
||||
| distance | | | 距离 |
|
||||
| fastFree | | | 快充空闲 |
|
||||
| fastTotal | | | 总快充 |
|
||||
| slowFree | | | 慢充空闲 |
|
||||
| slowTotal | | | 总慢充 |
|
||||
| electricityPrice | | | 电费 |
|
||||
| servicePrice | | | 服务费 |
|
||||
| totalPrice | | | 总费用 |
|
||||
| stationImgList | | | 站点图片 |
|
||||
| | | | |
|
||||
|
||||
|
||||
|
||||
# 订单接口
|
||||
|
||||
## 5001 生成订单
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/order/generateOrder
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------------------- |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| connectorCode | String | Y | 枪口号 |
|
||||
| pileConnectorCode | String | Y | 桩枪口编号（桩编码+枪口号） |
|
||||
| memToken | String | Y | 用户token（写在Header中） |
|
||||
|
||||
备注：pileSn + connectorCode 或 pileConnectorCode 选其一，接口都支持
|
||||
|
||||
**反参**
|
||||
|
||||
```
|
||||
## 4002 结束充电
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/order/settleOrder
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------------------- |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| connectorCode | String | Y | 枪口号 |
|
||||
| pileConnectorCode | String | Y | 桩枪口编号（桩编码+枪口号） |
|
||||
|
||||
### 反参
|
||||
|
||||
null，若成功，msg中会有“==操作成功==”提示
|
||||
```
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
|
||||
|
||||
|
||||
## 5002 支付订单
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/pay/payOrder
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | -------- |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
| payMode | String | Y | 支付方式 |
|
||||
| payAmount | String | Y | 支付金额 |
|
||||
|
||||
**反参**
|
||||
|
||||
null，提示”==操作成功==“
|
||||
|
||||
|
||||
|
||||
## 5003 结算订单
|
||||
|
||||
> 接口地址：http://localhost:8080/uniapp/order/settleOrder
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------------------- |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| connectorCode | String | Y | 枪口号 |
|
||||
| pileConnectorCode | String | Y | 桩枪口编号（桩编码+枪口号） |
|
||||
|
||||
**反参**
|
||||
|
||||
null，若成功，msg中会有“==操作成功==”提示
|
||||
|
||||
|
||||
|
||||
## 5004 查询订单列表
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/order/getOrderList
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------------------- |
|
||||
| memberId | String | Y | 会员id |
|
||||
| pageSize | Number | Y | |
|
||||
| pageNum | Number | Y | |
|
||||
| orderStatus | String | Y | 订单状态 1-全部 2-未完成 3-已完成 |
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------------------- |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| connectorCode | String | Y | 枪口号 |
|
||||
| stationName | String | Y | 站点名称 |
|
||||
| pileConnectorCode | String | Y | 桩枪口编号（桩编码+枪口号） |
|
||||
| chargingDegree | BigDecimal | Y | 充电度数|
|
||||
| orderAmount | BigDecimal | Y | 订单金额 |
|
||||
| orderStatus | String | Y | 订单状态(0-待支付；1-充电中；2-待结算；3-待补缴；4-异常；5-可疑；6-订单完成) |
|
||||
| startTime | String | Y | 订单开始时间 |
|
||||
| endTime | String | Y | 订单结束时间 |
|
||||
| payAmount | BigDecimal | Y | 用户支付金额 |
|
||||
| payStatus | String | Y | 支付状态(0-待支付；1-支付完成) |
|
||||
| reason | String | Y | 订单异常原因 |
|
||||
|
||||
|
||||
|
||||
## 5005 订单停止充电
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/order/stopCharging
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| orderCode | String | Y | 订单号 |
|
||||
|
||||
**反参**
|
||||
|
||||
null，提示”==操作成功==“
|
||||
|
||||
|
||||
|
||||
## 5006 查询未开票订单
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/order/queryUninvoicedOrderList
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------- | ---- | -------- | -------- |
|
||||
| pageNo | int | Y | 查询页码 |
|
||||
| pageSize | int | Y | 每页数量 |
|
||||
|
||||
**出参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------ | ------ | -------- | -------- |
|
||||
| orderCode | String | Y | 订单编号 |
|
||||
| stationName | String | Y | 站点名称 |
|
||||
| chargingTime | String | Y | 充电时长 |
|
||||
| orderAmount | number | Y | 订单金额 |
|
||||
|
||||
|
||||
|
||||
## 5007 申请开票接口
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/order/applyOrderInvoice
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------------ | -------- | ------------ |
|
||||
| orderCodes | List<String> | Y | 订单编号列表 |
|
||||
| titleId | String | Y | 抬头id |
|
||||
|
||||
**出参**
|
||||
|
||||
无
|
||||
|
||||
|
||||
|
||||
# 首页大数据展示
|
||||
|
||||
## 8001 概况
|
||||
|
||||
> 请求地址：http://localhost:8080/index/getGeneralSituation
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| stationId | String | N | 站点id |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------------------- | ------ | -------- | ---------- |
|
||||
| totalChargingDegree | String | Y | 总充电电量 |
|
||||
| totalChargingAmount | String | Y | 总充电费用 |
|
||||
| totalChargingQuantity | String | Y | 总充电笔数 |
|
||||
| totalPileQuantity | String | Y | 总设备数量 |
|
||||
| totalMemberAmount | String | Y | 总客户余额 |
|
||||
|
||||
|
||||
|
||||
## 8002 订单
|
||||
|
||||
> 请求地址：http://localhost:8080/index/getOrderInfo
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------ |
|
||||
| stationId | String | N | 站点id |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------------------------- | ------ | -------- | -------------- |
|
||||
| date | String | Y | 日期 |
|
||||
| totalElectricity | String | Y | 总用电量 |
|
||||
| totalOrderAmount | String | Y | 总订单金额 |
|
||||
| totalSharpUsedElectricity | String | Y | 尖时段总用电量 |
|
||||
| totalPeakUsedElectricity | String | Y | 峰时段总用电量 |
|
||||
| totalFlatUsedElectricity | String | Y | 平时段总用电量 |
|
||||
| totalValleyUsedElectricity | String | Y | 谷时段总用电量 |
|
||||
|
||||
|
||||
|
||||
# 个人桩相关
|
||||
|
||||
## 9001 用户绑定个人桩
|
||||
|
||||
> 请求地址： http://localhost:8080/uniapp/personalPile/pileMemberBinding
|
||||
>
|
||||
> 请求方式： POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------- | ------ | -------- | -------------- |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| phoneNumber | String | Y | 用户手机号码 |
|
||||
| verificationCode | String | Y | 用户手机验证码 |
|
||||
|
||||
**反参**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 9002 桩管理员下发给其他用户
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/personalPile/adminIssuePile
|
||||
>
|
||||
> 请求方式： POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | -------------------- |
|
||||
| PileSn | String | Y | 桩编码 |
|
||||
| phoneNumber | String | Y | 另一个用户的手机号码 |
|
||||
|
||||
|
||||
|
||||
## 9003 获取个人桩列表
|
||||
|
||||
> 请求地址： http://localhost:8080/uniapp/personalPile/getPersonalPileList
|
||||
>
|
||||
> 请求方式： GET
|
||||
|
||||
**反参**
|
||||
|
||||
**List<PersonalPileInfoVO>**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------ | ------ | -------- | ---------------------------- |
|
||||
| pileSn | String | Y | 桩编码 |
|
||||
| connectorNum | String | Y | 枪口数量==(2023.02.23新增)== |
|
||||
| memberId | String | Y | 会员id |
|
||||
| type | String | Y | 身份类型 |
|
||||
| modelName | String | Y | 型号 |
|
||||
| ratedPower | String | Y | 额定功率 |
|
||||
| ratedCurrent | String | Y | 额定电流 |
|
||||
| ratedVoltage | String | Y | 额定电压 |
|
||||
| speedType | String | Y | 充电类型 |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 9004 获取枪口实时数据
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/personalPile/getConnectorRealTimeInfo
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | -------- |
|
||||
| pileConnectorCode | String | Y | 桩枪口号 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| -------------- | ------ | -------- | -------- |
|
||||
| instantCurrent | Number | Y | 实时电流 |
|
||||
| instantVoltage | Number | Y | 实时电压 |
|
||||
| instantPower | Number | Y | 实时功率 |
|
||||
|
||||
|
||||
|
||||
## 9005 累积充电量数据
|
||||
|
||||
> 请求地址：http://localhost:8080/uniapp/personalPile/getAccumulativeInfo
|
||||
>
|
||||
> 请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | -------- |
|
||||
| pileConnectorCode | String | Y | 桩枪口号 |
|
||||
| startTime | String | Y | 开始日期 |
|
||||
| endTime | String | Y | 结束日期 |
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------------- | ------ | -------- | ------------ |
|
||||
| memberId | String | Y | 会员id |
|
||||
| startTime | String | Y | 开始日期 |
|
||||
| endTime | String | Y | 结束日期 |
|
||||
| sumChargingElectricity | String | Y | 累计充电量 |
|
||||
| sumChargingTime | String | Y | 累计充电时长 |
|
||||
|
||||
|
||||
|
||||
## 9006 充电记录
|
||||
|
||||
请求地址：http://localhost:8080/uniapp/personalPile/getChargingRecord
|
||||
|
||||
请求方式：POST
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | -------- |
|
||||
| pileConnectorCode | String | Y | 桩枪口号 |
|
||||
| pageNum | Number | Y | 页码 |
|
||||
| pageSize | Number | Y | 每页数量 |
|
||||
|
||||
|
||||
|
||||
**反参**
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------- | ------ | -------- | -------- |
|
||||
| startChargingTime | String | Y | 启动时间 |
|
||||
| endChargingTime | String | Y | 结束时间 |
|
||||
| chargingElectricity | String | Y | 用电量 |
|
||||
| chargingTime | String | Y | 充电时长 |
|
||||
|
||||
134
docs/接口文档.md
Normal file
134
docs/接口文档.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 根据充电桩id查询详情接口
|
||||
|
||||
>根据充电桩id查询相关信息，包括运营商信息、充电站信息、充电枪信息、协议信息、sim卡信息等。
|
||||
|
||||
入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ------ | -------- | -------- |
|
||||
| pileId | String | Y | 充电桩id |
|
||||
|
||||
反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | ---------------------------- |
|
||||
| sn | String | Y | sn号 |
|
||||
| stationName | String | Y | 站点名称 station |
|
||||
| merchantName | String | Y | 运营商名称 merchant |
|
||||
| pileType | String | Y | 设备类型(1-汽车桩，2-电单车) model |
|
||||
| gunNum | int | Y | 枪数量 model |
|
||||
| interfaceStandard | String | Y | 接口标准 model |
|
||||
| ratedPower | int | Y | 额定功率(单位W) model |
|
||||
| outputCurrent | int | Y | 输出电流(单位A) model |
|
||||
| ICCID | String | Y | sim卡信息 |
|
||||
| registrationTime | String | Y | 注册时间 licence |
|
||||
| expireTime | String | Y | 到期时间 licence |
|
||||
|
||||
|
||||
|
||||
## 站点管理列表
|
||||
|
||||
#### 反参
|
||||
|
||||
PileStationVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------- | -------- | :----------: |
|
||||
| id | String | | 站点id |
|
||||
| stationName | string | | 站点名称 |
|
||||
| areaCode | S | | 省市辖区编码 |
|
||||
| area | S | | 地区 |
|
||||
| address | S | | 地址 |
|
||||
| PileNum | Integer | | 充电设备数量 |
|
||||
| merchantId | S | | 运营商ID |
|
||||
| merchantName | S | | 运营商名称 |
|
||||
| merchantAdminName | S | | 运营商管理员 |
|
||||
| stationStatus | Integer | | 站点状态 |
|
||||
| stationType | s | | 站点类型 |
|
||||
| createTime | s | | 创建时间 |
|
||||
| stationTel | s | | 站点电话 |
|
||||
| matchCars | s | | 适用车型描述 |
|
||||
| stationLng | s | | 经度 |
|
||||
| stationLat | s | | 纬度 |
|
||||
| construction | s | | 建设场所 |
|
||||
| businessHours | s | | 营业时间描述 |
|
||||
| organizationCode | s | | 组织结构代码 |
|
||||
| publicFlag | s | | 是否对外开放 |
|
||||
| openFlag | s | | 是否营业中 |
|
||||
|
||||
## BatchCreatePileDTO
|
||||
|
||||
| 字段名 | 类型 | | 备注 |
|
||||
| ---------------- | ---- | ---- | ---------------------------- |
|
||||
| merchantId | s | | 运营商id |
|
||||
| stationId | s | | 充电站id |
|
||||
| modelId | s | | 型号id |
|
||||
| softwareProtocol | s | | 软件协议（1-云快充；2-永联） |
|
||||
| productionDate | Date | | 生成日期 |
|
||||
| connectorNum | int | | 接口数量 |
|
||||
| num | int | | 生成台数 |
|
||||
| remark | s | | 备注 |
|
||||
|
||||
### 计费模板时段详情
|
||||
|
||||
```
|
||||
CreateBillingTemplateDTO
|
||||
```
|
||||
|
||||
| 字段名 | 类型 | | 备注 |
|
||||
| ----------------- | -------------------------------------- | ---- | ---------------------------------------- |
|
||||
| name | s | | 模板名称 |
|
||||
| type | s | | 时段类型 |
|
||||
| electricityPriceA | BigDecimal | | 尖时段电费 |
|
||||
| servicePriceA | BigDecimal | | 尖时段服务费 |
|
||||
| electricityPriceB | BigDecimal | | 峰时段电费 |
|
||||
| servicePriceB | | | 峰时段服务费 |
|
||||
| electricityPriceC | | | 平时段电费 |
|
||||
| servicePriceC | | | 平时段服务费 |
|
||||
| electricityPriceD | | | 谷时段电费 |
|
||||
| servicePriceD | | | 谷时段服务费 |
|
||||
| remark | s | | 备注 |
|
||||
| 时段清单 | private List<BillingTimeDTO> timeList; | | |
|
||||
| type | String | | 时段类型（1-尖时；2-峰时；3-平时；4-谷时 |
|
||||
| timeDesc | s | | 时段 例如：00：00-05：00 |
|
||||
|
||||
### 快速建站DTO FastCreateStationDTO
|
||||
|
||||
| 字段名 | | | 备注 |
|
||||
| ----------- | ---- | ---- | ------------ |
|
||||
| merchantId | S | | 所属运营商id |
|
||||
| stationName | S | | 名称 |
|
||||
| address | S | | 地址 |
|
||||
| areaCode | S | | 区域 |
|
||||
|
||||
### 站点导入计费模板dto ImportBillingTemplateDTO
|
||||
|
||||
| 字段名 | 类型 | | 备注 |
|
||||
| ----------------- | ---- | ---- | ---------- |
|
||||
| stationId | | | 站点id |
|
||||
| billingTemplateId | | | 计费模板id |
|
||||
|
||||
### 查询充电枪返回前台参数
|
||||
|
||||
PileConnectorInfoVO
|
||||
|
||||
| 字段名 | 类型 | | 备注 |
|
||||
| ------------------ | ---- | ---- | --------------------------- |
|
||||
| connectorId | S | | 充电枪口id |
|
||||
| connectorCode | S | | 枪口编号，由充电桩SN+01生成 |
|
||||
| connectorQrCodeUrl | S | | 充电二维码 |
|
||||
| status | int | | 状态 |
|
||||
| type | S | | 类型 |
|
||||
| instantPower | B | | 即时功率 |
|
||||
| electricity | big | | 电量 |
|
||||
| SOC | S | | SOC |
|
||||
| plantformOrderNum | S | | 平台订单 |
|
||||
| equipmentOrderNum | S | | 设备订单号 |
|
||||
| chargingTime | S | | 充电时长 |
|
||||
| voltage | B | | 电压 |
|
||||
| current | B | | 电流 |
|
||||
| temperature | B | | 温度 |
|
||||
| userInfo | S | | 用户信息 |
|
||||
| orderId | S | | 订单id |
|
||||
| carNo | S | | 车牌号 |
|
||||
|
||||
5
docs/测试问题.md
Normal file
5
docs/测试问题.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# 测试问题
|
||||
|
||||
1、充电桩型号表 pile_model_info ==speed_type== 和==charger_pile_type==字段，在前台新增桩型号时未设置值
|
||||
|
||||
2、用户正常开始充电后，桩由于意外情况清除订单记录，此时后台该订单一直为充电中状态，用户的开始扣款金额无法退回
|
||||
389
docs/运营小程序接口文档.md
Normal file
389
docs/运营小程序接口文档.md
Normal file
@@ -0,0 +1,389 @@
|
||||
|
||||
|
||||
|
||||
|
||||
# 查询站点的数据统计
|
||||
|
||||
```TEXT
|
||||
接口地址：http://localhost:8080/business/pile/station/getStationStatisticsInfos
|
||||
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------------ | -------- | ---------- |
|
||||
| merchantId | String | N | 运营商id |
|
||||
| stationIds | List<String> | N | 站点id列表 |
|
||||
| startTime | String | N | 开始时间 |
|
||||
| endTime | String | N | 结束时间 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------------- | --------------------------- | -------- | ---------------- |
|
||||
| stationStatisticsInfos | List<StationStatisticsInfo> | Y | 站点统计信息集合 |
|
||||
|
||||
#### StationStatisticsInfo
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------------------- | ---------- | -------- | ----------------------- |
|
||||
| stationId | String | Y | 站点id |
|
||||
| stationName | String | Y | 站点名称 |
|
||||
| chargeDegree | BigDecimal | Y | 充电度数（度） |
|
||||
| chargeAmount | BigDecimal | Y | 充电总金额（元） |
|
||||
| orderQuantity | Integer | Y | 订单数量（单） |
|
||||
| connectorAvailability | String | Y | ==充电枪可使用率（%）== |
|
||||
| chargingConnectorNum | Integer | Y | 充电中（枪口数量） |
|
||||
| freeConnectorNum | Integer | Y | 空闲（枪口数量） |
|
||||
| occupiedConnectorNum | Integer | Y | 占用（枪口数量） |
|
||||
| hangingConnectorNum | Integer | Y | 挂起（枪口数量） |
|
||||
| offlineConnectorNum | Integer | Y | 离线（枪口数量） |
|
||||
| faultConnectorNum | Integer | Y | 故障（枪口数量） |
|
||||
|
||||
|
||||
|
||||
<img src="C:\Users\admin\AppData\Roaming\Typora\typora-user-images\image-20240723100712169.png" alt="image-20240723100712169" style="zoom: 25%;" />
|
||||
|
||||
# 站点经营分析统计图
|
||||
|
||||
```text
|
||||
接口地址：http://localhost:8080/business/pile/station/getStationBusinessAnalyzeInfo
|
||||
接口地址(12个月数据)：http://localhost:8080/business/pile/station/getStationMonthlyBusinessAnalyzeInfo
|
||||
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------------ | -------- | ------------------------------------------------------ |
|
||||
| dateTime | String | N | 不传时默认查周期列表数据，传入时为用户选中某一天的日期 |
|
||||
| type | String | N | 日期类型（1-近7天；2-近30天） |
|
||||
| stationIds | List<String> | Y | 站点id列表 |
|
||||
|
||||
### 反参
|
||||
|
||||
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------------------- | ------------------------------- | -------- | ------------------------ |
|
||||
| electricityGrowthRate | String | Y | 充电量增长率 |
|
||||
| orderAmountGrowthRate | String | Y | 订单金额增长率 |
|
||||
| serviceAmountGrowthRate | String | Y | 服务费增长率 |
|
||||
| businessOrderDetailInfoVOList | List<BusinessOrderDetailInfoVO> | N | 运营端小程序订单详情List |
|
||||
| settleOrderReportList | List<SettleOrderReport> | N | 结算订单报表List |
|
||||
|
||||
#### businessOrderDetailInfoVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------------- | ---------- | -------- | -------------------- |
|
||||
| tradeDate | String | Y | 交易日期(yyyy-MM-dd) |
|
||||
| sharpUsedElectricity | BigDecimal | Y | 尖时段用电量 |
|
||||
| sharpAmount | BigDecimal | Y | 尖时段总金额 |
|
||||
| sharpElectricityPrice | BigDecimal | Y | 尖时段电费 |
|
||||
| peakUsedElectricity | BigDecimal | Y | 峰时段用电量 |
|
||||
| peakAmount | BigDecimal | Y | 峰时段总金额 |
|
||||
| peakElectricityPrice | BigDecimal | Y | 峰时段电费 |
|
||||
| flatUsedElectricity | BigDecimal | Y | 平时段用电量 |
|
||||
| flatAmount | BigDecimal | Y | 平时段总金额 |
|
||||
| flatElectricityPrice | BigDecimal | Y | 平时段电费 |
|
||||
| valleyUsedElectricity | BigDecimal | Y | 谷时段用电量 |
|
||||
| valleyAmount | BigDecimal | Y | 谷时段总金额 |
|
||||
| valleyElectricityPrice | BigDecimal | Y | 谷时段电费 |
|
||||
| totalServiceAmount | BigDecimal | Y | 总服务费 |
|
||||
| settleAmount | BigDecimal | Y | 结算金额 |
|
||||
| totalUsedElectricity | BigDecimal | Y | 总充电量 |
|
||||
|
||||
#### SettleOrderReport
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ---------- | -------- | ---------- |
|
||||
| useElectricity | BigDecimal | Y | 用电度数 |
|
||||
| totalAmount | BigDecimal | Y | 收入金额 |
|
||||
| electricityAmount | BigDecimal | Y | 电费金额 |
|
||||
| serviceAmount | BigDecimal | Y | 服务费金额 |
|
||||
|
||||
# 站点充点分布统计图
|
||||
|
||||
接口地址：
|
||||
|
||||
请求方式：
|
||||
|
||||
入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ---- |
|
||||
| | | | |
|
||||
|
||||
反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ------------------------- |
|
||||
| | | Y | 时间（小时） |
|
||||
| | | Y | 每个时段的充电量（度） |
|
||||
| | | Y | 时段充电量同比增长率（%） |
|
||||
|
||||
# 站点订单趋势统计图
|
||||
|
||||
```text
|
||||
接口地址：http://localhost:8080/business/pile/station/getStationOrderQuantityInfo
|
||||
|
||||
请求方式：POST
|
||||
```
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------------ | -------- | --------------------------------------- |
|
||||
| stationIds | List<String> | Y | 站点id数组 |
|
||||
| type | String | Y | 日期类型（1-近7天；2-近30天；3-近一年） |
|
||||
| dateTime | String | N | 用户选中某天的日期 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------------------------- | ------------------------------ | -------- | --------------------------- |
|
||||
| stationOrderQuantityInfoList | List<StationOrderQuantityInfo> | Y | 站点订单数量趋势信息 |
|
||||
| orderNumRateGrowthRate | String | Y | 每天订单数量同比增长率（%） |
|
||||
|
||||
### StationOrderQuantityInfo
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------- | ------ | -------- | -------- |
|
||||
| tradeDate | String | Y | 交易日期 |
|
||||
| orderNumber | int | Y | 订单数量 |
|
||||
|
||||
|
||||
|
||||
# 站点利用率趋势统计图
|
||||
|
||||
接口地址：http://localhost:8080/business/pile/station/getStationConnectorUsedInfo
|
||||
|
||||
请求方式：POST
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ---------- | ------------ | -------- | --------------------------------------- |
|
||||
| stationIds | List<String> | Y | 站点id数组 |
|
||||
| type | String | Y | 日期类型（1-近7天；2-近30天；3-近一年） |
|
||||
| dateTime | String | N | 用户选中某天的日期 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------------------------------- | ------------------------- | -------- | ---------------- |
|
||||
| connectorUsedRiseRate | String | Y | 枪口利用率增长值 |
|
||||
| List<BusinessOrderDetailInfoVO> | BusinessOrderDetailInfoVO | Y | 运营端订单详情 |
|
||||
|
||||
### BusinessOrderDetailInfoVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------- | ------ | -------- | ------------------------ |
|
||||
| tradeDate | String | Y | 交易日期 |
|
||||
| chargeNum | int | Y | 充电次数（枪口使用次数） |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# 站点充电实况列表
|
||||
|
||||
接口地址：http://localhost:8080/business/pile/connector/getBusinessConnectorInfoList
|
||||
|
||||
请求方式：POST
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| --------------- | ------- | -------- | ------------------------------------------------------------ |
|
||||
| stationId | String | Y | 站点id |
|
||||
| connectorStatus | String | N | 枪口状态（0：离网 ；1：空闲；2：占用（未充电）；3：占用（充电中）；4：占用（预约锁定）即挂起 ；255：故障 |
|
||||
| pageNum | Integer | N | 页码 |
|
||||
| pageSize | Integer | N | 每页条数 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------------- | ------------------------- | -------- | -------------- |
|
||||
| | | Y | 站点名称 |
|
||||
| connectorNum | Integer | Y | 全部枪口数量 |
|
||||
| chargingConnectorNum | Integer | Y | 充电中枪口数量 |
|
||||
| freeConnectorNum | Integer | Y | 空闲枪口数量 |
|
||||
| hangingConnectorNum | Integer | Y | 挂起枪口数量 |
|
||||
| occupiedConnectorNum | Integer | Y | 占用枪口数量 |
|
||||
| offlineConnectorNum | Integer | Y | 离线枪口数量 |
|
||||
| faultConnectorNum | Integer | Y | 故障枪口数量 |
|
||||
| pileConnectorInfoVOList | List<PileConnectorInfoVO> | Y | 枪口信息数组 |
|
||||
|
||||
### PileConnectorInfoVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | -------------------------- |
|
||||
| pileConnectorCode | String | Y | 充电枪编号 |
|
||||
| SOC | String | Y | 充电中soc（%） |
|
||||
| timeRemaining | String | Y | 充电中充满剩余时长（分钟） |
|
||||
| chargingTime | String | Y | 已充时长 |
|
||||
| faultReason | String | Y | 故障原因 |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# 站点充电实况搜索
|
||||
|
||||
接口地址：http://localhost:8080/business/pile/connector/searchConnectorInfo
|
||||
|
||||
请求方式：POST
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | ---------- |
|
||||
| stationId | String | Y | 站点id |
|
||||
| pileConnectorCode | String | Y | 充电枪编号 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | ---------- |
|
||||
| pileConnectorCode | String | Y | 充电枪编号 |
|
||||
| orderCode | String | N | 订单编号 |
|
||||
| SOC | String | N | 充电百分比 |
|
||||
| chargingTime | String | N | 已充时长 |
|
||||
| timeRemaining | String | N | 剩余时长 |
|
||||
|
||||
# 充电枪情况
|
||||
|
||||
请求地址：http://localhost:8080/business/pile/connector/getBusinessPileConnectorDetail/{pileConnectorCode}
|
||||
|
||||
请求方式：GET
|
||||
|
||||
### 入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | -------- |
|
||||
| pileConnectorCode | String | Y | 枪口编码 |
|
||||
|
||||
### 反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------------- | ----------------------- | -------- | ---- |
|
||||
| BusinessConnectorInfoVO | BusinessConnectorInfoVO | Y | |
|
||||
|
||||
### BusinessConnectorInfoVO
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ----------------- | ------ | -------- | --------------- |
|
||||
| pileConnectorCode | String | Y | 枪口编号 |
|
||||
| status | String | Y | 状态 |
|
||||
| startSoc | String | N | 起始soc |
|
||||
| endSoc | String | N | 终止（当前）soc |
|
||||
| chargeDegree | String | N | 充电度数 |
|
||||
| timeRemaining | String | N | 剩余时长 |
|
||||
| faultReason | String | N | 故障原因 |
|
||||
|
||||
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ------------------------------------------------- |
|
||||
| | | Y | 已充时长（充电中） |
|
||||
| | | Y | 最新订单启动时间 |
|
||||
| | | Y | 充电度数（充电中：以充电度数 / 最新订单充电度数） |
|
||||
| | | Y | 起止SOC |
|
||||
|
||||
# 充电枪情况中订单详情
|
||||
|
||||
请求地址：
|
||||
|
||||
请求方式：
|
||||
|
||||
入参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ---- |
|
||||
| | | | |
|
||||
|
||||
反参
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | --------------------- |
|
||||
| | | Y | 创建订单时间 |
|
||||
| | | Y | 开始充电时间 |
|
||||
| | | Y | 充电完成时间 |
|
||||
| | | Y | 充电完成原因 |
|
||||
| | | Y | 生成账单时间 |
|
||||
| | | Y | 支付完成时间 |
|
||||
| | | Y | 结算完成时间 |
|
||||
| | | Y | 订单号 |
|
||||
| | | Y | 场站名称 |
|
||||
| | | Y | 订单来源 |
|
||||
| | | Y | 外部订单号 |
|
||||
| | | Y | 启动方式 |
|
||||
| | | Y | 充电桩号 |
|
||||
| | | Y | 充电枪口号 |
|
||||
| | | Y | 结束SOC（%） |
|
||||
| | | Y | 时长（分钟） |
|
||||
| | | Y | 充电量（度） |
|
||||
| | | Y | 停止原因 |
|
||||
| | | Y | 占位符 |
|
||||
| | | Y | 订单总额（元） |
|
||||
| | | Y | 活动优惠金额(元) |
|
||||
| | | Y | 优惠券金额(元) |
|
||||
| | | Y | 其他优惠金额(元) |
|
||||
| | | Y | 用户实付金额(元) |
|
||||
| | | Y | 支付方式 |
|
||||
| | List | Y | 收费明细 |
|
||||
| | | Y | 用户信息 |
|
||||
| | | Y | SOC、电流、电压统计图 |
|
||||
|
||||
### 收费明细
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ------------------------------------------------------------ |
|
||||
| | | Y | 订单某个时段的时间截至（2024-04-12 21:55:35 至 024-04-12 22:55:00） |
|
||||
| | | Y | 当前时段的用电量（度） |
|
||||
| | | Y | 当前时段的电费单价（元） |
|
||||
| | | Y | 当前时段的服务费单价（元） |
|
||||
| | | Y | 当前时段总价（元） |
|
||||
|
||||
### 用户信息
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | -------- |
|
||||
| | | Y | 公司 |
|
||||
| | | Y | 手机号 |
|
||||
| | | Y | 车牌号 |
|
||||
| | | Y | VIN码 |
|
||||
| | | Y | 卡号 |
|
||||
| | | Y | 车辆编号 |
|
||||
| | | Y | 路线 |
|
||||
|
||||
|
||||
|
||||
### SOC、电流、电压统计图
|
||||
|
||||
| 字段名 | 类型 | 是否必传 | 备注 |
|
||||
| ------ | ---- | -------- | ------------- |
|
||||
| | | Y | 时间 |
|
||||
| | | Y | soc（%） |
|
||||
| | | Y | 需求电流（A） |
|
||||
| | | Y | 实际电流（A） |
|
||||
| | | Y | 需求电压（V） |
|
||||
| | | Y | 实际电压（V） |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
1、在 ==站点管理== ——> ==运营管理== 中勾选浙江省平台，点击保存按钮
|
||||
|
||||
<img src="C:\Users\admin\AppData\Roaming\Typora\typora-user-images\image-20240816100744446.png" alt="image-20240816100744446" style="zoom: 33%;" />
|
||||
|
||||
2、在 ==三方平台管理== ——> ==对接第三方平台关系== 页面中找到浙江省平台，点击 ==同步数据==，找到对应站点，点击 ==打开推送菜单== 页面， 点击右侧 ==推送充电站信息变化== 右侧的 ==推送== 按钮
|
||||
|
||||
<img src="C:\Users\admin\AppData\Roaming\Typora\typora-user-images\image-20240816100551217.png" alt="image-20240816100551217" style="zoom: 50%;" />
|
||||
Reference in New Issue
Block a user