jsowell-charger-web/doc/Web项目充电桩同步功能实现总结.md

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

jcpp:
  sync:
    # JCPP 同步接口地址
    api-url: http://localhost:8080/api/sync
    # 批量同步大小
    batch-size: 100
    # 超时时间（毫秒）
    timeout: 60000
    # 是否启用自动增量同步
    auto-sync-enabled: false
    # 自动同步间隔（分钟）
    auto-sync-interval: 30

---

二、核心实现逻辑

1. 数据转换逻辑

充电桩数据转换

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'

充电枪数据转换

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：

mysql -u username -p database_name < sql/jcpp_sync_record.sql

2. 配置 JCPP 接口地址

修改 application-sit.yml：

jcpp:
  sync:
    api-url: http://jcpp-server:8080/api/sync  # 修改为实际地址

3. API 调用示例

全量同步

curl -X POST http://localhost:8080/jcpp/sync/full \
  -H "Authorization: Bearer {token}"

增量同步

curl -X POST "http://localhost:8080/jcpp/sync/incremental?lastSyncTime=2025-12-30 10:00:00" \
  -H "Authorization: Bearer {token}"

单个充电桩同步

curl -X POST http://localhost:8080/jcpp/sync/pile/20231212000010 \
  -H "Authorization: Bearer {token}"

查询同步记录

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 - 详细实现计划
• JCPP项目配合实现Prompt.md - 给 JCPP 项目的实现指南
• JCPP对接进度文档.md - JCPP 整体对接进度

---

七、问题反馈

如有任何问题，请及时反馈：

1. 接口调用异常
2. 数据转换错误
3. 性能问题
4. 其他技术问题

---

文档版本：v1.0 最后更新：2025-12-30 维护人员：jsowell 团队