---
name: pref-web-dev
description: >-
  风机数据管理平台（performance-test / pref-web）开发与联调指南。涵盖 Vue 2
  Options API、多代理 devServer、健康分析 healthApi 联调、动态路由与组织树风场
  选择。在用户修改本仓库前端/后端、新增 API 联调、健康/性能/驾驶舱模块或询问
  项目规范时使用。
---

# pref-web 项目开发 Skill

## 权威文档（先读后改）

1. `docs/AI_SPECS.md` — 技术栈、目录、API、安全底线
2. `.cursor/rules/project-rules.mdc` — 全项目总则
3. `.cursor/rules/frontend-rules.mdc` — Vue 2 前端
4. `.cursor/rules/backend-rules.mdc` — `server/`、`downLoadServer/`

Rules 是精简硬约束；Specs 是详细说明。改代码前读 Specs 相关章节，不必把 Specs 全文塞进 Rule。

## 技术栈速查

| 层 | 技术 |
|----|------|
| 前端 | Vue 2.6、Vue Router 3、Vuex 3、Element UI、SCSS、ECharts、Vue CLI 5 |
| 主 API | `@/utils/request.js` → `baseURL: /api` |
| 独立服务 | 各模块自建 `axios` 实例 + `vue.config.js` 代理前缀 |
| 后端 | `server/`（mysql2）、`downLoadServer/`（图表/报告导出） |

**禁止**：迁移 TypeScript / Vue 3 / Composition API；引入新 UI 库或新请求库。

## 环境与启动

```bash
npm run serve:dev   # .env.dev
npm run serve:dt    # .env.dt（大唐）
npm run serve:hd    # .env.hd（华电）
npm run serve:jl    # .env.jl
```

修改 `vue.config.js` 代理后**必须重启** dev server。

## 多代理约定

主业务走 `/api`；其他服务用**独立前缀**，**禁止**用 `/health`（与路由 `/home/health` 冲突）。

| 前缀 | 环境变量 | 用途 |
|------|----------|------|
| `/api` | `VUE_APP_APIPROXY` | 主业务 energy-manage-service |
| `/healthApi` | `VUE_APP_HEALTH_APIPROXY` | 健康分析 energy-manage-analyse-service |
| `/WZLapi` | `VUE_APP_WZLAPIPROXY` | 振动/激光 |
| `/AnalysisMulti` | `VUE_APP_AnalysisMultiAPIPROXY` | 健康评估算法 |
| `/downLoadChart` | `VUE_APP_downLoadChartAPIPROXY` | 图表下载 |

**不要**自定义 `historyApiFallback.rewrites` 覆盖默认 SPA 回退，否则 `/home/*` 会返回 Tomcat 404 而非 `index.html`。

新增独立服务时：
1. `.env.*` 加 `VUE_APP_XXX_APIPROXY`
2. `vue.config.js` `devServer.proxy` 加前缀（勿与路由路径冲突）
3. `src/utils/xxxRequest.js` 新建 axios 实例
4. `src/api/xxx.js` 封装接口

## 前端 API 联调流程

```
1. 确认 swagger 或接口文档 → 路径、方法、query/body、响应 ResultResp<T>
2. src/api/<module>.js 具名导出 export function getXxx(params)
3. 选择 request 实例（主 /api 或专用 healthRequest 等）
4. POST + query 参数时显式传 params: { fieldCode, datatime }
5. 页面 methods 调用，判断 res.code === 200 后取 res.data
6. 复杂响应抽到 views/<module>/utils/*Mapper.js 映射 UI 结构
```

### 响应约定

```javascript
// 标准包装
{ code: 200, data: T, msg: string, status: boolean }
```

拦截器已处理非 200；页面 catch 后清空或保留上次数据，**不要** router.push 到 404 页。

### 接口 404 / HTML 错误

- 仅 `Message.error` 提示，保持当前页面
- `healthRequest` 会识别 Tomcat HTML 响应并 reject
- 代理路径错误时检查 Network 是否走 `/healthApi/...` 而非 `/api/...`

## 健康模块（health）

| 文件 | 职责 |
|------|------|
| `src/views/health/index.vue` | 仪表盘页 |
| `src/views/health/components/health/HealthHeader.vue` | 风场树（portal 到 header） |
| `src/api/healthAnalyse.js` | 健康分析接口 |
| `src/utils/healthRequest.js` | `/healthApi` 专用请求 |
| `src/views/health/utils/healthDashboardMapper.js` | API → UI 数据映射 |

### 风场 fieldCode

- `fieldCode` = 组织树节点的 `codeNumber`
- 默认选中：`tree[0].children[0]`（第一个根节点的第一个子节点）
- `HealthHeader` 的 `change` 事件携带 `{ ...node, fieldCode: codeNumber }`
- 组织树接口走主 `/api`（`getSysOrganizationAuthTreeByRoleId`），健康数据走 `/healthApi`

### 健康分析接口（swagger 2.X版本）

```
POST /energy-manage-analyse-service/healthscores/getHealthOverview
  params: fieldCode(required), datatime(optional)
POST /energy-manage-analyse-service/healthscores/getHealthscoresWindList
POST /energy-manage-analyse-service/healthscores/getLastDaysTrend
  params: day, engineId, fieldId
```

完整设计见 `docs/API_DESIGN_REPORT_energy-manage-analyse.md`。

## 路由与菜单

- 静态路由：`src/router/index.js`（`/home` 壳 + 驾驶舱）
- 动态路由：登录后 `store/auth.js` → `getAuthRouterFn` 按权限注入
- 菜单跳转：`MenuDt.vue` → `router.push(`${path}?id=${id}`)`
- 健康页典型路径：`/home/health/index?id=264`

catch-all `path: '*'` 在 `auth.js` 末尾注册；接口代理路径（`/api`、`/healthApi` 等）不应进入 404 页面组件。

## 编码风格要点

- Vue 2 **Options API**；`.vue` 结构 `template` / `script` / `style lang="scss"`
- API 放 `src/api/*.js`；双引号、保留分号
- 样式跟现有 SCSS 变量与 `html[data-theme="..."]`
- 驾驶舱全局样式：`src/views/admin/cockpitManage/cockpit-dashboard.scss`（勿改 scoped）
- 健康仪表盘样式：`src/views/health/components/health/health-dashboard.scss`
- 图表复用 `src/assets/js/constants/echarts-config/` 与已有 mixin

## 安全红线

- 不输出/硬编码 `.env*`、token、数据库密码、MinIO 凭据
- 不擅自改 PM2、nginx、部署脚本、生产代理
- 数据库结构变更：先给迁移 SQL + 回滚方案，等确认后再动
- 接口改动保持向后兼容

## 变更检查清单

```
- [ ] 是否复用已有组件/工具/API？
- [ ] 新接口是否放对 request 实例与代理前缀？
- [ ] 是否保持 Options API 与局部最小 diff？
- [ ] 错误处理是否只提示、不跳转 404 页？
- [ ] vue.config 代理改动是否提醒重启 serve？
- [ ] 是否检查相关文件 lint？
```

## 延伸阅读

- 代理与健康 API 细节：[reference.md](reference.md)
- Swagger 分析报告：`docs/API_DESIGN_REPORT_energy-manage-analyse.md`