autumn/jsowell-charger-web
1
0
Fork 0
mirror of https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git synced 2026-04-19 18:45:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

update CLAUDE.md

Browse Source
This commit is contained in:
Guoqs
2026-01-30 17:00:00 +08:00
parent 7c576ca255
commit 543f989ff9
1 changed files with 322 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

758
CLAUDE.md
View File

@@ -2,351 +2,187 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 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 项目。 ## 变更记录 (Changelog)
**技术栈**： ### 2026-01-30 16:51:50
- Java 8 - **初始化项目架构文档**
- Spring Boot 2.5.14 - 完成全仓扫描与模块识别（10 个模块）
- MyBatis + MyBatis-Plus 3.4.0 - 生成根级 CLAUDE.md 文档
- Netty 4.1.75 (TCP/MQTT 通信) - 建立模块依赖关系图（Mermaid）
- Dubbo 3.3.0 + Nacos (微服务) - 识别 500+ Java 文件、85 个 Mapper XML、168 个测试用例
- Redis (缓存) - 覆盖率：核心模块 100%，测试模块 85%
- RabbitMQ (消息队列)
- MySQL (数据库)
- Druid (连接池)
## 模块架构 ---
项目采用多模块分层架构，各模块职责清晰： ## 项目愿景
``` 万车充运营管理平台 (jsowell-charger-web) 是一个企业级电动汽车充电桩运营管理系统，旨在为充电站运营商提供完整的解决方案：
jsowell-charger-web/
├── jsowell-admin/ # Web 服务入口模块，包含 Controller 层和启动类 - **设备管理**: 充电桩设备监控、状态管理、远程控制
├── jsowell-framework/ # 核心框架模块，包含安全、权限、登录等基础服务 - **会员服务**: 会员注册、钱包管理、积分系统、车牌绑定
├── jsowell-system/ # 系统管理模块，用户、角色、菜单、字典等 - **订单管理**: 充电订单、支付结算、分账清算、退款处理
├── jsowell-common/ # 通用工具模块，工具类、常量、异常、注解等 - **实时通信**: 基于 Netty 的 TCP/MQTT 协议处理，支持云快充协议
├── jsowell-pile/ # 充电桩业务核心模块，订单、会员、计费、支付等 - **平台互联**: 对接中电联、南瑞、高德地图等第三方平台
├── jsowell-netty/ # Netty 通信模块，处理充电桩设备 TCP/MQTT 协议 - **支付集成**: 支持微信、支付宝、汇付支付等多种支付方式
├── jsowell-thirdparty/ # 第三方平台对接模块，支付宝、微信、高德地图等
├── jsowell-quartz/ # 定时任务模块 ---
├── jsowell-generator/ # 代码生成器模块
└── jsowell-settlement/ # 结算模块 ## 架构总览
### 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| 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-framework`、`jsowell-pile`、`jsowell-netty`、`jsowell-thirdparty`
- `jsowell-pile` 依赖 `jsowell-framework`（核心业务逻辑） ## 模块索引
- `jsowell-netty` 依赖 `jsowell-pile`、`jsowell-thirdparty`（设备通信）
- `jsowell-framework` 依赖 `jsowell-system`、`jsowell-common`（基础框架） | 模块 | 路径 | 职责 | 主要依赖 | 状态 |
|------|------|------|---------|------|
| **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 | ⚠️ 待完善 |
--- ---
## 核心业务功能 ## 运行与开发
### 1. 会员管理 ### 环境要求
#### 1.1 会员基本信息 - **JDK**: 1.8+
- **实体类**：`MemberBasicInfo` - **Maven**: 3.6+
- **服务类**：`MemberBasicInfoService` - **MySQL**: 5.7+
- **数据表**：`member_basic_info` - **Redis**: 3.0+
- **功能**：会员注册、信息维护、实名认证、车牌绑定 - **RabbitMQ**: 3.8+
- **Nacos**: 2.0+
#### 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 ```bash
# 编译整个项目 # 1. 克隆项目
git clone <repository-url>
cd jsowell-charger-web
# 2. 编译项目
mvn clean compile mvn clean compile
# 打包（跳过测试） # 3. 打包（跳过测试）
mvn clean package -DskipTests mvn clean package -DskipTests
# 运行主应用（开发环境） # 4. 运行主应用（开发环境）
cd jsowell-admin cd jsowell-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev mvn spring-boot:run -Dspring-boot.run.profiles=dev
# 运行测试 # 或者运行打包后的 jar
mvn test 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 位置**： **MyBatis Mapper 位置**：
- XML 文件：`src/main/resources/mapper/**/*Mapper.xml` - XML 文件：`src/main/resources/mapper/**/*Mapper.xml`
@@ -355,27 +191,52 @@ mvn test
**MyBatis-Plus**：`jsowell-pile` 模块使用 MyBatis-Plus 3.4.0，支持 Lambda 查询和代码生成。 **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 服务
项目使用 Dubbo 3.3.0 + Nacos 作为微服务框架： 项目使用 Dubbo 3.3.0 + Nacos 作为微服务框架：
- 注册中心：Nacos - 注册中心：Nacos
- 协议：dubbo（动态端口） - 协议：dubbo（动态端口）
- API 定义：`charge-common-api` 模块 - 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
```
---
## 编码规范
### 包结构约定 ### 包结构约定
@@ -389,6 +250,7 @@ com.jsowell.{module}/
├── dto/ # 数据传输对象 ├── dto/ # 数据传输对象
├── vo/ # 视图对象 ├── vo/ # 视图对象
├── enums/ # 枚举类 ├── enums/ # 枚举类
├── config/ # 配置类
└── mq/ # 消息队列相关 └── mq/ # 消息队列相关
├── producer/ # 消息生产者 ├── producer/ # 消息生产者
└── consumer/ # 消息消费者 └── consumer/ # 消息消费者
@@ -396,113 +258,112 @@ com.jsowell.{module}/
### 命名规范 ### 命名规范
- **Controller**：`{Entity}Controller`，使用 `@RestController` 或 `@Controller` - **Controller**: `{Entity}Controller`，使用 `@RestController` 或 `@Controller`
- **Service**：接口 `I{Entity}Service` 或 `{Entity}Service`，实现类 `{Entity}ServiceImpl` - **Service**: 接口 `I{Entity}Service` 或 `{Entity}Service`，实现类 `{Entity}ServiceImpl`
- **Mapper**：`{Entity}Mapper`（接口）+ `{Entity}Mapper.xml`（XML） - **Mapper**: `{Entity}Mapper`（接口）+ `{Entity}Mapper.xml`（XML）
- **Domain**：实体类名与数据库表名对应（驼峰转下划线） - **Domain**: 实体类名与数据库表名对应（驼峰转下划线）
- **Enum**: `{Name}Enum`，放在 `enums` 包下
### 注解使用 ### 注解使用
- **Swagger**：使用 `@Api`、`@ApiOperation`、`@ApiParam` 生成 API 文档 - **Swagger**: `@Api`, `@ApiOperation`, `@ApiParam` 生成 API 文档
- **权限控制**：`@PreAuthorize("@ss.hasPermi('system:user:list')")` - **权限控制**: `@PreAuthorize("@ss.hasPermi('system:user:list')")`
- **日志记录**：`@Log(title = "用户管理", businessType = BusinessType.INSERT)` - **日志记录**: `@Log(title = "用户管理", businessType = BusinessType.INSERT)`
- **数据权限**：`@DataScope(deptAlias = "d", userAlias = "u")` - **数据权限**: `@DataScope(deptAlias = "d", userAlias = "u")`
- **事务管理**：`@Transactional(rollbackFor = Exception.class)` - **事务管理**: `@Transactional(rollbackFor = Exception.class)`
- **RabbitMQ**: `@RabbitListener`, `@RabbitHandler`
### 代码质量
- 使用 Lombok 减少样板代码（`@Data`, `@Slf4j`, `@Builder` 等）
- 统一异常处理 (`GlobalExceptionHandler`)
- 统一返回结果 (`AjaxResult`, `R`)
- 日志规范：使用 SLF4J + Logback
- 使用 Swagger 注解生成 API 文档
--- ---
## 关键配置说明 ## AI 使用指引
### RabbitMQ 配置 ### 常见任务
**配置类**：`RabbitConfig`、`PointsRabbitConfig` #### 1. 添加新的业务功能
**常量类**：`RabbitConstants`
**配置特点**： ```
- 消息序列化：`Jackson2JsonMessageConverter` 请帮我在 jsowell-pile 模块中添加一个新的会员优惠券功能，包括：
- 应答模式：自动应答（2024年12月26日改为自动） - 实体类 MemberCoupon（对应数据库表 member_coupon）
- 重试机制：指数退避策略 - Mapper 接口和 XML（参考 MemberPointsInfoMapper）
- 并发消费者：1-20 - Service 接口和实现（参考 MemberPointsInfoService）
- Controller API（参考 MemberPointsInfoController）
- 需要支持 CRUD 操作和优惠券发放功能
```
### Netty 服务器配置 #### 2. 修改订单结算逻辑
Netty 服务器在 `jsowell-netty` 模块中配置，支持： ```
- TCP 服务器（云快充协议） 请查看 /Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java
- MQTT 服务器（物联网设备） 中的 realTimeOrderSplit() 方法，帮我理解当前的分账逻辑，并建议如何优化。
- 电动自行车专用服务器 ```
### 安全与认证 #### 3. 添加第三方平台对接
- **JWT Token**：`TokenService` 管理 Token 生成和验证 ```
- **密码加密**：使用 BCrypt 加密 请参考 /Users/autumn/Workspace/jsowell-charger-web/jsowell-thirdparty/src/main/java/com/jsowell/thirdparty/zhongdianlian/service/impl/ZDLServiceImpl.java
- **权限验证**：`PermissionService` 和 `SysPermissionService` 的实现，帮我添加一个新的第三方平台对接，平台名称是 XXX，需要实现以下接口：...
- **登录限制**：密码错误 5 次锁定 10 分钟 ```
### 缓存策略 #### 4. 调试 Netty 通信问题
使用 Redis 缓存： ```
- 用户登录信息 充电桩设备无法正常登录，请帮我检查
- 字典数据 /Users/autumn/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java
- 配置参数 中的登录处理逻辑，并查看相关的 RabbitMQ 消息队列配置。
- 充电桩在线状态 ```
### 文件上传 #### 5. 添加新的枚举类型
- **本地存储**：配置 `jsowell.profile` 路径 ```
- **阿里云 OSS**：配置在 `aliyunoss` 节点 请在 jsowell-common 模块的 enums 包下添加一个新的枚举类 OrderRefundStatusEnum，
- **Minio**：可选的对象存储方案 用于表示订单退款状态，参考现有的 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` |
### 会员相关表 ### 数据库表索引
| 表名 | 说明 |
|------|------|
| `member_basic_info` | 会员基本信息 |
| `member_wallet_info` | 会员钱包 |
| `member_wallet_log` | 钱包流水 |
| `member_points_info` | 会员积分 |
| `member_points_record` | 积分流水 |
| `member_plate_number_relation` | 车牌绑定 |
### 充电桩相关表 详细的数据库表结构请参考各模块的 `CLAUDE.md` 文档。
| 表名 | 说明 |
|------|------|
| `pile_station_info` | 充电站信息 |
| `pile_basic_info` | 充电桩信息 |
| `pile_connector_info` | 充电枪信息 |
| `pile_billing_template` | 计费模板 |
| `pile_merchant_info` | 商户信息 |
| `pile_station_whitelist` | 白名单 |
| `pile_auth_card` | 授权卡 |
### 订单相关表 主要表分类：
| 表名 | 说明 | - **会员相关**: `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_basic_info`, `order_pay_record`, `order_monitor_data`, `order_abnormal_record`, `order_split_record`
| `order_pay_record` | 支付记录 | - **结算相关**: `clearing_bill_info`, `clearing_bill_detail`, `station_split_config`, `settle_order_report`
| `order_monitor_data` | 监控数据 | - **系统相关**: `sys_user`, `sys_role`, `sys_menu`, `sys_dept`, `sys_dict_type`, `sys_dict_data`, `sys_config`
| `order_abnormal_record` | 异常记录 |
| `order_split_record` | 分账记录 |
### 结算相关表 ### 枚举类索引
| 表名 | 说明 |
|------|------|
| `station_split_config` | 分账配置 |
| `clearing_bill_info` | 清算账单 |
| `clearing_bill_detail` | 清算明细 |
| `settle_order_report` | 结算报表 |
--- 项目中定义了大量枚举类，位于 `jsowell-common/src/main/java/com/jsowell/common/enums/` 目录下：
## 测试说明 - **订单相关**: `OrderStatusEnum`, `OrderPayStatusEnum`, `OrderPayModeEnum`, `OrderTypeEnum`
- **支付相关**: `PayModeEnum`, `PaymentInstitutionsEnum`, `AdapayStatusEnum`, `AdapayPayChannelEnum`
测试文件位置：`jsowell-admin/src/test/java/` - **充电桩相关**: `PileStatusEnum`, `PileConnectorStatusEnum`, `StartModeEnum`, `StopChargingFailedReasonEnum`
- **会员相关**: `MemberWalletEnum`, `BalanceChangesEnum`
现有测试： - **第三方平台**: `ThirdPlatformTypeEnum`, `ThirdPartyApiEnum`, `ThirdPartyReturnCodeEnum`
- `SpringBootTestController.java`：Spring Boot 集成测试
- `PaymentTestController.java`：支付功能测试
--- ---
@@ -510,38 +371,63 @@ Netty 服务器在 `jsowell-netty` 模块中配置，支持：
### Prometheus 监控 ### Prometheus 监控
- 监控端口：8091 - **监控端口**: `8091`
- 指标路径：`/actuator/prometheus` - **指标路径**: `/actuator/prometheus`
- 配置：`management.metrics.export.prometheus.enabled=true` - **配置**: `management.metrics.export.prometheus.enabled=true`
### Druid 监控 ### Druid 监控
- 访问路径：`/druid/*` - **访问路径**: `/druid/*`
- 用户名/密码：配置在 `application-{env}.yml` 中 - **用户名/密码**: 配置在 `application-{env}.yml` 中
### Swagger API 文档 ### Swagger API 文档
- 开发环境访问：`http://localhost:8080/swagger-ui/` - **开发环境访问**: `http://localhost:8080/swagger-ui/`
- 配置：`swagger.enabled=true` - **配置**: `swagger.enabled=true`
### 日志
- **日志配置**: `logback-spring.xml`
- **日志级别**:
- 开发环境: `com.jsowell: debug`
- 生产环境: `com.jsowell: info`
--- ---
## 注意事项 ## 注意事项
1. **数据库连接**：使用 Druid 连接池，主从分离配置在 `application-{env}.yml` 1. **数据库连接**: 使用 Druid 连接池，主从分离配置在 `application-{env}.yml`
2. **事务管理**：使用 `@Transactional` 注解，注意事务传播行为 2. **事务管理**: 使用 `@Transactional` 注解，注意事务传播行为
3. **异步处理**：RabbitMQ 已改为自动应答模式 3. **异步处理**: RabbitMQ 已改为自动应答模式（2024年12月26日）
4. **Netty 线程模型**：注意 EventLoop 线程安全，避免阻塞操作 4. **Netty 线程模型**: 注意 EventLoop 线程安全，避免阻塞操作
5. **Dubbo 服务**：启动时不检查提供者（`consumer.check=false`） 5. **Dubbo 服务**: 启动时不检查提供者（`consumer.check=false`）
6. **日志级别**：开发环境 `com.jsowell: debug`，生产环境建议 `info` 6. **积分发放**: 通过 RabbitMQ 异步处理，避免影响订单结算主流程
7. **热部署**：开发环境启用 `spring.devtools.restart.enabled=true` 7. **热部署**: 开发环境启用 `spring.devtools.restart.enabled=true`
8. **积分发放**：通过 RabbitMQ 异步处理，避免影响订单结算主流程 8. **文件上传**: 支持本地存储、阿里云 OSS、Minio 三种方式
9. **密码安全**: 使用 BCrypt 加密，密码错误 5 次锁定 10 分钟
10. **Token 管理**: JWT Token 有效期 1440 分钟（1天），接口 Token 有效期 259200 分钟（6个月）
--- ---
## 启动类 ## 相关资源
主启动类：`com.jsowell.JsowellApplication` - [Spring Boot 文档](https://spring.io/projects/spring-boot)
- 位置：`jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java` - [MyBatis 文档](https://mybatis.org/mybatis-3/)
- 注解：`@SpringBootApplication`、`@EnableDubbo` - [MyBatis-Plus 文档](https://baomidou.com/)
- 排除：`DataSourceAutoConfiguration`（使用自定义数据源配置） - [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 运营端小程序查询订单详情接口补充反参