# Cursor Rules for Finyx Frontend

## 项目概述
这是一个基于 Vue 3 + TypeScript + Vite 的前端项目，主要功能包括智能问答、智能写作、智能审核和知识库管理。

## 技术栈
- **框架**: Vue 3.3.4 (Composition API)
- **构建工具**: Vite 6.3.5
- **语言**: TypeScript 5.1.6
- **UI框架**: Element Plus 2.9.1
- **状态管理**: Pinia 2.1.6
- **路由**: Vue Router 4.2.4
- **HTTP客户端**: Axios 0.28.0
- **样式**: SCSS
- **代码编辑器**: CodeMirror 6.0.1
- **Markdown编辑器**: md-editor-v3 5.8.4

## 代码规范

### 1. 语言与注释
- 默认使用中文回答问题，除非用户特别要求英文
- 默认使用英文代码注释，除非特别要求中文
- 公共 API 使用 JSDoc/TSDoc 格式

### 2. 回答风格
- 尽量简洁明了，避免不必要的废话和重复说明
- 先给出关键答案，再提供简短解释或示例

### 3. 安全与稳健性（最高优先级）
- 绝对禁止硬编码任何敏感信息（密码、API密钥、IP）
- 所有配置必须从环境变量或配置文件中读取
- 必须进行错误处理，对可能失败的操作使用 try-catch 或等效机制

### 4. 代码整洁与可维护性（参考《代码整洁之道》）
- 函数短小且单一职责，每个函数只做一件事
- 变量、函数、类命名语义清晰，易读易理解
- 避免重复代码（遵循 DRY 原则）
- 错误处理明确且一致，保证程序健壮
- 模块和类职责明确，依赖清晰，便于扩展和维护

## 项目结构

### 目录结构
```
src/
├── api/              # API接口定义
├── assets/           # 静态资源
├── bus/              # 事件总线
├── components/       # 全局组件
├── directives/       # 自定义指令
├── enums/            # 枚举定义
├── layout/           # 布局组件
├── request/          # HTTP请求封装
├── router/           # 路由配置
├── servers/          # 服务层API
│   ├── base/         # 基础服务
│   ├── finyx/        # Finyx业务服务
│   └── oauth/        # 认证服务
├── stores/           # Pinia状态管理
│   └── modules/      # 状态模块
├── styles/           # 全局样式
├── utils/            # 工具函数
└── views/            # 页面组件
    ├── chat/         # 聊天页面
    ├── knowledge/    # 知识中心
    ├── login/        # 登录页面
    └── smart/        # 智能中心
```

### 命名规范
- **组件**: PascalCase (如 `AppAvatar.vue`)
- **文件/目录**: kebab-case (如 `app-avatar/`)
- **变量/函数**: camelCase (如 `getUserInfo`)
- **常量**: UPPER_SNAKE_CASE (如 `MAX_SIZE`)
- **类型/接口**: PascalCase (如 `UserInfo`)

## 开发规范

### Vue组件规范
1. **使用 Composition API**: 优先使用 `<script setup>` 语法
2. **组件结构**: template -> script -> style
3. **Props定义**: 使用 TypeScript 类型定义
4. **响应式数据**: 使用 `ref` 和 `reactive` 明确声明
5. **生命周期**: 使用组合式API的生命周期钩子

### TypeScript规范
1. **类型定义**: 所有函数参数和返回值必须定义类型
2. **接口定义**: 使用 `interface` 定义数据结构
3. **类型导入**: 使用 `import type` 导入类型
4. **避免使用 `any`**: 尽量使用具体类型或 `unknown`

### API请求规范
1. **统一使用**: `src/request/http.ts` 封装的请求方法
2. **错误处理**: 在请求拦截器中统一处理
3. **Token管理**: 通过 `dada` store 管理认证信息
4. **请求头**: 自动添加 Token、TenantId、AuthId、ApplicationId

### 状态管理规范
1. **使用 Pinia**: 所有状态管理使用 Pinia
2. **Store模块化**: 按功能模块划分 store
3. **当前Store模块**:
   - `dada`: 用户认证和基础信息
   - `docs`: 文档管理
   - `chat`: 聊天相关
   - `answerSetting`: 问答设置
   - `knowledge`: 知识库管理

### 路由规范
1. **路由配置**: 统一在 `src/router/routes.ts` 中定义
2. **路由守卫**: 在 `src/router/index.ts` 中实现
3. **路由元信息**: 使用 `meta` 字段定义标题、图标、权限等
4. **懒加载**: 使用动态导入 `() => import()` 实现路由懒加载

### 样式规范
1. **使用SCSS**: 所有样式文件使用 SCSS
2. **CSS变量**: 使用全局CSS变量（定义在 `src/styles/variables.scss`）
3. **作用域**: 组件样式使用 `scoped`
4. **BEM命名**: 复杂组件可考虑使用BEM命名规范

### 组件开发规范
1. **全局组件**: 在 `src/components/index.ts` 中注册
2. **组件导出**: 使用具名导出
3. **Props验证**: 使用 TypeScript 类型验证
4. **事件命名**: 使用 kebab-case (如 `@update-value`)

## 环境变量

### 环境变量文件位置
- 环境变量文件存放在 `env/` 目录
- 通过 `VITE_` 前缀暴露给前端

### 常用环境变量
- `VITE_APP_PORT`: 开发服务器端口
- `VITE_BASE_PATH`: 基础路径
- `VITE_MOCK_DEV_SERVER`: 是否启用Mock服务
- `VITE_BUILD`: 构建模式

## 构建与部署

### 开发命令
```bash
pnpm dev              # 启动开发服务器
pnpm build            # 构建生产版本
pnpm build:prd        # 构建生产版本（含类型检查）
pnpm preview          # 预览构建结果
pnpm lint             # 代码检查
pnpm format           # 代码格式化
```

### 构建配置
- **压缩**: 使用 Terser 压缩
- **代码分割**: 按模块手动分割（vue, lodash, echarts等）
- **资源处理**: SVG图标自动生成雪碧图
- **Gzip压缩**: 生产环境启用Gzip压缩

## 注意事项

1. **API代理**: 开发环境通过 Vite 代理配置转发请求
2. **Token管理**: Token失效会自动跳转登录页
3. **错误码处理**: 特定错误码（11011-11016）表示认证失效
4. **文件上传**: 使用 `src/servers/base/api/wenjianshangchuan.ts`
5. **Markdown渲染**: 使用 md-editor-v3，支持 KaTeX、Mermaid、代码高亮等

## 代码审查要点

1. ✅ 是否进行了错误处理
2. ✅ 是否使用了类型定义
3. ✅ 是否遵循命名规范
4. ✅ 是否避免了硬编码
5. ✅ 是否遵循单一职责原则
6. ✅ 是否进行了代码复用
7. ✅ 是否添加了必要的注释