From b6006e0dfea09f9061aa70098e7387efc59e18a3 Mon Sep 17 00:00:00 2001
From: yexb <553699424@qq.com>
Date: Thu, 14 May 2026 16:28:48 +0800
Subject: [PATCH] docs: add steady trend page design

---
 ...5-14-steady-data-view-trend-page-design.md | 237 ++++++++++++++++++
 1 file changed, 237 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-14-steady-data-view-trend-page-design.md

diff --git a/docs/superpowers/specs/2026-05-14-steady-data-view-trend-page-design.md b/docs/superpowers/specs/2026-05-14-steady-data-view-trend-page-design.md
new file mode 100644
index 0000000..f1c1719
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-14-steady-data-view-trend-page-design.md
@@ -0,0 +1,237 @@
+# 稳态数据历史趋势页面设计
+
+## 1. 背景
+
+当前 `frontend/src/views/steady/steadyDataView/index.vue` 是稳态数据分页列表页，已接入：
+
+- `POST /steady/data/view/page`
+- `POST /steady/data/view/export`
+
+同目录下已有 `2026-05-14-steady-data-view-trend-design.md`，定义了稳态历史趋势能力：台账树、指标树、趋势查询、按天加载、统计摘要和谐波展示策略。
+
+本次页面设计按用户确认的 B 方案执行：直接将当前 `steadyDataView` 页面改造成“稳态历史趋势”页面，暂不保留原分页列表视图。
+
+## 2. 已确认范围
+
+### 2.1 页面目标
+
+在 `steadyDataView` 页面内展示稳态历史趋势工作台，用于先验证趋势页面交互和展示结构。
+
+### 2.2 数据来源
+
+- 台账树使用真实数据，优先复用 `tools/addLedger` 的 `getAddLedgerTree()`。
+- 指标树使用前端模拟数据。
+- 趋势曲线使用前端模拟数据。
+- 当前范围统计摘要使用前端模拟数据。
+- 谐波趋势、谱图和 TopN 第一版均使用模拟数据和模拟面板，不接真实后端。
+
+### 2.3 不在本次范围
+
+- 不实现 InfluxDB 真实查询。
+- 不新增后端接口。
+- 不保留原稳态分页表入口。
+- 不执行重型构建、打包或 Electron 构建。
+
+## 3. 推荐方案
+
+采用“真实台账 + 前端模拟趋势”的最小落地方案。
+
+页面入口仍为：
+
+- `frontend/src/views/steady/steadyDataView/index.vue`
+
+页面按现有复杂页面拆分约定维护：
+
+- `index.vue` 只保留布局编排、顶层状态、接口调用流程和事件分发。
+- `components/` 放台账树、指标树、查询工具栏、趋势图、统计摘要等展示组件。
+- `utils/` 放指标目录、台账归一化、模拟趋势生成、统计计算、图表配置构造等纯函数。
+
+该方案后续接真实接口时，只需要将 `utils/mockTrendData` 替换为 API 调用，并保持组件 props / emits 基本稳定。
+
+## 4. 页面布局
+
+页面采用三栏工作台结构，不叠加页面级外边距，跟随 `el-main` 默认 `15px` 内容区。
+
+### 4.1 顶部查询区
+
+顶部查询区固定在页面上方，包含：
+
+- 时间范围选择，默认近 24 小时。
+- 统计类型选择：平均值、最大值、最小值、CP95。
+- 相别选择：A、B、C 或 T，根据当前指标动态可用。
+- 查询按钮。
+- 重置按钮。
+
+查询按钮使用 `type="primary"`，重置使用 `type="primary" plain`。
+
+### 4.2 左侧台账树
+
+左侧上半区展示真实台账树：
+
+- 工程
+- 项目
+- 设备
+- 监测点
+
+台账树支持搜索和勾选。
+
+选择规则：
+
+- 选中监测点时，直接作为趋势查询的测点。
+- 选中设备、项目、工程时，自动收集下级监测点。
+- 第一版前端限制最多 8 个监测点参与查询，超过时给出提示。
+
+当真实台账接口不可用或返回空时，页面显示空状态，不自动伪造台账树。这样可以明确区分真实台账数据与模拟趋势数据。
+
+### 4.3 左侧指标树
+
+左侧下半区展示模拟指标树，分组包括：
+
+- 电压趋势
+- 电流趋势
+- 频率趋势
+- 谐波趋势
+- 功率趋势
+- 闪变趋势
+
+指标叶子节点包含：
+
+- 指标编码
+- 指标名称
+- 单位
+- 支持相别
+- 支持统计类型
+- 是否谐波指标
+
+查询模式限制：
+
+- 多测点查询时，只允许选择一个指标。
+- 单测点查询时，允许选择多个指标，最多 8 个。
+- 单次生成曲线不超过 24 条，超过时提示缩小选择范围。
+
+### 4.4 中间趋势图区
+
+中间区域展示 ECharts 折线图，复用已有 `frontend/src/components/echarts/line/index.vue`。
+
+图表能力：
+
+- 多序列折线。
+- 图例开关。
+- tooltip。
+- dataZoom。
+- 采样信息展示，包括原始点数、展示点数、bucket。
+
+趋势点位由前端根据当前测点、指标、相别、统计类型和时间范围生成模拟数据。模拟数据应保持不同指标的数值区间差异，例如：
+
+- 电压约 `210-235V`
+- 电流约 `20-120A`
+- 频率约 `49.8-50.2Hz`
+- 功率约 `20-900kW`
+- 闪变约 `0.2-1.2`
+- 谐波含量约 `0-8%`
+
+### 4.5 右侧统计摘要
+
+右侧展示当前查询结果的统计摘要：
+
+- 最大值
+- 平均值
+- 最小值
+- CP95
+
+摘要以序列为维度展示，可滚动。每个摘要项展示测点、指标、相别、统计类型、单位和值。
+
+### 4.6 谐波扩展区
+
+当选中谐波类指标时，趋势图上方显示：
+
+- 谐波次数选择，范围 2-50，第一版默认选 3、5、7 次。
+- 趋势 / 谱图 / TopN 切换。
+
+第一版规则：
+
+- 趋势模式展示所选谐波次数的模拟趋势曲线。
+- 谱图模式展示当前时刻的模拟谐波柱状数据。
+- TopN 模式展示当前范围内模拟 TopN 排名。
+
+## 5. 数据流
+
+### 5.1 初始化
+
+1. 页面加载。
+2. 调用 `getAddLedgerTree()` 获取真实台账树。
+3. 归一化台账节点。
+4. 初始化指标树和默认查询条件。
+5. 如果存在可用监测点，则默认选中第一个监测点和第一个电压指标，生成模拟趋势。
+
+### 5.2 查询
+
+1. 用户选择台账节点、指标、相别、统计类型和时间范围。
+2. 页面构造查询上下文。
+3. 执行前端限制校验。
+4. 调用模拟数据生成函数。
+5. 生成图表 option 和统计摘要。
+6. 更新趋势图与右侧摘要。
+
+### 5.3 重置
+
+重置恢复：
+
+- 默认近 24 小时时间范围。
+- 默认统计类型为平均值。
+- 默认相别为 A、B、C。
+- 默认选中首个可用测点和电压有效值指标。
+
+## 6. 文件设计
+
+预计新增或修改：
+
+- `frontend/src/views/steady/steadyDataView/index.vue`
+- `frontend/src/views/steady/steadyDataView/components/TrendToolbar.vue`
+- `frontend/src/views/steady/steadyDataView/components/TrendLedgerTree.vue`
+- `frontend/src/views/steady/steadyDataView/components/TrendIndicatorTree.vue`
+- `frontend/src/views/steady/steadyDataView/components/TrendChartPanel.vue`
+- `frontend/src/views/steady/steadyDataView/components/TrendSummaryPanel.vue`
+- `frontend/src/views/steady/steadyDataView/components/types.ts`
+- `frontend/src/views/steady/steadyDataView/utils/ledgerTree.ts`
+- `frontend/src/views/steady/steadyDataView/utils/indicatorCatalog.ts`
+- `frontend/src/views/steady/steadyDataView/utils/mockTrendData.ts`
+- `frontend/src/views/steady/steadyDataView/utils/trendChart.ts`
+- `frontend/src/views/steady/steadyDataView/utils/trendQuery.ts`
+
+现有 `utils/queryParams.ts` 只服务原列表页。页面替换后可保留不引用，避免额外删除历史代码；如果类型检查或 lint 提示未使用，再按最小范围清理本次造成的问题。
+
+## 7. 样式原则
+
+- 不使用营销式 hero。
+- 不额外叠加页面级外边距。
+- 工作区以紧凑、可扫描为主。
+- 卡片只用于明确的工具面板，不做多层卡片嵌套。
+- 按钮沿用业务页按钮约定。
+- 图表区域需要稳定高度，避免查询条件变化造成布局跳动。
+
+## 8. 验证方案
+
+默认不执行重型构建。
+
+建议验证：
+
+1. 代码结构：`index.vue` 只保留编排、状态和事件分发。
+2. 台账真实数据：页面调用 `getAddLedgerTree()`，空数据时显示空状态。
+3. 指标模拟数据：指标树包含电压、电流、频率、谐波、功率、闪变分组。
+4. 查询限制：多测点多指标、超 8 测点、超 8 指标、超 24 曲线时有明确提示。
+5. 图表展示：查询后折线图、图例、tooltip、dataZoom 可用。
+6. 统计摘要：最大值、平均值、最小值、CP95 随当前模拟序列更新。
+7. 谐波模式：选择谐波指标后显示次数选择和模式切换。
+8. 轻量命令：优先执行 `cd frontend; npm run type-check`，必要时执行 `npm run lint`。
+
+## 9. 风险与注意事项
+
+- 台账接口是真实数据，页面需要处理接口失败、空树和节点字段大小写不一致。
+- 趋势和统计是模拟数据，界面上应避免让用户误以为已经接入 InfluxDB。
+- 当前页面替换原列表后，原导出入口会暂时不可见。
+- 后续接真实趋势接口时，需要补充 API 类型、接口封装和异常处理。
+
+## 10. 结论
+
+本设计按用户确认的 B 方案将 `steadyDataView` 直接改造为稳态历史趋势页面。第一版使用真实台账树验证业务选择路径，其余趋势相关数据全部使用前端模拟数据，以最小改动先完成页面结构、交互和视觉验证。