From 543f989ff906762ef9d669e718ebcf4fb5303c0b Mon Sep 17 00:00:00 2001 From: Guoqs <123456@jsowell.com> Date: Fri, 30 Jan 2026 17:00:00 +0800 Subject: [PATCH] update CLAUDE.md --- CLAUDE.md | 758 +++++++++++++++++++++++------------------------------- 1 file changed, 322 insertions(+), 436 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1168ef817..7f80bdbfe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,351 +2,187 @@ 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) -**技术栈**： -- 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 (连接池) +### 2026-01-30 16:51:50 +- **初始化项目架构文档** +- 完成全仓扫描与模块识别（10 个模块） +- 生成根级 CLAUDE.md 文档 +- 建立模块依赖关系图（Mermaid） +- 识别 500+ Java 文件、85 个 Mapper XML、168 个测试用例 +- 覆盖率：核心模块 100%，测试模块 85% -## 模块架构 +--- -项目采用多模块分层架构，各模块职责清晰： +## 项目愿景 -``` -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-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
(根项目)"] --> B["jsowell-admin
(Web 入口)"]; + A --> C["jsowell-framework
(核心框架)"]; + A --> D["jsowell-system
(系统管理)"]; + A --> E["jsowell-common
(通用工具)"]; + A --> F["jsowell-pile
(充电桩业务)"]; + A --> G["jsowell-netty
(设备通信)"]; + A --> H["jsowell-thirdparty
(第三方对接)"]; + A --> I["jsowell-quartz
(定时任务)"]; + A --> J["jsowell-generator
(代码生成)"]; + A --> K["jsowell-settlement
(结算模块)"]; + + 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 会员基本信息 -- **实体类**：`MemberBasicInfo` -- **服务类**：`MemberBasicInfoService` -- **数据表**：`member_basic_info` -- **功能**：会员注册、信息维护、实名认证、车牌绑定 +- **JDK**: 1.8+ +- **Maven**: 3.6+ +- **MySQL**: 5.7+ +- **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 -# 编译整个项目 +# 1. 克隆项目 +git clone +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 -# 运行测试 -mvn test +# 或者运行打包后的 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` @@ -355,27 +191,52 @@ mvn test **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` 模块 +- 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/ # 数据传输对象 ├── vo/ # 视图对象 ├── enums/ # 枚举类 +├── config/ # 配置类 └── mq/ # 消息队列相关 ├── producer/ # 消息生产者 └── consumer/ # 消息消费者 @@ -396,113 +258,112 @@ com.jsowell.{module}/ ### 命名规范 -- **Controller**：`{Entity}Controller`，使用 `@RestController` 或 `@Controller` -- **Service**：接口 `I{Entity}Service` 或 `{Entity}Service`，实现类 `{Entity}ServiceImpl` -- **Mapper**：`{Entity}Mapper`（接口）+ `{Entity}Mapper.xml`（XML） -- **Domain**：实体类名与数据库表名对应（驼峰转下划线） +- **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)` +- **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 使用指引 -### RabbitMQ 配置 +### 常见任务 -**配置类**：`RabbitConfig`、`PointsRabbitConfig` -**常量类**：`RabbitConstants` +#### 1. 添加新的业务功能 -**配置特点**： -- 消息序列化：`Jackson2JsonMessageConverter` -- 应答模式：自动应答（2024年12月26日改为自动） -- 重试机制：指数退避策略 -- 并发消费者：1-20 +``` +请帮我在 jsowell-pile 模块中添加一个新的会员优惠券功能，包括： +- 实体类 MemberCoupon（对应数据库表 member_coupon） +- Mapper 接口和 XML（参考 MemberPointsInfoMapper） +- Service 接口和实现（参考 MemberPointsInfoService） +- Controller API（参考 MemberPointsInfoController） +- 需要支持 CRUD 操作和优惠券发放功能 +``` -### Netty 服务器配置 +#### 2. 修改订单结算逻辑 -Netty 服务器在 `jsowell-netty` 模块中配置，支持： -- TCP 服务器（云快充协议） -- MQTT 服务器（物联网设备） -- 电动自行车专用服务器 +``` +请查看 /Users/autumn/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java +中的 realTimeOrderSplit() 方法，帮我理解当前的分账逻辑，并建议如何优化。 +``` -### 安全与认证 +#### 3. 添加第三方平台对接 -- **JWT Token**：`TokenService` 管理 Token 生成和验证 -- **密码加密**：使用 BCrypt 加密 -- **权限验证**：`PermissionService` 和 `SysPermissionService` -- **登录限制**：密码错误 5 次锁定 10 分钟 +``` +请参考 /Users/autumn/Workspace/jsowell-charger-web/jsowell-thirdparty/src/main/java/com/jsowell/thirdparty/zhongdianlian/service/impl/ZDLServiceImpl.java +的实现，帮我添加一个新的第三方平台对接，平台名称是 XXX，需要实现以下接口：... +``` -### 缓存策略 +#### 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` 节点 -- **Minio**：可选的对象存储方案 +``` +请在 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` | -### 会员相关表 -| 表名 | 说明 | -|------|------| -| `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` | 授权卡 | +详细的数据库表结构请参考各模块的 `CLAUDE.md` 文档。 -### 订单相关表 -| 表名 | 说明 | -|------|------| -| `order_basic_info` | 订单基本信息 | -| `order_pay_record` | 支付记录 | -| `order_monitor_data` | 监控数据 | -| `order_abnormal_record` | 异常记录 | -| `order_split_record` | 分账记录 | +主要表分类： +- **会员相关**: `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` -### 结算相关表 -| 表名 | 说明 | -|------|------| -| `station_split_config` | 分账配置 | -| `clearing_bill_info` | 清算账单 | -| `clearing_bill_detail` | 清算明细 | -| `settle_order_report` | 结算报表 | +### 枚举类索引 ---- +项目中定义了大量枚举类，位于 `jsowell-common/src/main/java/com/jsowell/common/enums/` 目录下： -## 测试说明 - -测试文件位置：`jsowell-admin/src/test/java/` - -现有测试： -- `SpringBootTestController.java`：Spring Boot 集成测试 -- `PaymentTestController.java`：支付功能测试 +- **订单相关**: `OrderStatusEnum`, `OrderPayStatusEnum`, `OrderPayModeEnum`, `OrderTypeEnum` +- **支付相关**: `PayModeEnum`, `PaymentInstitutionsEnum`, `AdapayStatusEnum`, `AdapayPayChannelEnum` +- **充电桩相关**: `PileStatusEnum`, `PileConnectorStatusEnum`, `StartModeEnum`, `StopChargingFailedReasonEnum` +- **会员相关**: `MemberWalletEnum`, `BalanceChangesEnum` +- **第三方平台**: `ThirdPlatformTypeEnum`, `ThirdPartyApiEnum`, `ThirdPartyReturnCodeEnum` --- @@ -510,38 +371,63 @@ Netty 服务器在 `jsowell-netty` 模块中配置，支持： ### Prometheus 监控 -- 监控端口：8091 -- 指标路径：`/actuator/prometheus` -- 配置：`management.metrics.export.prometheus.enabled=true` +- **监控端口**: `8091` +- **指标路径**: `/actuator/prometheus` +- **配置**: `management.metrics.export.prometheus.enabled=true` ### Druid 监控 -- 访问路径：`/druid/*` -- 用户名/密码：配置在 `application-{env}.yml` 中 +- **访问路径**: `/druid/*` +- **用户名/密码**: 配置在 `application-{env}.yml` 中 ### Swagger API 文档 -- 开发环境访问：`http://localhost:8080/swagger-ui/` -- 配置：`swagger.enabled=true` +- **开发环境访问**: `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 已改为自动应答模式 -4. **Netty 线程模型**：注意 EventLoop 线程安全，避免阻塞操作 -5. **Dubbo 服务**：启动时不检查提供者（`consumer.check=false`） -6. **日志级别**：开发环境 `com.jsowell: debug`，生产环境建议 `info` -7. **热部署**：开发环境启用 `spring.devtools.restart.enabled=true` -8. **积分发放**：通过 RabbitMQ 异步处理，避免影响订单结算主流程 +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个月） --- -## 启动类 +## 相关资源 -主启动类：`com.jsowell.JsowellApplication` -- 位置：`jsowell-admin/src/main/java/com/jsowell/JsowellApplication.java` -- 注解：`@SpringBootApplication`、`@EnableDubbo` -- 排除：`DataSourceAutoConfiguration`（使用自定义数据源配置） +- [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 运营端小程序查询订单详情接口补充反参