Files

2026-05-14 15:52:32 +08:00

13 KiB

Raw Permalink Blame History

steady-DataView 稳态历史趋势设计方案

目标

在 steady/steady-DataView 中新增稳态历史趋势查看能力，用于展示 InfluxDB 中的稳态数据历史趋势图。数据结构与 tools/add-data 中的 13 张 data_* 表字段保持一致，但查询数据源改为 InfluxDB 时序库。

本方案只设计后端接口、查询模型、页面交互和性能策略，不包含代码实现。

当前上下文

steady-DataView 当前已有 /steady/data-view/page、/detail、/templates，主要面向 MySQL 稳态数据分页、详情和模板查询。
tools/add-data 已维护 13 张稳态数据表定义，字段包含基础字段 TIMEID、LINEID、PHASIC_TYPE、QUALITYFLAG，以及业务值字段和 _MAX、_MIN、_CP95 等统计字段。
tools/add-ledger 已提供台账树能力，层级固定为：工程 -> 项目 -> 设备 -> 监测点。
tools/wave-tool 已有趋势图点位返回结构，可参考 points、sampled、displayPointCount 等概念。

总体方案

新增趋势查看能力时，steady-DataView 负责统一编排：

从 add-ledger 复用台账层级，生成趋势页面左侧监测点设备树。
从稳态指标目录生成指标树，指标范围覆盖电压、电流、频率、谐波、功率、闪变。
将页面选择的监测点、指标、相别、统计类型、时间范围转换成 InfluxDB 查询。
返回趋势图可直接消费的多序列点位数据。
按天和分桶粒度动态加载，避免大范围一次性返回明细点。

保留现有分页和详情接口，不在本次设计中移除。

左侧设备树

页面左侧展示台账监测点设备树，口径参照 add-ledger：

工程（设备数 / 监测点数）
  项目（设备数 / 监测点数）
    设备（监测点数）
      监测点

数量统计口径：

台账节点：cs_ledger.State = 1
设备：cs_equipment_delivery.run_status <> 0
监测点：cs_line.status = 1
设备数：当前节点下有效设备数量
监测点数：当前节点下有效监测点数量

建议新增趋势专用接口：

GET /steady/data-view/ledger-tree

返回字段：

{
  "id": "project-001",
  "parentId": "engineering-001",
  "name": "10kV一号站",
  "level": 1,
  "sort": 0,
  "deviceCount": 4,
  "lineCount": 28,
  "selectable": false,
  "children": []
}

节点选择规则：

监测点节点可直接作为趋势查询的 lineId。
设备节点选中时，等价于选中其下全部有效监测点。
工程、项目节点选中时，等价于选中其下全部有效监测点，但需要做数量限制。
搜索设备名或监测点名时，应保留完整父级路径，避免返回孤立节点。

指标树

新增趋势指标树接口：

GET /steady/data-view/indicator-tree

指标分组沿用用户提供的结构：

电压趋势
电流趋势
频率趋势
谐波趋势
功率趋势
闪变趋势

后端不直接散落前端 JS 节点，而是维护统一指标目录。每个叶子指标建议包含：

{
  "indicatorCode": "V_RMS",
  "name": "相电压有效值",
  "groupCode": "VOLTAGE",
  "tableName": "data_v",
  "baseFields": ["RMS"],
  "phaseCodes": ["A", "B", "C"],
  "seriesFields": [
    {
      "field": "RMS",
      "name": "相电压有效值"
    }
  ],
  "supportStats": ["AVG", "MAX", "MIN", "CP95"],
  "harmonic": false,
  "harmonicOrderStart": null,
  "harmonicOrderEnd": null,
  "unit": "V"
}

普通指标通过 baseFields 映射到 InfluxDB field。phaseCodes 用于约束 PHASIC_TYPE 查询条件，seriesFields 用于描述一个指标最终生成几条曲线。谐波指标通过 fieldPrefix + harmonicOrder + statSuffix 生成字段，如 V_5、V_5_MAX、V_5_MIN、V_5_CP95。

部分指标只支持 T 相，不能套用全局 A/B/C/T 相别选择。指标树只负责选择业务指标，相别选择由当前指标目录动态驱动：

phaseCodes = ["A", "B", "C"] 的指标，页面展示 A/B/C 相别选择，默认可全选。
phaseCodes = ["T"] 的指标，页面固定为 T 相，可隐藏相别选择或显示为“总量/三相统计”。
单监测点多指标查询时，每个指标按自己的 phaseCodes 生成曲线，不强制取多个指标的相别交集。
多监测点单指标查询时，按该指标的 phaseCodes 展示相别选择。

T 相不一定只对应一条曲线。例如线电压有效值使用 PHASIC_TYPE = 'T' 过滤，但会展开 RMSAB、RMSBC、RMSCA 三条曲线：

{
  "indicatorCode": "V_LINE_RMS",
  "name": "线电压有效值",
  "tableName": "data_v",
  "phaseCodes": ["T"],
  "seriesFields": [
    {
      "field": "RMSAB",
      "name": "AB线电压"
    },
    {
      "field": "RMSBC",
      "name": "BC线电压"
    },
    {
      "field": "RMSCA",
      "name": "CA线电压"
    }
  ],
  "supportStats": ["AVG", "MAX", "MIN", "CP95"],
  "unit": "V"
}

InfluxDB 配置

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

本地密码可配置为 123456，但不建议提交明文密码到仓库配置文件。

从截图判断当前更接近 InfluxDB 1.x 连接方式，查询方案优先按 InfluxQL 设计。如实际为 InfluxDB 2.x，需要将 database 改为 bucket/org/token 模型。

InfluxDB 数据模型

建议保持与 add-data 表结构一致：

measurement：沿用表名，如 data_v、data_i、data_harmrate_v
time：InfluxDB 内置时间，等价原 TIMEID
tag：LINEID、PHASIC_TYPE、QUALITYFLAG
field：沿用原业务字段，如 RMS、RMS_MAX、RMS_MIN、RMS_CP95

查询时必须使用 AddDataTableRegistry 或趋势指标目录做 measurement 和 field 白名单校验，禁止前端传任意表名或字段名直接拼接查询。

趋势查询接口

建议新增：

POST /steady/data-view/trend/query
POST /steady/data-view/trend/day
POST /steady/data-view/trend/summary

trend/query 用于首次查询，返回图表元数据、首屏数据和可加载日期范围。

trend/day 用于按天动态加载。前端切换日期、拖动缩放或需要补齐某天数据时调用。

请求示例：

{
  "lineIds": ["line-001"],
  "indicatorCodes": ["V_RMS", "FREQ"],
  "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": 86400,
  "displayPointCount": 144,
  "series": [
    {
      "seriesKey": "line-001|V_RMS|A|AVG",
      "lineId": "line-001",
      "lineName": "进线一",
      "indicatorCode": "V_RMS",
      "indicatorName": "相电压有效值",
      "phase": "A",
      "statType": "AVG",
      "unit": "V",
      "points": [
        {
          "time": "2026-05-01 00:00:00",
          "value": 220.1
        }
      ]
    }
  ]
}

trend/summary 返回当前查询范围或当前可视窗口内的统计值：

{
  "items": [
    {
      "seriesKey": "line-001|V_RMS|A",
      "max": 232.1,
      "avg": 220.4,
      "min": 214.8,
      "cp95": 228.7
    }
  ]
}

统计口径

统计类型包括：

MAX：最大值
AVG：平均值
MIN：最小值
CP95：95% 概率大值

优先读取已有统计字段：

AVG 读取基础字段，如 RMS、FREQ、V_5
MAX 读取 _MAX 字段
MIN 读取 _MIN 字段
CP95 读取 _CP95 字段

如果某些表没有独立统计字段，如部分闪变和波动字段，则接口应在指标目录中标明不支持的统计类型，前端禁用对应选项。仅在明确需要时才使用 InfluxDB 动态聚合兜底。

查询模式限制

支持两种主要查询模式：

一个监测点，多指标
多个监测点，一个指标

为了保证图表可读性和查询效率，建议限制：

普通趋势：最多 8 个监测点或 8 个指标。
多监测点查询时，默认只允许 1 个指标。
单监测点查询时，可选择多个指标。
多指标混查时，每个指标使用自己的相别配置，避免 A/B/C 指标与 T 相指标交集为空导致无法查询。
单次序列数量建议不超过 24 条，超过时提示缩小监测点、指标、相别或统计类型范围。

谐波展示方案

谐波类包含 2~50 次谐波，不适合一次性全部画趋势线。建议拆成三种展示：

趋势图模式
- 用户选择谐波类型后，再选择 1 到 6 个谐波次数。
- 只展示被选次数随时间变化。
- 适合观察 3、5、7、11、13 次等重点谐波。
谐波谱模式
- 用户在趋势图上选中某个时间点。
- 展示该时刻 2~50 次谐波柱状图。
- 适合查看单个时刻的谐波分布。
TopN 模式
- 后端按当前时间范围统计每个谐波次数的 MAX 或 CP95。
- 默认返回 Top 10。
- 适合快速定位主要谐波次数。

谐波趋势默认禁止直接加载 2~50 全部次数。必须指定 harmonicOrders 或使用 topN。

按天动态加载

前端首次查询时只加载当前可视范围或默认第一天数据。用户滚动、缩放、切换日期时按天请求。

后端按时间范围自动给出建议 bucket：

范围小于 6 小时：1m
6 小时到 1 天：5m 或 10m
1 天到 7 天：按天加载，每天 10m 或 30m
大于 7 天：优先按天加载摘要，进入某天后再加载细节

接口返回 sampled、sourcePointCount、displayPointCount，前端可提示当前是否已下采样。

缓存策略

建议增加短期查询缓存，缓存 key 包含：

lineIds + indicatorCodes + phases + statTypes + day + bucket + qualityFlag

缓存粒度以单日为主，避免一个大时间范围缓存过大。缓存只用于趋势点位，不缓存配置密码和连接对象以外的敏感信息。

页面布局

推荐布局：

顶部：时间范围 / 相别 / 统计类型 / 查询 / 重置

左侧：
  台账监测点树
  - 工程、项目、设备、监测点
  - 显示设备数、监测点数
  - 支持搜索与勾选

左侧下方或中左：
  稳态指标树
  - 电压趋势
  - 电流趋势
  - 频率趋势
  - 谐波趋势
  - 功率趋势
  - 闪变趋势

中间：
  趋势图
  - 折线图
  - 图例开关
  - tooltip
  - 缩放联动
  - 按天动态加载

右侧：
  当前范围统计
  - 最大值
  - 平均值
  - 最小值
  - CP95

谐波类指标被选中时，趋势图上方增加：

谐波次数选择器
趋势 / 谱图 / TopN 切换

后端模块划分

建议在 steady-DataView 中按职责拆分：

SteadyDataViewLedgerController：趋势页面台账树
SteadyDataViewIndicatorController：指标树
SteadyDataViewTrendController：趋势查询、按天加载、统计摘要
SteadyDataViewLedgerService：复用 add-ledger 口径生成带数量的树
SteadyDataViewIndicatorService：维护指标目录和字段映射
SteadyDataViewTrendService：参数校验、查询编排、结果组装
SteadyInfluxQueryComponent：InfluxDB 查询封装
SteadyTrendFieldResolver：指标到 measurement/field 的白名单转换

保留现有 SteadyDataViewController 的分页、详情、模板职责，不继续把所有新接口堆到一个大 Controller。

验证方式

方案落地后，默认验证不执行 Maven 构建，除非用户明确要求。

建议检查：

配置检查：InfluxDB 配置项可被 Spring Boot 读取，密码未硬编码提交。
指标映射检查：所有指标都能解析到合法 measurement 和 field。
台账树检查：设备数、监测点数与 add-ledger 有效数据口径一致。
查询限制检查：超出监测点、指标、谐波次数限制时返回明确提示。
查询语句检查：InfluxDB 查询必须带时间范围、LINEID 和必要 tag 条件。
趋势返回检查：返回 series、points、统计摘要结构稳定，前端可直接绘图。
谐波检查：趋势模式不默认返回 2~50 全部次数，谱图和 TopN 按独立接口或模式返回。

分期建议

第一期：

InfluxDB 可配置连接
台账监测点树，包含设备数和监测点数
稳态指标树
普通指标趋势查询
最大值、平均值、最小值、CP95
按天动态加载
谐波趋势支持手动选择次数

第二期：

谐波谱图
谐波 TopN
查询缓存优化
大范围摘要视图
前端交互细节优化

待确认事项

InfluxDB 版本是否确定为 1.x。
生产环境 InfluxDB measurement 是否完全沿用 data_* 表名。
QUALITYFLAG 在 InfluxDB 中是否作为 tag 保存。
谐波相角、间谐波等字段命名是否与 add-data 当前 SQL 完全一致。
前端是否已有可复用的 ECharts 趋势图组件，还是只参考 waveform 返回结构重新接入。

13 KiB Raw Permalink Blame History Unescape Escape