# 风机数据管理平台 — 健康评估子系统设计说明

| 项目 | 说明 |
|------|------|
| 文档版本 | V1.0 |
| 适用系统 | 健康评估子系统 |
| 文档类型 | 软件设计说明 |
| 适用对象 | 开发、测试、运维、项目交付 |
| 编制日期 | 2026-07-06 |

---

## 1. 设计概述

### 1.1 建设目标

健康评估子系统面向风电场运维与管理人员，对风场及单台风机的运行健康状态进行量化评分、分级展示与趋势分析。系统以 **风场（fieldCode）**、**分析日期（datatime）** 为统一查询维度，支持从首页驾驶舱汇总下钻至风场全景页，再下钻至单机组分项诊断，形成「总览 → 风场 → 机组」三级分析链路。

### 1.2 设计范围

| 范围 | 说明 |
|------|------|
| 包含 | 首页驾驶舱健康 Tab、健康评估仪表盘、机组详情抽屉、与健康相关的 API 联调与数据映射 |
| 不包含 | 异常检测、风资源尾流、数据入库/接入等并列子系统（仅说明驾驶舱跳转关系） |
| 遗留模块 | 振动分析（`health/vibration`）、故障诊断（`health/malfunction`）为历史页面，本设计以新版 `health/index` 为主 |

### 1.3 技术栈

| 层级 | 技术选型 |
|------|----------|
| 前端框架 | Vue 2.6 + Vue Router 3 + Vuex 3 |
| UI 组件 | Element UI |
| 图表 | ECharts 5 |
| 样式 | SCSS + CSS 变量多主题（`green/light/blue/dark/tech-blue`） |
| HTTP | Axios（健康接口独立实例 `healthRequest`，前缀 `/healthApi`） |
| 后端服务 | `energy-manage-analyse-service`（健康模块 3 个 POST 接口） |

---

## 2. 系统架构设计

### 2.1 逻辑架构

```
┌─────────────────────────────────────────────────────────────┐
│                    风机数据管理平台（前端）                    │
├──────────────┬──────────────────────────────┬─────────────────┤
│ 首页驾驶舱    │      健康评估仪表盘           │  组织/权限服务   │
│ CockpitHealth│  health/index + 子组件         │  /api 主网关     │
│ Panel        │  HealthHeader / Panels / Card│  ledger 组织树   │
└──────┬───────┴──────────────┬───────────────┴────────┬────────┘
       │                      │                        │
       │ getHealthscoresWindList│ getHealthOverview      │ getSysOrganization...
       │                      │ getLastDaysTrend       │
       └──────────────────────┴────────────────────────┘
                              │
                    /healthApi → energy-manage-analyse-service
                              /healthscores/*
```

### 2.2 模块划分

| 模块 | 路径 | 职责 |
|------|------|------|
| 驾驶舱健康面板 | `src/views/admin/cockpitManage/component/CockpitHealthPanel.vue` | 风场级优/良/中/差饼图与滚动表格，支持跳转健康页 |
| 健康仪表盘 | `src/views/health/index.vue` | 风场健康全景：评分环、子系统柱图、排行榜、风机卡片网格 |
| 查询头 | `src/views/health/components/health/HealthHeader.vue` | 组织树风场选择、日期选择（portal 至顶栏） |
| 数据映射 | `src/views/health/utils/healthDashboardMapper.js` | 将 `HealthOverviewVO` 转为 UI 模型 |
| 等级规则 | `src/views/health/utils/healthLevel.js` | 评分区间 → 优/良/中/差及颜色 |
| API 封装 | `src/api/healthAnalyse.js` | 健康分析 3 接口 |

---

## 3. 功能设计

### 3.1 首页驾驶舱 — 健康 Tab

**入口**：`/home/cockpitManage`，右侧面板 `CockpitHealthPanel`。

| 功能点 | 设计说明 |
|--------|----------|
| Tab 权限 | 「健康」Tab 需按钮权限 `home:health:btn`；无权限时 Tab 与内容区均不展示 |
| KPI 饼图 | 调用 `getHealthscoresWindList`，按风场聚合优/良/中/差台数并绘制环形图 |
| 风场列表 | `CockpitHealthTable` 展示各风场四档台数，支持自动滚动；点击风场名称跳转健康评估页 |
| 跳转状态 | 通过 `sessionStorage.cockpitHealthNavigateState` 传递 `fieldCode`、`datatime`，健康页 `created` 时消费 |

### 3.2 健康评估仪表盘

**路由**：动态菜单 `/home/health/index`（权限下发，`permissionUrl: /health/index.vue`）。

#### 3.2.1 页面布局

| 区域 | 组件 | 功能 |
|------|------|------|
| 顶栏工具 | `HealthHeader` | 风场树 + 分析日期 |
| 第一行 | `HealthScorePanel` | 全场健康度环形图 + 四档统计 |
| 第一行 | `HealthSubsystemPanel` | 子系统健康度柱状图 |
| 第一行 | `HealthRankingPanel` | 健康榜 / 预警榜 Top5，自动轮播 |
| 第二行 | `HealthUnitCard` 网格 | 单机组卡片，支持等级筛选与评分排序 |
| 详情 | `HealthUnitDetailDrawer` | 仪表评分、分项结构、近 N 天趋势折线 |

#### 3.2.2 健康等级划分

| 等级 | 评分区间 | 业务含义 |
|------|----------|----------|
| 优 | [90, 100] | 运行状态优秀 |
| 良 | [70, 90) | 运行状态良好 |
| 中 | [50, 70) | 运行状态一般，需关注 |
| 差 | (0, 50) | 运行状态较差，建议重点排查 |

实现位置：`healthLevel.js` 的 `resolveHealthLevel(score)`，颜色通过 CSS 变量 `--health-level-*` 注入。

#### 3.2.3 风机列表交互

- **筛选**：全部 / 优 / 良 / 中 / 差（`healthUnitListFilter.js`）
- **排序**：评分从高到低 / 从低到高
- **卡片点击**：打开详情抽屉，展示结构/系统/部件分项及趋势图

### 3.3 机组详情抽屉

| 数据项 | 来源 |
|--------|------|
| 静态分项 | 卡片 `unit.overview`（来自 `HealthOverviewListVO`）经 `unitDetailData.js` 映射 |
| 趋势折线 | `getLastDaysTrend({ day, engineId, fieldId, dateTime })` → `healthTrendMapper.js` → ECharts |

支持切换近 7 天 / 30 天（`day` 参数）。

---

## 4. 接口设计

### 4.1 服务前缀

- 开发代理：`/healthApi` → 分析服务网关
- 业务前缀：`/energy-manage-analyse-service/healthscores`
- 响应包装：`ResultResp<T>`，`code === 200` 为成功

### 4.2 接口清单

| 接口 | 方法 | 主要参数 | 用途 |
|------|------|----------|------|
| `getHealthOverview` | POST | `fieldCode`(必填), `datatime?` | 健康评估页：风场汇总 + 风机列表 |
| `getHealthscoresWindList` | POST | `fieldCode?`, `datatime?` | 驾驶舱：多风场四档台数 |
| `getLastDaysTrend` | POST | `day`, `engineId`, `fieldId`, `dateTime?` | 机组详情趋势图 |

### 4.3 核心 VO 说明

| VO | 关键字段 | 前端用途 |
|----|----------|----------|
| `HealthOverviewVO` | 风场总分、风机列表 | 映射为 `totalScore`、`unitCards`、子系统数据 |
| `HealthOverviewListVO` | 单机各维度评分 | 风机卡片、详情分项 |
| `HealthscoresWindVO` | 风场名、优/良/中/差台数 | 驾驶舱表格与饼图聚合 |
| `HealthscoresTendencyVO` | 按日多维评分序列 | 趋势折线图 |

### 4.4 组织树接口

风场选择复用主网关：`getSysOrganizationAuthTreeByRoleId`（`src/api/ledger.js`），与健康分析服务分离。

---

## 5. 数据流设计

### 5.1 健康评估页加载流程

```
1. HealthHeader 加载组织树 → 用户选择风场/日期
2. handleQueryChange(fieldCode) 
3. POST getHealthOverview({ fieldCode, datatime })
4. mapHealthOverviewToDashboard(res.data)
5. applyDashboard → 分发至各 Panel / UnitCard
6. 用户打开抽屉 → POST getLastDaysTrend → 渲染趋势图
```

### 5.2 驾驶舱 → 健康页跳转

```
1. 用户点击风场名称（CockpitHealthTable）
2. navigateToHealthDashboard() 写入 sessionStorage
3. router.push 解析动态路由 /home/health/index?id=菜单ID
4. health/index.vue consumeHealthNavigateState() 回填查询条件
5. fetchDashboard() 拉取 getHealthOverview
```

### 5.3 映射层职责

`healthDashboardMapper.js` 负责：

- 全场评分与四档分布聚合
- 子系统柱状图 series 构建
- 健康榜 / 预警榜排序截取
- 风机卡片字段标准化（`engineId`、`name`、`score`、`level`）

---

## 6. 前端组件设计

### 6.1 目录结构

```
src/views/health/
├── index.vue                          # 仪表盘主页面
├── components/health/
│   ├── HealthHeader.vue               # 查询头
│   ├── HealthScorePanel.vue           # 全场健康度
│   ├── HealthSubsystemPanel.vue       # 子系统柱图
│   ├── HealthRankingPanel.vue         # 排行榜轮播
│   ├── HealthUnitCard.vue             # 风机卡片
│   ├── HealthUnitDetailDrawer.vue     # 详情抽屉
│   ├── health-dashboard.scss          # 页面主题样式
│   └── unitDetailData.js              # 详情分项静态映射
└── utils/
    ├── healthDashboardMapper.js
    ├── healthLevel.js
    ├── healthTrendMapper.js
    └── healthUnitListFilter.js
```

### 6.2 驾驶舱相关

```
src/views/admin/cockpitManage/component/
├── CockpitHealthPanel.vue
├── CockpitHealthTable.vue
├── cockpitHealthMapper.js
├── cockpitHealthData.js
├── cockpitFieldNavigate.js
└── tabroll.vue                        # 表格自动滚动
```

### 6.3 状态管理

| 状态类型 | 存储方式 | 说明 |
|----------|----------|------|
| 菜单/路由 | Vuex `auth.dynamicRouter` | 动态注入健康页路由 |
| 按钮权限 | Vuex `auth.authBtnList` | `v-hasPermi` 校验 |
| 驾驶舱跳转 | `sessionStorage` | 风场/日期跨页传递 |
| 页面数据 | 组件 `data` | 无独立 health Vuex 模块 |

---

## 7. 界面与主题设计

### 7.1 主题策略

| 主题 | 样式文件 | 说明 |
|------|----------|------|
| 业务浅色 | `health-dashboard.scss` 内 `html:not([data-theme="tech-blue"])` | 随 `green/light/blue/dark` 切换 `--health-*` 变量 |
| 科技蓝大屏 | `health-dashboard.scss` 内 `html[data-theme="tech-blue"]` | 玻璃卡片、霓虹描边、scan-line 动效 |
| 驾驶舱 | `cockpit-dashboard.scss` | `--cockpit-health-*` 高度与表格变量 |

**原则**：健康页样式独立维护；不得因新需求改动 `tech-blue` 已验收块；组件内颜色优先 `var(--health-*)` 而非写死色值。

### 7.2 响应式

`index.vue` 使用 CSS Grid 适配宽屏与中等屏宽；风机卡片网格 `auto-fill` 列布局；图表容器在 `resize` 时调用 ECharts `resize()`。

---

## 8. 权限与安全设计

| 权限码 | 作用域 |
|--------|--------|
| `home:health:btn` | 驾驶舱健康 Tab 及内容 |
| 菜单 `permissionCode` | 左侧「健康评估」菜单可见性 |
| 组织树 | 按角色过滤可见风场 |

接口鉴权：请求头携带登录 Token（`healthRequest` 与主 `request` 均注入）。

---

## 9. 异常与空态设计

| 场景 | 处理方式 |
|------|----------|
| 未选风场 | 不发起 `getHealthOverview`，展示空态 |
| 接口失败 | `console.error` + 清空 dashboard，子组件展示「暂无数据」 |
| 筛选无结果 | 风机列表区提示「暂无符合条件的风机」 |
| 趋势无数据 | 抽屉内折线图展示空态 graphic |

---

## 10. 部署与联调

| 项 | 说明 |
|----|------|
| 环境变量 | `.env.*` 中 `VUE_APP_HEALTH_API` 或 `public/runtime-config.js` 配置生产网关 |
| 开发代理 | `vue.config.js`：`/healthApi` → 分析服务地址 |
| 构建命令 | `npm run build:dt` 等环境脚本 |
| 验证要点 | 驾驶舱饼图/表格、健康页四块面板、抽屉趋势、跳转状态恢复 |

---

## 11. 扩展与维护建议

1. **新增子系统维度**：在 `healthDashboardMapper` 扩展映射，对应 `HealthSubsystemPanel` 增加 series。
2. **新增驾驶舱指标**：优先复用 `getHealthscoresWindList`，避免与健康页接口语义混用。
3. **主题扩展**：新建主题 SCSS 文件，仅追加 `html[data-theme="新主题"]` 块，勿改已有 `tech-blue` 规则。
4. **详情分项**：若后端补充维度字段，同步更新 `unitDetailData.js` 与抽屉模板。

---

## 12. 参考文档

| 文档 | 路径 |
|------|------|
| 健康评估操作说明 | `docs/OPERATION_MANUAL_HEALTH.md` |
| 分析服务 API 报告 | `docs/API_DESIGN_REPORT_energy-manage-analyse.md` |
| 前端部署说明 | `docs/DEPLOY_FRONTEND.md` |
| 项目 AI 规范 | `docs/AI_SPECS.md` |