jsowell-charger-web/CLAUDE.md

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-thirdparty
• jsowell-pile 依赖 jsowell-framework（核心业务逻辑）
• jsowell-netty 依赖 jsowell-pile、jsowell-thirdparty（设备通信）
• jsowell-framework 依赖 jsowell-system、jsowell-common（基础框架）

核心业务流程

充电桩通信架构

系统通过 Netty 实现与充电桩设备的实时通信：

1. TCP 服务器：jsowell-netty 模块启动 TCP 服务器监听充电桩连接
2. 协议处理：
   • 云快充协议：com.jsowell.netty.handler.yunkuaichong.*Handler（50+ 个处理器）
   • 电动自行车协议：com.jsowell.netty.handler.electricbicycles.*Handler
3. MQTT 支持：BootNettyMqttChannelInboundHandler 处理 MQTT 协议
4. 业务服务：
   • 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

注意事项

1. 数据库连接：使用 Druid 连接池，主从分离配置在 application-{env}.yml
2. 事务管理：使用 @Transactional 注解，注意事务传播行为
3. 异步处理：RabbitMQ 配置手动确认模式（acknowledge-mode: manual）
4. Netty 线程模型：注意 EventLoop 线程安全，避免阻塞操作
5. Dubbo 服务：启动时不检查提供者（consumer.check=false）
6. 日志级别：开发环境 com.jsowell: debug，生产环境建议 info
7. 热部署：开发环境启用 spring.devtools.restart.enabled=true

启动类

主启动类：com.jsowell.JsowellApplication

• 位置：jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java
• 注解：@SpringBootApplication、@EnableDubbo
• 排除：DataSourceAutoConfiguration（使用自定义数据源配置）