mirror of
https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git
synced 2026-04-20 02:55:04 +08:00
16 KiB
16 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
项目概述
万车充运营管理平台 (jsowell-charger-web) - 电动汽车充电桩管理系统，基于 Spring Boot 2.5.14 + MyBatis + Netty 构建的多模块 Maven 项目。
技术栈：
- Java 8
- Spring Boot 2.5.14
- MyBatis + MyBatis-Plus 3.4.0
- Netty 4.1.75 (TCP/MQTT 通信)
- Dubbo 3.3.0 + Nacos (微服务)
- Redis (缓存)
- RabbitMQ (消息队列)
- MySQL (数据库)
- Druid (连接池)
模块架构
项目采用多模块分层架构，各模块职责清晰：
jsowell-charger-web/
├── jsowell-admin/ # Web 服务入口模块，包含 Controller 层和启动类
├── jsowell-framework/ # 核心框架模块，包含安全、权限、登录等基础服务
├── jsowell-system/ # 系统管理模块，用户、角色、菜单、字典等
├── jsowell-common/ # 通用工具模块，工具类、常量、异常、注解等
├── jsowell-pile/ # 充电桩业务核心模块，订单、会员、计费、支付等
├── jsowell-netty/ # Netty 通信模块，处理充电桩设备 TCP/MQTT 协议
├── jsowell-thirdparty/ # 第三方平台对接模块，支付宝、微信、高德地图等
├── jsowell-quartz/ # 定时任务模块
├── jsowell-generator/ # 代码生成器模块
└── jsowell-settlement/ # 结算模块
模块依赖关系：
jsowell-admin依赖jsowell-framework、jsowell-pile、jsowell-netty、jsowell-thirdpartyjsowell-pile依赖jsowell-framework（核心业务逻辑）jsowell-netty依赖jsowell-pile、jsowell-thirdparty（设备通信）jsowell-framework依赖jsowell-system、jsowell-common（基础框架）
核心业务功能
1. 会员管理
1.1 会员基本信息
- 实体类：
MemberBasicInfo - 服务类：
MemberBasicInfoService - 数据表：
member_basic_info - 功能：会员注册、信息维护、实名认证、车牌绑定
1.2 会员钱包
- 实体类：
MemberWalletInfo、MemberWalletLog - 服务类：
MemberWalletInfoService、MemberWalletLogService - 数据表：
member_wallet_info、member_wallet_log - 功能：
- 余额管理（本金余额、赠金余额）
- 充值记录
- 消费记录
- 退款处理
1.3 会员积分系统
- 实体类：
MemberPointsInfo、MemberPointsRecord - 服务类：
MemberPointsInfoService、MemberPointsRecordService - 数据表：
member_points_info、member_points_record - Controller：
MemberPointsInfoController（路径：/points）
积分规则：
- 积分类型：
1-充电奖励、2-消费抵扣 - 发放条件：
- 结算金额大于 0
- 在线支付（微信支付 payMode=4、支付宝支付 payMode=5）
- 积分计算：积分数量 = 实际结算金额（保留两位小数）
- 异步发放：通过 RabbitMQ 队列
ykc.pointsReward-topic.member-group异步处理
积分 API：
| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| GET | /points/balance |
查询积分余额 | member:points:query |
| GET | /points/list |
查询积分明细 | member:points:list |
| POST | /points/add |
增加积分 | member:points:add |
| POST | /points/deduct |
扣减积分 | member:points:deduct |
| POST | /points/init |
初始化积分账户 | member:points:init |
积分相关类：
- 消息实体：
PointsRewardMessage - 消息生产者：
PointsRewardProducer - 消息消费者：
PointsRewardConsumer - RabbitMQ 配置：
PointsRabbitConfig
2. 充电桩管理
2.1 充电站
- 实体类：
PileStationInfo - 服务类：
PileStationInfoService - 数据表：
pile_station_info - 功能：充电站基本信息、地理位置、营业时间、服务设施
2.2 充电桩设备
- 实体类：
PileBasicInfo - 服务类：
PileBasicInfoService - 数据表：
pile_basic_info - 功能：充电桩信息、在线状态、功率配置
2.3 充电枪（连接器）
- 实体类：
PileConnectorInfo - 服务类：
PileConnectorInfoService - 数据表：
pile_connector_info - 功能：充电枪状态、充电功率、故障信息
2.4 计费模板
- 实体类：
PileBillingTemplate - 服务类：
PileBillingTemplateService - 数据表：
pile_billing_template - 功能：分时电价、服务费配置、计费规则
3. 订单管理
3.1 充电订单
- 实体类：
OrderBasicInfo - 服务类：
OrderBasicInfoService - 数据表：
order_basic_info - Mapper：
OrderBasicInfoMapper
订单状态（OrderStatusEnum）：
0- 待支付1- 充电中2- 充电完成3- 已取消4- 异常结束
支付状态：
0- 待支付1- 支付完成2- 无需支付3- 待补缴
支付方式（OrderPayModeEnum）：
1- 余额支付（本金）2- 赠金支付3- 白名单支付（免费）4- 微信支付5- 支付宝支付6- ETC 支付
3.2 订单支付记录
- 实体类：
OrderPayRecord - 服务类：
OrderPayRecordService - 数据表：
order_pay_record - 功能：记录每笔支付的详细信息，支持多次支付
3.3 订单监控数据
- 实体类：
OrderMonitorData - 服务类：
OrderMonitorDataService - 数据表：
order_monitor_data - 功能：充电过程实时数据（电压、电流、功率、SOC）
3.4 订单异常记录
- 实体类：
OrderAbnormalRecord - 服务类：
OrderAbnormalRecordService - 数据表：
order_abnormal_record - 功能：记录充电异常情况
4. 支付与结算
4.1 支付方式
微信支付：
- 服务类：
WxAppletRemoteService - 配置类：
WechatPayConfig - 使用微信支付 V3 API
- 支持小程序支付
支付宝支付：
- 服务类：
AliAppletRemoteService - 支持支付宝小程序支付
汇付支付：
- 服务类：
AdapayService、AdapayMemberAccountService - 配置类：
AdapayConfig - 用于分账和清算
4.2 订单结算流程
结算入口：OrderBasicInfoServiceImpl.realTimeOrderSplit()
结算流程：
- 校验订单支付金额、消费金额、退款金额
- 白名单支付直接返回（不做处理）
- 余额支付校验：消费金额 - 折扣金额 + 退款金额 = 支付金额
- 在线支付校验：结算金额 + 退款金额 = 支付金额
- 执行退款（如有）
- 执行分账
- 发放积分奖励（异步）
分账逻辑：splittingMethod()
- 根据站点分账配置计算各方分成
- 支持电费和服务费分别计算
- 调用汇付支付接口执行分账
4.3 分账配置
- 实体类：
StationSplitConfig - 服务类：
StationSplitConfigService - 数据表：
station_split_config - 功能：配置各参与方的分账比例
4.4 分账记录
- 实体类：
OrderSplitRecord - 服务类：
OrderSplitRecordService - 数据表：
order_split_record - 功能：记录每笔订单的分账详情
4.5 清算账单
- 实体类：
ClearingBillInfo、ClearingBillDetail - 服务类：
ClearingBillInfoService、ClearingBillDetailService - 数据表：
clearing_bill_info、clearing_bill_detail - 功能：商户清算账单管理
5. 充电桩通信
5.1 通信架构
- 模块：
jsowell-netty - 协议：云快充协议（TCP）、MQTT 协议
- 服务器：Netty TCP Server
5.2 云快充协议处理器
位置：com.jsowell.netty.handler.yunkuaichong
主要处理器：
PileLoginHandler- 充电桩登录HeartBeatHandler- 心跳检测RealTimeDataHandler- 实时数据上报TransactionRecordHandler- 交易记录上报StartChargeHandler- 启动充电StopChargeHandler- 停止充电
5.3 业务服务
YKCBusinessService- 云快充业务逻辑EBikeBusinessService- 电动自行车业务逻辑CameraBusinessService- 摄像头业务逻辑
5.4 消息队列处理
- 监听器：
OrderRabbitListener、PileRabbitListener - 队列常量：
RabbitConstants
主要队列：
| 队列名称 | 用途 |
|---|---|
ykc.pileLogin-topic.device-group |
充电桩登录 |
ykc.heartBeat-topic.device-group |
心跳消息 |
ykc.realtimeData-topic.device-group |
实时数据 |
ykc.chargeOrderData-topic.device-group |
订单结算 |
ykc.pointsReward-topic.member-group |
积分奖励 |
6. 第三方平台对接
6.1 地图服务
- 高德地图：
AMapService- 充电站信息同步到高德
6.2 停车场系统
QcyunsService- 青城云停车LTYTService- 蓝天云停RJService- 睿捷停车
6.3 充电平台互联互通
ZDLService- 中电联平台NRService- 南瑞平台XDTService- 新电途平台
6.4 第三方关系映射
- 实体类：
ThirdpartySnRelation - 服务类：
IThirdpartySnRelationService - 功能：管理本地设备与第三方平台设备的映射关系
7. 商户管理
7.1 商户信息
- 实体类：
PileMerchantInfo - 服务类：
PileMerchantInfoService - 数据表：
pile_merchant_info - 功能：商户基本信息、资质认证、结算账户
7.2 商户汇付账户
- 实体类：
MemberAdapayRecord - 服务类：
MemberAdapayRecordService、AdapayMemberAccountService - 功能：商户在汇付的分账账户管理
8. 白名单管理
- 实体类：
PileStationWhitelist - 服务类：
PileStationWhitelistService - 数据表：
pile_station_whitelist - 功能：
- 免费充电白名单
- 支持按车牌、会员、卡号设置
- 白名单用户充电不扣费
9. 授权卡管理
- 实体类：
PileAuthCard - 服务类：
PileAuthCardService - 数据表：
pile_auth_card - 功能：
- 刷卡充电授权
- 卡号与会员绑定
- 卡片状态管理
常用开发命令
构建与运行
# 编译整个项目
mvn clean compile
# 打包（跳过测试）
mvn clean package -DskipTests
# 运行主应用（开发环境）
cd jsowell-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# 运行测试
mvn test
数据库相关
MyBatis Mapper 位置：
- XML 文件：
src/main/resources/mapper/**/*Mapper.xml - Java 接口：
src/main/java/**/mapper/*Mapper.java - 配置：
mybatis-config.xml（在jsowell-admin/src/main/resources/mybatis/）
MyBatis-Plus：jsowell-pile 模块使用 MyBatis-Plus 3.4.0，支持 Lambda 查询和代码生成。
环境配置
配置文件位置：jsowell-admin/src/main/resources/
application.yml：主配置文件application-dev.yml：开发环境application-sit.yml：测试环境application-pre.yml：预发布环境application-prd.yml：生产环境
切换环境：修改 application.yml 中的 spring.profiles.active
Dubbo 服务
项目使用 Dubbo 3.3.0 + Nacos 作为微服务框架：
- 注册中心：Nacos
- 协议：dubbo（动态端口）
- API 定义：
charge-common-api模块
代码规范
包结构约定
com.jsowell.{module}/
├── controller/ # REST API 控制器
├── service/ # 业务逻辑接口
│ └── impl/ # 业务逻辑实现
├── mapper/ # MyBatis Mapper 接口
├── domain/ # 实体类（对应数据库表）
├── dto/ # 数据传输对象
├── vo/ # 视图对象
├── enums/ # 枚举类
└── mq/ # 消息队列相关
├── producer/ # 消息生产者
└── consumer/ # 消息消费者
命名规范
- Controller：
{Entity}Controller，使用@RestController或@Controller - Service：接口
I{Entity}Service或{Entity}Service，实现类{Entity}ServiceImpl - Mapper：
{Entity}Mapper（接口）+{Entity}Mapper.xml（XML） - Domain：实体类名与数据库表名对应（驼峰转下划线）
注解使用
- Swagger：使用
@Api、@ApiOperation、@ApiParam生成 API 文档 - 权限控制：
@PreAuthorize("@ss.hasPermi('system:user:list')") - 日志记录：
@Log(title = "用户管理", businessType = BusinessType.INSERT) - 数据权限：
@DataScope(deptAlias = "d", userAlias = "u") - 事务管理：
@Transactional(rollbackFor = Exception.class)
关键配置说明
RabbitMQ 配置
配置类：RabbitConfig、PointsRabbitConfig
常量类：RabbitConstants
配置特点：
- 消息序列化：
Jackson2JsonMessageConverter - 应答模式：自动应答（2024年12月26日改为自动）
- 重试机制：指数退避策略
- 并发消费者：1-20
Netty 服务器配置
Netty 服务器在 jsowell-netty 模块中配置，支持：
- TCP 服务器（云快充协议）
- MQTT 服务器（物联网设备）
- 电动自行车专用服务器
安全与认证
- JWT Token：
TokenService管理 Token 生成和验证 - 密码加密：使用 BCrypt 加密
- 权限验证：
PermissionService和SysPermissionService - 登录限制：密码错误 5 次锁定 10 分钟
缓存策略
使用 Redis 缓存：
- 用户登录信息
- 字典数据
- 配置参数
- 充电桩在线状态
文件上传
- 本地存储：配置
jsowell.profile路径 - 阿里云 OSS：配置在
aliyunoss节点 - Minio：可选的对象存储方案
数据库表结构
会员相关表
| 表名 | 说明 |
|---|---|
member_basic_info |
会员基本信息 |
member_wallet_info |
会员钱包 |
member_wallet_log |
钱包流水 |
member_points_info |
会员积分 |
member_points_record |
积分流水 |
member_plate_number_relation |
车牌绑定 |
充电桩相关表
| 表名 | 说明 |
|---|---|
pile_station_info |
充电站信息 |
pile_basic_info |
充电桩信息 |
pile_connector_info |
充电枪信息 |
pile_billing_template |
计费模板 |
pile_merchant_info |
商户信息 |
pile_station_whitelist |
白名单 |
pile_auth_card |
授权卡 |
订单相关表
| 表名 | 说明 |
|---|---|
order_basic_info |
订单基本信息 |
order_pay_record |
支付记录 |
order_monitor_data |
监控数据 |
order_abnormal_record |
异常记录 |
order_split_record |
分账记录 |
结算相关表
| 表名 | 说明 |
|---|---|
station_split_config |
分账配置 |
clearing_bill_info |
清算账单 |
clearing_bill_detail |
清算明细 |
settle_order_report |
结算报表 |
测试说明
测试文件位置：jsowell-admin/src/test/java/
现有测试：
SpringBootTestController.java：Spring Boot 集成测试PaymentTestController.java：支付功能测试
监控与运维
Prometheus 监控
- 监控端口：8091
- 指标路径：
/actuator/prometheus - 配置：
management.metrics.export.prometheus.enabled=true
Druid 监控
- 访问路径：
/druid/* - 用户名/密码：配置在
application-{env}.yml中
Swagger API 文档
- 开发环境访问：
http://localhost:8080/swagger-ui/ - 配置：
swagger.enabled=true
注意事项
- 数据库连接：使用 Druid 连接池，主从分离配置在
application-{env}.yml - 事务管理：使用
@Transactional注解，注意事务传播行为 - 异步处理：RabbitMQ 已改为自动应答模式
- Netty 线程模型：注意 EventLoop 线程安全，避免阻塞操作
- Dubbo 服务：启动时不检查提供者（
consumer.check=false） - 日志级别：开发环境
com.jsowell: debug，生产环境建议info - 热部署：开发环境启用
spring.devtools.restart.enabled=true - 积分发放：通过 RabbitMQ 异步处理，避免影响订单结算主流程
启动类
主启动类：com.jsowell.JsowellApplication
- 位置：
jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java - 注解：
@SpringBootApplication、@EnableDubbo - 排除：
DataSourceAutoConfiguration（使用自定义数据源配置）