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

- 精简开发者指南，聚焦于本地开发流程和环境准备 - 更新系统概述，明确系统定位和核心能力 - 删除冗余引用和目录，优化文档结构
2026-05-09 20:39:55 +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/README.md
+++ 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. 必要时查看 `代码审查/` 中的已知风险与修复建议
+
+## 文档维护约定
+
+- 优先更新原有文档，避免新建同主题重复文档
+- 关键改动（架构、链路、接口）必须同步更新对应文档
+- 代码评审建议放入 `代码审查/`，并标明日期与影响范围
--- 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`
--- a/docs/系统概述.md
+++ b/docs/系统概述.md
@@ -1,279 +1,55 @@
 # 系统概述

-<cite>
-**本文档引用的文件**   
- [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)
-</cite>
+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有望成为电动汽车充电领域的标准解决方案，为充电基础设施的智能化管理做出重要贡献。
+- 架构设计：`架构设计/`
+- 协议细节：`核心模块详解/协议实现模块/`
+- API 文档：`API接口参考/`
+- 运维排障：`监控与运维.md`
+- 开发上手：`开发者指南.md`