performance-test/docs/AI_SPECS.md

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 生成代码原则

1. 优先查找并复用已有组件、工具函数、API 封装、样式变量和图表配置。
2. 不要为了单个需求引入新框架、新状态管理、新请求库或新 UI 库。
3. 对已有复杂页面只做局部、可回滚修改，避免重构式改写。
4. 修改接口调用时优先放在 src/api/*.js，除非所在模块已有直接 axios 风格。
5. 新增样式应优先作用于明确作用域，避免污染全局；驾驶舱主题例外，应维护 cockpit-dashboard.scss 的主题结构。
6. 新增主题时须主题隔离：只新增 src/themes/<name>.scss 与对应的 html[data-theme="<name>"] 样式块；不得修改已有主题（尤其 tech-blue）的变量与选择器来适配新主题。详见 .cursor/rules/theme-rules.mdc。
7. 不输出密钥，不读取或展示 .env 内容中的具体敏感值。
8. 变更后应检查相关文件 lint；如无法运行完整测试，应说明未验证项。

规则文件映射

• .cursor/rules/project-rules.mdc：全项目通用规则、复用原则和生产安全底线。
• .cursor/rules/frontend-rules.mdc：Vue 2 前端、样式、请求、路由、状态、图表与大屏页面规则。
• .cursor/rules/theme-rules.mdc：多主题隔离规范；新增主题不得影响已有主题（尤其 tech-blue）。
• .cursor/rules/backend-rules.mdc：server/ 与 downLoadServer/ 的 Express、数据库、文件上传、图表导出与安全规则。