174 lines
6.1 KiB
Plaintext
174 lines
6.1 KiB
Plaintext
# 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. ✅ 是否添加了必要的注释
|
||
|