mirror of https://gitee.com/san-bing/JChargePointProtocol synced 2026-07-17 12:17:53 +08:00

Files

三丙 fa9524d302 wiki生成

2025-10-28 14:39:06 +08:00

19 KiB

Raw Blame History

云快充协议下行消息处理链路

**本文档引用的文件** - [DownlinkController.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/adapter/DownlinkController.java) - [DownlinkGrpcService.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/adapter/DownlinkGrpcService.java) - [YunKuaiChongDownlinkCmdExe.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/YunKuaiChongDownlinkCmdExe.java) - [YunKuaiChongDownlinkCmdConverter.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/mapping/YunKuaiChongDownlinkCmdConverter.java) - [YunKuaiChongV150RemoteStartDLCmd.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/cmd/YunKuaiChongV150RemoteStartDLCmd.java) - [YunKuaiChongProtocolMessageProcessor.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/YunKuaiChongProtocolMessageProcessor.java) - [AbstractYunKuaiChongCmdExe.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/AbstractYunKuaiChongCmdExe.java) - [ProtocolSession.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/domain/ProtocolSession.java) - [TcpChannelHandler.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/tcp/TcpChannelHandler.java) - [DownlinkCmdEnum.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/domain/DownlinkCmdEnum.java)

概述

云快充协议下行消息处理链路是一个完整的从外部系统发起控制请求到最终发送到充电桩设备的处理流程。该系统支持两种主要的外部接口：REST API 和 gRPC 服务，通过统一的协议处理框架实现对云快充协议的下行指令处理。

系统架构

graph TB
subgraph "外部接口层"
REST[REST API<br/>DownlinkController]
GRPC[gRPC服务<br/>DownlinkGrpcService]
end
subgraph "协议处理层"
PMM[协议消息处理器<br/>YunKuaiChongProtocolMessageProcessor]
DCC[命令转换器<br/>YunKuaiChongDownlinkCmdConverter]
DCE[命令执行器基类<br/>AbstractYunKuaiChongCmdExe]
end
subgraph "命令执行层"
RS[远程启动命令<br/>YunKuaiChongV150RemoteStartDLCmd]
SS[停止充电命令<br/>YunKuaiChongV150RemoteStopDLCmd]
TS[时间同步命令<br/>YunKuaiChongV150TimeSyncDLCmd]
end
subgraph "传输层"
PS[协议会话<br/>ProtocolSession]
TC[TCP通道处理器<br/>TcpChannelHandler]
CH[通道<br/>Channel]
end
REST --> PMM
GRPC --> PMM
PMM --> DCC
PMM --> DCE
DCE --> RS
DCE --> SS
DCE --> TS
RS --> PS
PS --> TC
TC --> CH

图表来源

外部接口层

REST API 接口

REST API 提供了一个标准的 HTTP 接口，通过 /api/onDownlink 端点接收下行控制请求。

sequenceDiagram
participant Client as 外部客户端
participant Controller as DownlinkController
participant Registry as SessionRegistry
participant Session as ProtocolSession
Client->>Controller : POST /api/onDownlink<br/>protobuf消息
Controller->>Controller : 解析消息获取sessionId
Controller->>Registry : 获取ProtocolSession
Registry-->>Controller : 返回session或null
alt session存在
Controller->>Session : onDownlink(downlinkMsg)
Session-->>Controller : 处理完成
Controller-->>Client : 200 OK
else session不存在
Controller-->>Client : 404 Not Found
end

图表来源

DownlinkController.java

gRPC 服务接口

gRPC 服务提供了高性能的双向流式通信接口，支持实时的下行控制请求处理。

sequenceDiagram
participant Client as gRPC客户端
participant Service as DownlinkGrpcService
participant Registry as SessionRegistry
participant Session as ProtocolSession
Client->>Service : onDownlink(stream)<br/>连接请求
Service->>Service : 建立连接状态
Client->>Service : onDownlink(stream)<br/>下行请求
Service->>Service : 解析消息获取sessionId
Service->>Registry : 获取ProtocolSession
Registry-->>Service : 返回session或null
alt session存在
Service->>Session : onDownlink(downlinkMsg)
Session-->>Service : 处理完成
Service-->>Client : 响应确认
else session不存在
Service-->>Client : 记录日志
end

图表来源

DownlinkGrpcService.java

章节来源

协议处理层

协议消息处理器

协议消息处理器负责接收来自外部接口的下行请求，并将其转换为内部的消息格式进行处理。

flowchart TD
Start([接收下行请求]) --> ParseMsg["解析DownlinkRequestMessage"]
ParseMsg --> ConvertCmd["转换命令类型"]
ConvertCmd --> CheckSupport{"命令是否支持?"}
CheckSupport --> |否| LogWarn["记录警告日志"]
CheckSupport --> |是| CreateMsg["创建YunKuaiChongDwonlinkMessage"]
CreateMsg --> GetExecutor["获取命令执行器"]
GetExecutor --> ExecutorExists{"执行器是否存在?"}
ExecutorExists --> |否| LogInfo["记录未知指令日志"]
ExecutorExists --> |是| ExecuteCmd["执行命令"]
ExecuteCmd --> End([处理完成])
LogWarn --> End
LogInfo --> End

图表来源

YunKuaiChongProtocolMessageProcessor.java

命令枚举定义

系统定义了完整的下行命令枚举，涵盖了所有支持的云快充协议指令。

命令类型	描述	协议支持
LOGIN_ACK	登录应答	全版本
HEARTBEAT_ACK	心跳应答	全版本
SET_PRICING	设置定价模型	V1.5+
REMOTE_START_CHARGING	远程启动充电	V1.5+
REMOTE_STOP_CHARGING	远程停止充电	V1.5+
TRANSACTION_RECORD_ACK	交易记录确认	V1.5+
SYNC_TIME_REQUEST	同步时间请求	V1.5+
OFFLINE_CARD_QUERY_REQUEST	离线卡查询请求	V1.5+

章节来源

命令转换层

命令转换器

命令转换器负责将通用的 DownlinkCmdEnum 转换为云快充协议特定的命令码。

classDiagram
class DownlinkCmdConverter {
<<interface>>
+convertToCmd(DownlinkCmdEnum) Integer
+supports(DownlinkCmdEnum) boolean
+getProtocolName() String
}
class YunKuaiChongDownlinkCmdConverter {
-COMMAND_MAP Map~DownlinkCmdEnum,Integer~
-INSTANCE YunKuaiChongDownlinkCmdConverter
+getInstance() YunKuaiChongDownlinkCmdConverter
+convertToCmd(DownlinkCmdEnum) Integer
+getProtocolName() String
}
DownlinkCmdConverter <|-- YunKuaiChongDownlinkCmdConverter
note for YunKuaiChongDownlinkCmdConverter "单例模式，使用ConcurrentHashMap存储转换关系\n提供O(1)查找性能"

图表来源

YunKuaiChongDownlinkCmdConverter.java

转换映射表

以下是部分关键命令的转换映射：

通用命令	云快充协议命令码	功能描述
REMOTE_START_CHARGING	0x34	远程启动充电
REMOTE_STOP_CHARGING	0x36	远程停止充电
SET_PRICING	0x58	设置定价模型
SYNC_TIME_REQUEST	0x56	同步时间请求
TRANSACTION_RECORD_ACK	0x40	交易记录确认

章节来源

YunKuaiChongDownlinkCmdConverter.java

消息构建层

命令执行器基类

抽象命令执行器基类提供了消息编码和发送的核心功能。

classDiagram
class AbstractYunKuaiChongCmdExe {
-DOWNLINK_CMD_CONVERTER DownlinkCmdConverter
+encode(int, int, int, ByteBuf) byte[]
+encodeAndWriteFlush(int, int, int, ByteBuf, TcpSession) void
+encodeAndWriteFlush(int, ByteBuf, TcpSession) void
+encodeAndWriteFlush(DownlinkCmdEnum, int, int, ByteBuf, TcpSession) void
+encodeAndWriteFlush(DownlinkCmdEnum, ByteBuf, TcpSession) void
+encodePileCode(String) byte[]
+encodeGunCode(String) byte[]
+encodeTradeNo(String) byte[]
+encodeLogicalCardNo(String) byte[]
+encodePhysicalCardNo(String) long
}
class YunKuaiChongV150RemoteStartDLCmd {
+execute(TcpSession, YunKuaiChongDwonlinkMessage, ProtocolContext) void
}
AbstractYunKuaiChongCmdExe <|-- YunKuaiChongV150RemoteStartDLCmd
note for AbstractYunKuaiChongCmdExe "提供协议特定的消息编码功能\n包括BCD编码、CRC校验等"

图表来源

AbstractYunKuaiChongCmdExe.java

远程启动命令实现

以远程启动充电命令为例，展示具体的命令处理流程。

sequenceDiagram
participant Cmd as YunKuaiChongV150RemoteStartDLCmd
participant Base as AbstractYunKuaiChongCmdExe
participant Session as TcpSession
participant Channel as Netty Channel
Cmd->>Cmd : 解析请求参数
Note over Cmd : pileCode, gunCode, tradeNo<br/>logicalCardNo, physicalCardNo<br/>limitYuan
Cmd->>Cmd : 创建ByteBuf
Cmd->>Cmd : 写入交易流水号(32字节BCD)
Cmd->>Cmd : 写入桩编码(14字节BCD)
Cmd->>Cmd : 写入枪号(2字节BCD)
Cmd->>Cmd : 写入逻辑卡号(16字节BCD)
Cmd->>Cmd : 写入物理卡号(8字节LE Long)
Cmd->>Cmd : 写入账户余额(4字节LE Int)
Cmd->>Base : encodeAndWriteFlush(cmd, msgBody, session)
Base->>Base : encode(cmd, seqNo, flag, msgBody)
Note over Base : 添加协议头、长度、序列号<br/>加密标志、命令字、数据域<br/>计算CRC校验和
Base->>Session : writeAndFlush(encodedMessage)
Session->>Channel : 发送到网络

图表来源

协议消息格式

云快充协议的下行消息格式如下：

字段	长度	描述
帧头	1字节	固定值 0x68
数据长度	1字节	包含后续所有字段的长度
序列号	2字节	LE格式，自动递增
加密标志	1字节	0表示正常加密
命令字	1字节	下行命令类型
数据域	可变	具体命令的数据内容
校验和	2字节	CRC校验，多项式0x180D

章节来源

传输层

协议会话管理

协议会话负责维护与充电桩设备的连接状态和消息路由。

classDiagram
class ProtocolSession {
<<abstract>>
#protocolName String
#id UUID
#lastActivityTime LocalDateTime
#pileCodeSet Set~String~
#requestCache Cache~String,Object~
+onDownlink(DownlinkRequestMessage) void
+close(SessionCloseReason) void
+addPileCode(String) void
+addSchedule(String, Function) void
}
class TcpSession {
-sendDownlinkConsumer Consumer~DownlinkRequestMessage~
-writeAndFlushConsumer Consumer~ByteBuf~
-sequenceNumber AtomicInteger
+nextSeqNo(SequenceNumberLength) int
+writeAndFlush(ByteBuf) void
+onDownlink(DownlinkRequestMessage) void
}
ProtocolSession <|-- TcpSession
note for TcpSession "继承自ProtocolSession<br/>提供TCP连接的下行消息发送功能"

图表来源

TCP通道处理器

TCP通道处理器负责实际的网络数据传输和消息发送。

flowchart TD
Start([消息发送请求]) --> CheckSession{"会话是否有效?"}
CheckSession --> |否| LogError["记录错误日志"]
CheckSession --> |是| EncodeMsg["编码协议消息"]
EncodeMsg --> WriteToChannel["写入Netty Channel"]
WriteToChannel --> CheckResult{"发送是否成功?"}
CheckResult --> |否| LogFailure["记录发送失败"]
CheckResult --> |是| LogSuccess["记录发送成功"]
LogError --> End([结束])
LogFailure --> End
LogSuccess --> End

图表来源

TcpChannelHandler.java

章节来源

错误处理与超时机制

超时处理

系统在多个层面实现了超时处理机制：

HTTP超时: REST API 默认超时时间为3秒
gRPC超时: 连接建立和消息处理都有超时保护
消息发送超时: TCP通道处理器记录发送时间并监控结果

错误恢复策略

flowchart TD
Error([发生错误]) --> CheckType{"错误类型"}
CheckType --> |网络错误| Retry["重试机制"]
CheckType --> |协议错误| LogError["记录错误日志"]
CheckType --> |超时错误| TimeoutAction["超时处理"]
Retry --> RetryCount{"重试次数检查"}
RetryCount --> |未超限| DelayRetry["延迟重试"]
RetryCount --> |超限| FailFast["快速失败"]
DelayRetry --> SendAgain["重新发送"]
SendAgain --> Success{"发送成功?"}
Success --> |是| LogSuccess["记录成功"]
Success --> |否| LogError
TimeoutAction --> LogTimeout["记录超时"]
LogError --> Cleanup["清理资源"]
FailFast --> Cleanup
LogSuccess --> Cleanup
LogTimeout --> Cleanup
Cleanup --> End([结束])

异常处理机制

系统提供了完善的异常处理机制，包括：

DownlinkException: 下行消息处理异常
IllegalArgumentException: 参数验证异常
RuntimeException: 通用运行时异常处理

章节来源

完整时序图

以下展示了从外部系统发起远程启动充电请求到设备响应的完整时序：

sequenceDiagram
participant Client as 外部客户端
participant Controller as DownlinkController
participant PMM as 协议消息处理器
participant Converter as 命令转换器
participant Executor as 命令执行器
participant Session as 协议会话
participant Channel as TCP通道
participant Device as 充电桩设备
Note over Client,Device : 远程启动充电流程
Client->>Controller : POST /api/onDownlink<br/>RemoteStartChargingRequest
Controller->>Controller : 解析protobuf消息
Controller->>Session : 获取ProtocolSession
Session-->>Controller : 返回会话对象
Controller->>PMM : downlinkHandle(sessionToHandlerMsg)
PMM->>Converter : convertToCmd(REMOTE_START_CHARGING)
Converter-->>PMM : 返回命令码 0x34
PMM->>Executor : 获取YunKuaiChongV150RemoteStartDLCmd
Executor->>Executor : 解析请求参数
Executor->>Executor : 构建消息体
Note over Executor : 交易流水号+桩编码+枪号<br/>卡号+余额等信息
Executor->>Executor : encodeAndWriteFlush(0x34, msgBody, session)
Executor->>Session : writeAndFlush(encodedMessage)
Session->>Channel : 发送到网络
Channel->>Device : 传输协议消息
Device-->>Channel : 设备响应
Channel-->>Session : 接收响应
Session-->>PMM : 处理上行消息
PMM-->>Controller : 处理完成
Controller-->>Client : 返回成功响应

图表来源

总结

云快充协议下行消息处理链路展现了现代工业物联网系统的典型架构特点：

分层架构: 清晰的分层设计使得系统具有良好的可维护性和扩展性
多接口支持: 同时支持REST API和gRPC两种接口，满足不同场景需求
协议抽象: 通过命令转换器实现协议无关的设计
高效传输: 基于Netty的异步非阻塞IO，确保高并发处理能力
健壮性: 完善的错误处理和超时机制保证系统稳定性

该系统为云快充平台提供了可靠、高效的下行指令处理能力，支撑着大规模充电桩的远程控制需求。通过模块化的架构设计和标准化的协议处理流程，系统能够快速适配新的协议版本和功能需求。

19 KiB Raw Blame History Unescape Escape

云快充协议下行消息处理链路

目录

概述

系统架构

外部接口层

REST API 接口

gRPC 服务接口

协议处理层

协议消息处理器

命令枚举定义

命令转换层

命令转换器

转换映射表

消息构建层

命令执行器基类

远程启动命令实现

协议消息格式

传输层

协议会话管理

TCP通道处理器

错误处理与超时机制

超时处理

错误恢复策略

异常处理机制

完整时序图

总结

19 KiB

Raw Blame History