# 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、数据库、文件上传、图表导出与安全规则。