jsowell-charger-web/jsowell-netty/CLAUDE.md

[根目录](../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
<dependencies>
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-all</artifactId>
        <version>4.1.75.Final</version>
    </dependency>
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-codec-mqtt</artifactId>
        <version>4.1.79.Final</version>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-pile</artifactId>
    </dependency>
    <dependency>
        <groupId>com.jsowell</groupId>
        <artifactId>jsowell-thirdparty</artifactId>
    </dependency>
</dependencies>
```

---

## 数据模型

### 协议数据结构

| 类 | 说明 |
|-----|------|
| `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
```