LingChong V2 协议对接笔记

# LingChong V2 协议对接笔记

这篇笔记记录本次 LingChong V2 充电桩协议对接过程中已经确认的帧类型、业务流程和几个容易踩坑的点，方便后面联调和排查。

## 一、协议帧清单

### 桩到平台

| 帧类型 | 方向 | 业务含义 | 当前实现 |
|---|---|---|---|
| 0x01 | 桩 -> 平台 | 登录鉴权 UP_LOGIN | 已实现 |
| 0x03 | 桩 -> 平台 | 心跳 UP_HEARTBEAT | 已实现 |
| 0x05 | 桩 -> 平台 | 请求计费费率 UP_REQUEST_RATE | 已实现 |
| 0x08 | 桩 -> 平台 | 费率设置应答 UP_RATE_SETTING_REPLY | 已实现 |
| 0x09 | 桩 -> 平台 | 充电过程数据 UP_PROCESS | 已实现 |
| 0x0B | 桩 -> 平台 | 远程启动应答 UP_START_CHARGE_REPLY | 已实现 |
| 0x0D | 桩 -> 平台 | 功率设置应答 UP_SEND_POWER_REPLY | 已实现 |
| 0x0F | 桩 -> 平台 | 远程停止应答 UP_STOP_CHARGE_REPLY | 已实现 |
| 0x10 | 桩 -> 平台 | 充电订单/结算订单 UP_ORDER | 已实现 |
| 0x13 | 桩 -> 平台 | 对时应答 UP_SYNC_TIME_REPLY | 已实现 |
| 0x15 | 桩 -> 平台 | 二维码下发应答 UP_SEND_QRCODE_REPLY | 已实现 |
| 0x17 | 桩 -> 平台 | 升级应答 UP_SEND_UPGRADE_REPLY | 已实现 |
| 0x18 | 桩 -> 平台 | 充电握手 UP_CHARGE_HANDSHAKE | 已实现 |
| 0x19 | 桩 -> 平台 | 参数配置 UP_PARAM_CONFIG | 已实现 |
| 0x1A | 桩 -> 平台 | BMS 需求 UP_CHARGE_BMS_DEMAND | 已实现 |
| 0x1B | 桩 -> 平台 | BMS 过程信息 UP_CHARGE_BMS_INFO | 已实现 |
| 0x1D | 桩 -> 平台 | 远程重启应答 UP_REMOTE_RESTART_REPLY | 已实现 |
| 0x1E | 桩 -> 平台 | 刷卡/VIN 启动鉴权 UP_CARD_START_CHARGE | 已实现 |
| 0x22 | 桩 -> 平台 | 故障告警 UP_FAULT_ALARM | 已实现 |
| 0x81 | 桩 -> 平台 | 费率校验请求 UP_REQUEST_RATE_CHECK | 兼容保留 |
| 0x84 | 桩 -> 平台 | BMS 结束 UP_CHARGE_BMS_END | 兼容保留 |
| 0x85 | 桩 -> 平台 | BMS 中止 UP_CHARGE_BMS_STOP | 兼容保留 |
| 0x86 | 桩 -> 平台 | BMS/桩中止 UP_CHARGE_BMS_PILE_STOP | 兼容保留 |
| 0x87 | 桩 -> 平台 | 离线卡同步应答 | 兼容保留 |
| 0x89 | 桩 -> 平台 | 离线卡清除应答 | 兼容保留 |
| 0x8B | 桩 -> 平台 | 离线卡查询应答 | 兼容保留 |

### 平台到桩

| 帧类型 | 方向 | 业务含义 | 当前实现 |
|---|---|---|---|
| 0x02 | 平台 -> 桩 | 登录鉴权应答 DOWN_LOGIN_REPLY | 已实现 |
| 0x04 | 平台 -> 桩 | 心跳应答 DOWN_HEARTBEAT_REPLY | 已实现 |
| 0x06 | 平台 -> 桩 | 请求费率应答 DOWN_REQUEST_RATE_REPLY | 已实现 |
| 0x07 | 平台 -> 桩 | 主动下发费率 DOWN_SEND_RATE | 已实现 |
| 0x0A | 平台 -> 桩 | 远程启动 DOWN_START_CHARGE | 已实现 |
| 0x0C | 平台 -> 桩 | 下发功率 DOWN_SEND_POWER | 已实现 |
| 0x0E | 平台 -> 桩 | 远程停止 DOWN_STOP_CHARGE | 已实现 |
| 0x11 | 平台 -> 桩 | 订单确认 DOWN_ORDER_REPLY | 已实现 |
| 0x12 | 平台 -> 桩 | 对时 DOWN_SYNC_TIME | 已实现 |
| 0x14 | 平台 -> 桩 | 下发二维码 DOWN_SEND_QRCODE | 已实现 |
| 0x16 | 平台 -> 桩 | 远程升级 DOWN_SEND_UPGRADE | 已实现 |
| 0x1C | 平台 -> 桩 | 远程重启 DOWN_REMOTE_RESTART | 已实现 |
| 0x1F | 平台 -> 桩 | 刷卡/VIN 启动鉴权应答 DOWN_PILE_START | 已实现 |
| 0x23 | 平台 -> 桩 | 故障告警应答 DOWN_FAULT_ALARM_REPLY | 已实现 |
| 0x82 | 平台 -> 桩 | 费率校验应答 DOWN_REQUEST_RATE_CHECK_REPLY | 兼容保留 |
| 0x83 | 平台 -> 桩 | 请求实时数据 DOWN_REQUEST_REALTIME | 兼容保留 |
| 0x88 | 平台 -> 桩 | 离线卡同步 | 兼容保留 |
| 0x8A | 平台 -> 桩 | 离线卡清除 | 兼容保留 |
| 0x8C | 平台 -> 桩 | 离线卡查询 | 兼容保留 |

## 二、登录流程注意事项

真实桩的登录报文和最早模拟器报文有差异，主要体现在设备号、软件版本、SIM 卡号、运营商等字段的位置和长度。最终以真实桩报文为准修改了解析逻辑。

登录配置里增加过：

```yaml
saas:
  protocol:
    login:
      direct-reply: true
```

这个配置的作用是让协议服务收到登录后直接先回登录应答，避免完全等待业务侧异步 ONLINE_REPLY 导致桩侧超时重登。业务侧仍会收到 ONLINE 状态消息。

## 三、二维码下发注意事项

二维码帧是 `0x14`，应答是 `0x15`。

本次联调最终确认的二维码规则不是完全按 PDF 原始示例，而是按桩侧实际要求：

- 二维码格式字段发送 `0x02`，表示二维码 URL。
- 二维码内容只下发 URL 前缀：`https://test.demo.com.cn/qrcode/XXXXYYYYZZZZ/`
- 不再拼接设备编码。
- 不再拼接枪号。
- 不需要按两个枪口分别下发两次，整桩下发一次即可，具体枪号由桩侧自己拼接。
- 如果业务侧 URL 缺少 `http://` 或 `https://`，协议层自动补 `https://`。
- 二维码长度按最终实际 URL 的 ASCII 字节数计算，不能按模板字符串长度计算。

早期问题包括：

- URL 没有协议头。
- `{deviceCode}`、`{connectorNum}` 模板没有替换。
- 后来又确认设备编码和枪号都不需要拼进 URL。

## 四、对时注意事项

对时帧是 `0x12`，应答是 `0x13`。

对时字段必须使用 7 字节 CP56Time2a 格式：

```text
毫秒低字节、毫秒高字节、分钟、小时、日、月、年
```

之前只发了 6 字节，导致桩侧解析成类似 `2031-10-4 27:14:5` 这样的异常时间。修正后平台下发和桩侧应答都按 7 字节处理。

## 五、功率控制和远程重启

功率控制不是 `0x20`，而是：

- 平台下发功率：`0x0C`
- 桩侧功率设置应答：`0x0D`

当前功率下发报文体：

```text
桩编号 8 字节 + 枪号 1 字节 + 功率 4 字节小端 + 电流 4 字节小端 + 控制类型 1 字节
```

控制类型：

- `1`：限制功率
- `2`：限制电流

远程重启也已经实现：

- 平台下发远程重启：`0x1C`
- 桩侧远程重启应答：`0x1D`

报文体：

```text
桩编号 8 字节 + controlType 1 字节
```

`controlType=1` 表示立即执行，其他值按 `2` 空闲执行处理。代码注释里曾残留 `0x92/0x91`，那是其他协议的旧注释，LingChong V2 实际以 `CommandEnum` 为准，即 `0x1C/0x1D`。

## 六、刷卡/VIN 启动注意事项

刷卡/VIN 启动鉴权帧是 `0x1E`，平台应答是 `0x1F`。

真实桩上报的卡号和 VIN 都是反序字节：

- 卡号需要反序字节后，再转大写 HEX 字符串。
- VIN 需要反序字节后，再按 ASCII 字符串处理并去掉 `0x00`。

例子：

```text
桩侧卡号：8D38E35D00000000
协议原始字段需要反序后才能得到这个卡号
```

如果不处理反序，会出现业务侧查不到卡号、在线卡建单缺少 userId、桩侧收不到有效启动应答并重复发起刷卡鉴权的问题。

为了处理桩侧 5 秒未收到回复会重发的问题，协议层对刷卡/VIN 启动结果做了去抖和应答复用：同一设备、枪号、卡号/VIN、短时间窗口内的重复请求，尽量复用同一业务结果，避免生成多个不同订单号。

## 七、实时数据和订单金额

充电过程帧 `0x09` 和订单帧 `0x10` 中，电量、费用字段要注意倍率。

本次确认：

- 桩侧分时电费字段按 `1 / 100000` 解析。
- 桩侧分时服务费字段按 `1 / 100000` 解析。
- 早期按 `1 / 10000` 或其他倍率会导致订单金额、实付金额偏大。

举例：

```text
80F2(hex) = 33010(dec) -> 0.33010 或按对应字段倍率得到 3.301 度
182D6(hex) = 99030(dec) -> 0.99030 电费
203C8(hex) = 132040(dec) -> 1.32040 服务费
```

最终订单电量可以以桩侧为准，但平台订单电费、服务费、总费用建议由平台按费率重新计算，避免完全信任桩侧费用字段造成金额偏差。

## 八、停止码映射

LingChong V2 的停止码已经按最新厂家表重新映射到根协议停止码。

需要注意的是：

- LingChong V2 原始停止码应保留在 `pileStopReasonCode`，方便排查厂家原始原因。
- 平台统一停止原因使用根协议 `EndReasonEnum` 映射值。
- 范围类停止码如 `0x6C-0x7F`、`0x8C-0x94`、`0x99-0xA4`、`0xCA-0xE6`、`0xE7-0xFA` 已按保留/预留区间处理。

实际日志里确认过：

- 刷卡停止并不是旧表里的 `1008`。
- 真实刷卡停止曾出现 `0x5D`，十进制 `93`，最新表含义是“集控器刷卡中止”。
- 另一次订单出现 `0x5F`，十进制 `95`，最新表含义是“集控器界面按钮中止”。

因此排查停止原因时不要只看旧 PDF 表，要结合最新停止码表和原始报文中的停止码字段。

## 九、日志和排查建议

协议服务建议同时控制台打印和按天落地文件，方便联调后回放原始报文。重点关注这些日志关键字：

- `原始报文`
- `协议类型`
- `UP-LOGIN`
- `DOWN-LOGIN_REPLY`
- `UP-PROCESS`
- `UP-ORDER`
- `DOWN-SEND_QRCODE`
- `UP-QRCODE_REPLY`
- `DOWN-SYNC_TIME`
- `UP-SYNC_TIME_REPLY`
- `DOWN-SEND_POWER`
- `UP-SEND_POWER_REPLY`

排查时优先用原始报文拆字段，不要只看业务 JSON。业务 JSON 经过了协议层转换、倍率处理、根协议映射，定位底层协议问题时原始十六进制最可靠。

## 十、联调结论

LingChong V2 当前主流程已经打通：

1. 登录鉴权
2. 心跳
3. 请求/下发费率
4. 对时
5. 二维码下发
6. 实时数据上报
7. 刷卡/VIN 启动鉴权
8. 远程启动/停止
9. 功率控制
10. 订单上报
11. 故障告警
12. 远程重启

后续重点仍然是用真实桩继续验证边界场景：重复刷卡、异常停止、费率跨时段、离线卡、故障告警、远程升级和保留帧兼容。