JChargePointProtocol/docs/开发者指南.md

# 开发者指南

本文档面向首次参与 JChargePointProtocol 开发的同学，提供一套可执行的本地开发流程。

## 1. 环境准备

请先安装以下工具并确保命令可用：

- JDK 21
- Maven 3.9+
- Node.js 18+（建议 LTS）
- Docker / Docker Compose

建议验证：

```bash
java -version
mvn -version
node -v
docker -v
```

## 2. 获取代码

```bash
git clone https://github.com/sanbing-java/JChargePointProtocol.git
cd JChargePointProtocol
```

## 3. 启动依赖服务

优先使用项目脚本：

```bash
bash docker/start.sh
```

若需手动启动，可按环境组合对应的 compose 文件（PostgreSQL/Redis/Kafka）。

## 4. 后端构建与运行

### 4.1 全量构建（推荐）

```bash
mvn clean license:format install
```

### 4.2 启动应用服务

```bash
mvn spring-boot:run -pl jcpp-app-bootstrap
```

### 4.3 启动协议服务（微服务模式）

```bash
mvn spring-boot:run -pl jcpp-protocol-bootstrap
```

## 5. 前端构建与运行

```bash
cd jcpp-web-ui
npm install
npm run dev
```

默认情况下通过前端开发服务器访问页面，后端接口走代理配置。

## 6. 常用开发任务

### 6.1 新增协议实现

1. 在对应 `jcpp-protocol-*` 模块新增协议 bootstrap 与命令处理器
2. 对齐上行解析、下行编码、会话管理
3. 增加必要测试与文档（`核心模块详解/协议实现模块/`）

### 6.2 新增业务接口

1. 在 `jcpp-app` 中补充 Service 与 Controller
2. 同步更新 `API接口参考/`
3. 联调协议层下行/上行链路

### 6.3 数据模型变更

1. 更新实体、Mapper 与 SQL 迁移
2. 同步更新 `数据模型与数据库设计.md`
3. 执行回归验证

## 7. 调试建议

- 优先看协议层连接与会话日志，再看业务层处理日志
- 问题定位按链路走：连接建立 -> 报文解析 -> 消息转发 -> 业务处理 -> 回包
- 关注缓存与会话一致性，避免“会话存在但通道失效”类问题

## 8. 提交前检查清单

- 编译通过：`mvn clean license:format install`
- 核心链路自测通过（至少覆盖一条上行与一条下行）
- 文档已同步（接口/架构/运维任一变更都需更新）
- 无明显日志污染与调试代码残留

## 9. 相关文档

- `系统概述.md`
- `架构设计/架构设计.md`
- `核心模块详解/核心模块详解.md`
- `监控与运维.md`