7.1 KiB
7.1 KiB
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
请求示例：
{
"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>
请求示例：
{
"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>
请求示例：
{
"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
}
返回示例：
{
"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 个：
{
"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。
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当前与实际返回点数一致，未额外发 InfluxDBcount查询。