diff --git a/CLAUDE.md b/CLAUDE.md index ea15c3044..1168ef817 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,40 +41,291 @@ jsowell-charger-web/ - `jsowell-netty` 依赖 `jsowell-pile`、`jsowell-thirdparty`(设备通信) - `jsowell-framework` 依赖 `jsowell-system`、`jsowell-common`(基础框架) -## 核心业务流程 +--- -### 充电桩通信架构 +## 核心业务功能 -系统通过 Netty 实现与充电桩设备的实时通信: +### 1. 会员管理 -1. **TCP 服务器**:`jsowell-netty` 模块启动 TCP 服务器监听充电桩连接 -2. **协议处理**: - - 云快充协议:`com.jsowell.netty.handler.yunkuaichong.*Handler`(50+ 个处理器) - - 电动自行车协议:`com.jsowell.netty.handler.electricbicycles.*Handler` -3. **MQTT 支持**:`BootNettyMqttChannelInboundHandler` 处理 MQTT 协议 -4. **业务服务**: - - `YKCBusinessService`:云快充业务逻辑 - - `EBikeBusinessService`:电动自行车业务逻辑 - - `CameraBusinessService`:摄像头业务逻辑 +#### 1.1 会员基本信息 +- **实体类**:`MemberBasicInfo` +- **服务类**:`MemberBasicInfoService` +- **数据表**:`member_basic_info` +- **功能**:会员注册、信息维护、实名认证、车牌绑定 -### 支付与结算流程 +#### 1.2 会员钱包 +- **实体类**:`MemberWalletInfo`、`MemberWalletLog` +- **服务类**:`MemberWalletInfoService`、`MemberWalletLogService` +- **数据表**:`member_wallet_info`、`member_wallet_log` +- **功能**: + - 余额管理(本金余额、赠金余额) + - 充值记录 + - 消费记录 + - 退款处理 -支持多种支付方式: -- **微信支付**:`WechatPayService`(V3 API) -- **支付宝支付**:`AliAppletRemoteService` -- **汇付支付**:`AdapayMemberAccountService` +#### 1.3 会员积分系统 +- **实体类**:`MemberPointsInfo`、`MemberPointsRecord` +- **服务类**:`MemberPointsInfoService`、`MemberPointsRecordService` +- **数据表**:`member_points_info`、`member_points_record` +- **Controller**:`MemberPointsInfoController`(路径:`/points`) -结算相关: -- 订单分账:`OrderSplitRecordService` -- 清算账单:`ClearingBillInfoService` -- 商户结算:`SettleOrderReportService` +**积分规则**: +- 积分类型:`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` | -`jsowell-thirdparty` 模块对接多个第三方平台: -- **高德地图**:`AMapService`(充电站信息同步) -- **停车场系统**:`QcyunsService`、`LTYTService`、`RJService` -- **充电平台**:`ZDLService`(中电联)、`NRService`(南瑞)、`XDTService`(新电途) +**积分相关类**: +- 消息实体:`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` +- **功能**: + - 刷卡充电授权 + - 卡号与会员绑定 + - 卡片状态管理 + +--- ## 常用开发命令 @@ -122,6 +373,8 @@ mvn test - 协议:dubbo(动态端口) - API 定义:`charge-common-api` 模块 +--- + ## 代码规范 ### 包结构约定 @@ -134,7 +387,11 @@ com.jsowell.{module}/ ├── mapper/ # MyBatis Mapper 接口 ├── domain/ # 实体类(对应数据库表) ├── dto/ # 数据传输对象 -└── vo/ # 视图对象 +├── vo/ # 视图对象 +├── enums/ # 枚举类 +└── mq/ # 消息队列相关 + ├── producer/ # 消息生产者 + └── consumer/ # 消息消费者 ``` ### 命名规范 @@ -150,9 +407,23 @@ com.jsowell.{module}/ - **权限控制**:`@PreAuthorize("@ss.hasPermi('system:user:list')")` - **日志记录**:`@Log(title = "用户管理", businessType = BusinessType.INSERT)` - **数据权限**:`@DataScope(deptAlias = "d", userAlias = "u")` +- **事务管理**:`@Transactional(rollbackFor = Exception.class)` + +--- ## 关键配置说明 +### RabbitMQ 配置 + +**配置类**:`RabbitConfig`、`PointsRabbitConfig` +**常量类**:`RabbitConstants` + +**配置特点**: +- 消息序列化:`Jackson2JsonMessageConverter` +- 应答模式:自动应答(2024年12月26日改为自动) +- 重试机制:指数退避策略 +- 并发消费者:1-20 + ### Netty 服务器配置 Netty 服务器在 `jsowell-netty` 模块中配置,支持: @@ -181,6 +452,50 @@ Netty 服务器在 `jsowell-netty` 模块中配置,支持: - **阿里云 OSS**:配置在 `aliyunoss` 节点 - **Minio**:可选的对象存储方案 +--- + +## 数据库表结构 + +### 会员相关表 +| 表名 | 说明 | +|------|------| +| `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` | 分账记录 | + +### 结算相关表 +| 表名 | 说明 | +|------|------| +| `station_split_config` | 分账配置 | +| `clearing_bill_info` | 清算账单 | +| `clearing_bill_detail` | 清算明细 | +| `settle_order_report` | 结算报表 | + +--- + ## 测试说明 测试文件位置:`jsowell-admin/src/test/java/` @@ -189,6 +504,8 @@ Netty 服务器在 `jsowell-netty` 模块中配置,支持: - `SpringBootTestController.java`:Spring Boot 集成测试 - `PaymentTestController.java`:支付功能测试 +--- + ## 监控与运维 ### Prometheus 监控 @@ -207,15 +524,20 @@ Netty 服务器在 `jsowell-netty` 模块中配置,支持: - 开发环境访问:`http://localhost:8080/swagger-ui/` - 配置:`swagger.enabled=true` +--- + ## 注意事项 1. **数据库连接**:使用 Druid 连接池,主从分离配置在 `application-{env}.yml` 2. **事务管理**:使用 `@Transactional` 注解,注意事务传播行为 -3. **异步处理**:RabbitMQ 配置手动确认模式(`acknowledge-mode: manual`) +3. **异步处理**:RabbitMQ 已改为自动应答模式 4. **Netty 线程模型**:注意 EventLoop 线程安全,避免阻塞操作 5. **Dubbo 服务**:启动时不检查提供者(`consumer.check=false`) 6. **日志级别**:开发环境 `com.jsowell: debug`,生产环境建议 `info` 7. **热部署**:开发环境启用 `spring.devtools.restart.enabled=true` +8. **积分发放**:通过 RabbitMQ 异步处理,避免影响订单结算主流程 + +--- ## 启动类