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
Files
master
jsowell-charger-web/CLAUDE.md
Guoqs 80f53d9f51 update claude.md
2026-02-03 14:20:30 +08:00

17 KiB
Raw Permalink Blame History

CLAUDE.md

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

变更记录 (Changelog)

2026-02-03 11:32:30

  • 增量更新项目架构文档
  • 更新文件统计：600+ Java 文件、80 个 Mapper XML、60 个枚举类
  • 新增各模块 CLAUDE.md 文档（10 个模块）
  • 更新模块依赖关系与覆盖率报告
  • 识别 108 个 Controller、80 个 Service 实现类
  • 覆盖率：核心模块 100%，测试模块 90%

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. 积分系统: 充电奖励积分，异步发放，支持积分抵扣

模块结构图

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+

快速启动

# 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 个测试用例

运行测试

# 运行所有测试
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个月）

相关资源

联系方式

  • 项目维护: jsowell 团队
  • Git 分支:
    • 主分支: master
    • 开发分支: dev（当前分支）
  • 最近提交:
    • 543f989ff - update CLAUDE.md
    • 7c576ca25 - bugfix 查询订单详情字段为空
    • c1db659cc - update
Reference in New Issue View Git Blame Copy Permalink