---
name: backend-conventions
description: 后端 C++ 规范。用于修改本仓库后端接口、Controller、Manager、配置文件与接口文档时，统一 JSON 处理、字段命名、响应结构与文档同步要求。
---

# 后端规范

## JSON 规则

- 统一使用 `nlohmann/json`
- 在实现文件中统一写：`using json = nlohmann::json;`
- 禁止新增 `jsoncpp` 依赖
- 解析请求体时必须处理非法 JSON 分支

## Drogon 响应构建

- 优先复用 `ResponseUtil`，避免每个接口自行拼装响应
- 明确设置 `Content-Type: application/json`
- 可预期失败走业务错误响应，不直接向前端暴露底层异常细节

示例：

```cpp
auto resp = HttpResponse::newHttpResponse();
resp->setContentTypeCode(CT_APPLICATION_JSON);
resp->setStatusCode(k200OK);
resp->setBody(ResponseUtil::GenerateSuccessResponse(data).dump());
callback(resp);
```

## 字段命名

- 请求体、响应体、配置文件统一 `snake_case`
- 禁止在 JSON 中混用 `camelCase`

## 响应约定

- 响应结构和状态码语义以当前模块现状为准（不要凭空定义新格式）
- 错误码与错误文案保持稳定，避免前后端契约漂移

## 日志与错误信息

- 先复用同模块既有日志前缀和措辞
- 对外错误信息默认中文（除非该接口已约定英文）
- 不要无故把已有中文日志改成英文

## 文档同步

- 改后端接口时，必须同步更新该模块 `docs/接口文档.md`
- 若前端有 API 封装，同提交同步更新封装层
- 新增接口时补齐：路径、方法、参数、成功/失败示例
- **每次新增或修改协议时，必须同步更新 `collector/docs/协议支持清单.md` 文档**
- **每次新增协议或修改协议细节时，必须在 `collector/docs/protocols/` 下新增或更新对应的协议实现文档，并且文档内强制要求写入底层依赖库来源及其具体安装/编译方式**

## 协议开发规范

- **新增协议驱动时，严禁在应用层类中直接调用底层的原生 API（如原生 Socket API、原生串口操作函数等），除非有特殊需求需要和我确认。**
- **必须注入并使用通用的公共类进行通信，例如：**
  - TCP 连接使用 `TcpTransport`
  - UDP 连接使用 `UdpTransport`
  - 串口连接使用 `SerialTransport`
  - 这些类均应继承自核心抽象接口 `ITransport`。

## 协议配置规范

> 详细规则参见 `collector/docs/协议支持清单.md` 的"更新规范"章节。

### protocol_name

- 全大写 + 下划线：`MODBUS_TCP`、`FINS_TCP`
- 同一协议不同连接方式**拆分为独立条目**，后缀：`_TCP`/`_RTU`/`_SERIAL`/`_OVERTCP`
- 驱动注册标识必须与 `protocol_name` 完全一致

### brand

- 有品牌协议：使用品牌原名，不附加连接方式或描述
- 通用协议（Modbus/OPC UA）：使用标准协议名
- 无品牌行业标准：使用**应用领域**（如 `"电力仪表"`, `"水气仪表"`），避免与 protocol_name 重复
- ✅ `"西门子"`, `"电力仪表"` / ❌ `"哈斯串口"`, `"IEC104"`（与 protocol_name 冗余）

### connection_type

- 每个协议条目只允许一种 `connection_type`（`"ethernet"` 或 `"serial"`）
- 需要同时支持串口和以太网时，新增独立协议条目