414 lines
12 KiB
Markdown
414 lines
12 KiB
Markdown
# Finyx Frontend 代码架构说明文档
|
||
|
||
## 项目简介
|
||
|
||
Finyx Frontend 是一个基于 Vue 3 + TypeScript + Vite 构建的企业级前端应用，主要提供智能问答、智能写作、智能审核和知识库管理等核心功能。
|
||
|
||
## 技术架构
|
||
|
||
### 核心技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Vue | 3.3.4 | 前端框架 |
|
||
| TypeScript | 5.1.6 | 类型系统 |
|
||
| Vite | 6.3.5 | 构建工具 |
|
||
| Element Plus | 2.9.1 | UI组件库 |
|
||
| Pinia | 2.1.6 | 状态管理 |
|
||
| Vue Router | 4.2.4 | 路由管理 |
|
||
| Axios | 0.28.0 | HTTP客户端 |
|
||
| CodeMirror | 6.0.1 | 代码编辑器 |
|
||
| md-editor-v3 | 5.8.4 | Markdown编辑器 |
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
finyx_frontend/
|
||
├── docs/ # 文档目录
|
||
├── env/ # 环境变量配置
|
||
├── mock/ # Mock数据
|
||
├── public/ # 静态资源
|
||
├── src/
|
||
│ ├── api/ # API接口定义
|
||
│ │ ├── dada.ts # 用户认证API
|
||
│ │ ├── finyxbot.ts # Finyx Bot API
|
||
│ │ ├── review.ts # 审核API
|
||
│ │ └── writing.ts # 写作API
|
||
│ ├── assets/ # 资源文件
|
||
│ │ ├── agent/ # 智能体相关图标
|
||
│ │ ├── dataset/ # 数据集图标
|
||
│ │ ├── fileType/ # 文件类型图标
|
||
│ │ ├── icons/ # SVG图标
|
||
│ │ └── logo/ # Logo资源
|
||
│ ├── bus/ # 事件总线
|
||
│ │ └── index.ts # 事件总线实例
|
||
│ ├── components/ # 全局组件
|
||
│ │ ├── app-avatar/ # 头像组件
|
||
│ │ ├── app-charts/ # 图表组件
|
||
│ │ ├── app-table/ # 表格组件
|
||
│ │ ├── card-box/ # 卡片组件
|
||
│ │ ├── markdown/ # Markdown组件
|
||
│ │ └── ... # 其他组件
|
||
│ ├── directives/ # 自定义指令
|
||
│ │ ├── clickoutside.ts # 点击外部指令
|
||
│ │ ├── infiniteScrollUp.ts # 无限滚动指令
|
||
│ │ ├── pathToSrc.ts # 路径转换指令
|
||
│ │ └── resize.ts # 尺寸监听指令
|
||
│ ├── enums/ # 枚举定义
|
||
│ │ └── application.ts # 应用枚举
|
||
│ ├── layout/ # 布局组件
|
||
│ │ ├── AppLayout.vue # 主布局
|
||
│ │ ├── AppNoMenu.vue # 无菜单布局
|
||
│ │ └── components/ # 布局子组件
|
||
│ ├── request/ # HTTP请求封装
|
||
│ │ ├── http.ts # 主请求封装
|
||
│ │ ├── reviewHttp.ts # 审核请求
|
||
│ │ ├── writingHttp.ts # 写作请求
|
||
│ │ └── fetchWithAbort.ts # 可取消请求
|
||
│ ├── router/ # 路由配置
|
||
│ │ ├── index.ts # 路由实例
|
||
│ │ └── routes.ts # 路由定义
|
||
│ ├── servers/ # 服务层API
|
||
│ │ ├── base/ # 基础服务
|
||
│ │ │ └── api/ # 基础API（组织、员工、角色等）
|
||
│ │ ├── finyx/ # Finyx业务服务
|
||
│ │ │ └── api/ # 业务API（知识库、智能体等）
|
||
│ │ └── oauth/ # 认证服务
|
||
│ │ └── api/ # 认证API
|
||
│ ├── stores/ # Pinia状态管理
|
||
│ │ ├── index.ts # Store入口
|
||
│ │ └── modules/ # Store模块
|
||
│ │ ├── dada.ts # 用户认证Store
|
||
│ │ ├── docs.ts # 文档Store
|
||
│ │ ├── chat.ts # 聊天Store
|
||
│ │ ├── answerSetting.ts # 问答设置Store
|
||
│ │ └── knowledge.ts # 知识库Store
|
||
│ ├── styles/ # 全局样式
|
||
│ │ ├── index.scss # 样式入口
|
||
│ │ ├── variables.scss # CSS变量
|
||
│ │ ├── element-plus.scss # Element Plus样式覆盖
|
||
│ │ └── app.scss # 应用样式
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── common.ts # 通用工具
|
||
│ │ ├── crypto.ts # 加密工具
|
||
│ │ ├── storage.ts # 存储工具
|
||
│ │ ├── time.ts # 时间工具
|
||
│ │ └── ... # 其他工具
|
||
│ ├── views/ # 页面组件
|
||
│ │ ├── chat/ # 聊天页面
|
||
│ │ ├── knowledge/ # 知识中心
|
||
│ │ ├── login/ # 登录页面
|
||
│ │ └── smart/ # 智能中心
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 应用入口
|
||
├── vite.config.ts # Vite配置
|
||
├── tsconfig.json # TypeScript配置
|
||
└── package.json # 项目配置
|
||
```
|
||
|
||
## 核心模块说明
|
||
|
||
### 1. 路由系统 (router/)
|
||
|
||
#### 路由结构
|
||
- **智能中心** (`/smart`)
|
||
- 智能问答 (`/smart/answer/index`)
|
||
- 智能写作 (`/smart/writing/list`)
|
||
- 智能审核 (`/smart/review/list`)
|
||
|
||
- **知识中心** (`/knowledge`)
|
||
- 知识库管理 (`/knowledge/dataset/index`)
|
||
- 文档管理 (`/knowledge/document/index`)
|
||
- 标签管理 (`/knowledge/tag/index`)
|
||
|
||
#### 路由守卫
|
||
- 认证检查：未登录用户自动跳转登录页
|
||
- 权限验证：根据路由meta中的permission字段验证权限
|
||
- Token处理：支持通过query参数传递token
|
||
|
||
### 2. 状态管理 (stores/)
|
||
|
||
#### Store模块
|
||
|
||
**dada Store** (`stores/modules/dada.ts`)
|
||
- 用户认证信息
|
||
- Token管理
|
||
- 租户信息
|
||
- 用户基本信息
|
||
|
||
**docs Store** (`stores/modules/docs.ts`)
|
||
- 文档相关状态
|
||
|
||
**chat Store** (`stores/modules/chat.ts`)
|
||
- 聊天会话状态
|
||
- 消息历史
|
||
|
||
**answerSetting Store** (`stores/modules/answerSetting.ts`)
|
||
- 智能问答设置
|
||
- 模型配置
|
||
|
||
**knowledge Store** (`stores/modules/knowledge.ts`)
|
||
- 知识库状态
|
||
- 文档列表
|
||
|
||
### 3. HTTP请求封装 (request/)
|
||
|
||
#### 请求拦截器
|
||
- 自动添加认证头：Token、TenantId、AuthId、ApplicationId
|
||
- 统一错误处理：处理token失效、权限错误等
|
||
|
||
#### 响应拦截器
|
||
- Token失效处理：自动清除token并跳转登录
|
||
- 错误码处理：
|
||
- 11011-11016: 认证相关错误
|
||
- 11051: 权限不足
|
||
|
||
#### 请求方法
|
||
- `get`: GET请求
|
||
- `post`: POST请求
|
||
- `put`: PUT请求
|
||
- `del`: DELETE请求
|
||
- `exportExcel`: 导出Excel
|
||
- `exportFile`: 导出文件
|
||
- `postStream`: 流式请求
|
||
|
||
### 4. 服务层 (servers/)
|
||
|
||
#### 服务分类
|
||
|
||
**base服务** (`servers/base/api/`)
|
||
- 组织管理 (`zuzhi.ts`)
|
||
- 员工管理 (`yuangong.ts`)
|
||
- 角色管理 (`jiaose.ts`)
|
||
- 岗位管理 (`gangwei.ts`)
|
||
- 文件上传 (`wenjianshangchuan.ts`)
|
||
- 业务附件 (`yewufujian.ts`)
|
||
|
||
**finyx服务** (`servers/finyx/api/`)
|
||
- 知识库 (`zhishiku.ts`)
|
||
- 文档 (`wendang.ts`)
|
||
- 智能体 (`zhinengti.ts`)
|
||
- 智能写作 (`zhinengxiezuo.ts`)
|
||
- 智能问答对话记录 (`zhinengtiduihuajilu.ts`)
|
||
- 机器人服务 (`jiqirenfuwu.ts`)
|
||
|
||
**oauth服务** (`servers/oauth/api/`)
|
||
- 用户登录 (`denglutuichuzhuce.ts`)
|
||
- 用户信息 (`yonghujibenxinxi.ts`)
|
||
- 验证码 (`yanzhengma.ts`)
|
||
|
||
### 5. 组件系统 (components/)
|
||
|
||
#### 全局组件
|
||
|
||
**布局组件**
|
||
- `LayoutContainer`: 布局容器
|
||
- `LoginContainer`: 登录容器
|
||
|
||
**业务组件**
|
||
- `CardBox`: 卡片盒子
|
||
- `CardBoxAgent`: 智能体卡片
|
||
- `CardBoxDataset`: 数据集卡片
|
||
- `AppTable`: 表格组件
|
||
- `AppAvatar`: 头像组件
|
||
|
||
**编辑器组件**
|
||
- `MdEditor`: Markdown编辑器
|
||
- `MdPreview`: Markdown预览
|
||
- `CodemirrorEditor`: 代码编辑器
|
||
|
||
**其他组件**
|
||
- `InfiniteScroll`: 无限滚动
|
||
- `AutoTooltip`: 自动提示
|
||
- `TagEllipsis`: 标签省略
|
||
- `DialogBox`: 对话框
|
||
|
||
### 6. 页面模块 (views/)
|
||
|
||
#### 智能中心 (smart/)
|
||
|
||
**智能问答** (`smart/answer/`)
|
||
- `index.vue`: 问答列表页
|
||
- `setting.vue`: 问答设置页
|
||
- 功能：创建智能体、配置模型、对话调试
|
||
|
||
**智能写作** (`smart/writing/`)
|
||
- `list.vue`: 写作列表页
|
||
- `index.vue`: 写作编辑页
|
||
- 功能：文档生成、大纲编辑、内容润色
|
||
|
||
**智能审核** (`smart/review/`)
|
||
- `list.vue`: 审核列表页
|
||
- `audit/index.vue`: 审核页面
|
||
- `extraction/index.vue`: 文档抽取页
|
||
- `plan.vue`: 审核方案页
|
||
- `rule/index.vue`: 规则详情页
|
||
- 功能：审核方案管理、规则配置、文档审核
|
||
|
||
#### 知识中心 (knowledge/)
|
||
|
||
**知识库管理** (`knowledge/dataset/`)
|
||
- `index.vue`: 知识库列表
|
||
- `view.vue`: 知识库详情
|
||
- `importDoc.vue`: 导入文档
|
||
- `viewParagraph.vue`: 查看分段
|
||
- 功能：知识库创建、文档导入、分段管理
|
||
|
||
**文档管理** (`knowledge/document/`)
|
||
- `index.vue`: 文档列表
|
||
- `uploadDoc.vue`: 上传文档
|
||
- `reviewDoc.vue`: 预览文档
|
||
- 功能：文档上传、预览、分类管理
|
||
|
||
**标签管理** (`knowledge/tag/`)
|
||
- `index.vue`: 标签列表
|
||
- `create.vue`: 创建标签
|
||
- `viewTag.vue`: 查看标签
|
||
- 功能：维度管理、标签创建、文档关联
|
||
|
||
#### 聊天模块 (chat/)
|
||
- `index.vue`: 聊天主页面
|
||
- 功能：智能体对话、消息历史、会话管理
|
||
|
||
### 7. 工具函数 (utils/)
|
||
|
||
#### 常用工具
|
||
|
||
**common.ts**
|
||
- 通用工具函数
|
||
|
||
**crypto.ts**
|
||
- 加密解密工具
|
||
|
||
**storage.ts**
|
||
- 本地存储封装（localStorage/sessionStorage）
|
||
|
||
**time.ts**
|
||
- 时间格式化工具
|
||
|
||
**message.ts**
|
||
- 消息提示封装
|
||
|
||
**clipboard.ts**
|
||
- 剪贴板操作
|
||
|
||
**uuid.ts**
|
||
- UUID生成
|
||
|
||
## 数据流
|
||
|
||
### 请求流程
|
||
```
|
||
组件/页面
|
||
↓
|
||
API调用 (api/*.ts)
|
||
↓
|
||
服务层 (servers/*/api/*.ts)
|
||
↓
|
||
HTTP请求 (request/http.ts)
|
||
↓
|
||
请求拦截器 (添加Token等)
|
||
↓
|
||
后端API
|
||
↓
|
||
响应拦截器 (错误处理)
|
||
↓
|
||
返回数据
|
||
```
|
||
|
||
### 状态管理流程
|
||
```
|
||
组件触发Action
|
||
↓
|
||
Store Action
|
||
↓
|
||
API调用
|
||
↓
|
||
更新State
|
||
↓
|
||
组件响应式更新
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
### 开发环境
|
||
- 端口：通过 `VITE_APP_PORT` 配置
|
||
- 代理：配置在 `vite.config.ts` 中
|
||
- Mock：可通过 `VITE_MOCK_DEV_SERVER` 启用
|
||
|
||
### 生产环境
|
||
- 构建：`pnpm build:prd`
|
||
- 压缩：Terser压缩，Gzip压缩
|
||
- 代码分割：按模块分割
|
||
- 打包：自动生成zip包
|
||
|
||
## 安全机制
|
||
|
||
1. **Token管理**
|
||
- Token存储在localStorage
|
||
- 自动检测Token失效
|
||
- Token失效自动跳转登录
|
||
|
||
2. **权限控制**
|
||
- 路由级权限验证
|
||
- API级权限验证（错误码11051）
|
||
|
||
3. **请求安全**
|
||
- 自动添加认证头
|
||
- 请求超时处理
|
||
- 错误统一处理
|
||
|
||
## 性能优化
|
||
|
||
1. **代码分割**
|
||
- 路由懒加载
|
||
- 按模块分割chunk
|
||
|
||
2. **资源优化**
|
||
- SVG图标雪碧图
|
||
- 图片资源压缩
|
||
- Gzip压缩
|
||
|
||
3. **构建优化**
|
||
- Terser压缩
|
||
- Tree-shaking
|
||
- 移除console.log
|
||
|
||
## 开发指南
|
||
|
||
### 添加新页面
|
||
1. 在 `src/views/` 创建页面组件
|
||
2. 在 `src/router/routes.ts` 添加路由
|
||
3. 如需API，在 `src/api/` 或 `src/servers/` 添加接口
|
||
|
||
### 添加新组件
|
||
1. 在 `src/components/` 创建组件
|
||
2. 如需全局注册，在 `src/components/index.ts` 注册
|
||
|
||
### 添加新Store
|
||
1. 在 `src/stores/modules/` 创建store文件
|
||
2. 在 `src/stores/index.ts` 导出
|
||
|
||
### 添加新API
|
||
1. 在 `src/servers/` 对应目录添加API文件
|
||
2. 使用 `src/request/http.ts` 的请求方法
|
||
|
||
## 常见问题
|
||
|
||
### 1. Token失效处理
|
||
Token失效会自动清除并跳转登录页，错误码：11011-11016
|
||
|
||
### 2. 权限不足
|
||
权限不足返回错误码11051，会显示错误提示
|
||
|
||
### 3. 请求超时
|
||
请求超时时间60秒，超时会显示错误并跳转登录
|
||
|
||
### 4. 环境变量
|
||
环境变量文件在 `env/` 目录，通过 `VITE_` 前缀暴露
|
||
|
||
## 更新日志
|
||
|
||
查看项目Git提交历史获取详细更新记录。
|
||
|