我叫洪圣文

2026-05-15 16:36:50 +08:00
parent b6006e0dfe
commit 6687cf0339
36 changed files with 2201 additions and 271 deletions
--- a/frontend/src/views/steady/steadyDataView/API_DEBUG.md
+++ b/frontend/src/views/steady/steadyDataView/API_DEBUG.md
@@ -0,0 +1,239 @@
+# steady-DataView API 调试文档
+
+## 1. 基础信息
+
+- 模块：`steady/steady-DataView`
+- 控制器：`SteadyDataViewController`
+- 接口前缀：`/steady/data-view`
+- 本地默认地址：`http://localhost:18192`
+- Content-Type：`application/json`
+- 认证：除登录和 Swagger 资源外，请求需要携带登录后的 `Authorization` 头。
+
+## 2. 分页查询稳态数据
+
+- 路径：`POST /steady/data-view/page`
+- 返回：`HttpResult<Page<SteadyDataViewVO>>`
+- 默认表：`data_v`
+- 默认时间范围：当前月 1 日 `00:00:00` 到当前时间
+- 默认排序：`TIMEID DESC, LINEID ASC, PHASIC_TYPE ASC`
+
+请求示例：
+
+```json
+{
+  "pageNum": 1,
+  "pageSize": 10,
+  "tableName": "data_v",
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-09 23:59:59",
+  "phasicType": "A",
+  "qualityFlag": 1,
+  "lineIds": [
+    "line-001"
+  ],
+  "engineeringName": "示例工程",
+  "projectName": "示例项目",
+  "equipmentName": "示例设备",
+  "lineName": "示例测点"
+}
+```
+
+`tableName` 只允许 `tools/add-data` 已注册的 13 张 `data_*` 表；台账关键字会先通过 `add-ledger` 转换为监测点 ID，再查询稳态数据表。
+
+## 3. 查询稳态数据详情
+
+- 路径：`POST /steady/data-view/detail`
+- 返回：`HttpResult<SteadyDataViewVO>`
+
+请求示例：
+
+```json
+{
+  "tableName": "data_v",
+  "lineId": "line-001",
+  "timeId": "2026-05-09 10:20:30",
+  "phasicType": "A"
+}
+```
+
+详情使用 `LINEID + TIMEID + PHASIC_TYPE` 定位单条数据。
+
+## 4. 查询稳态数据模板
+
+- 路径：`GET /steady/data-view/templates`
+- 返回：`HttpResult<List<SteadyDataViewTemplateVO>>`
+
+模板来自 `tools/add-data` 的前端展示模板，返回参数名称、表名、相别和当前表可展示值字段。
+
+## 5. 查询趋势台账树
+
+- 路径：`GET /steady/data-view/ledger-tree`
+- 返回：`HttpResult<List<SteadyDataViewLedgerNodeVO>>`
+- 查询参数：`keyword`，可选，按台账节点名称搜索并保留父级路径。
+
+节点字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 台账节点 ID |
+| `parentId` | 父节点 ID |
+| `name` | 节点名称 |
+| `level` | 层级：0 工程，1 项目，2 设备，3 监测点 |
+| `deviceCount` | 当前节点下有效设备数 |
+| `lineCount` | 当前节点下有效监测点数 |
+| `selectable` | 是否可直接选择 |
+| `children` | 子节点 |
+
+## 6. 查询趋势指标树
+
+- 路径：`GET /steady/data-view/indicator-tree`
+- 返回：`HttpResult<List<SteadyDataViewIndicatorNodeVO>>`
+
+当前指标目录覆盖：
+
+- 电压趋势：`V_RMS`、`V_LINE_RMS`
+- 电流趋势：`I_RMS`
+- 频率趋势：`FREQ`
+- 谐波趋势：`V_THD`、`I_THD`、`V_HARMONIC`、`I_HARMONIC`、`V_HARMONIC_RATE`、`I_HARMONIC_RATE`、`I_INTER_HARMONIC`、`P_HARMONIC_POWER`、`Q_HARMONIC_POWER`、`S_HARMONIC_POWER`
+- 闪变趋势：`FLUC`、`PST`、`PLT`
+
+叶子节点会返回 `tableName`、`phaseCodes`、`seriesFields`、`supportStats`、`harmonicOrderStart`、`harmonicOrderEnd`、`unit`，前端按这些字段驱动相别、统计类型和谐波次数选择。
+
+## 7. 查询趋势数据
+
+- 路径：`POST /steady/data-view/trend/query`
+- 返回：`HttpResult<SteadyTrendQueryVO>`
+
+请求示例：
+
+```json
+{
+  "lineIds": ["line-001"],
+  "indicatorCodes": ["V_RMS"],
+  "statTypes": ["AVG", "MAX", "MIN", "CP95"],
+  "phases": ["A", "B", "C"],
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59",
+  "bucket": "10m",
+  "qualityFlag": 1
+}
+```
+
+返回示例：
+
+```json
+{
+  "sampled": true,
+  "bucket": "10m",
+  "sourcePointCount": 144,
+  "displayPointCount": 144,
+  "loadableDays": ["2026-05-01"],
+  "series": [
+    {
+      "seriesKey": "line-001|V_RMS|A|AVG|RMS",
+      "lineId": "line-001",
+      "lineName": "进线一",
+      "indicatorCode": "V_RMS",
+      "indicatorName": "相电压有效值",
+      "seriesName": "相电压有效值",
+      "phase": "A",
+      "statType": "AVG",
+      "unit": "V",
+      "points": [
+        {
+          "time": "2026-05-01 00:00:00",
+          "value": 220.1
+        }
+      ]
+    }
+  ]
+}
+```
+
+谐波请求必须指定 `harmonicOrders`，最多 6 个：
+
+```json
+{
+  "lineIds": ["line-001"],
+  "indicatorCodes": ["V_HARMONIC"],
+  "statTypes": ["MAX"],
+  "phases": ["A"],
+  "harmonicOrders": [3, 5, 7],
+  "timeStart": "2026-05-01 00:00:00",
+  "timeEnd": "2026-05-01 23:59:59",
+  "bucket": "10m",
+  "qualityFlag": 1
+}
+```
+
+## 8. 按天查询趋势数据
+
+- 路径：`POST /steady/data-view/trend/day`
+- 返回：`HttpResult<SteadyTrendQueryVO>`
+
+请求体与 `/trend/query` 一致。前端切换日期或加载某一天数据时，将 `timeStart`、`timeEnd` 控制在当天范围即可。
+
+## 9. 查询趋势统计摘要
+
+- 路径：`POST /steady/data-view/trend/summary`
+- 返回：`HttpResult<SteadyTrendSummaryVO>`
+
+请求体与 `/trend/query` 一致。后端按当前查询范围返回每条曲线的 `max`、`avg`、`min`、`cp95`。
+
+## 10. InfluxDB 配置
+
+配置项前缀：`steady.influxdb`。
+
+```yaml
+steady:
+  influxdb:
+    url: http://192.168.1.103:18086
+    database: pqsbase
+    username: admin
+    password: ${STEADY_INFLUXDB_PASSWORD:}
+    ssl: false
+    connect-timeout-ms: 5000
+    read-timeout-ms: 30000
+```
+
+接口按 InfluxDB 1.x InfluxQL `/query` 方式访问。代码不会提交明文密码；本地密码请通过环境变量或本地覆盖配置提供。
+
+## 11. 返回字段说明
+
+| 字段 | 说明 |
+| --- | --- |
+| `tableName` | 数据表名 |
+| `lineId` | 监测点 ID |
+| `timeId` | 数据时间 |
+| `phasicType` | 相别 |
+| `qualityFlag` | 质量标识 |
+| `equipmentName` | 设备名称，台账缺失时为 `-` |
+| `engineeringName` | 工程名称，台账缺失时为 `-` |
+| `projectName` | 项目名称，台账缺失时为 `-` |
+| `lineName` | 监测点名称，台账缺失时为 `-` |
+| `values` | 动态指标字段，字段名与目标 `data_*` 表保持一致 |
+
+## 12. 常见错误场景
+
+| 场景 | 后端提示 |
+| --- | --- |
+| 表名不在 add-data 注册表范围内 | `稳态数据表不支持：xxx` |
+| 开始时间大于结束时间 | `开始时间不能大于结束时间` |
+| 时间格式无法解析 | `时间格式不正确，仅支持 yyyy-MM-dd HH:mm:ss` |
+| 相别不为 `A/B/C/T` | `相别只能是 A、B、C、T` |
+| 质量标识不为 `0/1` | `质量标识只能是 0 或 1` |
+| `lineIds` 超过 1000 个 | `监测点 ID 查询数量不能超过 1000 个` |
+| 台账关键字匹配监测点超过 1000 个 | `台账检索匹配监测点过多，请缩小查询条件` |
+| 趋势监测点为空 | `监测点 ID 不能为空` |
+| 趋势指标为空 | `指标不能为空` |
+| 多监测点同时多指标查询 | `多监测点查询时只能选择 1 个指标` |
+| 趋势曲线超过 24 条 | `趋势曲线数量不能超过 24 条，请缩小监测点、指标、相别或统计类型范围` |
+| 谐波指标未传次数 | `谐波次数不能为空` |
+| 谐波次数超过 6 个 | `谐波次数最多选择 6 个` |
+| InfluxDB 未配置地址 | `InfluxDB 地址未配置` |
+
+## 13. 当前限制
+
+- 当前仅提供分页、详情和模板查询，未提供动态 Excel 导出。
+- 趋势接口已提供后端结构和 InfluxQL 查询封装，未做真实 InfluxDB 联调。
+- `sourcePointCount` 当前与实际返回点数一致，未额外发 InfluxDB `count` 查询。