同步充电桩数据

2026-04-20 02:55:04 +08:00 · 2025-12-30 15:59:34 +08:00
parent 3f42441869
commit ee7a3425d0
38 changed files with 4663 additions and 131 deletions
--- a/doc/Web项目充电桩同步功能实现总结.md
+++ b/doc/Web项目充电桩同步功能实现总结.md
@@ -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 团队