AI Specs

本文档用于约束 AI 在本项目中生成、修改和审查代码时的行为。所有 AI 输出应优先保持现有实现方式、目录组织和编码风格一致，避免引入不必要的新架构。

项目概览

项目名称：风机数据管理平台（pref-web / performance-test）。
主体是 Vue 2 前端工程，基于 Vue CLI 5 构建。
仓库内包含两个 Node.js 服务：
- server/：Express + mysql2 的数据库读取服务。
- downLoadServer/：Express 图表/报告下载服务，包含 ECharts、Plotly、Puppeteer、MinIO、DOCX 等能力。
项目通过多套 .env.* 与 vue.config.js 代理区分不同环境和客户模式。

技术栈

前端

Vue ^2.6.14
Vue Router ^3.5.1
Vuex ^3.6.2
Vue CLI Service ~5.0.0
Element UI ^2.15.14
SCSS / Sass，入口样式位于 src/styles/index.scss
Tailwind CSS PostCSS 7 兼容版本
ECharts ^5.5.1、ECharts GL ^2.0.9
OpenLayers ol ^9.2.3
Axios ^1.6.8
DataV、Quill、WangEditor、Vue Virtual Scroller、Vue Draggable Resizable 等

服务端

server/：Node.js ESM、Express ^4.21.1、mysql2 ^3.11.5
downLoadServer/：Node.js ESM、Express ^4.19.1、CORS、dotenv、multer、archiver、docx/docxtemplater、Puppeteer、MinIO、Plotly/ECharts

目录结构

src/main.js：Vue 入口，注册 Element UI、全局组件、指令、主题、日期工具和路由守卫。
src/router/index.js：Vue Router 配置，按环境变量切换驾驶舱组件。
src/store/：Vuex 模块，使用 vuex-persistedstate 持久化部分模块。
src/api/：前端接口封装，优先通过 @/utils/request 统一请求。
src/utils/request.js：Axios 实例、token 注入、响应错误处理和统一请求函数。
src/views/：业务页面，按模块组织，如 admin/cockpitManage、performance、health、overview。
src/components/：通用组件，包括地图、虚拟列表、富文本、SVG 等。
src/assets/js/constants/echarts-config/：图表配置模板。
src/styles/、src/themes/：全局样式和主题样式。
server/index.js：数据库读取服务入口。
downLoadServer/src/server/：下载服务入口、路由、控制器、中间件和图表工具。
public/runtime-config.js：运行时配置。

编码风格

前端主要使用 Vue 2 Options API（data、computed、watch、methods、生命周期钩子）。
.vue 文件通常采用单文件组件结构：template、script、style lang="scss"。
现有代码以 JavaScript 为主，不使用 TypeScript。
字符串多使用双引号；分号保留。
业务接口函数使用具名导出，例如 export function getWindFieldNames(data) { ... }。
组件和页面命名混合使用 PascalCase 与业务英文/拼音名；新增代码应优先跟随所在目录命名风格。
样式优先沿用 SCSS、CSS 变量和已有主题选择器，例如 html[data-theme="tech-blue"]。
大屏/驾驶舱样式集中在 cockpit-dashboard.scss，该文件为全局样式，不能随意改为 scoped。
图表逻辑大量使用 ECharts/Plotly 配置对象，应复用已有图表配置和 mixin。

框架版本与构建方式

构建命令来自根目录 package.json：
- serve:dev、serve:hd、serve:dt、serve:demo、serve:jl
- build:dev、build:hd、build:dt、build:demo、build:jl
vue.config.js 使用 Vue CLI 配置：
- @ 指向 src
- svg-sprite-loader 处理 src/icons
- Workbox 生成 Service Worker
- devServer.proxy 代理 /api、/WZLapi、/ETLapi、/tiles、/AnalysisMulti、/transDataWeb、/sAlgorithm、/databaseApi、/downLoadChart

API 组织方式

前端统一请求优先使用 src/utils/request.js。
request 默认 baseURL 为 window?._BASE_CONFIG?.API || "/api"。
请求拦截器从 sessionStorage.vuex.auth.userInfo.token 注入 headers.token。
响应拦截器期望后端返回 code === 200，否则使用 Element UI Message 提示并 reject。
src/api/*.js 按业务模块组织 API 函数。
少量旧代码仍直接使用 axios.get/post，修改时优先保持局部兼容，不应大范围重写。

数据库使用方式

前端本身不直接连接数据库。
server/index.js 使用 mysql2/promise 动态创建连接池。
数据库连接参数来自请求参数或请求体（IP、host、baseName、username、password）。
SQL 主要使用 SHOW TABLES、DESCRIBE、SHOW COLUMNS、SELECT ... LIMIT 500。
当前未发现 ORM 或数据库迁移框架。
涉及数据库结构变更时，必须先输出迁移方案、回滚方案和兼容性评估，不得直接修改生产数据。

生产环境安全规范

禁止修改 PM2 配置。
禁止修改部署脚本。
禁止修改 nginx 配置。
禁止输出包含密钥、token、数据库密码、MinIO 凭据、私有地址口令的信息。
禁止将 .env*、downLoadServer/.env 中的敏感内容复制到回答或新文件。
修改接口时必须保持兼容：保留原 URL、请求方法、字段名和返回结构，新增字段必须可选。
涉及数据库变更必须先生成迁移方案和回滚方案，并等待确认。
不得在未授权情况下修改 public/runtime-config.js、环境变量、代理目标或构建/部署命令。

AI 生成代码原则

优先查找并复用已有组件、工具函数、API 封装、样式变量和图表配置。
不要为了单个需求引入新框架、新状态管理、新请求库或新 UI 库。
对已有复杂页面只做局部、可回滚修改，避免重构式改写。
修改接口调用时优先放在 src/api/*.js，除非所在模块已有直接 axios 风格。
新增样式应优先作用于明确作用域，避免污染全局；驾驶舱主题例外，应维护 cockpit-dashboard.scss 的主题结构。
不输出密钥，不读取或展示 .env 内容中的具体敏感值。
变更后应检查相关文件 lint；如无法运行完整测试，应说明未验证项。

规则文件映射

.cursor/rules/project-rules.mdc：全项目通用规则、复用原则和生产安全底线。
.cursor/rules/frontend-rules.mdc：Vue 2 前端、样式、请求、路由、状态、图表与大屏页面规则。
.cursor/rules/backend-rules.mdc：server/ 与 downLoadServer/ 的 Express、数据库、文件上传、图表导出与安全规则。