# 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提交历史获取详细更新记录。