From 80f53d9f510d70df063720e6d624384a963f1455 Mon Sep 17 00:00:00 2001 From: Guoqs <123456@jsowell.com> Date: Tue, 3 Feb 2026 14:20:30 +0800 Subject: [PATCH] update claude.md --- CLAUDE.md | 10 +- jsowell-admin/CLAUDE.md | 187 ++++++++++++++++++++++++++++++ jsowell-common/CLAUDE.md | 171 +++++++++++++++++++++++++++ jsowell-framework/CLAUDE.md | 137 ++++++++++++++++++++++ jsowell-generator/CLAUDE.md | 127 ++++++++++++++++++++ jsowell-netty/CLAUDE.md | 218 +++++++++++++++++++++++++++++++++++ jsowell-pile/CLAUDE.md | 184 +++++++++++++++++++++++++++++ jsowell-quartz/CLAUDE.md | 137 ++++++++++++++++++++++ jsowell-settlement/CLAUDE.md | 61 ++++++++++ jsowell-system/CLAUDE.md | 146 +++++++++++++++++++++++ jsowell-thirdparty/CLAUDE.md | 135 ++++++++++++++++++++++ 11 files changed, 1512 insertions(+), 1 deletion(-) create mode 100644 jsowell-admin/CLAUDE.md create mode 100644 jsowell-common/CLAUDE.md create mode 100644 jsowell-framework/CLAUDE.md create mode 100644 jsowell-generator/CLAUDE.md create mode 100644 jsowell-netty/CLAUDE.md create mode 100644 jsowell-pile/CLAUDE.md create mode 100644 jsowell-quartz/CLAUDE.md create mode 100644 jsowell-settlement/CLAUDE.md create mode 100644 jsowell-system/CLAUDE.md create mode 100644 jsowell-thirdparty/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md index 7f80bdbfe..128b225d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 变更记录 (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 个模块） @@ -428,6 +436,6 @@ com.jsowell.{module}/ - 主分支: `master` - 开发分支: `dev`（当前分支） - **最近提交**: + - `543f989ff` - update CLAUDE.md - `7c576ca25` - bugfix 查询订单详情字段为空 - `c1db659cc` - update - - `5ffb8826f` - 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-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-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 +```