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`（基础框架）

---

## 核心业务功能

### 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-消费抵扣`
- 发放条件：
  1. 结算金额大于 0
  2. 在线支付（微信支付 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()`

**结算流程**：
1. 校验订单支付金额、消费金额、退款金额
2. 白名单支付直接返回（不做处理）
3. 余额支付校验：消费金额 - 折扣金额 + 退款金额 = 支付金额
4. 在线支付校验：结算金额 + 退款金额 = 支付金额
5. 执行退款（如有）
6. 执行分账
7. 发放积分奖励（异步）

**分账逻辑**：`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`
- **功能**：
  - 刷卡充电授权
  - 卡号与会员绑定
  - 卡片状态管理

---

## 常用开发命令

### 构建与运行

```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/               # 视图对象
├── 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`

---

## 注意事项

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

---

## 启动类

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