CN_Tool/steady/steady-DataView/API_DEBUG.md

# 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` 查询。