前端工程治理
一、 架构设计
目前需要改进一下基于fastapi构建py后端服务一些架构设计，这是现有的项目结构：
bash
RagFrontend/
├── .dockerignore
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── .npmignore
├── .prettierrc
├── Dockerfile
├── FSB.ico
├── README.md
├── eslint.config.ts
├── index.html
├── lensAPI.md
├── nginx.conf
├── package-lock.json
├── package.json
├── postcss.config.js
├── public/
│ ├── favicon.ico
│ ├── tdesign-logo.svg
├── src/
│ ├── App.vue
│ ├── main.ts
│ ├── vite-env.d.ts
│ ├── assets/
│ │ ├── README.md
│ │ ├── fadein.css
│ │ ├── logo-rag.png
│ │ ├── scroll.css
│ │ ├── tailwind.css
│ │ ├── styles/
│ │ │ └── global.css
│ │ ├── svg/
│ │ │ └── vite-logo.svg
│ ├── components/
│ │ ├── BackToTop.vue
│ │ ├── ErrorBoundary.vue
│ │ ├── GlobalSearch.vue
│ │ ├── ModelSelector.vue
│ │ ├── RetrievalConfig.vue
│ │ ├── ShareModal.vue
│ │ ├── SideBar.vue
│ │ ├── SmartAssistant.vue
│ │ ├── T-HeadBar.vue
│ │ ├── VoiceInput.vue
│ │ ├── canvas-point-unit/
│ │ │ ├── CanvasPoint.ts
│ │ │ ├── CanvasPoint.vue
│ │ │ └── DynamicLogo.vue
│ │ ├── chat-main-unit/
│ │ │ ├── chat-main-unit.vue
│ │ │ └── sseRequest-reasoning.ts
│ │ ├── ERS-Pages/
│ │ │ └── 404.vue
│ │ ├── graph-unit/
│ │ │ └── graph-main.vue
│ │ ├── knowledge-unit/
│ │ │ ├── KbCard.vue
│ │ │ └── knowledge-cards.vue
│ │ ├── search-unit/
│ │ │ └── search.vue
│ │ └── user-primary/
│ │ ├── ComingSoon.vue
│ │ ├── DSX_info.vue
│ │ └── user-primary.vue
│ ├── composables/
│ │ ├── useInteractions.ts
│ │ ├── useScrollReveal.ts
│ │ └── useTheme.ts
│ ├── i18n/
│ │ └── index.ts
│ ├── router/
│ │ └── index.ts
│ ├── store/
│ │ └── index.ts
│ │ └── modules/
│ │ ├── useCardData.ts
│ │ ├── useChatImg.ts
│ │ ├── useDataUser.ts
│ │ └── useEvalStore.ts
│ ├── styles/
│ │ └── animations.css
│ ├── utils/
│ │ ├── apiConfig.ts
│ │ ├── ASFaxios.ts
│ │ ├── ollamaApi.ts
│ │ └── request.ts
│ └── views/
│ ├── ACMD_serach/
│ │ └── ACMD_search.vue
│ ├── Agent.vue
│ ├── Architecture.vue
│ ├── Chat.vue
│ ├── Creation.vue
│ ├── DevTools.vue
│ ├── DOC.vue
│ ├── FileManagement.vue
│ ├── History.vue
│ ├── KnowledgePages/
│ │ ├── file-upload.ts
│ │ ├── knowledge-setting-card.vue
│ │ ├── knowledgebase-create.ts
│ │ ├── KnowledgeBase.vue
│ │ ├── KnowledgeDetail.vue
│ │ └── knowledge_graph_setting.vue
│ ├── LogonOrRegister/
│ │ ├── LoginRegisterForm.vue
│ │ └── LogonOrRegister.vue
│ ├── Ollama_Pages/
│ │ ├── OllamaModelDownload.vue
│ │ ├── OllamaModelList.vue
│ │ ├── OllamaSettings.vue
│ │ └── ollama_basic_pages.vue
│ ├── Settings.vue
│ ├── SettingsTabs/
│ │ ├── CommercialTab.vue
│ │ ├── ComplianceTab.vue
│ │ ├── EnterpriseToolsTab.vue
│ │ ├── MultiModelTab.vue
│ │ ├── OcrTab.vue
│ │ ├── RagEvalTab.vue
│ │ ├── RbacTab.vue
│ │ └── VersionTab.vue
│ ├── SharedKnowledge/
│ │ ├── SharedDetail.vue
│ │ └── SharedSquare.vue
│ └── TabHeader/
│ └── User_Page.vue
├── tailwind.config.js
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts项目 RagFrontend 是一个典型的基于 Vue 3 + TypeScript + Vite 的中大型前端应用。目前的结构虽然功能完备，但随着业务模块（如 Ollama、Knowledge、Chat 等）的增加，现有的“扁平化”结构会逐渐显露出维护困难、命名冲突和代码复用率低的问题。
针对目前的项目规模，需要从 “按类型分类” 转向 “按功能模块分类 + 基础设施分离” 的架构设计。
遂进行相关工作：
- 将 API 请求、类型定义、业务逻辑与 UI 组件解耦。
- 特定业务模块的组件、样式、逻辑应聚合在该模块目录下，而不是散落在全局。
- 将通用的 UI 组件（如 BackToTop）、工具函数、网络请求封装到底层库中。
二、 改进后的项目结构树
计划对 src/ 目录进行重构，结构如下：
bash
RagFrontend/
├── public/ # 静态资源 (不变)
├── src/
│ ├── App.vue # 根组件
│ ├── main.ts # 入口文件
│ ├── vite-env.d.ts # Vite 类型声明
│ │
│ ├── api/ # [重构] 网络请求层 (从 utils 中剥离)
│ │ ├── index.ts # Axios 实例配置、拦截器 (原 ASFaxios.ts)
│ │ ├── modules/ # 按业务模块划分 API
│ │ │ ├── knowledge.ts # 知识库相关 API
│ │ │ ├── chat.ts # 聊天相关 API
│ │ │ ├── ollama.ts # Ollama 模型 API
│ │ │ └── user.ts # 用户认证 API
│ │ └── types.ts # API 通用响应类型定义
│ │
│ ├── assets/ # 静态资源 (合并整理)
│ │ ├── images/ # 图片资源
│ │ └── styles/ # 全局样式 (合并原 assets/styles 和 src/styles)
│ │ ├── index.css # 样式入口
│ │ ├── tailwind.css # Tailwind 入口
│ │ ├── animations.css # 动画
│ │ └── global.css # 全局覆盖
│ │
│ ├── components/ # [重构] 组件库
│ │ ├── common/ # 通用基础组件 (无强业务逻辑)
│ │ │ ├── BackToTop.vue
│ │ │ ├── ErrorBoundary.vue
│ │ │ ├── GlobalSearch.vue
│ │ │ └── loading/
│ │ │
│ │ ├── business/ # 业务通用组件 (跨模块复用)
│ │ │ ├── ModelSelector.vue
│ │ │ ├── RetrievalConfig.vue
│ │ │ ├── VoiceInput.vue
│ │ │ └── layout/ # 布局相关
│ │ │ ├── SideBar.vue
│ │ │ └── T-HeadBar.vue
│ │ │
│ │ └── canvas/ # 特定功能组件 (原 canvas-point-unit)
│ │ ├── CanvasPoint.vue
│ │ └── DynamicLogo.vue
│ │
│ ├── composables/ # 组合式函数 (Hooks)
│ │ ├── useInteractions.ts
│ │ ├── useTheme.ts
│ │ └── useScrollReveal.ts
│ │
│ ├── constants/ # [新增] 常量定义
│ │ ├── app.ts # 应用级常量
│ │ └── ollama.ts # Ollama 默认配置等
│ │
│ ├── i18n/ # 国际化 (不变)
│ │ └── index.ts
│ │
│ ├── router/ # 路由配置
│ │ ├── index.ts # 路由入口
│ │ └── modules/ # [新增] 路由模块化
│ │ ├── knowledge.ts
│ │ └── ollama.ts
│ │
│ ├── store/ # 状态管理
│ │ ├── index.ts
│ │ └── modules/
│ │ ├── useChatStore.ts # 重命名：增加 Store 后缀以区分 Composables
│ │ ├── useUserStore.ts
│ │ └── useEvalStore.ts
│ │
│ ├── types/ # [新增] TypeScript 类型定义
│ │ ├── global.d.ts # 全局类型
│ │ ├── knowledge.d.ts # 业务实体类型
│ │ └── ollama.d.ts
│ │
│ ├── utils/ # 纯工具函数 (无网络请求)
│ │ ├── file-helper.ts # 文件处理 (提取自 views/KnowledgePages)
│ │ ├── date.ts # 时间处理
│ │ └── storage.ts # 本地存储封装
│ │
│ └── views/ # 页面视图 (按业务领域聚合)
│ ├── chat/ # 聊天模块
│ │ ├── Chat.vue # 主页面
│ │ └── components/ # 聊天专属子组件 (原 chat-main-unit)
│ │ └── ChatMainUnit.vue
│ │
│ ├── knowledge/ # 知识库模块 (合并 KnowledgePages, SharedKnowledge)
│ │ ├── KnowledgeBase.vue
│ │ ├── KnowledgeDetail.vue
│ │ ├── components/ # 知识库专属组件
│ │ │ ├── KbCard.vue
│ │ │ └── KnowledgeSettingCard.vue
│ │ └── composables/ # 知识库专属逻辑
│ │ └── useFileUpload.ts
│ │
│ ├── ollama/ # Ollama 模块 (合并 Ollama_Pages)
│ │ ├── OllamaView.vue # 入口页
│ │ ├── components/
│ │ │ ├── ModelList.vue
│ │ │ └── ModelDownload.vue
│ │ └── utils/ # Ollama 专属工具
│ │
│ ├── settings/ # 设置模块
│ │ ├── Settings.vue
│ │ └── components/ # 原 SettingsTabs
│ │ ├── CommercialTab.vue
│ │ └── RagEvalTab.vue
│ │
│ ├── auth/ # 认证模块 (原 LogonOrRegister)
│ │ └── Login.vue
│ │
│ └── error/ # 错误页面
│ └── 404.vue
│
├── .env # 环境变量
├── Dockerfile
└── ... (配置文件)三、 工程治理
1. API 层剥离
现状：API 配置 (apiConfig.ts)、请求封装 (ASFaxios.ts) 和具体业务 API (ollamaApi.ts) 混在 utils 中。 改进：
- 建立
src/api目录。 src/api/index.ts负责创建 Axios 实例，配置拦截器（Token 注入、全局错误处理）。src/api/modules/下按业务划分，例如chat.ts包含sendMessage,stopStream等方法。- 收益：业务代码中不再直接处理 HTTP 状态码，只需调用 API 函数。
2. Views 模块化
现状：KnowledgePages 里有 .ts 文件 (file-upload.ts)，views 下既有文件夹又有散乱文件 (Agent.vue, Chat.vue)。 改进：
- 将功能高度相关的页面聚合。例如，将
KnowledgePages和SharedKnowledge合并或关联到views/knowledge下。 - 子组件下沉：原
components/chat-main-unit这种只被Chat.vue使用的组件，应移动到views/chat/components/下。这避免了全局components目录的膨胀。 - 逻辑提取：
KnowledgePages/file-upload.ts这种逻辑如果是该模块独有的，放入views/knowledge/composables/或utils/；如果是通用的，放入src/utils/。
3. Components 分层
现状：SideBar.vue 和 canvas-point-unit 平级，但它们的复用度显然不同。 改进：
- Common (基础组件)：
BackToTop,ErrorBoundary这种不依赖业务数据的组件。 - Business (业务组件)：
ModelSelector,RetrievalConfig这种包含业务逻辑、被多个页面共用的组件。 - Layout (布局组件)：
SideBar,T-HeadBar单独管理。
4. 类型管理
现状：没有看到专门的 types 目录，类型可能散落在 .vue 文件中或 utils 中。 改进：
- 建立
src/types。定义后端返回的数据结构接口，如KnowledgeBase,ChatMessage,OllamaModel。 - 在
api/modules和store中引用这些类型，实现端到端的类型安全。
5. 样式治理
现状：assets 下有 CSS，src/styles 下也有 CSS。 改进：
- 统一合并到
src/assets/styles。 tailwind.css只包含 Tailwind 的指令。global.css放置全局覆盖样式。- 在
main.ts中统一引入import '@/assets/styles/index.css'。
按以下步骤逐步重构：
- 第一步：整理
api。将utils里的请求逻辑迁移到src/api，并在main.ts或组件中替换引用。 - 第二步：整理
views。先处理最复杂的模块（如 Knowledge），创建目录，将相关文件移动进去，更新路由路径。 - 第三步：清理
components。识别哪些是页面专属的，移动到对应 View 目录下；剩下的按 Common/Business 分类。
最后新的架构设计最好能支持项目未来一段时间的快速迭代