---
name: wind-backend-conventions
description: wind_power_cal 后端 Drogon 规范。用于新增/修改后端 Controller、接口、响应、配置时，遵循 HttpController 模式与统一响应信封。
---

# 后端 Drogon 规范

## 新增 Controller
1. `backend/src/controllers/XxxController.{h,cpp}`（CMake `GLOB_RECURSE src/*.cpp` 自动纳入，无需改 CMakeLists）
2. 头文件继承 `drogon::HttpController<XxxController>`，用 `METHOD_LIST_BEGIN / ADD_METHOD_TO / METHOD_LIST_END` 声明路由：
   ```cpp
   METHOD_LIST_BEGIN
   ADD_METHOD_TO(XxxController::GetXxx, "/api/xxx", Get);
   METHOD_LIST_END
   ```
3. handler 签名：`void GetXxx(const HttpRequestPtr&, std::function<void(const HttpResponsePtr&)>&& callback)`
4. `main.cpp` 注册：`app().registerController(std::make_shared<XxxController>());`

## 响应信封（必须遵守）
统一 `{"status":0,"msg":"success","data":{...}}`，用 `backend/src/utils/ResponseUtil.h`（header-only，自 edge_collector 复制）：
```cpp
#include "utils/ResponseUtil.h"
json data; data["version"] = "0.1.0";
SendSuccess(callback, data);          // 成功带数据
SendSuccess(callback);                // 成功无数据
SendError(callback, 1, "参数错误");   // 业务错误
SendForbidden(callback);             // 无权限（code 3, 403）
```

## include / 命名空间
- `#include <nlohmann/json.hpp>`（third_party/nlohmann 已在 include path）
- `main.cpp` 必须 `using namespace drogon;`，否则 `app()` / `HttpResponse` / `CT_TEXT_HTML` 未声明

## 配置 / SPA
- `backend/config/server_config.json`：listener（默认 :8848）、CORS、`document_root ./web`
- SPA 回退：`app().setCustom404Page(HttpResponse::newFileResponse("./web/index.html","",CT_TEXT_HTML), false)`

## 现有 Controller
- `SystemController`：`/api/system/health`、`/api/system/version`
- `WindPowerController`：风电功率计算业务接口