复现已有算法

2026-07-14 15:43:18 +08:00
parent abebd2a683
commit 50b8111fd9
860 changed files with 182250 additions and 18 deletions
@@ -0,0 +1,238 @@
+# 接口文档
+
+## 通用响应
+
+后端接口统一返回：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {}
+}
+```
+
+`status` 为 `0` 表示成功，非 `0` 表示业务失败。
+
+## 系统接口
+
+### GET /api/system/health
+
+返回服务健康状态。
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "status": "ok"
+  }
+}
+```
+
+### GET /api/system/version
+
+返回服务版本信息。
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "name": "wind_power_cal",
+    "version": "0.1.0"
+  }
+}
+```
+
+## 风功率计算接口
+
+### POST /api/wind/jobs/start
+
+创建风功率计算任务。前端已完成 Excel 表头解析和字段映射，后端只保存任务元数据。
+
+请求：
+
+```json
+{
+  "files": [
+    {
+      "file_name": "01_风机历史数据.xls",
+      "row_count": 51906
+    }
+  ],
+  "mapping": {
+    "time": "时间",
+    "fan_id": "风机编号",
+    "wind_speed": "风速(m/s)",
+    "active_power": "有功功率(kW)",
+    "generator_speed": "发电机转速(rpm)"
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "job_id": "job_123"
+  }
+}
+```
+
+### POST /api/wind/jobs/chunk
+
+上传标准化后的数据分片。每行字段必须使用标准字段名。
+
+请求：
+
+```json
+{
+  "job_id": "job_123",
+  "chunk_index": 0,
+  "rows": [
+    {
+      "time": "2024-09-01 14:00:00",
+      "fan_id": "01#",
+      "wind_speed": 3.414,
+      "active_power": 114.3471,
+      "generator_speed": 1109.3143
+    }
+  ]
+}
+```
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "accepted_rows": 1
+  }
+}
+```
+
+### POST /api/wind/jobs/finish
+
+完成任务并执行清洗、排序、分箱和功率曲线计算。
+
+请求：
+
+```json
+{
+  "job_id": "job_123",
+  "options": {
+    "rated_power": 4800,
+    "rated_wind_speed": 18,
+    "power_step": 5,
+    "cleaning_wind_speed_step": 0.25,
+    "curve_wind_speed_step": 0.5,
+    "wind_speed_change_threshold": 1,
+    "iqr_lower_multiplier": 1.8,
+    "iqr_upper_multiplier": 2,
+    "minimum_generator_speed": 1,
+    "generator_speed_k": 0.9
+  }
+}
+```
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "summary": {
+      "raw_rows": 51906,
+      "valid_rows": 38017,
+      "invalid_rows": 13889,
+      "duplicate_rows": 0,
+      "limit_power_rows": 0,
+      "tip_speed_ratio_outlier_rows": 0,
+      "speed_power_outlier_rows": 0,
+      "invalid_reasons": {
+        "invalid_active_power": 13889,
+        "limit_power": 0,
+        "tip_speed_ratio_outlier": 0,
+        "speed_power_outlier": 0
+      },
+      "fan_count": 1
+    },
+    "fans": ["01#"],
+    "curves": {
+      "01#": [
+        {
+          "wind_speed_start": 3.0,
+          "wind_speed_end": 3.5,
+          "wind_speed": 3.25,
+          "sample_count": 120,
+          "average_power": 180.5,
+          "median_power": 176.2,
+          "stddev_power": 32.1,
+          "p25_power": 150.0,
+          "p75_power": 205.0,
+          "confidence": "脚本分箱"
+        }
+      ]
+    },
+    "bins": {
+      "01#": []
+    },
+    "scatter_points": {
+      "01#": [
+        {
+          "wind_speed": 3.414,
+          "active_power": 114.3471
+        }
+      ]
+    },
+    "filtered_points": {
+      "01#": [
+        {
+          "wind_speed": 5.2,
+          "active_power": 430.0,
+          "reason": "speed_power_outlier"
+        }
+      ]
+    }
+  }
+}
+```
+
+清洗规则：
+
+- `active_power <= 0` 的数据剔除。
+- `generator_speed < generator_speed_k * minimum_generator_speed` 的数据剔除。
+- 时间不可解析的数据剔除。
+- 风机编号为空的数据剔除。
+- `wind_speed <= 0` 的数据剔除。
+- 同一风机同一时间重复记录保留第一条。
+- 限功率识别按参考脚本执行：按功率分箱、按日期分组，组内风速跨度大于阈值时剔除。
+- 叶尖速比使用参考脚本公式 `generator_speed * 3.14 * 162 * 78 * 30 / wind_speed`，按风速分箱做 IQR 清洗。
+- 风速-功率关系按同一风速分箱和 IQR 参数清洗。
+- 最终曲线按 `curve_wind_speed_step` 左开右闭分箱，区间非空即输出平均功率点。
+- `scatter_points` 返回清洗后保留点，`filtered_points` 返回限功率和 IQR 阶段滤除的点。
+
+### DELETE /api/wind/jobs/{job_id}
+
+清理未完成任务的临时文件。
+
+成功响应：
+
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": null
+}
+```