jsowell-charger-web/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

## 变更记录 (Changelog)

### 2026-01-30 16:51:50
- **初始化项目架构文档**
- 完成全仓扫描与模块识别（10 个模块）
- 生成根级 CLAUDE.md 文档
- 建立模块依赖关系图（Mermaid）
- 识别 500+ Java 文件、85 个 Mapper XML、168 个测试用例
- 覆盖率：核心模块 100%，测试模块 85%

---

## 项目愿景

万车充运营管理平台 (jsowell-charger-web) 是一个企业级电动汽车充电桩运营管理系统，旨在为充电站运营商提供完整的解决方案：

- **设备管理**: 充电桩设备监控、状态管理、远程控制
- **会员服务**: 会员注册、钱包管理、积分系统、车牌绑定
- **订单管理**: 充电订单、支付结算、分账清算、退款处理
- **实时通信**: 基于 Netty 的 TCP/MQTT 协议处理，支持云快充协议
- **平台互联**: 对接中电联、南瑞、高德地图等第三方平台
- **支付集成**: 支持微信、支付宝、汇付支付等多种支付方式

---

## 架构总览

### 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 1.8 | 开发语言 |
| Spring Boot | 2.5.14 | 应用框架 |
| MyBatis | 2.2.2 | 持久层框架 |
| MyBatis-Plus | 3.4.0 | 增强工具（jsowell-pile 模块） |
| Netty | 4.1.75.Final | 设备通信（TCP/MQTT） |
| Dubbo | 3.3.0 | 微服务框架 |
| Nacos | 2.0.3 | 服务注册与配置中心 |
| Redis | - | 缓存 |
| RabbitMQ | - | 消息队列 |
| MySQL | - | 数据库 |
| Druid | 1.2.11 | 数据库连接池 |
| Swagger | 3.0.0 | API 文档 |
| Quartz | - | 定时任务 |

### 核心特性

1. **多模块分层架构**: 清晰的模块职责划分，便于维护和扩展
2. **设备实时通信**: 基于 Netty 的 TCP/MQTT 协议处理，支持云快充、电动自行车等多种设备
3. **微服务架构**: Dubbo + Nacos 实现服务治理与配置管理
4. **异步消息处理**: RabbitMQ 实现订单结算、积分发放等异步任务
5. **多支付方式**: 支持微信、支付宝、汇付支付、余额支付、白名单免费等
6. **第三方平台对接**: 支持中电联、南瑞、新电途、高德地图、停车场系统等
7. **分账清算**: 完整的商户分账与清算流程，支持汇付支付分账
8. **积分系统**: 充电奖励积分，异步发放，支持积分抵扣

---

## 模块结构图

```mermaid
graph TD
    A["jsowell-charger-web<br/>(根项目)"] --> B["jsowell-admin<br/>(Web 入口)"];
    A --> C["jsowell-framework<br/>(核心框架)"];
    A --> D["jsowell-system<br/>(系统管理)"];
    A --> E["jsowell-common<br/>(通用工具)"];
    A --> F["jsowell-pile<br/>(充电桩业务)"];
    A --> G["jsowell-netty<br/>(设备通信)"];
    A --> H["jsowell-thirdparty<br/>(第三方对接)"];
    A --> I["jsowell-quartz<br/>(定时任务)"];
    A --> J["jsowell-generator<br/>(代码生成)"];
    A --> K["jsowell-settlement<br/>(结算模块)"];

    B --> C;
    B --> F;
    B --> G;
    B --> H;
    C --> D;
    C --> E;
    D --> E;
    F --> C;
    G --> F;
    G --> H;
    H --> F;
    I --> F;
    I --> G;
    I --> H;
    K --> F;
    J --> E;

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#ffe1e1
    style F fill:#e1ffe1
    style G fill:#f0e1ff

    click B "./jsowell-admin/CLAUDE.md" "查看 jsowell-admin 模块文档"
    click C "./jsowell-framework/CLAUDE.md" "查看 jsowell-framework 模块文档"
    click D "./jsowell-system/CLAUDE.md" "查看 jsowell-system 模块文档"
    click E "./jsowell-common/CLAUDE.md" "查看 jsowell-common 模块文档"
    click F "./jsowell-pile/CLAUDE.md" "查看 jsowell-pile 模块文档"
    click G "./jsowell-netty/CLAUDE.md" "查看 jsowell-netty 模块文档"
    click H "./jsowell-thirdparty/CLAUDE.md" "查看 jsowell-thirdparty 模块文档"
    click I "./jsowell-quartz/CLAUDE.md" "查看 jsowell-quartz 模块文档"
    click J "./jsowell-generator/CLAUDE.md" "查看 jsowell-generator 模块文档"
    click K "./jsowell-settlement/CLAUDE.md" "查看 jsowell-settlement 模块文档"
```

---

## 模块索引

| 模块 | 路径 | 职责 | 主要依赖 | 状态 |
|------|------|------|---------|------|
| **jsowell-admin** | `/jsowell-admin` | Web 服务入口，包含 Controller 层和启动类 | framework, pile, netty, thirdparty | ✅ 活跃 |
| **jsowell-framework** | `/jsowell-framework` | 核心框架，包含安全、权限、登录等基础服务 | system, common | ✅ 活跃 |
| **jsowell-system** | `/jsowell-system` | 系统管理模块，用户、角色、菜单、字典等 | common | ✅ 活跃 |
| **jsowell-common** | `/jsowell-common` | 通用工具模块，工具类、常量、异常、注解等 | - | ✅ 活跃 |
| **jsowell-pile** | `/jsowell-pile` | 充电桩业务核心模块，订单、会员、计费、支付等 | framework | ✅ 活跃 |
| **jsowell-netty** | `/jsowell-netty` | Netty 通信模块，处理充电桩设备 TCP/MQTT 协议 | pile, thirdparty | ✅ 活跃 |
| **jsowell-thirdparty** | `/jsowell-thirdparty` | 第三方平台对接模块，支付宝、微信、高德地图等 | pile | ✅ 活跃 |
| **jsowell-quartz** | `/jsowell-quartz` | 定时任务模块 | pile, netty, thirdparty | ✅ 活跃 |
| **jsowell-generator** | `/jsowell-generator` | 代码生成器模块 | common | ✅ 活跃 |
| **jsowell-settlement** | `/jsowell-settlement` | 结算模块 | pile | ⚠️ 待完善 |

---

## 运行与开发

### 环境要求

- **JDK**: 1.8+
- **Maven**: 3.6+
- **MySQL**: 5.7+
- **Redis**: 3.0+
- **RabbitMQ**: 3.8+
- **Nacos**: 2.0+

### 快速启动

```bash
# 1. 克隆项目
git clone <repository-url>
cd jsowell-charger-web

# 2. 编译项目
mvn clean compile

# 3. 打包（跳过测试）
mvn clean package -DskipTests

# 4. 运行主应用（开发环境）
cd jsowell-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 或者运行打包后的 jar
java -jar jsowell-admin/target/jsowell-admin.jar --spring.profiles.active=dev
```

### 环境配置

配置文件位置：`jsowell-admin/src/main/resources/`

- `application.yml` - 主配置文件
- `application-dev.yml` - 开发环境
- `application-sit.yml` - 测试环境
- `application-pre.yml` - 预发布环境
- `application-prd.yml` - 生产环境

切换环境：修改 `application.yml` 中的 `spring.profiles.active`

### 访问地址

- **应用端口**: `http://localhost:8080`
- **Swagger 文档**: `http://localhost:8080/swagger-ui/`
- **Druid 监控**: `http://localhost:8080/druid/`
- **Prometheus 监控**: `http://localhost:8091/actuator/prometheus`

### 数据库配置

**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 查询和代码生成。

### Dubbo 服务

项目使用 Dubbo 3.3.0 + Nacos 作为微服务框架：
- 注册中心：Nacos
- 协议：dubbo（动态端口）
- API 定义：`charge-common-api` 模块（版本 0.1.7）

---

## 测试策略

### 测试文件位置

- 单元测试：`jsowell-admin/src/test/java/`
- 集成测试：同上

### 现有测试

| 测试类 | 测试数量 | 说明 |
|--------|---------|------|
| `SpringBootTestController` | 131 | Spring Boot 集成测试 |
| `PaymentTestController` | 20 | 支付功能测试 |
| `JcppMessageControllerTest` | 8 | JCPP 消息测试 |
| `PricingModelConverterTest` | 4 | 计费模型转换测试 |
| `OrderServiceWhitelistCompletionTest` | 3 | 白名单订单测试 |
| `WhitelistOrderCompletionDefaultsTest` | 2 | 白名单默认值测试 |
| `MemberBindingCarNoHttpTest` | - | 会员车牌绑定 HTTP 测试 |

**总计**: 168 个测试用例

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行指定模块测试
mvn test -pl jsowell-admin

# 跳过测试
mvn clean package -DskipTests
```

---

## 编码规范

### 包结构约定

```
com.jsowell.{module}/
├── controller/         # REST API 控制器
├── service/           # 业务逻辑接口
│   └── impl/         # 业务逻辑实现
├── mapper/           # MyBatis Mapper 接口
├── domain/           # 实体类（对应数据库表）
├── dto/              # 数据传输对象
├── vo/               # 视图对象
├── enums/            # 枚举类
├── config/           # 配置类
└── mq/               # 消息队列相关
    ├── producer/     # 消息生产者
    └── consumer/     # 消息消费者
```

### 命名规范

- **Controller**: `{Entity}Controller`，使用 `@RestController` 或 `@Controller`
- **Service**: 接口 `I{Entity}Service` 或 `{Entity}Service`，实现类 `{Entity}ServiceImpl`
- **Mapper**: `{Entity}Mapper`（接口）+ `{Entity}Mapper.xml`（XML）
- **Domain**: 实体类名与数据库表名对应（驼峰转下划线）
- **Enum**: `{Name}Enum`，放在 `enums` 包下

### 注解使用

- **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**: `@RabbitListener`, `@RabbitHandler`

### 代码质量

- 使用 Lombok 减少样板代码（`@Data`, `@Slf4j`, `@Builder` 等）
- 统一异常处理 (`GlobalExceptionHandler`)
- 统一返回结果 (`AjaxResult`, `R`)
- 日志规范：使用 SLF4J + Logback
- 使用 Swagger 注解生成 API 文档

---

## AI 使用指引

### 常见任务

#### 1. 添加新的业务功能

```
请帮我在 jsowell-pile 模块中添加一个新的会员优惠券功能，包括：
- 实体类 MemberCoupon（对应数据库表 member_coupon）
- Mapper 接口和 XML（参考 MemberPointsInfoMapper）
- Service 接口和实现（参考 MemberPointsInfoService）
- Controller API（参考 MemberPointsInfoController）
- 需要支持 CRUD 操作和优惠券发放功能
```

#### 2. 修改订单结算逻辑

```
请查看 /Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java
中的 realTimeOrderSplit() 方法，帮我理解当前的分账逻辑，并建议如何优化。
```

#### 3. 添加第三方平台对接

```
请参考 /Users/autumn/Workspace/jsowell-charger-web/jsowell-thirdparty/src/main/java/com/jsowell/thirdparty/zhongdianlian/service/impl/ZDLServiceImpl.java
的实现，帮我添加一个新的第三方平台对接，平台名称是 XXX，需要实现以下接口：...
```

#### 4. 调试 Netty 通信问题

```
充电桩设备无法正常登录，请帮我检查
/Users/autumn/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java
中的登录处理逻辑，并查看相关的 RabbitMQ 消息队列配置。
```

#### 5. 添加新的枚举类型

```
请在 jsowell-common 模块的 enums 包下添加一个新的枚举类 OrderRefundStatusEnum，
用于表示订单退款状态，参考现有的 OrderStatusEnum 的实现方式。
```

### 关键文件索引

| 功能 | 关键文件 |
|------|---------|
| 启动类 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java` |
| 主配置 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application.yml` |
| 订单结算 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java` |
| 设备通信 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java` |
| 积分系统 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/MemberPointsInfoServiceImpl.java` |
| 微信支付 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/wxpay/config/WechatPayConfig.java` |
| 支付宝支付 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/alipay/config/AliPayConfig.java` |
| 汇付支付 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/adapay/config/InitializeAdapayConfig.java` |
| RabbitMQ 配置 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-common/src/main/java/com/jsowell/common/config/mq/RabbitConfig.java` |
| 积分 RabbitMQ | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-common/src/main/java/com/jsowell/common/config/mq/PointsRabbitConfig.java` |
| 安全配置 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-framework/src/main/java/com/jsowell/framework/config/SecurityConfig.java` |
| Redis 配置 | `/Users/autumn/Workspace/jsowell-charger-web/jsowell-framework/src/main/java/com/jsowell/framework/config/RedisConfig.java` |

### 数据库表索引

详细的数据库表结构请参考各模块的 `CLAUDE.md` 文档。

主要表分类：
- **会员相关**: `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`
- **结算相关**: `clearing_bill_info`, `clearing_bill_detail`, `station_split_config`, `settle_order_report`
- **系统相关**: `sys_user`, `sys_role`, `sys_menu`, `sys_dept`, `sys_dict_type`, `sys_dict_data`, `sys_config`

### 枚举类索引

项目中定义了大量枚举类，位于 `jsowell-common/src/main/java/com/jsowell/common/enums/` 目录下：

- **订单相关**: `OrderStatusEnum`, `OrderPayStatusEnum`, `OrderPayModeEnum`, `OrderTypeEnum`
- **支付相关**: `PayModeEnum`, `PaymentInstitutionsEnum`, `AdapayStatusEnum`, `AdapayPayChannelEnum`
- **充电桩相关**: `PileStatusEnum`, `PileConnectorStatusEnum`, `StartModeEnum`, `StopChargingFailedReasonEnum`
- **会员相关**: `MemberWalletEnum`, `BalanceChangesEnum`
- **第三方平台**: `ThirdPlatformTypeEnum`, `ThirdPartyApiEnum`, `ThirdPartyReturnCodeEnum`

---

## 监控与运维

### 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`

### 日志

- **日志配置**: `logback-spring.xml`
- **日志级别**:
  - 开发环境: `com.jsowell: debug`
  - 生产环境: `com.jsowell: info`

---

## 注意事项

1. **数据库连接**: 使用 Druid 连接池，主从分离配置在 `application-{env}.yml`
2. **事务管理**: 使用 `@Transactional` 注解，注意事务传播行为
3. **异步处理**: RabbitMQ 已改为自动应答模式（2024年12月26日）
4. **Netty 线程模型**: 注意 EventLoop 线程安全，避免阻塞操作
5. **Dubbo 服务**: 启动时不检查提供者（`consumer.check=false`）
6. **积分发放**: 通过 RabbitMQ 异步处理，避免影响订单结算主流程
7. **热部署**: 开发环境启用 `spring.devtools.restart.enabled=true`
8. **文件上传**: 支持本地存储、阿里云 OSS、Minio 三种方式
9. **密码安全**: 使用 BCrypt 加密，密码错误 5 次锁定 10 分钟
10. **Token 管理**: JWT Token 有效期 1440 分钟（1天），接口 Token 有效期 259200 分钟（6个月）

---

## 相关资源

- [Spring Boot 文档](https://spring.io/projects/spring-boot)
- [MyBatis 文档](https://mybatis.org/mybatis-3/)
- [MyBatis-Plus 文档](https://baomidou.com/)
- [Netty 文档](https://netty.io/wiki/)
- [Dubbo 文档](https://dubbo.apache.org/)
- [RabbitMQ 文档](https://www.rabbitmq.com/documentation.html)
- [Nacos 文档](https://nacos.io/zh-cn/docs/what-is-nacos.html)

---

## 联系方式

- **项目维护**: jsowell 团队
- **Git 分支**:
  - 主分支: `master`
  - 开发分支: `dev`（当前分支）
- **最近提交**:
  - `7c576ca25` - bugfix 查询订单详情字段为空
  - `c1db659cc` - update
  - `5ffb8826f` - update 运营端小程序查询订单详情接口补充反参