docs: 更新开发者指南和系统概述，简化内容并增强可读性

- 精简开发者指南，聚焦于本地开发流程和环境准备 - 更新系统概述，明确系统定位和核心能力 - 删除冗余引用和目录，优化文档结构
2026-06-28 02:47:51 +08:00 · 2026-05-08 15:27:19 +08:00
parent ea0feba4c1
commit 771b10eb10
3 changed files with 141 additions and 579 deletions
--- a/docs/开发者指南.md
+++ b/docs/开发者指南.md
@@ -1,367 +1,108 @@
 # 开发者指南

-<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>
+本文档面向首次参与 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)
+- 优先看协议层连接与会话日志，再看业务层处理日志
+- 问题定位按链路走：连接建立 -> 报文解析 -> 消息转发 -> 业务处理 -> 回包
+- 关注缓存与会话一致性，避免“会话存在但通道失效”类问题
+
+## 8. 提交前检查清单
+
+- 编译通过：`mvn clean license:format install`
+- 核心链路自测通过（至少覆盖一条上行与一条下行）
+- 文档已同步（接口/架构/运维任一变更都需更新）
+- 无明显日志污染与调试代码残留
+
+## 9. 相关文档
+
+- `系统概述.md`
+- `架构设计/架构设计.md`
+- `核心模块详解/核心模块详解.md`
+- `监控与运维.md`