diff --git a/CLAUDE.md b/CLAUDE.md index 1168ef817..128b225d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,351 +2,195 @@ 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-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/ -├── 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 +199,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 +258,7 @@ com.jsowell.{module}/ ├── dto/ # 数据传输对象 ├── vo/ # 视图对象 ├── enums/ # 枚举类 +├── config/ # 配置类 └── mq/ # 消息队列相关 ├── producer/ # 消息生产者 └── consumer/ # 消息消费者 @@ -396,113 +266,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 +379,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`（当前分支） +- **最近提交**: + - `543f989ff` - update CLAUDE.md + - `7c576ca25` - bugfix 查询订单详情字段为空 + - `c1db659cc` - update diff --git a/jsowell-admin/CLAUDE.md b/jsowell-admin/CLAUDE.md new file mode 100644 index 000000000..6f64586c9 --- /dev/null +++ b/jsowell-admin/CLAUDE.md @@ -0,0 +1,187 @@ +[根目录](../CLAUDE.md) > **jsowell-admin** + +# jsowell-admin 模块 + +Web 服务入口模块，包含应用启动类、Controller 层和配置文件。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 108 个 Controller +- 统计测试用例 168 个 + +--- + +## 模块职责 + +- **应用启动**: Spring Boot 启动类 `JsowellApplication` +- **REST API**: 所有 HTTP 接口的 Controller 层 +- **配置管理**: 多环境配置文件（dev/sit/pre/prd） +- **测试入口**: 单元测试和集成测试 + +--- + +## 入口与启动 + +### 启动类 + +```java +// JsowellApplication.java +@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class}) +@EnableDubbo +public class JsowellApplication { + public static void main(String[] args) { + SpringApplication.run(JsowellApplication.class, args); + } +} +``` + +### 启动命令 + +```bash +# 开发环境 +mvn spring-boot:run -Dspring-boot.run.profiles=dev + +# 生产环境 +java -jar jsowell-admin.jar --spring.profiles.active=prd +``` + +--- + +## 对外接口 + +### Controller 分类 + +| 包路径 | 数量 | 说明 | +|--------|------|------| +| `com.jsowell.web.controller.system` | 14 | 系统管理（用户、角色、菜单等） | +| `com.jsowell.web.controller.pile` | 22 | 充电桩业务（订单、会员、站点等） | +| `com.jsowell.web.controller.monitor` | 6 | 监控管理（缓存、日志、在线用户） | +| `com.jsowell.api.thirdparty` | 30+ | 第三方平台对接 API | +| `com.jsowell.api.uniapp.customer` | 12 | 小程序用户端 API | +| `com.jsowell.api.uniapp.business` | 5 | 小程序运营端 API | +| `com.jsowell.web.controller.jcpp` | 4 | JCPP 协议接口 | + +### 主要 Controller + +| Controller | 路径 | 说明 | +|------------|------|------| +| `SysLoginController` | `/login`, `/logout` | 登录认证 | +| `SysUserController` | `/system/user/**` | 用户管理 | +| `OrderBasicInfoController` | `/pile/order/**` | 订单管理 | +| `MemberBasicInfoController` | `/pile/member/**` | 会员管理 | +| `PileStationInfoController` | `/pile/station/**` | 站点管理 | +| `PileBasicInfoController` | `/pile/pile/**` | 充电桩管理 | +| `ZDLController` | `/api/zdl/**` | 中电联对接 | + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + com.jsowell + jsowell-framework + + + com.jsowell + jsowell-pile + + + com.jsowell + jsowell-netty + + + com.jsowell + jsowell-thirdparty + + + com.jsowell + jsowell-quartz + + + com.jsowell + jsowell-generator + + +``` + +### 配置文件 + +| 文件 | 说明 | +|------|------| +| `application.yml` | 主配置，环境切换 | +| `application-dev.yml` | 开发环境 | +| `application-sit.yml` | 测试环境 | +| `application-pre.yml` | 预发布环境 | +| `application-prd.yml` | 生产环境 | +| `mybatis/mybatis-config.xml` | MyBatis 配置 | +| `logback-spring.xml` | 日志配置 | + +--- + +## 测试与质量 + +### 测试文件 + +| 测试类 | 说明 | +|--------|------| +| `SpringBootTestController` | 集成测试（131 个用例） | +| `PaymentTestController` | 支付功能测试 | +| `JcppMessageControllerTest` | JCPP 消息测试 | +| `PricingModelConverterTest` | 计费模型测试 | +| `OrderServiceWhitelistCompletionTest` | 白名单订单测试 | + +### 运行测试 + +```bash +mvn test -pl jsowell-admin +``` + +--- + +## 常见问题 (FAQ) + +### Q: 如何切换环境？ +修改 `application.yml` 中的 `spring.profiles.active` 或启动时指定 `--spring.profiles.active=xxx` + +### Q: Swagger 文档无法访问？ +检查 `swagger.enabled` 配置是否为 `true`，生产环境默认关闭 + +### Q: 启动报数据库连接错误？ +检查对应环境配置文件中的数据库连接信息 + +--- + +## 相关文件清单 + +``` +jsowell-admin/ +├── src/main/java/com/jsowell/ +│ ├── JsowellApplication.java # 启动类 +│ ├── JsowellServletInitializer.java # Servlet 初始化 +│ ├── api/ # API 接口 +│ │ ├── feign/ # Feign 客户端 +│ │ ├── thirdparty/ # 第三方平台 API +│ │ └── uniapp/ # 小程序 API +│ ├── service/ # 本模块服务 +│ └── web/controller/ # Web 控制器 +│ ├── common/ # 通用控制器 +│ ├── jcpp/ # JCPP 协议 +│ ├── monitor/ # 监控管理 +│ ├── pile/ # 充电桩业务 +│ ├── system/ # 系统管理 +│ ├── thirdparty/ # 第三方配置 +│ └── tool/ # 工具类 +├── src/main/resources/ +│ ├── application*.yml # 配置文件 +│ ├── mybatis/ # MyBatis 配置 +│ └── logback-spring.xml # 日志配置 +└── src/test/java/ # 测试代码 +``` diff --git a/jsowell-admin/src/main/java/com/jsowell/web/controller/pile/OrderBasicInfoController.java b/jsowell-admin/src/main/java/com/jsowell/web/controller/pile/OrderBasicInfoController.java index 27c259283..93d8329c3 100644 --- a/jsowell-admin/src/main/java/com/jsowell/web/controller/pile/OrderBasicInfoController.java +++ b/jsowell-admin/src/main/java/com/jsowell/web/controller/pile/OrderBasicInfoController.java @@ -12,6 +12,7 @@ import com.jsowell.common.enums.BusinessType; import com.jsowell.common.enums.ykc.ReturnCodeEnum; import com.jsowell.common.exception.BusinessException; import com.jsowell.common.response.RestApiResponse; +import com.jsowell.common.util.SecurityUtils; import com.jsowell.common.util.YKCUtils; import com.jsowell.common.util.poi.ExcelUtil; import com.jsowell.pile.domain.OrderBasicInfo; @@ -33,6 +34,7 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.math.BigDecimal; import java.util.List; +import java.util.Objects; /** * 订单Controller @@ -94,6 +96,9 @@ public class OrderBasicInfoController extends BaseController { // 为空表示没有权限，返回空数组 return new AjaxResult(); } + if (Objects.nonNull(SecurityUtils.getLoginUser())) { + dto.setParams(ImmutableMap.of("roleId", SecurityUtils.getLoginUser().getUserId())); + } String deptId = authorizedMap.getDeptId(); if (CollectionUtils.isNotEmpty(authorizedMap.getStationDeptIds())) { // 为站点管理员 diff --git a/jsowell-common/CLAUDE.md b/jsowell-common/CLAUDE.md new file mode 100644 index 000000000..56716d3dd --- /dev/null +++ b/jsowell-common/CLAUDE.md @@ -0,0 +1,171 @@ +[根目录](../CLAUDE.md) > **jsowell-common** + +# jsowell-common 模块 + +通用工具模块，提供工具类、常量、异常、注解等基础组件。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 60 个枚举类 +- 统计 100+ 工具类和数据结构 + +--- + +## 模块职责 + +- **工具类**: 字符串、日期、文件、HTTP 等工具 +- **常量定义**: 系统常量、RabbitMQ 常量 +- **枚举类**: 订单状态、支付方式、设备状态等 +- **注解定义**: 日志、权限、数据源等注解 +- **基础实体**: BaseEntity、AjaxResult、R +- **协议数据**: 云快充协议、电动自行车协议数据结构 +- **MQ 配置**: RabbitMQ 队列、交换机配置 + +--- + +## 入口与启动 + +本模块为基础工具模块，无独立启动入口。 + +--- + +## 对外接口 + +### 核心类 + +| 类 | 说明 | +|-----|------| +| `AjaxResult` | 统一返回结果 | +| `R` | 泛型返回结果 | +| `BaseEntity` | 基础实体类 | +| `BaseController` | 基础控制器 | +| `LoginUser` | 登录用户信息 | + +### 注解 + +| 注解 | 说明 | +|------|------| +| `@Log` | 操作日志 | +| `@DataScope` | 数据权限 | +| `@DataSource` | 数据源切换 | +| `@RateLimiter` | 接口限流 | +| `@RepeatSubmit` | 防重复提交 | +| `@Anonymous` | 匿名访问 | +| `@CostTime` | 耗时统计 | + +### 枚举类（60+） + +**订单相关**: +- `OrderStatusEnum` - 订单状态 +- `OrderPayStatusEnum` - 支付状态 +- `OrderPayModeEnum` - 支付方式 +- `OrderTypeEnum` - 订单类型 + +**支付相关**: +- `PayModeEnum` - 支付方式 +- `PaymentInstitutionsEnum` - 支付机构 +- `AdapayStatusEnum` - 汇付状态 +- `AdapayPayChannelEnum` - 汇付渠道 + +**设备相关**: +- `PileStatusEnum` - 充电桩状态 +- `PileConnectorStatusEnum` - 充电枪状态 +- `StartModeEnum` - 启动方式 + +**第三方平台**: +- `ThirdPlatformTypeEnum` - 平台类型 +- `ThirdPartyApiEnum` - API 类型 +- `ThirdPartyReturnCodeEnum` - 返回码 + +--- + +## 关键依赖与配置 + +### RabbitMQ 配置 + +```java +// RabbitConfig.java - 主配置 +// PointsRabbitConfig.java - 积分队列配置 +// DirectRabbitConfig.java - 直连交换机配置 +// TopicRabbitConfig.java - 主题交换机配置 +``` + +### 常量定义 + +```java +// RabbitConstants.java +public class RabbitConstants { + public static final String ORDER_QUEUE = "order.queue"; + public static final String POINTS_QUEUE = "points.queue"; + // ... +} +``` + +--- + +## 数据模型 + +### 云快充协议数据 + +| 类 | 说明 | +|-----|------| +| `YKCDataProtocol` | 协议数据 | +| `YKCBaseMessage` | 基础消息 | +| `LoginRequestData` | 登录数据 | +| `RealTimeMonitorData` | 实时监控数据 | +| `TransactionRecordsData` | 交易记录 | + +### 设备到平台数据（0x01-0xF1） + +位于 `com.jsowell.common.core.domain.ykc.device2platform/` + +### 平台到设备数据（0x02-0x56） + +位于 `com.jsowell.common.core.domain.ykc.platform2device/` + +--- + +## 常见问题 (FAQ) + +### Q: 如何添加新的枚举？ +在 `com.jsowell.common.enums` 包下创建，参考现有枚举实现 + +### Q: 如何添加新的 RabbitMQ 队列？ +在 `RabbitConfig` 或新建配置类中定义 Queue、Exchange、Binding + +--- + +## 相关文件清单 + +``` +jsowell-common/ +├── src/main/java/com/jsowell/common/ +│ ├── annotation/ # 注解定义 +│ ├── config/ # 配置类 +│ │ └── mq/ # RabbitMQ 配置 +│ ├── constant/ # 常量定义 +│ ├── core/ +│ │ ├── controller/ # BaseController +│ │ └── domain/ # 基础实体 +│ │ ├── entity/ # 系统实体 +│ │ ├── model/ # 登录模型 +│ │ ├── ykc/ # 云快充协议 +│ │ └── ebike/ # 电动自行车协议 +│ ├── enums/ # 枚举类 (60+) +│ │ ├── adapay/ +│ │ ├── ebike/ +│ │ ├── lianlian/ +│ │ ├── parkplatform/ +│ │ ├── sim/ +│ │ ├── thirdparty/ +│ │ ├── uniapp/ +│ │ └── ykc/ +│ ├── exception/ # 异常类 +│ ├── filter/ # 过滤器 +│ └── utils/ # 工具类 +└── pom.xml +``` diff --git a/jsowell-framework/CLAUDE.md b/jsowell-framework/CLAUDE.md new file mode 100644 index 000000000..722ad8c18 --- /dev/null +++ b/jsowell-framework/CLAUDE.md @@ -0,0 +1,137 @@ +[根目录](../CLAUDE.md) > **jsowell-framework** + +# jsowell-framework 模块 + +核心框架模块，提供安全、权限、登录等基础服务。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 45 个核心类 + +--- + +## 模块职责 + +- **安全框架**: Spring Security 配置 +- **JWT 认证**: Token 生成与验证 +- **权限控制**: 数据权限、接口权限 +- **数据源管理**: 动态数据源、Druid 配置 +- **AOP 切面**: 日志、限流、数据权限 +- **异常处理**: 全局异常处理 + +--- + +## 入口与启动 + +本模块为基础框架模块，无独立启动入口。 + +--- + +## 对外接口 + +### 核心服务 + +| 服务 | 说明 | +|------|------| +| `TokenService` | JWT Token 服务 | +| `SysLoginService` | 登录服务 | +| `SysPasswordService` | 密码服务 | +| `PermissionService` | 权限服务 | +| `UserDetailsServiceImpl` | 用户详情服务 | + +### 配置类 + +| 配置类 | 说明 | +|--------|------| +| `SecurityConfig` | Spring Security 配置 | +| `RedisConfig` | Redis 配置 | +| `DruidConfig` | Druid 数据源配置 | +| `MyBatisConfig` | MyBatis 配置 | +| `ThreadPoolConfig` | 线程池配置 | + +### AOP 切面 + +| 切面 | 说明 | +|------|------| +| `LogAspect` | 操作日志记录 | +| `DataScopeAspect` | 数据权限过滤 | +| `DataSourceAspect` | 动态数据源切换 | +| `RateLimiterAspect` | 接口限流 | +| `CostTimeAspect` | 耗时统计 | + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-aop + + + com.alibaba + druid-spring-boot-starter + + + com.jsowell + jsowell-system + + +``` + +--- + +## 常见问题 (FAQ) + +### Q: Token 过期如何处理？ +Token 有效期配置在 `application.yml` 的 `token.expireTime`，默认 1440 分钟 + +### Q: 如何添加接口白名单？ +在 `SecurityConfig` 中配置 `permitAllUrls` 或使用 `@Anonymous` 注解 + +### Q: 数据权限如何配置？ +使用 `@DataScope` 注解，配置 `deptAlias` 和 `userAlias` + +--- + +## 相关文件清单 + +``` +jsowell-framework/ +├── src/main/java/com/jsowell/framework/ +│ ├── aspectj/ # AOP 切面 +│ │ ├── LogAspect.java +│ │ ├── DataScopeAspect.java +│ │ ├── DataSourceAspect.java +│ │ ├── RateLimiterAspect.java +│ │ └── CostTimeAspect.java +│ ├── async/ # 异步处理 +│ ├── config/ # 配置类 +│ │ ├── SecurityConfig.java +│ │ ├── RedisConfig.java +│ │ ├── DruidConfig.java +│ │ ├── MyBatisConfig.java +│ │ └── ThreadPoolConfig.java +│ ├── datasource/ # 动态数据源 +│ ├── interceptor/ # 拦截器 +│ ├── manager/ # 管理器 +│ ├── security/ # 安全相关 +│ │ ├── filter/ +│ │ └── handle/ +│ └── web/ +│ ├── domain/ # 服务器信息 +│ ├── exception/ # 异常处理 +│ └── service/ # 核心服务 +└── pom.xml +``` diff --git a/jsowell-generator/CLAUDE.md b/jsowell-generator/CLAUDE.md new file mode 100644 index 000000000..b92ce6645 --- /dev/null +++ b/jsowell-generator/CLAUDE.md @@ -0,0 +1,127 @@ +[根目录](../CLAUDE.md) > **jsowell-generator** + +# jsowell-generator 模块 + +代码生成器模块，基于 Velocity 模板生成 CRUD 代码。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 13 个 Java 文件 + +--- + +## 模块职责 + +- **代码生成**: 根据数据库表生成 CRUD 代码 +- **模板管理**: Velocity 模板配置 +- **表结构解析**: 数据库表结构读取与解析 + +--- + +## 入口与启动 + +本模块为工具模块，无独立启动入口。 + +--- + +## 对外接口 + +### Controller + +| Controller | 路径 | 说明 | +|------------|------|------| +| `GenController` | `/tool/gen/**` | 代码生成 | + +### Service + +| Service | 说明 | +|---------|------| +| `IGenTableService` | 表信息服务 | +| `IGenTableColumnService` | 列信息服务 | + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + org.apache.velocity + velocity-engine-core + + + com.jsowell + jsowell-common + + +``` + +### 生成配置 + +```java +// GenConfig.java +public class GenConfig { + // 作者、包路径、自动去除表前缀等配置 +} +``` + +--- + +## 数据模型 + +### 核心实体 + +| 实体类 | 数据库表 | 说明 | +|--------|---------|------| +| `GenTable` | `gen_table` | 代码生成表 | +| `GenTableColumn` | `gen_table_column` | 代码生成列 | + +### Mapper XML 文件 + +位置：`src/main/resources/mapper/generator/` + +- `GenTableMapper.xml` (206 行) +- `GenTableColumnMapper.xml` (127 行) + +--- + +## 常见问题 (FAQ) + +### Q: 如何生成代码？ +1. 访问 `/tool/gen` 页面 +2. 导入数据库表 +3. 配置生成选项 +4. 点击生成代码 + +--- + +## 相关文件清单 + +``` +jsowell-generator/ +├── src/main/java/com/jsowell/generator/ +│ ├── config/ # 配置 +│ │ └── GenConfig.java +│ ├── controller/ # 控制器 +│ │ └── GenController.java +│ ├── domain/ # 实体类 +│ │ ├── GenTable.java +│ │ └── GenTableColumn.java +│ ├── mapper/ # Mapper 接口 +│ ├── service/ # Service 接口 +│ │ └── impl/ # Service 实现 +│ └── util/ # 工具类 +│ ├── GenUtils.java +│ ├── VelocityInitializer.java +│ └── VelocityUtils.java +├── src/main/resources/ +│ ├── mapper/generator/ # Mapper XML +│ └── vm/ # Velocity 模板 +└── pom.xml +``` diff --git a/jsowell-netty/CLAUDE.md b/jsowell-netty/CLAUDE.md new file mode 100644 index 000000000..47609f22b --- /dev/null +++ b/jsowell-netty/CLAUDE.md @@ -0,0 +1,218 @@ +[根目录](../CLAUDE.md) > **jsowell-netty** + +# jsowell-netty 模块 + +Netty 通信模块，处理充电桩设备的 TCP/MQTT 协议通信。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别云快充协议处理器 70+ 个 +- 识别电动自行车协议处理器 7 个 + +--- + +## 模块职责 + +- **TCP 服务**: 基于 Netty 的 TCP 服务器，处理充电桩设备连接 +- **MQTT 服务**: MQTT 协议支持 +- **协议解析**: 云快充协议、电动自行车协议解析 +- **消息处理**: 设备登录、心跳、充电控制、数据上报 +- **远程控制**: 远程启停充电、参数配置、固件升级 + +--- + +## 入口与启动 + +### Netty 服务器 + +```java +// NettyServer.java - 云快充 TCP 服务器 +@Component +public class NettyServer { + // 启动 TCP 服务器，监听充电桩连接 +} + +// MqttSever.java - MQTT 服务器 +@Component +public class MqttSever { + // 启动 MQTT 服务器 +} +``` + +### 服务管理 + +```java +// NettyServerManager.java +@Component +public class NettyServerManager { + // 管理多个 Netty 服务器实例 +} +``` + +--- + +## 对外接口 + +### 协议处理器（云快充） + +| Handler | 帧类型 | 说明 | +|---------|--------|------| +| `LoginRequestHandler` | 0x01 | 设备登录 | +| `HeartbeatRequestHandler` | 0x03 | 心跳 | +| `BillingTemplateRequestHandler` | 0x05 | 计费模板请求 | +| `RemoteStartChargingRequestHandler` | 0x33 | 远程启动充电 | +| `RemoteStopChargingRequestHandler` | 0x35 | 远程停止充电 | +| `UploadRealTimeMonitorHandler` | 0x13 | 实时监控数据上报 | +| `ChargeEndHandler` | 0x15 | 充电结束 | +| `ConfirmStartChargingRequestHandler` | 0x17 | 确认启动充电 | + +### 协议处理器（电动自行车） + +| Handler | 说明 | +|---------|------| +| `RegistrationHandler` | 设备注册 | +| `HeartbeatHandler` | 心跳 | +| `SettlementUploadHandler` | 结算上报 | +| `PowerHeartbeatHandler` | 电源心跳 | + +### 业务服务 + +```java +// YKCBusinessService.java - 云快充业务服务 +public interface YKCBusinessService { + void handleLogin(LoginRequestData data); + void handleHeartbeat(HeartbeatData data); + void handleChargeEnd(TransactionRecordsData data); + // ... +} + +// EBikeBusinessService.java - 电动自行车业务服务 +public interface EBikeBusinessService { + void handleRegistration(RegistrationData data); + void handleSettlement(SettlementData data); + // ... +} +``` + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + io.netty + netty-all + 4.1.75.Final + + + io.netty + netty-codec-mqtt + 4.1.79.Final + + + com.jsowell + jsowell-pile + + + com.jsowell + jsowell-thirdparty + + +``` + +--- + +## 数据模型 + +### 协议数据结构 + +| 类 | 说明 | +|-----|------| +| `YKCDataProtocol` | 云快充协议数据 | +| `YKCBaseMessage` | 基础消息 | +| `LoginRequestData` | 登录请求数据 | +| `RealTimeMonitorData` | 实时监控数据 | +| `TransactionRecordsData` | 交易记录数据 | +| `EBikeDataProtocol` | 电动自行车协议数据 | + +### 帧类型码 + +定义在 `YKCFrameTypeCode.java`： +- `0x01/0x02` - 登录请求/响应 +- `0x03/0x04` - 心跳请求/响应 +- `0x13/0x14` - 实时数据上报/响应 +- `0x15/0x16` - 充电结束上报/响应 +- `0x33/0x34` - 远程启动/响应 +- `0x35/0x36` - 远程停止/响应 + +--- + +## 测试与质量 + +### 测试客户端 + +```java +// TestNettyClient.java +public class TestNettyClient { + // 用于测试 Netty 服务器的客户端 +} +``` + +--- + +## 常见问题 (FAQ) + +### Q: 设备无法连接？ +1. 检查 TCP 端口是否开放 +2. 检查设备 SN 是否已注册 +3. 查看 `YKCBusinessServiceImpl.handleLogin()` 日志 + +### Q: 充电无法启动？ +1. 检查设备在线状态 +2. 检查充电枪状态 +3. 查看 `RemoteStartChargingRequestHandler` 处理逻辑 + +### Q: 实时数据不更新？ +1. 检查心跳是否正常 +2. 检查 `UploadRealTimeMonitorHandler` 处理 +3. 查看 RabbitMQ 消息队列状态 + +--- + +## 相关文件清单 + +``` +jsowell-netty/ +├── src/main/java/com/jsowell/netty/ +│ ├── client/ # Netty 客户端 +│ ├── decoder/ # 协议解码器 +│ │ ├── YkcProtocolDecoder.java +│ │ ├── YouDianProtocolDecoder.java +│ │ └── YunKuaiChongDecoder.java +│ ├── domain/ # 数据模型 +│ ├── factory/ # 处理器工厂 +│ │ ├── YKCOperateFactory.java +│ │ └── EBikeOperateFactory.java +│ ├── handler/ # 消息处理器 +│ │ ├── yunkuaichong/ # 云快充处理器 (70+) +│ │ └── electricbicycles/ # 电动自行车处理器 +│ ├── server/ # Netty 服务器 +│ │ ├── yunkuaichong/ # 云快充服务器 +│ │ ├── electricbicycles/ # 电动自行车服务器 +│ │ └── mqtt/ # MQTT 服务器 +│ ├── service/ # 业务服务 +│ │ ├── yunkuaichong/ +│ │ ├── electricbicycles/ +│ │ ├── camera/ +│ │ └── rabbitmq/ # RabbitMQ 监听 +│ └── strategy/ # 策略模式 +│ └── ykc/ # 云快充策略 +└── pom.xml +``` diff --git a/jsowell-pile/CLAUDE.md b/jsowell-pile/CLAUDE.md new file mode 100644 index 000000000..6c795e86b --- /dev/null +++ b/jsowell-pile/CLAUDE.md @@ -0,0 +1,184 @@ +[根目录](../CLAUDE.md) > **jsowell-pile** + +# jsowell-pile 模块 + +充电桩业务核心模块，包含订单、会员、计费、支付等核心业务逻辑。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 80 个 Service 实现类 +- 统计 60+ Mapper XML 文件 + +--- + +## 模块职责 + +- **订单管理**: 充电订单创建、结算、分账、退款 +- **会员服务**: 会员注册、钱包管理、积分系统 +- **计费管理**: 计费模板、时段电价、服务费 +- **支付集成**: 微信支付、支付宝、汇付支付（Adapay） +- **设备管理**: 充电桩、充电枪、站点信息 +- **商户管理**: 商户信息、分账配置、清算账单 + +--- + +## 入口与启动 + +本模块为业务模块，无独立启动入口，由 `jsowell-admin` 模块引用。 + +### 核心 Service + +| Service | 说明 | +|---------|------| +| `OrderBasicInfoServiceImpl` | 订单核心服务（创建、结算、分账） | +| `MemberBasicInfoServiceImpl` | 会员服务 | +| `MemberWalletInfoServiceImpl` | 钱包服务 | +| `MemberPointsInfoServiceImpl` | 积分服务 | +| `PileStationInfoServiceImpl` | 站点服务 | +| `PileBasicInfoServiceImpl` | 充电桩服务 | +| `PileConnectorInfoServiceImpl` | 充电枪服务 | +| `PileBillingTemplateServiceImpl` | 计费模板服务 | +| `WechatPayServiceImpl` | 微信支付服务 | +| `AdapayService` | 汇付支付服务 | + +--- + +## 对外接口 + +### RPC 服务 + +```java +// WccServiceImpl.java - Dubbo RPC 服务 +@DubboService +public class WccServiceImpl implements WccService { + // 提供给其他服务调用的接口 +} +``` + +### RabbitMQ 消费者 + +```java +// OrderRabbitListener.java +@RabbitListener(queues = RabbitConstants.ORDER_QUEUE) +public void handleOrderMessage(Message message) { + // 处理订单消息 +} +``` + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + com.jsowell + jsowell-framework + + + com.baomidou + mybatis-plus-boot-starter + 3.4.0 + + + com.huifu.adapay + adapay-java-sdk + + + com.alipay.sdk + alipay-sdk-java + + +``` + +--- + +## 数据模型 + +### 核心实体 + +| 实体类 | 数据库表 | 说明 | +|--------|---------|------| +| `OrderBasicInfo` | `order_basic_info` | 充电订单 | +| `OrderPayRecord` | `order_pay_record` | 支付记录 | +| `OrderSplitRecord` | `order_split_record` | 分账记录 | +| `MemberBasicInfo` | `member_basic_info` | 会员信息 | +| `MemberWalletInfo` | `member_wallet_info` | 会员钱包 | +| `MemberPointsInfo` | `member_points_info` | 会员积分 | +| `PileStationInfo` | `pile_station_info` | 充电站 | +| `PileBasicInfo` | `pile_basic_info` | 充电桩 | +| `PileConnectorInfo` | `pile_connector_info` | 充电枪 | +| `PileBillingTemplate` | `pile_billing_template` | 计费模板 | +| `PileMerchantInfo` | `pile_merchant_info` | 商户信息 | +| `ClearingBillInfo` | `clearing_bill_info` | 清算账单 | + +### Mapper XML 文件 + +位置：`src/main/resources/mapper/pile/` + +主要文件： +- `OrderBasicInfoMapper.xml` (3620 行) +- `PileMerchantInfoMapper.xml` (1304 行) +- `PersonalChargingRecordMapper.xml` (1413 行) +- `OrderDetailMapper.xml` (1306 行) +- `OrderPileOccupyMapper.xml` (1043 行) + +--- + +## 测试与质量 + +### 单元测试 + +测试位于 `jsowell-admin/src/test/java/`，涉及本模块的测试： +- `OrderServiceWhitelistCompletionTest` +- `WhitelistOrderCompletionDefaultsTest` + +--- + +## 常见问题 (FAQ) + +### Q: 订单分账失败如何处理？ +检查 `OrderBasicInfoServiceImpl.realTimeOrderSplit()` 方法，查看分账配置和汇付账户状态 + +### Q: 积分发放延迟？ +积分通过 RabbitMQ 异步发放，检查 `PointsRabbitConfig` 配置和消息队列状态 + +### Q: 支付回调未收到？ +检查支付平台回调地址配置，查看 `WxpayCallbackRecord` 或 `AdapayCallbackRecord` 表 + +--- + +## 相关文件清单 + +``` +jsowell-pile/ +├── src/main/java/com/jsowell/ +│ ├── adapay/ # 汇付支付 +│ │ ├── config/ # 支付配置 +│ │ ├── dto/ # 数据传输对象 +│ │ ├── service/ # 支付服务 +│ │ └── vo/ # 视图对象 +│ ├── alipay/ # 支付宝 +│ ├── wxpay/ # 微信支付 +│ ├── mq/ # RabbitMQ 消费者 +│ ├── pile/ +│ │ ├── domain/ # 实体类 +│ │ ├── dto/ # DTO +│ │ ├── mapper/ # Mapper 接口 +│ │ ├── service/ # Service 接口 +│ │ │ └── impl/ # Service 实现 +│ │ ├── vo/ # VO +│ │ ├── jcpp/ # JCPP 协议 +│ │ ├── rpc/ # RPC 服务 +│ │ └── transaction/ # 事务服务 +│ └── thirdparty/ # 第三方服务 +├── src/main/resources/ +│ └── mapper/pile/ # Mapper XML (60+ 文件) +└── src/main/proto/ # Protobuf 定义 +``` diff --git a/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/BusinessFinancialServiceImpl.java b/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/BusinessFinancialServiceImpl.java index 0f4e558c6..23e007588 100644 --- a/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/BusinessFinancialServiceImpl.java +++ b/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/BusinessFinancialServiceImpl.java @@ -42,15 +42,20 @@ public class BusinessFinancialServiceImpl implements BusinessFinancialService { // 查询账户余额 BigDecimal acctBalance = BigDecimal.ZERO; + BigDecimal pendingAmount = BigDecimal.ZERO; try { AdapayAccountBalanceVO accountBalanceVO = adapayService.queryAdapayAccountBalance(dto.getMerchantId()); if (accountBalanceVO != null && accountBalanceVO.getAcctBalance() != null) { acctBalance = accountBalanceVO.getAcctBalance(); } + if (accountBalanceVO != null && accountBalanceVO.getPendingAmount() != null) { + pendingAmount = accountBalanceVO.getPendingAmount(); + } } catch (BaseAdaPayException e) { log.error("查询汇付账户余额异常 merchantId:{}", dto.getMerchantId(), e); } result.getMerchantOrderReport().setAcctBalance(acctBalance); + result.getMerchantOrderReport().setPendingAmount(pendingAmount); // 查询累计提现金额 BigDecimal totalWithdraw = BigDecimal.ZERO; diff --git a/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java b/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java index 202ec196f..e02d765f6 100644 --- a/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java +++ b/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java @@ -4,6 +4,7 @@ import com.alibaba.fastjson2.JSON; import com.alibaba.fastjson2.JSONObject; import com.github.pagehelper.PageHelper; import com.github.pagehelper.PageInfo; +import com.google.common.collect.ImmutableMap; import com.google.common.collect.Lists; import com.google.common.collect.Maps; import com.google.common.collect.Sets; @@ -68,7 +69,6 @@ import com.jsowell.pile.vo.uniapp.business.BusinessOrderListVO; import com.jsowell.pile.vo.uniapp.business.BusinessOrderQueryResultVO; import com.jsowell.pile.vo.uniapp.customer.*; import com.jsowell.pile.vo.web.*; -import com.jsowell.pile.vo.web.OrderStatisticsVO; import com.jsowell.wxpay.common.WeChatPayParameter; import com.jsowell.wxpay.response.WechatPayRefundRequest; import com.jsowell.wxpay.response.WechatPayRefundResponse; @@ -295,6 +295,9 @@ public class OrderBasicInfoServiceImpl implements OrderBasicInfoService { } dto.setStationDeptIds(authorizedMap.getStationDeptIds()); dto.setMerchantDeptIds(authorizedMap.getMerchantDeptIds()); + if (Objects.nonNull(SecurityUtils.getLoginUser())) { + dto.setParams(ImmutableMap.of("roleId", SecurityUtils.getLoginUser().getUserId())); + } return selectOrderBasicInfoList(dto); } diff --git a/jsowell-pile/src/main/java/com/jsowell/pile/util/UserUtils.java b/jsowell-pile/src/main/java/com/jsowell/pile/util/UserUtils.java index d254a3d8f..31cf7a9d0 100644 --- a/jsowell-pile/src/main/java/com/jsowell/pile/util/UserUtils.java +++ b/jsowell-pile/src/main/java/com/jsowell/pile/util/UserUtils.java @@ -107,6 +107,7 @@ public class UserUtils { if (Objects.isNull(loginUser)) { return resultVO; } + resultVO.setLoginUser(loginUser); // 获取登录用户对应的user对象 SysUser user = loginUser.getUser(); if (Objects.isNull(user)) { diff --git a/jsowell-pile/src/main/java/com/jsowell/pile/vo/base/LoginUserDetailVO.java b/jsowell-pile/src/main/java/com/jsowell/pile/vo/base/LoginUserDetailVO.java index 0873bf8e3..902170d89 100644 --- a/jsowell-pile/src/main/java/com/jsowell/pile/vo/base/LoginUserDetailVO.java +++ b/jsowell-pile/src/main/java/com/jsowell/pile/vo/base/LoginUserDetailVO.java @@ -1,5 +1,6 @@ package com.jsowell.pile.vo.base; +import com.jsowell.common.core.domain.model.LoginUser; import lombok.Getter; import lombok.Setter; @@ -11,6 +12,10 @@ import java.util.List; @Getter @Setter public class LoginUserDetailVO { + /** + * 登录用户 + */ + LoginUser loginUser; /** * 有权限的一级运营商idList * 平台级账号有多个一级运营商权限 diff --git a/jsowell-pile/src/main/java/com/jsowell/pile/vo/web/OrderReportDetail.java b/jsowell-pile/src/main/java/com/jsowell/pile/vo/web/OrderReportDetail.java index 3d61fd276..8d10a1398 100644 --- a/jsowell-pile/src/main/java/com/jsowell/pile/vo/web/OrderReportDetail.java +++ b/jsowell-pile/src/main/java/com/jsowell/pile/vo/web/OrderReportDetail.java @@ -52,4 +52,7 @@ public class OrderReportDetail { */ private BigDecimal totalWithdraw; + // 在途金额 + private BigDecimal pendingAmount; + } diff --git a/jsowell-pile/src/main/resources/mapper/pile/OrderBasicInfoMapper.xml b/jsowell-pile/src/main/resources/mapper/pile/OrderBasicInfoMapper.xml index cc1675c2b..4a0a2f552 100644 --- a/jsowell-pile/src/main/resources/mapper/pile/OrderBasicInfoMapper.xml +++ b/jsowell-pile/src/main/resources/mapper/pile/OrderBasicInfoMapper.xml @@ -2004,6 +2004,9 @@ and t1.vin_code = #{vinCode,jdbcType=VARCHAR} + + and t1.review_flag = '1' + and t1.plate_number = #{plateNumber,jdbcType=VARCHAR} @@ -2055,6 +2058,9 @@ and t1.create_time #{endTime,jdbcType=VARCHAR} + + and t1.review_flag = '1' + and t1.settlement_time = ]]> #{startSettleTime,jdbcType=VARCHAR} diff --git a/jsowell-quartz/CLAUDE.md b/jsowell-quartz/CLAUDE.md new file mode 100644 index 000000000..b3b86e8aa --- /dev/null +++ b/jsowell-quartz/CLAUDE.md @@ -0,0 +1,137 @@ +[根目录](../CLAUDE.md) > **jsowell-quartz** + +# jsowell-quartz 模块 + +定时任务模块，基于 Quartz 实现任务调度。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 19 个 Java 文件 + +--- + +## 模块职责 + +- **任务管理**: 定时任务 CRUD +- **任务调度**: Quartz 调度器配置 +- **任务执行**: 任务执行与日志记录 +- **业务任务**: 充电桩业务相关定时任务 + +--- + +## 入口与启动 + +本模块为功能模块，无独立启动入口。 + +--- + +## 对外接口 + +### Controller + +| Controller | 路径 | 说明 | +|------------|------|------| +| `SysJobController` | `/monitor/job/**` | 任务管理 | +| `SysJobLogController` | `/monitor/jobLog/**` | 任务日志 | + +### Service + +| Service | 说明 | +|---------|------| +| `ISysJobService` | 任务服务 | +| `ISysJobLogService` | 任务日志服务 | + +### 业务任务 + +```java +// JsowellTask.java +@Component("jsowellTask") +public class JsowellTask { + // 充电桩业务相关定时任务 +} + +// RyTask.java +@Component("ryTask") +public class RyTask { + // 示例任务 +} +``` + +--- + +## 关键依赖与配置 + +### Quartz 配置 + +```java +// ScheduleConfig.java +@Configuration +public class ScheduleConfig { + // Quartz 调度器配置 +} +``` + +--- + +## 数据模型 + +### 核心实体 + +| 实体类 | 数据库表 | 说明 | +|--------|---------|------| +| `SysJob` | `sys_job` | 定时任务 | +| `SysJobLog` | `sys_job_log` | 任务日志 | + +### Mapper XML 文件 + +位置：`src/main/resources/mapper/quartz/` + +- `SysJobMapper.xml` (111 行) +- `SysJobLogMapper.xml` (94 行) + +--- + +## 常见问题 (FAQ) + +### Q: 如何添加新的定时任务？ +1. 创建任务类，使用 `@Component` 注解 +2. 在管理后台添加任务配置 +3. 调用目标字符串格式：`beanName.methodName(params)` + +### Q: 任务执行失败如何排查？ +查看 `sys_job_log` 表的执行日志和异常信息 + +--- + +## 相关文件清单 + +``` +jsowell-quartz/ +├── src/main/java/com/jsowell/quartz/ +│ ├── config/ # Quartz 配置 +│ │ └── ScheduleConfig.java +│ ├── controller/ # 控制器 +│ │ ├── SysJobController.java +│ │ └── SysJobLogController.java +│ ├── domain/ # 实体类 +│ │ ├── SysJob.java +│ │ └── SysJobLog.java +│ ├── mapper/ # Mapper 接口 +│ ├── service/ # Service 接口 +│ │ └── impl/ # Service 实现 +│ ├── task/ # 业务任务 +│ │ ├── JsowellTask.java +│ │ └── RyTask.java +│ └── util/ # 工具类 +│ ├── AbstractQuartzJob.java +│ ├── CronUtils.java +│ ├── JobInvokeUtil.java +│ └── ScheduleUtils.java +├── src/main/resources/ +│ └── mapper/quartz/ # Mapper XML +└── pom.xml +``` diff --git a/jsowell-settlement/CLAUDE.md b/jsowell-settlement/CLAUDE.md new file mode 100644 index 000000000..5d1e5f170 --- /dev/null +++ b/jsowell-settlement/CLAUDE.md @@ -0,0 +1,61 @@ +[根目录](../CLAUDE.md) > **jsowell-settlement** + +# jsowell-settlement 模块 + +结算模块，处理商户结算相关业务（待完善）。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 模块状态：待完善 + +--- + +## 模块职责 + +- **商户结算**: 商户账单结算 +- **清算处理**: 清算账单生成 + +--- + +## 入口与启动 + +本模块为业务模块，无独立启动入口。 + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + com.jsowell + jsowell-pile + + +``` + +--- + +## 模块状态 + +当前模块处于待完善状态，主要业务逻辑在 `jsowell-pile` 模块中实现： +- `ClearingBillInfoServiceImpl` - 清算账单服务 +- `ClearingBillDetailServiceImpl` - 清算明细服务 +- `ClearingWithdrawInfoServiceImpl` - 提现服务 + +--- + +## 相关文件清单 + +``` +jsowell-settlement/ +├── src/main/resources/ +│ └── rebel.xml # JRebel 配置 +└── pom.xml +``` diff --git a/jsowell-system/CLAUDE.md b/jsowell-system/CLAUDE.md new file mode 100644 index 000000000..59ae46124 --- /dev/null +++ b/jsowell-system/CLAUDE.md @@ -0,0 +1,146 @@ +[根目录](../CLAUDE.md) > **jsowell-system** + +# jsowell-system 模块 + +系统管理模块，提供用户、角色、菜单、字典等基础管理功能。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 15 个 Mapper XML +- 统计 52 个 Java 文件 + +--- + +## 模块职责 + +- **用户管理**: 用户 CRUD、密码管理 +- **角色管理**: 角色 CRUD、权限分配 +- **菜单管理**: 菜单 CRUD、路由生成 +- **部门管理**: 组织架构管理 +- **字典管理**: 数据字典维护 +- **岗位管理**: 岗位信息管理 +- **日志管理**: 操作日志、登录日志 + +--- + +## 入口与启动 + +本模块为基础模块，无独立启动入口。 + +--- + +## 对外接口 + +### Service 接口 + +| Service | 说明 | +|---------|------| +| `SysUserService` | 用户服务 | +| `SysRoleService` | 角色服务 | +| `SysMenuService` | 菜单服务 | +| `SysDeptService` | 部门服务 | +| `SysDictTypeService` | 字典类型服务 | +| `SysDictDataService` | 字典数据服务 | +| `SysPostService` | 岗位服务 | +| `SysConfigService` | 系统配置服务 | +| `SysOperLogService` | 操作日志服务 | +| `SysLogininforService` | 登录日志服务 | + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + com.jsowell + jsowell-common + + +``` + +--- + +## 数据模型 + +### 核心实体 + +| 实体类 | 数据库表 | 说明 | +|--------|---------|------| +| `SysUser` | `sys_user` | 用户信息 | +| `SysRole` | `sys_role` | 角色信息 | +| `SysMenu` | `sys_menu` | 菜单信息 | +| `SysDept` | `sys_dept` | 部门信息 | +| `SysDictType` | `sys_dict_type` | 字典类型 | +| `SysDictData` | `sys_dict_data` | 字典数据 | +| `SysPost` | `sys_post` | 岗位信息 | +| `SysConfig` | `sys_config` | 系统配置 | +| `SysOperLog` | `sys_oper_log` | 操作日志 | +| `SysLogininfor` | `sys_logininfor` | 登录日志 | + +### 关联表 + +| 实体类 | 数据库表 | 说明 | +|--------|---------|------| +| `SysUserRole` | `sys_user_role` | 用户角色关联 | +| `SysRoleMenu` | `sys_role_menu` | 角色菜单关联 | +| `SysRoleDept` | `sys_role_dept` | 角色部门关联 | +| `SysUserPost` | `sys_user_post` | 用户岗位关联 | + +### Mapper XML 文件 + +位置：`src/main/resources/mapper/system/` + +- `SysUserMapper.xml` (228 行) +- `SysMenuMapper.xml` (195 行) +- `SysDeptMapper.xml` (163 行) +- `SysRoleMapper.xml` (152 行) +- `SysDictDataMapper.xml` (124 行) +- `SysPostMapper.xml` (122 行) +- `SysConfigMapper.xml` (112 行) +- `SysDictTypeMapper.xml` (105 行) + +--- + +## 常见问题 (FAQ) + +### Q: 如何添加新的系统配置？ +在 `sys_config` 表中添加记录，通过 `SysConfigService.selectConfigByKey()` 获取 + +### Q: 如何添加新的字典？ +1. 在 `sys_dict_type` 添加字典类型 +2. 在 `sys_dict_data` 添加字典数据 + +--- + +## 相关文件清单 + +``` +jsowell-system/ +├── src/main/java/com/jsowell/system/ +│ ├── domain/ # 实体类 +│ │ ├── SysCache.java +│ │ ├── SysConfig.java +│ │ ├── SysLogininfor.java +│ │ ├── SysNotice.java +│ │ ├── SysOperLog.java +│ │ ├── SysPost.java +│ │ ├── SysRoleDept.java +│ │ ├── SysRoleMenu.java +│ │ ├── SysUserOnline.java +│ │ ├── SysUserPost.java +│ │ └── SysUserRole.java +│ ├── mapper/ # Mapper 接口 +│ ├── service/ # Service 接口 +│ │ └── impl/ # Service 实现 +│ └── vo/ # 视图对象 +├── src/main/resources/ +│ └── mapper/system/ # Mapper XML (15 文件) +└── pom.xml +``` diff --git a/jsowell-thirdparty/CLAUDE.md b/jsowell-thirdparty/CLAUDE.md new file mode 100644 index 000000000..9c9057cf5 --- /dev/null +++ b/jsowell-thirdparty/CLAUDE.md @@ -0,0 +1,135 @@ +[根目录](../CLAUDE.md) > **jsowell-thirdparty** + +# jsowell-thirdparty 模块 + +第三方平台对接模块，负责与外部系统的集成。 + +--- + +## 变更记录 (Changelog) + +### 2026-02-03 11:32:30 +- 初始化模块文档 +- 识别 20+ 第三方平台对接 + +--- + +## 模块职责 + +- **政府平台对接**: 中电联、南瑞、各省市监管平台 +- **地图服务**: 高德地图站点推送 +- **停车场系统**: 停车场优惠券、车牌识别 +- **支付通知**: 第三方平台订单通知 +- **数据同步**: 站点、设备、订单数据同步 + +--- + +## 入口与启动 + +本模块为业务模块，无独立启动入口。 + +--- + +## 对外接口 + +### 第三方平台服务 + +| 服务 | 说明 | +|------|------| +| `ZDLService` | 中电联平台对接 | +| `NRService` | 南瑞平台对接 | +| `AMapService` | 高德地图服务 | +| `LianLianService` | 联联平台 | +| `HuaWeiService` | 华为平台 | +| `NXJTService` | 宁夏交投平台 | +| `LTYTService` | 停车场服务 | +| `RJService` | 停车场服务 | +| `QcyunsService` | 停车场服务 | + +### 平台工厂 + +```java +// ThirdPartyPlatformFactory.java +public class ThirdPartyPlatformFactory { + // 根据平台类型获取对应的服务实现 +} +``` + +--- + +## 关键依赖与配置 + +### Maven 依赖 + +```xml + + + com.jsowell + jsowell-pile + + +``` + +--- + +## 数据模型 + +### 平台通用数据结构 + +| 类 | 说明 | +|-----|------| +| `StationInfo` | 站点信息 | +| `ConnectorStatusInfo` | 充电枪状态 | +| `ChargeOrderInfo` | 充电订单 | +| `AlarmInfo` | 告警信息 | + +### 高德地图数据 + +| 类 | 说明 | +|-----|------| +| `AMapStationInfo` | 高德站点信息 | +| `AMapEquipmentInfo` | 高德设备信息 | +| `AMapConnectorInfo` | 高德充电枪信息 | +| `AMapPriceChargingInfo` | 高德计费信息 | + +--- + +## 常见问题 (FAQ) + +### Q: 第三方平台数据同步失败？ +1. 检查平台配置（`ThirdPartyPlatformConfig`） +2. 检查密钥配置（`ThirdpartySecretInfo`） +3. 查看同步日志 + +### Q: 高德地图站点不显示？ +1. 检查站点是否已推送 +2. 检查站点状态是否正常 +3. 查看 `AMapService` 调用日志 + +--- + +## 相关文件清单 + +``` +jsowell-thirdparty/ +├── src/main/java/com/jsowell/thirdparty/ +│ ├── amap/ # 高德地图 +│ │ ├── domain/ +│ │ ├── service/ +│ │ └── util/ +│ ├── camera/ # 摄像头 +│ ├── common/ # 通用服务 +│ ├── huawei/ # 华为平台 +│ ├── lianlian/ # 联联平台 +│ ├── nanrui/ # 南瑞平台 +│ ├── ningxiajiaotou/ # 宁夏交投 +│ ├── parking/ # 停车场 +│ ├── platform/ # 平台通用 +│ │ ├── common/ +│ │ ├── domain/ +│ │ ├── factory/ +│ │ └── service/ +│ ├── yongchengboche/ # 永城泊车 +│ └── zhongdianlian/ # 中电联 +└── pom.xml +```