From 771b10eb10f9127c1fe22d2604b6cefb4630e514 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=89=E4=B8=99?= <10604541+sanbing-os@user.noreply.gitee.com> Date: Fri, 8 May 2026 15:27:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E8=80=85=E6=8C=87=E5=8D=97=E5=92=8C=E7=B3=BB=E7=BB=9F=E6=A6=82?= =?UTF-8?q?=E8=BF=B0=EF=BC=8C=E7=AE=80=E5=8C=96=E5=86=85=E5=AE=B9=E5=B9=B6?= =?UTF-8?q?=E5=A2=9E=E5=BC=BA=E5=8F=AF=E8=AF=BB=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 精简开发者指南，聚焦于本地开发流程和环境准备 - 更新系统概述，明确系统定位和核心能力 - 删除冗余引用和目录，优化文档结构 --- docs/README.md | 45 ++++++ docs/开发者指南.md | 377 +++++++-------------------------------------- docs/系统概述.md | 298 +++++------------------------------ 3 files changed, 141 insertions(+), 579 deletions(-) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..65329aa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,45 @@ +# JChargePointProtocol 文档中心 + +本目录用于沉淀项目的架构、开发、运维与接口文档，建议按“先总览、再开发、后专项”的顺序阅读。 + +## 快速导航 + +- `系统概述.md`：项目边界、核心能力、运行形态与关键链路 +- `开发者指南.md`：本地开发、构建、启动、调试与提交流程 +- `技术栈与依赖.md`：后端/前端/中间件依赖与版本约束 +- `部署与配置.md`：部署模式、配置项与环境差异 +- `监控与运维.md`：监控指标、日志排障、常见运维操作 +- `API接口参考/`：REST 与 gRPC 接口说明 +- `架构设计/`：架构模式、微服务拆分与数据流分析 +- `核心模块详解/`：协议处理、设备管理、具体协议实现细节 +- `数据模型与数据库设计.md`：核心实体、关系与表结构设计 +- `缓存架构.md`：缓存分层、键设计、失效与一致性策略 +- `消息队列集成.md`：Kafka 主题、消息流转与消费模型 +- `安全机制.md`：认证、鉴权与安全边界 +- `代码审查/`：阶段性 CR 报告与改进建议 + +## 推荐阅读路径 + +### 新同学入项 + +1. 读 `系统概述.md` 理解系统边界与整体链路 +2. 读 `开发者指南.md` 完成本地环境启动 +3. 读 `架构设计/架构设计.md` 与 `核心模块详解/核心模块详解.md` 理解代码分层 + +### 进行协议开发 + +1. 读 `核心模块详解/协议处理框架.md` +2. 读 `核心模块详解/协议实现模块/` 下目标协议文档 +3. 对照 `API接口参考/` 与 `消息队列集成.md` 联调 + +### 运维与排障 + +1. 读 `监控与运维.md` +2. 结合 `部署与配置.md` 与 `缓存架构.md` 定位问题 +3. 必要时查看 `代码审查/` 中的已知风险与修复建议 + +## 文档维护约定 + +- 优先更新原有文档，避免新建同主题重复文档 +- 关键改动（架构、链路、接口）必须同步更新对应文档 +- 代码评审建议放入 `代码审查/`，并标明日期与影响范围 diff --git a/docs/开发者指南.md b/docs/开发者指南.md index 0463bb8..00377cc 100644 --- a/docs/开发者指南.md +++ b/docs/开发者指南.md @@ -1,367 +1,108 @@ # 开发者指南 - -**本文档中引用的文件** -- [README.md](file://README.md) -- [pom.xml](file://pom.xml) -- [docker/start.sh](file://docker/start.sh) -- [docker/docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml) -- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml) -- [jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml](file://jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml) -- [jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java) -- [jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java) -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java) -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java) -- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java) -- [jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java) -- [jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java) -- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java) -- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json) - +本文档面向首次参与 JChargePointProtocol 开发的同学，提供一套可执行的本地开发流程。 -## 目录 +## 1. 环境准备 -1. [环境搭建](#环境搭建) -2. [代码获取与构建](#代码获取与构建) -3. [本地运行](#本地运行) -4. [开发新协议](#开发新协议) -5. [调试技巧](#调试技巧) +请先安装以下工具并确保命令可用： -## 环境搭建 +- JDK 21 +- Maven 3.9+ +- Node.js 18+（建议 LTS） +- Docker / Docker Compose -在开始开发之前，需要安装以下必要的开发工具： - -1. **JDK 21**：本项目基于Java 21开发，需安装JDK 21并配置JAVA_HOME环境变量。 -2. **Maven**：用于构建Java后端模块，建议使用最新稳定版本。 -3. **Node.js**：用于构建前端项目，建议使用LTS版本（如v18或v20）。 -4. **Docker**：用于启动依赖服务（PostgreSQL, Redis, Kafka等），建议安装最新稳定版。 - -安装完成后，可通过以下命令验证： +建议验证： ```bash java -version mvn -version -node --version -docker --version +node -v +docker -v ``` -**Section sources** - -- [pom.xml](file://pom.xml#L15-L20) -- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json#L1-L10) - -## 代码获取与构建 - -### 代码获取 - -使用Git克隆项目仓库： +## 2. 获取代码 ```bash git clone https://github.com/sanbing-java/JChargePointProtocol.git cd JChargePointProtocol ``` -### 后端构建 +## 3. 启动依赖服务 -项目包含多个Maven模块，主要后端模块包括`jcpp-app`和`jcpp-protocol-*`系列模块。 - -构建所有模块： - -```bash -mvn clean install -DskipTests -``` - -仅构建特定模块（如`jcpp-app`）： - -```bash -cd jcpp-app -mvn clean package -DskipTests -``` - -### 前端构建 - -前端项目位于`jcpp-web-ui`目录，使用npm进行构建。 - -进入前端目录并安装依赖： - -```bash -cd jcpp-web-ui -npm install -``` - -构建生产版本： - -```bash -npm run build -``` - -启动开发服务器： - -```bash -npm start -``` - -**Section sources** - -- [pom.xml](file://pom.xml#L100-L120) -- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json#L10-L20) - -## 本地运行 - -### 启动依赖服务 - -项目依赖PostgreSQL、Redis和Kafka等服务，可通过Docker Compose一键启动。 - -使用提供的启动脚本： +优先使用项目脚本： ```bash bash docker/start.sh ``` -或手动执行Docker Compose命令： +若需手动启动，可按环境组合对应的 compose 文件（PostgreSQL/Redis/Kafka）。 + +## 4. 后端构建与运行 + +### 4.1 全量构建（推荐） ```bash -docker-compose -f docker/docker-compose.postgres.yml -f docker/docker-compose.redis-standalone.yml -f docker/docker-compose.kafka.yml up -d +mvn clean license:format install ``` -### 启动应用服务 - -项目包含两个核心启动模块：`jcpp-app-bootstrap`（应用后端）和`jcpp-protocol-bootstrap`（协议前置）。 - -1. 启动应用后端服务： +### 4.2 启动应用服务 ```bash -cd jcpp-app-bootstrap -mvn spring-boot:run +mvn spring-boot:run -pl jcpp-app-bootstrap ``` -2. 启动协议前置服务： +### 4.3 启动协议服务（微服务模式） ```bash -cd jcpp-protocol-bootstrap -mvn spring-boot:run +mvn spring-boot:run -pl jcpp-protocol-bootstrap ``` -服务启动后，可通过以下地址访问： - -- 应用后端API：http://localhost:8080 -- 协议服务gRPC端口：9090 -- 管理后台：http://localhost:8080/page/dashboard - -```mermaid -graph TD -A[Docker Compose] --> B[PostgreSQL] -A --> C[Redis] -A --> D[Kafka] -E[jcpp-app-bootstrap] --> B -E --> C -F[jcpp-protocol-bootstrap] --> D -F --> C -E --> G[前端UI] -F --> E -``` - -**Diagram sources** - -- [docker/docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L20) -- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml#L1-L50) -- [jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml](file://jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml#L1-L50) - -**Section sources** - -- [docker/start.sh](file://docker/start.sh#L1-L20) -- [jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java#L1-L20) -- [jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java#L1-L20) - -## 开发新协议 - -以实现一个新的充电桩协议为例，说明开发流程。 - -### 继承ProtocolBootstrap - -创建新的协议启动类，继承`ProtocolBootstrap`抽象类。参考现有协议实现，如`YunkuaichongV150ProtocolBootstrap`。 - -```java -@ProtocolComponent("NEW_PROTOCOL_V100") -public class NewProtocolV100Bootstrap extends ProtocolBootstrap { - - @Override - protected String getProtocolName() { - return "NEW_PROTOCOL_V100"; - } - - @Override - protected void _init() { - // 初始化逻辑 - } - - @Override - protected void _destroy() { - // 销毁逻辑 - } - - @Override - protected ProtocolMessageProcessor messageProcessor() { - return new NewProtocolMessageProcessor(forwarder, protocolContext); - } -} -``` - -### 实现消息处理器 - -创建消息处理器类，继承`ProtocolMessageProcessor`，实现上行和下行消息处理逻辑。 - -```java -public class NewProtocolMessageProcessor extends ProtocolMessageProcessor { - - public NewProtocolMessageProcessor(Forwarder forwarder, ProtocolContext protocolContext) { - super(forwarder, protocolContext); - } - - @Override - protected void uplinkHandle(ListenerToHandlerMsg listenerToHandlerMsg) { - // 处理上行消息 - } - - @Override - protected void doDownlinkHandle(SessionToHandlerMsg sessionToHandlerMsg) { - // 处理下行消息 - } -} -``` - -### 定义命令类 - -根据协议规范定义上行和下行命令类，通常包含消息头、消息体、校验等字段。 - -### 配置文件注册 - -在`protocol-service.yml`中注册新协议的配置，包括监听端口、转发方式等。 - -```yaml -service: - protocols: - newProtocolV100: - enabled: true - listener: - tcp: - bind-port: 38021 - forwarder: - type: kafka -``` - -```mermaid -classDiagram -class ProtocolBootstrap { -+init() -+destroy() -+health() -+getProtocolName() -+_init() -+_destroy() -+messageProcessor() -} -class NewProtocolV100Bootstrap { -+getProtocolName() -+_init() -+_destroy() -+messageProcessor() -} -class ProtocolMessageProcessor { -+uplinkHandleAsync() -+downlinkHandle() -+uplinkHandle() -+doDownlinkHandle() -} -class NewProtocolMessageProcessor { -+uplinkHandle() -+doDownlinkHandle() -} -ProtocolBootstrap <|-- NewProtocolV100Bootstrap -ProtocolMessageProcessor <|-- NewProtocolMessageProcessor -NewProtocolV100Bootstrap --> NewProtocolMessageProcessor : "creates" -``` - -**Diagram sources** - -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L50) -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java#L1-L30) -- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L20) - -**Section sources** - -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L127) -- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java#L1-L78) -- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L48) -- [jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java#L1-L48) - -## 调试技巧 - -### 查看日志 - -应用日志默认输出到控制台，并保存在`logs/`目录下。关键日志文件包括： - -- `logs/accesslog/`：HTTP访问日志 -- `logs/gc/gc.log`：JVM GC日志 -- `logs/heapdump/`：内存溢出时的堆转储文件 - -可通过配置`app-service.yml`调整日志级别： - -```yaml -logging: - level: - sanbing: DEBUG -``` - -### 远程调试 - -通过JVM参数启用远程调试，修改启动脚本`docker/start.sh`： +## 5. 前端构建与运行 ```bash -export JAVA_OPTS_EXTEND="-Xdebug -Xrunjdwp:transport=dt_socket,address=0.0.0.0:8000,server=y,suspend=n" +cd jcpp-web-ui +npm install +npm run dev ``` -在IDE中配置远程调试连接： +默认情况下通过前端开发服务器访问页面，后端接口走代理配置。 -- 主机：localhost -- 端口：8000 -- 调试器：Java +## 6. 常用开发任务 -### RPC调用调试 +### 6.1 新增协议实现 -通过`RpcController`提供的API接口发送调试指令： +1. 在对应 `jcpp-protocol-*` 模块新增协议 bootstrap 与命令处理器 +2. 对齐上行解析、下行编码、会话管理 +3. 增加必要测试与文档（`核心模块详解/协议实现模块/`） -```bash -curl -X POST http://localhost:8080/api/rpc/oneway \ - -H "Content-Type: application/json" \ - -d '{ - "method": "startCharge", - "parameter": {"pileCode": "P123", "gunNo": "1"} - }' -``` +### 6.2 新增业务接口 -```mermaid -sequenceDiagram -participant Dev as 开发者 -participant IDE as IDE -participant App as jcpp-app-bootstrap -participant Protocol as jcpp-protocol-bootstrap -Dev->>IDE : 配置远程调试 -IDE->>App : 连接调试端口8000 -Dev->>App : 发送RPC指令 -App->>Protocol : 通过Kafka转发 -Protocol->>App : 处理协议消息 -App-->>Dev : 返回响应结果 -``` +1. 在 `jcpp-app` 中补充 Service 与 Controller +2. 同步更新 `API接口参考/` +3. 联调协议层下行/上行链路 -**Diagram sources** +### 6.3 数据模型变更 -- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java#L1-L70) -- [docker/start.sh](file://docker/start.sh#L15-L18) -- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml#L1-L10) +1. 更新实体、Mapper 与 SQL 迁移 +2. 同步更新 `数据模型与数据库设计.md` +3. 执行回归验证 -**Section sources** +## 7. 调试建议 -- [docker/start.sh](file://docker/start.sh#L15-L18) -- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java#L30-L150) -- [jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java#L1-L1000) \ No newline at end of file +- 优先看协议层连接与会话日志，再看业务层处理日志 +- 问题定位按链路走：连接建立 -> 报文解析 -> 消息转发 -> 业务处理 -> 回包 +- 关注缓存与会话一致性，避免“会话存在但通道失效”类问题 + +## 8. 提交前检查清单 + +- 编译通过：`mvn clean license:format install` +- 核心链路自测通过（至少覆盖一条上行与一条下行） +- 文档已同步（接口/架构/运维任一变更都需更新） +- 无明显日志污染与调试代码残留 + +## 9. 相关文档 + +- `系统概述.md` +- `架构设计/架构设计.md` +- `核心模块详解/核心模块详解.md` +- `监控与运维.md` diff --git a/docs/系统概述.md b/docs/系统概述.md index 85aaf89..6b8da08 100644 --- a/docs/系统概述.md +++ b/docs/系统概述.md @@ -1,279 +1,55 @@ # 系统概述 - -**本文档引用的文件** -- [README.md](file://README.md) -- [pom.xml](file://pom.xml) -- [JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java) -- [JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java) -- [PileController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/PileController.java) -- [StationController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/StationController.java) -- [GunController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/GunController.java) -- [ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java) -- [ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java) -- [Pile.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/dal/entity/Pile.java) -- [PileService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/PileService.java) -- [AttrKeyEnum.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/data/kv/AttrKeyEnum.java) -- [docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml) -- [package.json](file://jcpp-web-ui/package.json) - +JChargePointProtocol 是面向充电桩协议接入与设备管理的服务端平台，核心目标是把“多厂家私有协议”统一为“标准化平台能力”。 -## 目录 +## 系统定位 -1. [简介](#简介) -2. [项目结构](#项目结构) -3. [核心组件](#核心组件) -4. [架构概述](#架构概述) -5. [详细组件分析](#详细组件分析) -6. [依赖分析](#依赖分析) -7. [性能考虑](#性能考虑) -8. [故障排除指南](#故障排除指南) -9. [结论](#结论) +- 对下：通过 TCP 长连接接入充电桩，解析厂商协议 +- 对上：通过 REST/gRPC/Kafka 对业务系统提供统一能力 +- 对内：以模块化方式隔离协议差异，保证可扩展与可维护 -## 简介 +## 核心能力 -JChargePointProtocol是一个高性能、分布式、支持海量并发量的充电桩Java服务端平台，旨在为电动汽车充电网络提供基础能力。该项目设计支持多达100种充电桩协议，目前已实现对云快充和绿能等主流品牌充电桩协议的支持。系统采用微服务架构，通过统一的管理平台实现多品牌充电桩协议的集中管理，为充电应用提供稳定可靠的基础服务。 +- 设备管理：站点、充电桩、充电枪全生命周期管理 +- 协议接入：当前已支持云快充、绿能协议，可按模式扩展新协议 +- 指令下发：支持应用侧到协议侧的远程控制链路 +- 状态采集：上行消息实时解析、转发与状态更新 +- 运行治理：缓存、监控、日志、部署配置等基础支撑 -该平台在电动汽车充电网络中扮演着关键角色，作为充电桩与上层应用之间的桥梁，负责处理设备通信、协议转换、数据采集和远程控制等核心功能。系统支持通过TCP长连接与充电桩进行实时通信，利用Kafka实现异步消息处理，并通过gRPC提供高性能的指令下发能力，确保了系统的高可用性和可扩展性。 +## 模块划分 -## 项目结构 - -JChargePointProtocol项目采用模块化的微服务架构设计，各组件职责明确，协同工作。项目主要由三个核心服务组成：jcpp-app主服务、jcpp-protocol协议处理服务和jcpp-web-ui前端界面，通过Docker容器化部署实现服务的独立运行和弹性扩展。 - -```mermaid -graph TB -subgraph "前端界面" -WebUI[jcpp-web-ui] -end -subgraph "应用服务" -App[jcpp-app] -Protocol[jcpp-protocol] -end -subgraph "基础设施" -Kafka[Kafka] -Redis[Redis] -Postgres[PostgreSQL] -end -WebUI --> App -App --> Protocol -Protocol --> Kafka -App --> Kafka -App --> Redis -App --> Postgres +```text +jcpp-app 业务与管理接口 +jcpp-protocol-* 协议处理与设备通信 +jcpp-web-ui 可视化管理前端 +jcpp-infrastructure-* 通用基础设施（缓存、队列、工具等） ``` -**Diagram sources** +## 关键链路 -- [pom.xml](file://pom.xml) -- [docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml) -- [package.json](file://jcpp-web-ui/package.json) +### 上行链路（设备 -> 平台） -**Section sources** +1. 设备通过 TCP 发送协议报文 +2. 协议模块解析报文并构建标准消息 +3. 消息进入业务处理或转发到消息队列 +4. 应用层更新设备状态、业务数据 -- [pom.xml](file://pom.xml#L1-L699) -- [docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L29) -- [package.json](file://jcpp-web-ui/package.json#L1-L49) +### 下行链路（平台 -> 设备） -## 核心组件 +1. 应用层生成下行指令（REST/gRPC） +2. 协议模块根据会话定位目标连接 +3. 协议编码后写入 TCP 通道 +4. 设备执行并通过上行结果回传 -JChargePointProtocol系统的核心功能模块包括设备管理、协议处理、远程控制、数据采集与监控。这些模块协同工作，实现了对充电桩的全面管理和控制。设备管理模块负责充电桩、充电枪和充电站的全生命周期管理，包括创建、更新、删除和查询操作。协议处理模块是系统的核心，负责处理不同品牌充电桩的通信协议，实现协议的解析和封装。 +## 运行形态 -远程控制模块提供了对充电桩的远程操作能力，如启动充电、停止充电、重启设备等。数据采集与监控模块负责收集充电桩的实时数据，包括状态信息、充电数据和故障报警，并提供实时监控功能。系统通过属性键枚举（AttrKeyEnum）定义了标准化的状态属性，如STATUS（状态）、CONNECTED_AT（连接时间）、LAST_ACTIVE_TIME（最后活跃时间）等，确保了数据的一致性和可管理性。 +- 单体模式：`app + protocol` 同进程部署，适合开发与轻量场景 +- 微服务模式：应用服务与协议服务拆分部署，适合规模化场景 -**Section sources** +## 文档索引 -- [PileController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/PileController.java#L1-L112) -- [StationController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/StationController.java#L1-L108) -- [GunController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/GunController.java#L1-L116) -- [AttrKeyEnum.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/data/kv/AttrKeyEnum.java#L1-L70) - -## 架构概述 - -JChargePointProtocol采用微服务架构，整体布局清晰，各服务职责分明。系统主要由jcpp-app主服务、jcpp-protocol协议处理服务和jcpp-web-ui前端界面三大部分组成。jcpp-app主服务作为业务逻辑处理中心，负责设备管理、用户认证和API接口提供。jcpp-protocol协议处理服务专注于充电桩协议的解析和处理，支持多品牌协议的扩展。jcpp-web-ui前端界面提供直观的管理界面，方便管理员进行操作和监控。 - -```mermaid -graph TB -subgraph "前端层" -WebUI[jcpp-web-ui] -end -subgraph "应用层" -App[jcpp-app] -Protocol[jcpp-protocol] -end -subgraph "通信层" -Kafka[Kafka] -gRPC[gRPC] -TCP[TCP长连接] -end -subgraph "数据层" -Redis[Redis] -Postgres[PostgreSQL] -end -WebUI --> App -App --> Protocol -Protocol --> TCP -App --> Kafka -Protocol --> Kafka -App --> Redis -App --> Postgres -Protocol --> Redis -``` - -**Diagram sources** - -- [JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java#L1-L55) -- [JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java#L1-L59) -- [ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L127) - -## 详细组件分析 - -### 设备管理组件分析 - -设备管理组件是JChargePointProtocol系统的基础，负责充电桩、充电枪和充电站的全生命周期管理。该组件通过RESTful -API提供标准化的接口，支持设备的创建、查询、更新和删除操作。充电桩实体（Pile）包含丰富的属性信息，如桩编号（pileCode）、协议类型（protocol）、品牌（brand）和型号（model），为设备管理提供了完整的数据支持。 - -```mermaid -classDiagram -class Pile { -+UUID id -+LocalDateTime createdTime -+LocalDateTime updatedTime -+JsonNode additionalInfo -+String pileName -+String pileCode -+String protocol -+UUID stationId -+String brand -+String model -+String manufacturer -+PileTypeEnum type -+Integer version -} -class Station { -+UUID id -+String stationName -+String stationCode -+String address -+Double longitude -+Double latitude -} -class Gun { -+UUID id -+String gunCode -+UUID pileId -+Integer gunNumber -+Double maxPower -+Double voltageRange -} -Pile --> Station : "属于" -Gun --> Pile : "属于" -``` - -**Diagram sources** - -- [Pile.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/dal/entity/Pile.java#L1-L65) -- [PileService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/PileService.java#L1-L124) - -**Section sources** - -- [PileController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/PileController.java#L1-L112) -- [StationController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/StationController.java#L1-L108) -- [GunController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/GunController.java#L1-L116) - -### 协议处理组件分析 - -协议处理组件是JChargePointProtocol系统的核心，负责处理不同品牌充电桩的通信协议。该组件采用抽象基类ProtocolBootstrap的设计模式，为各种充电桩协议提供统一的初始化和销毁接口。ProtocolMessageProcessor作为消息处理器的基类，定义了上行和下行消息处理的统一框架，确保了协议处理的一致性和可扩展性。 - -```mermaid -sequenceDiagram -participant 充电桩 as 充电桩 -participant TCP监听器 as TcpListener -participant 协议处理器 as ProtocolMessageProcessor -participant Kafka转发器 as KafkaForwarder -充电桩->>TCP监听器 : TCP连接请求 -TCP监听器->>TCP监听器 : 创建TcpSession -充电桩->>TCP监听器 : 发送心跳数据 -TCP监听器->>协议处理器 : uplinkHandleAsync() -协议处理器->>Kafka转发器 : 转发上行消息 -Kafka转发器-->>后端服务 : 持久化处理 -后端服务->>协议处理器 : 下行指令 -协议处理器->>协议处理器 : doDownlinkHandle() -协议处理器->>TCP监听器 : 写入响应 -TCP监听器->>充电桩 : 发送响应数据 -``` - -**Diagram sources** - -- [ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L127) -- [ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java#L1-L78) -- [TcpListener.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/tcp/TcpListener.java#L1-L50) - -### 通信机制分析 - -JChargePointProtocol系统通过多种通信机制实现高效的数据交换和指令传输。系统使用TCP长连接与充电桩保持实时通信，通过Netty框架实现高性能的网络IO处理。IdleEventHandler组件负责检测空闲连接，当检测到读空闲状态时自动关闭连接，确保了连接资源的有效管理。Kafka作为消息中间件，实现了系统组件间的异步消息传递，提高了系统的吞吐量和可靠性。 - -```mermaid -flowchart TD -Start([TCP连接建立]) --> IdleCheck["配置IdleStateHandler"] -IdleCheck --> ReadIdle{"检测到读空闲?"} -ReadIdle --> |是| CloseConnection["关闭连接"] -ReadIdle --> |否| ContinueProcessing["继续处理消息"] -ContinueProcessing --> MessageReceived["接收充电桩消息"] -MessageReceived --> ProtocolProcessing["协议解析处理"] -ProtocolProcessing --> KafkaForward["转发到Kafka"] -KafkaForward --> DataPersistence["数据持久化"] -DataPersistence --> End([处理完成]) -style Start fill:#9f9,stroke:#333 -style End fill:#f9f,stroke:#333 -``` - -**Diagram sources** - -- [ChannelHandlerInitializer.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/ChannelHandlerInitializer.java#L1-L120) -- [IdleEventHandler.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/tcp/handler/IdleEventHandler.java#L1-L36) -- [TcpSession.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/tcp/TcpSession.java#L1-L100) - -## 依赖分析 - -JChargePointProtocol系统的组件间依赖关系清晰，通过合理的架构设计实现了高内聚低耦合。系统依赖于多种外部组件和服务，包括Kafka用于消息队列、Redis用于缓存、PostgreSQL用于数据持久化。jcpp-app服务依赖于jcpp-protocol服务进行协议处理，同时两者都依赖于基础设施服务。通过Docker -Compose配置文件定义了服务间的网络连接和端口映射，确保了服务的可部署性和可维护性。 - -```mermaid -graph TD -App[jcpp-app] --> Protocol[jcpp-protocol] -App --> Kafka[Kafka] -App --> Redis[Redis] -App --> Postgres[PostgreSQL] -Protocol --> Kafka -Protocol --> Redis -Protocol --> TCP[TCP网络] -WebUI[jcpp-web-ui] --> App -``` - -**Diagram sources** - -- [pom.xml](file://pom.xml#L1-L699) -- [docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L29) - -**Section sources** - -- [pom.xml](file://pom.xml#L1-L699) -- [docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L29) - -## 性能考虑 - -JChargePointProtocol系统在设计时充分考虑了性能因素，采用了多种优化策略确保系统的高并发处理能力。系统使用Netty框架处理TCP连接，利用其事件驱动的非阻塞IO模型，能够高效处理海量并发连接。通过Kafka实现异步消息处理，将耗时的操作（如数据持久化）与实时通信解耦，提高了系统的响应速度。gRPC的使用确保了服务间通信的高性能，特别是在指令下发场景下表现出色。 - -系统还采用了多级缓存策略，结合Caffeine本地缓存和Redis分布式缓存，有效减少了数据库访问压力。ShardingThreadPool的使用实现了任务的分片处理，避免了线程竞争，提高了处理效率。通过StatsFactory和MessagesStats组件，系统能够实时监控消息处理的性能指标，为性能优化提供了数据支持。 - -## 故障排除指南 - -当系统出现连接问题时，首先检查TCP监听器是否正常启动，端口是否被正确绑定。对于消息丢失问题，检查Kafka集群状态和主题配置，确保消息能够正常生产和消费。如果出现协议解析错误，检查充电桩发送的数据格式是否符合协议规范，以及协议处理器的解析逻辑是否正确。对于性能瓶颈，可以通过监控工具查看各组件的资源使用情况，重点关注CPU、内存和网络IO指标。 - -在处理充电桩心跳数据时，如果发现状态更新不及时，检查AttributeService的异步处理逻辑，确保状态属性能够及时更新。对于远程控制指令无法下发的问题，检查gRPC服务是否正常运行，以及充电桩的TCP连接状态是否正常。通过查看系统日志，特别是ProtocolMessageProcessor和TcpListener组件的日志，可以快速定位问题根源。 - -## 结论 - -JChargePointProtocol项目作为一个高性能的充电桩协议处理平台，通过合理的微服务架构设计和先进的技术选型，实现了对多品牌充电桩协议的统一管理。系统采用TCP长连接与充电桩通信，利用Kafka进行异步消息处理，并通过gRPC实现高性能指令下发，确保了系统的高可用性和可扩展性。项目结构清晰，核心组件职责明确，为电动汽车充电网络提供了稳定可靠的基础服务。 - -该平台不仅满足了当前充电桩管理的需求，还具备良好的扩展性，能够支持更多品牌和型号的充电桩协议。通过持续优化和功能完善，JChargePointProtocol有望成为电动汽车充电领域的标准解决方案，为充电基础设施的智能化管理做出重要贡献。 \ No newline at end of file +- 架构设计：`架构设计/` +- 协议细节：`核心模块详解/协议实现模块/` +- API 文档：`API接口参考/` +- 运维排障：`监控与运维.md` +- 开发上手：`开发者指南.md`