ui-vue3 项目架构分析
一、技术栈
#### 核心框架
- Vue 3.3.8（Composition API）
- TypeScript 5.3.3
- Vite 5.4.21
- Ant Design Vue 4.0.8
- Vue Router 4.2.5
- Pinia 2.3.1（状态管理）
- vue-i18n 9.14.5（国际化）
- Monaco Editor（代码编辑器）
- Axios 1.12.0（HTTP 客户端）
二、项目目录结构
ui-vue3/src/
├── api/ # API 服务层（17个服务文件）
│ ├── agent.ts
│ ├── common-api-service.ts
│ ├── cron-api-service.ts
│ └── ...
├── base/ # 基础配置
│ └── i18n/ # 国际化配置
├── components/ # 可复用组件（43个组件）
│ ├── chat/ # 聊天相关组件
│ ├── sidebar/ # 侧边栏组件
│ ├── editor/ # 编辑器组件
│ └── ...
├── composables/ # 组合式函数（3个）
│ ├── useRequest.ts
│ ├── useMessage.ts
│ └── useMcpConfigForm.ts
├── plugins/ # 插件
│ └── useToast.ts
├── router/ # 路由配置
│ ├── index.ts
│ └── defaultRoutes.ts
├── stores/ # Pinia 状态管理（6个 store）
│ ├── task.ts
│ ├── memory.ts
│ ├── namespace.ts
│ └── ...
├── types/ # TypeScript 类型定义（8个）
│ ├── agent-execution-detail.ts
│ ├── cron-task.ts
│ └── ...
├── utils/ # 工具函数（5个）
│ ├── request.ts
│ ├── plan-execution-manager.ts
│ └── ...
└── views/ # 页面视图（4个主要页面）
├── home/
├── direct/
├── configs/
└── init/
三、核心架构层次
#### 1. 入口层（Entry Layer）
``17:33:ui-vue3/src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import Antd from 'ant-design-vue'
import router from './router' import App from './App.vue' import 'ant-design-vue/dist/reset.css' import { i18n } from '@/base/i18n'
import Vue3ColorPicker from 'vue3-colorpicker' import 'vue3-colorpicker/style.css' import 'nprogress/nprogress.css'
const app = createApp(App) const pinia = createPinia()
app.use(pinia).use(Antd).use(Vue3ColorPicker).use(i18n).use(router).mount('#app')
职责：
- 初始化 Vue 应用
- 注册全局插件（Pinia、Ant Design、i18n、Router）
- 挂载根组件
#### 2. 路由层（Router Layer）
const options = { history: createWebHashHistory('/ui'), routes, } const router = createRouter(options)
// Global route guard for initialization check router.beforeEach(async (to, _from, next) => { // Skip initialization check for the init page itself if (to.path === '/init') { next() return }
try { // Check initialization status from server const response = await fetch('/api/init/status') const result = await response.json()
if (result.success && !result.initialized) { // System not initialized, redirect to init page localStorage.removeItem('hasInitialized') next('/init') return } else if (result.success && result.initialized) { // System is initialized, save to localStorage localStorage.setItem('hasInitialized', 'true') } } catch (error) { console.warn('Failed to check initialization status:', error) // If check fails, rely on localStorage const hasInitialized = localStorage.getItem('hasInitialized') === 'true' if (!hasInitialized) { next('/init') return } }
next() })
特点：
- 使用 Hash 路由（`createWebHashHistory`）
- 全局前置守卫：检查系统初始化状态
- 路由懒加载：使用动态 `import()`
路由结构：
- `/init` - 初始化页面
- `/home` - 首页（对话）
- `/direct/:id?` - 直接执行页面
- `/configs/:category?` - 配置页面
#### 3. API 服务层（API Service Layer）
组织方式：按功能模块划分，每个模块一个服务文件
/**
- Get all cron tasks
设计模式：
- 类静态方法模式（如 `CronApiService`）
- 函数导出模式（如 `agent.ts`）
- 统一错误处理：私有 `handleResponse` 方法
API 服务列表（17个）：
- `agent.ts` - 代理管理
- `common-api-service.ts` - 通用执行器
- `cron-api-service.ts` - 定时任务
- `config-api-service.ts` - 配置管理
- `memory-api-service.ts` - 记忆管理
- `model-api-service.ts` - 模型配置
- 等等...
#### 4. 状态管理层（State Management Layer）
使用 Pinia，采用 Composition API 风格：
// Set new task const setTask = (prompt: string) => { console.log('[TaskStore] setTask called with prompt:', prompt)
// Don't create tasks with empty prompts if (!prompt.trim()) { console.warn('[TaskStore] Empty prompt provided, not creating task') return }
const newTask = { prompt, timestamp: Date.now(), processed: false, } currentTask.value = newTask console.log('[TaskStore] Task set, currentTask.value:', currentTask.value) } // ... 更多方法
Store 列表（6个）：
- `task.ts` - 任务管理
- `memory.ts` - 记忆存储
- `namespace.ts` - 命名空间
- `sidebar.ts` - 侧边栏状态
- `uploadedFiles.ts` - 上传文件
- `counter.ts` - 计数器（示例）
#### 5. 组件层（Component Layer）
组件组织：按功能模块划分
主要组件模块：
- `chat/` - 聊天相关（9个组件）
- `ChatContainer.vue` - 聊天容器
- `ChatMessage.vue` - 消息组件
- `AssistantMessage.vue` - AI 助手消息
- `UserMessage.vue` - 用户消息
- `composables/` - 聊天相关组合式函数
- `sidebar/` - 侧边栏（6个组件）
- `Sidebar.vue` - 主侧边栏
- `PlanGenerator.vue` - 计划生成器
- `JsonEditor.vue` - JSON 编辑器
- `editor/` - 代码编辑器
- `MonacoEditor.ts` - Monaco 编辑器封装
- `configs/` - 配置相关组件
#### 6. 视图层（View Layer）
页面结构：
- `home/index.vue` - 首页（对话界面）
- `direct/index.vue` - 直接执行页面
- `configs/index.vue` - 配置页面（包含多个子配置）
- `init/index.vue` - 初始化页面
#### 7. 工具层（Utility Layer）
export function useRequest() { const loading = ref(false)
const executeRequest = async
if (result.success && successMessage) { // Need to pass showMessage function from outside to avoid circular dependencies console.log(successMessage) } else if (!result.success && errorMessage) { console.error(errorMessage) }
return result } catch (error) { console.error('Request execution failed:', error) if (errorMessage) { console.error(errorMessage) } return null } finally { loading.value = false } }
return { loading, executeRequest, } }
工具函数：
- `useRequest.ts` - 请求处理组合式函数
- `request.ts` - HTTP 请求封装
- `plan-execution-manager.ts` - 计划执行管理
- `cron-task-utils.ts` - 定时任务工具
### 四、数据流架构
### 五、设计模式与最佳实践
#### 1. 组合式 API（Composition API）
- 使用 `<script setup>` 语法
- 组合式函数（Composables）复用逻辑
#### 2. 关注点分离
- API 层：独立服务文件
- 状态管理：Pinia stores
- UI 组件：按功能模块组织
- 工具函数：独立 utils
#### 3. 类型安全
- TypeScript 类型定义（`types/` 目录）
- 接口定义用于 API 请求/响应
#### 4. 国际化支持
#### 5. 路由守卫
- 全局前置守卫检查初始化状态
- 自动重定向到初始化页面
六、构建与部署
#### 开发环境
- Vite 开发服务器
- 代理配置：
→ http://localhost:18080
热模块替换（HMR）
#### 生产环境
- 构建输出：
ui-vue3/ui/
部署到： src/main/resources/static/ui/`
七、架构特点总结
优点： 1. 模块化：按功能清晰划分 2. 类型安全：TypeScript 覆盖 3. 可维护性：代码组织清晰 4. 可扩展性：易于添加新功能 5. 前后端分离：独立开发和部署
技术亮点：
- Vue 3 Composition API
- Pinia 状态管理
- TypeScript 类型系统
- 组件化设计
- 国际化支持