240 lines
7.1 KiB
Markdown
240 lines
7.1 KiB
Markdown
# 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` 查询。
|