From de165697d917640a4e9a1eeb0485addba43be785 Mon Sep 17 00:00:00 2001 From: Guoqs <123@jsowell.com> Date: Mon, 22 Dec 2025 18:29:35 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0claude.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 + CLAUDE.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 2b3b68c30..ff48835bb 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,4 @@ build/ ### VS Code ### .vscode/ .mvn/ +/.claude/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..ea15c3044 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,225 @@ +# 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`（使用自定义数据源配置）