wiki生成

2026-06-20 23:19:41 +08:00 · 2025-10-28 14:39:06 +08:00
parent 26cec08d61
commit fa9524d302
31 changed files with 13636 additions and 1 deletions
--- a/docs/开发者指南.md
+++ b/docs/开发者指南.md
@@ -0,0 +1,367 @@
+# 开发者指南
+
+<cite>
+**本文档中引用的文件**  
+- [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)
+</cite>
+
+## 目录
+
+1. [环境搭建](#环境搭建)
+2. [代码获取与构建](#代码获取与构建)
+3. [本地运行](#本地运行)
+4. [开发新协议](#开发新协议)
+5. [调试技巧](#调试技巧)
+
+## 环境搭建
+
+在开始开发之前，需要安装以下必要的开发工具：
+
+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
+```
+
+**Section sources**
+
+- [pom.xml](file://pom.xml#L15-L20)
+- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json#L1-L10)
+
+## 代码获取与构建
+
+### 代码获取
+
+使用Git克隆项目仓库：
+
+```bash
+git clone https://github.com/sanbing-java/JChargePointProtocol.git
+cd JChargePointProtocol
+```
+
+### 后端构建
+
+项目包含多个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命令：
+
+```bash
+docker-compose -f docker/docker-compose.postgres.yml -f docker/docker-compose.redis-standalone.yml -f docker/docker-compose.kafka.yml up -d
+```
+
+### 启动应用服务
+
+项目包含两个核心启动模块：`jcpp-app-bootstrap`（应用后端）和`jcpp-protocol-bootstrap`（协议前置）。
+
+1. 启动应用后端服务：
+
+```bash
+cd jcpp-app-bootstrap
+mvn spring-boot:run
+```
+
+2. 启动协议前置服务：
+
+```bash
+cd jcpp-protocol-bootstrap
+mvn spring-boot:run
+```
+
+服务启动后，可通过以下地址访问：
+
+- 应用后端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`：
+
+```bash
+export JAVA_OPTS_EXTEND="-Xdebug -Xrunjdwp:transport=dt_socket,address=0.0.0.0:8000,server=y,suspend=n"
+```
+
+在IDE中配置远程调试连接：
+
+- 主机：localhost
+- 端口：8000
+- 调试器：Java
+
+### RPC调用调试
+
+通过`RpcController`提供的API接口发送调试指令：
+
+```bash
+curl -X POST http://localhost:8080/api/rpc/oneway \
+  -H "Content-Type: application/json" \
+  -d '{
+    "method": "startCharge",
+    "parameter": {"pileCode": "P123", "gunNo": "1"}
+  }'
+```
+
+```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 : 返回响应结果
+```
+
+**Diagram sources**
+
+- [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)
+
+**Section sources**
+
+- [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)