mirror of
https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git
synced 2026-04-20 02:55:04 +08:00
7.5 KiB
7.5 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（基础框架）
核心业务流程
充电桩通信架构
系统通过 Netty 实现与充电桩设备的实时通信：
- TCP 服务器：
jsowell-netty模块启动 TCP 服务器监听充电桩连接 - 协议处理：
- 云快充协议：
com.jsowell.netty.handler.yunkuaichong.*Handler（50+ 个处理器） - 电动自行车协议：
com.jsowell.netty.handler.electricbicycles.*Handler
- 云快充协议：
- MQTT 支持：
BootNettyMqttChannelInboundHandler处理 MQTT 协议 - 业务服务：
YKCBusinessService：云快充业务逻辑EBikeBusinessService：电动自行车业务逻辑CameraBusinessService：摄像头业务逻辑
支付与结算流程
支持多种支付方式：
- 微信支付：
WechatPayService（V3 API） - 支付宝支付：
AliAppletRemoteService - 汇付支付：
AdapayMemberAccountService
结算相关：
- 订单分账：
OrderSplitRecordService - 清算账单：
ClearingBillInfoService - 商户结算：
SettleOrderReportService
第三方平台对接
jsowell-thirdparty 模块对接多个第三方平台：
- 高德地图：
AMapService（充电站信息同步） - 停车场系统：
QcyunsService、LTYTService、RJService - 充电平台：
ZDLService（中电联）、NRService（南瑞）、XDTService（新电途）
常用开发命令
构建与运行
# 编译整个项目
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/ # 视图对象
命名规范
- 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")
关键配置说明
Netty 服务器配置
Netty 服务器在 jsowell-netty 模块中配置，支持：
- TCP 服务器（云快充协议）
- MQTT 服务器（物联网设备）
- 电动自行车专用服务器
安全与认证
- JWT Token：
TokenService管理 Token 生成和验证 - 密码加密：使用 BCrypt 加密
- 权限验证：
PermissionService和SysPermissionService - 登录限制：密码错误 5 次锁定 10 分钟
缓存策略
使用 Redis 缓存：
- 用户登录信息
- 字典数据
- 配置参数
- 充电桩在线状态
文件上传
- 本地存储：配置
jsowell.profile路径 - 阿里云 OSS：配置在
aliyunoss节点 - Minio：可选的对象存储方案
测试说明
测试文件位置：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 配置手动确认模式（
acknowledge-mode: manual） - Netty 线程模型：注意 EventLoop 线程安全，避免阻塞操作
- Dubbo 服务：启动时不检查提供者（
consumer.check=false） - 日志级别：开发环境
com.jsowell: debug，生产环境建议info - 热部署：开发环境启用
spring.devtools.restart.enabled=true
启动类
主启动类：com.jsowell.JsowellApplication
- 位置：
jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java - 注解：
@SpringBootApplication、@EnableDubbo - 排除：
DataSourceAutoConfiguration（使用自定义数据源配置）