performance-test/.cursor/skills/pref-web-dev/SKILL.md

---

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 库或新请求库。

环境与启动

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 结构

响应约定

// 标准包装
{ 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
• Swagger 分析报告：docs/API_DESIGN_REPORT_energy-manage-analyse.md