wind_power_cal/.agents/skills/backend-conventions/SKILL.md

name, description

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

后端规范

JSON 规则

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

Drogon 响应构建

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

示例：

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"）
• 需要同时支持串口和以太网时，新增独立协议条目