finyx_frontend/docs/ARCHITECTURE.md

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