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`（新电途）

## 常用开发命令

### 构建与运行

```bash
# 编译整个项目
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`（使用自定义数据源配置）