# Frontend Cursor Rules

## 1. 基础规范
- Vue 3 Composition API (`<script setup>`)
- TypeScript
- Arco Design Vue 2.x（组件自动导入）

## 2. 目录结构
- **API (`src/api/`)**: API 接口定义
  - 按功能模块组织文件（如 `user.ts`、`dashboard.ts`）
  - 使用 Axios 进行 HTTP 请求
  - 统一在 `src/api/interceptor.ts` 配置拦截器
- **组件 (`src/components/`)**: 全局可复用组件
  - 按功能模块组织子目录
  - 全局组件在 `src/components/index.ts` 中注册
  - 使用 Arco Design 组件时无需手动导入（自动导入已配置）
  - 注意：模块专用组件应放在对应模块目录下的 `components/` 文件夹，而非全局 `src/components/`
- **视图 (`src/views/`)**: 页面级组件
  - 按功能模块组织目录
  - 每个模块包含 `index.vue` 和 `locale/` 目录（国际化文案）
  - 模块专用组件放在模块目录下的 `components/` 文件夹（如 `src/views/User/UserInfo/components/`）
- **路由 (`src/router/`)**: 路由配置
  - 路由定义在 `router/routes/` 目录，按模块组织
  - 路由守卫在 `router/guard/` 目录
- **状态管理 (`src/store/`)**: Pinia Store
  - 按模块组织 store（如 `user/`、`app/`）
  - 使用 `defineStore` 定义 store
- **工具 (`src/utils/`)**: 通用工具函数
- **Hooks (`src/hooks/`)**: 组合式函数
  - 可复用的 Composition API 逻辑

## 2.1. 命名规范（重要）
- **目录命名**：必须使用**驼峰命名法（PascalCase）**
  - ✅ `UserManage/`、`QuestionBank/`、`PaperManage/`、`UserInfo/`
  - ❌ `user-manage/`、`question-bank/`、`user-info/`
- **组件文件命名**：必须使用**驼峰命名法（PascalCase）**
  - ✅ `UserList.vue`、`RoleManage.vue`、`MenuManage.vue`、`UserInfoHeader.vue`
  - ❌ `user-list.vue`、`role-manage.vue`、`user-info-header.vue`
- **独立子页面**：必须单独建立文件夹
  - 如果页面有独立的子页面（如用户详情页），应单独建立文件夹
  - 示例：`User/UserInfo/`、`User/UserSetting/`
  - 每个子页面目录包含 `index.vue` 和可选的 `components/` 文件夹

## 2.2. 组件化原则
- **公共组件**：放在 `src/components/` 目录下
  - 可在多个页面复用的组件
- **页面私有组件**：放在页面目录下的 `components/` 文件夹
  - 仅当前页面使用的组件
  - 示例：`User/UserInfo/components/UserInfoHeader.vue`
- **页面组件化**：能够拆成组件的都组件化
  - 将复杂页面拆分为多个小组件
  - 示例：`UserManage/index.vue` 包含 `UserList`、`RoleManage`、`MenuManage` 三个组件

## 2.3. 页面结构示例
```
views/
├── User/                    # 用户个人信息页面
│   ├── UserInfo/           # 用户信息子页面（独立文件夹）
│   │   ├── components/     # 私有组件（仅当前页面用）
│   │   │   ├── UserInfoHeader.vue
│   │   │   ├── LatestActivity.vue
│   │   │   └── MyProject.vue
│   │   └── index.vue       # 详情页主文件
│   └── UserSetting/        # 用户设置子页面（独立文件夹）
│       ├── components/
│       │   ├── UserPanel.vue
│       │   └── BasicInformation.vue
│       └── index.vue
│
└── UserManage/             # 用户管理页面（管理员功能）
    ├── components/         # 组件化（可复用）
    │   ├── UserList.vue    # 用户列表组件
    │   ├── RoleManage.vue  # 角色管理组件
    │   └── MenuManage.vue  # 菜单管理组件
    └── index.vue           # 主页面（标签页容器）
```

## 3. 代码风格

### 格式化规范（遵循 `.prettierrc.js`）
- **缩进**: 2 个空格（`tabWidth: 2`）
- **引号**: 单引号（`singleQuote: true`）
- **分号**: 必须使用分号（`semi: true`）
- **行宽**: 80 字符（`printWidth: 80`）
- **对象属性引号**: 保持一致（`quoteProps: 'consistent'`）
- **HTML 空白**: 严格模式（`htmlWhitespaceSensitivity: 'strict'`）
- **Vue 脚本样式缩进**: 启用（`vueIndentScriptAndStyle: true`）

### 代码检查规范（遵循 `.eslintrc.js`）
- **代码风格**: Airbnb JavaScript Style Guide
- **TypeScript**: 使用 `@typescript-eslint/recommended` 规则
- **Vue 3**: 使用 `plugin:vue/vue3-recommended` 规则
- **导入**: 使用 `plugin:import` 规则，支持 TypeScript 路径解析
- **关键规则**:
  - 事件名使用 camelCase（`vue/custom-event-name-casing`）
  - 允许 `@ts-ignore` 注释（`@typescript-eslint/ban-ts-comment: 0`）
  - 允许 `any` 类型（`@typescript-eslint/no-explicit-any: 0`）
  - 导入时不需要扩展名（`import/extensions`）
  - 生产环境禁止 `debugger`，开发环境允许

### TypeScript
- 使用 `camelCase` 命名变量和函数
- 使用 `PascalCase` 命名类和组件
- 使用类型提示，但不需要比 Python 更严格
- 避免使用 `abstract` 类和 `protected` 修饰符
- 命名方式需与后端 Python 代码保持一致（API 调用时保持命名一致性）

### Vue 组件
- 使用 `<script setup>` 语法
- **组件文件名必须使用 PascalCase**（如 `UserProfile.vue`、`UserList.vue`）
- **目录名必须使用 PascalCase**（如 `UserManage/`、`QuestionBank/`）
- Props 和 Emits 使用 `defineProps` 和 `defineEmits`
- 使用 `ref` 和 `reactive` 管理响应式状态
- 使用 `computed` 和 `watch` 处理派生状态和副作用
- 事件名使用 camelCase（如 `@update:value`）

### 样式
- 使用 Less 作为 CSS 预处理器
- 组件样式使用 `<style lang="less" scoped>`
- 全局样式在 `src/assets/style/global.less`
- 使用 Arco Design CSS 变量（如 `var(--color-bg-1)`）
- 响应式使用 Less 变量 `@screen-*`（定义在 `src/assets/style/breakpoint.less`）

## 4. UI 组件使用

### Arco Design 组件
- **优先使用 Arco Design 组件**: 优先使用 Arco Design Vue 提供的组件
- **自动导入**: Arco 组件已配置自动导入，无需手动 import
- **主题变量**: 使用 Arco Design CSS 变量，支持主题切换
- **图标**: 使用 `@arco-design/web-vue/es/icon` 中的图标
- **样式修改**: 不要擅自修改 Arco Design 组件的默认样式，除非收到明确的修改命令

### 自定义组件
- 放置在 `src/components/` 目录
- 按功能模块组织子目录
- 全局组件在 `src/components/index.ts` 中注册

## 5. API 调用

### 请求配置
- 使用 `src/api/interceptor.ts` 中的 Axios 实例
- 统一错误处理在拦截器中配置
- Token 认证通过请求头自动添加

### API 文件组织
- 按功能模块组织 API 文件（如 `user.ts`、`dashboard.ts`）
- 导出函数命名使用 camelCase
- 使用 TypeScript 类型定义请求和响应

## 6. 状态管理

### Pinia Store
- 使用 `defineStore` 定义 store
- Store 文件按模块组织在 `src/store/modules/` 目录
- 使用组合式 API 风格（`setup` 函数）

### 状态命名
- State 使用 camelCase
- Actions 使用 camelCase，动词开头（如 `fetchUserInfo`）
- Getters 使用 camelCase

## 7. 路由

### 路由配置
- 路由定义在 `router/routes/` 目录，按模块组织
- 使用懒加载：`component: () => import('@/views/xxx/index.vue')`
- 路由元信息在 `meta` 字段中定义

### 路由守卫
- 认证守卫：`router/guard/userLoginInfo.ts`
- 权限守卫：`router/guard/permission.ts`
- 全局守卫：`router/guard/index.ts`

## 8. 国际化
- 使用 `useI18n()` 获取 `t` 函数
- 页面文案：`views/[module]/locale/`，全局文案：`src/locale/`
- 文案 key 使用点号分隔（如 `user.login.title`）

## 9. 数据可视化

### ECharts
- 使用 `vue-echarts` 封装 ECharts
- 图表组件统一在 `src/components/chart/` 目录
- 图表配置使用 `hooks/chart-option.ts` 统一管理

## 10. 开发规范

### 环境变量
- 使用 Vite 环境变量（`VITE_*` 前缀）
- 开发环境：`.env.development`
- 生产环境：`.env.production`
- API 地址：`VITE_API_BASE_URL`

### Mock 数据
- 开发环境支持 Mock.js
- Mock 配置在 `src/mock/` 目录
- 使用 `src/utils/setup-mock.ts` 设置 Mock

### 代码质量
- **ESLint**: 代码检查（配置在 `.eslintrc.js`），遵循 Airbnb 风格和 Vue 3 规范
- **Prettier**: 代码格式化（配置在 `.prettierrc.js`），2空格缩进、单引号、分号
- **Stylelint**: 样式检查（配置在 `.stylelintrc.js`）
- **lint-staged**: 提交前自动格式化（配置在 `package.json`）
- **重要**: 生成的代码必须符合 Prettier 和 ESLint 规范，避免格式化错误

## 11. 性能优化
- 路由级别懒加载
- 组件按需加载

## 12. 响应式设计
- 使用 Less 变量 `@screen-xs` 到 `@screen-xxl`
- 使用 `hooks/responsive.ts` 获取响应式状态