10 - 前端架构与能力驱动UI

Vue 3.5 + Pinia + 14主题 + 22种能力枚举驱动的动态界面

一、前端技术栈

技术	版本	用途
Vue	3.5	响应式框架，Composition API
TypeScript	6	类型安全
Vite	8	构建工具，极速HMR
Pinia	3	状态管理（Composition API风格）
Vue Router	4	路由（HTML5 History模式）
Element Plus	-	UI组件库
GSAP	-	主题切换动画、卡片入场动画
tsparticles	-	粒子背景（按主题定制）
DOMPurify	-	HTML消毒（防XSS）
Playwright	-	E2E测试

二、前端架构总览

                    前端架构
                    ════════

  App.vue (2200行应用壳)
    ├── 导航栏 (权限过滤的菜单)
    ├── 侧边栏 (对话列表、Agent选择器)
    ├── 10个侧面板 (文档/相册/网盘/微信/简历...)
    ├── 主题选择器 (14种主题)
    └── 内容区 (Router View)

  路由层 (16条路由 + 权限守卫)
    ├── /login, /onboarding (游客路由)
    ├── /home (首页 - 轮播+Agent网格)
    ├── /chat (聊天 - SSE流+Plan模式+工具审批)
    ├── /data (数据分析)
    ├── /tasks (任务中心)
    ├── /ops (运维中心 - 监控/模型统计/安全日志)
    ├── /agent-runtime (Agent运行时监控)
    ├── /infra (基础设施)
    ├── /settings (设置)
    └── /channel-robots (通道机器人管理)

  状态管理 (5个Pinia Store)
    ├── user (JWT + 用户信息 + 权限)
    ├── agent (Agent列表 + 能力 + 分类)
    ├── model (模型选择 + 最近使用)
    ├── photo (相册状态)
    └── wechat (微信备份状态)

  API层 (26个模块)
    ├── http.ts (Axios封装 + authFetch统一认证 + 缓存 + JWT拦截)
    └── chat.ts (SSE流式通信)

三、能力驱动动态UI — 核心创新

这是前端架构的最大亮点：后端Agent声明22种能力枚举，前端根据能力自动渲染：

能力驱动动态UI:

  后端 Agent 声明能力:
  @Override
  public Set<AgentCapability> getCapabilities() {
      return Set.of(
          DOCUMENT_UPLOAD,      // 支持文档上传
          SOURCE_CITATION,      // 来源引用显示
          MODEL_SELECTION,      // 可切换模型
          PLAN_MODE            // 支持计划模式
      );
  }

  前端根据能力动态渲染:
  ┌─────────────────────────────────────────────┐
  │ 聊天面板                                    │
  │                                             │
  │ DOCUMENT_UPLOAD? → 显示上传按钮 📎         │
  │ MODEL_SELECTION? → 显示模型选择器 🤖       │
  │ PLAN_MODE?       → 显示计划模式切换 📋     │
  │ QUICK_ASK?       → 显示快速提问 ⚡          │
  │ SOURCE_CITATION? → 显示来源引用卡片 📄     │
  │                                             │
  │ 侧面板:                                    │
  │ NETDISK_VIEW?      → 网盘面板               │
  │ PHOTO_GALLERY?     → 相册面板               │
  │ WECHAT_BACKUP?     → 微信备份面板           │
  │ CONTENT_LIBRARY?   → 内容库面板             │
  │ RESUME_SCREENING?  → 简历筛选面板           │
  │ MOSAIC_GENERATION? → 马赛克拼图面板         │
  └─────────────────────────────────────────────┘

  新增Agent无需修改前端代码!
  只需在后端声明新的能力枚举 + 提供对应组件

四、SSE流式通信

前端SSE流式处理 (ChatView.vue):

  authFetch('/api/conversations/{id}/messages', {method:'POST'})
    │  ← authFetch 自动注入 JWT + 统一 401 处理
    ▼ response.body.getReader()
    │
    ├── ReadableStream 逐chunk读取
    │   手动SSE协议解析:
    │   · 按 "\n\n" 分割事件块
    │   · 提取 event: 和 data: 行
    │
    ├── 15+ 事件类型处理:
    │   ├── "content"     → 追加AI文本
    │   ├── "tool"        → 显示工具调用面板
    │   ├── "thinking"    → 显示思维链折叠块
    │   ├── "sources"     → 显示来源引用卡片
    │   ├── "plan_proposal" → 显示计划模式面板
    │   ├── "task_decomp" → 显示任务分解进度
    │   ├── "tool_approval_required" → 显示审批按钮
    │   ├── "guard_blocked" → 显示安全拦截警告
    │   └── "done"        → 结束流
    │
    └── AbortController 支持流取消
        用户可以随时停止生成

  自动滚动: 检测用户是否在底部
    ├── 是 → 自动跟随滚动
    └── 否 → 不打断用户阅读

五、14种主题系统

项目实现了14种视觉主题，包括10种亮色和4种暗色：

主题系统架构:

  CSS自定义属性驱动:
  [data-theme='default'] { --primary: #6366f1; --bg: #fff; ... }
  [data-theme='cyberpunk'] { --primary: #ff0080; --bg: #0a0a0f; ... }
  [data-theme='chinese-ink'] { --primary: #8b4513; --bg: #f5f0e8; ... }

  主题切换动画 (GSAP):
  ┌─────────────────────────────────────┐
  │ 1. 读取当前 computedStyle 所有变量  │
  │ 2. 临时切换到新主题                 │
  │ 3. 读取新主题所有变量               │
  │ 4. 恢复旧主题                       │
  │ 5. GSAP 从旧值动画到新值 (0.5s)    │
  │ 6. 动画完成 → 正式切换主题         │
  └─────────────────────────────────────┘

  主题专属粒子效果:
  · cyberpunk: 霓虹色粒子
  · aurora: 极光流动
  · chinese-ink: 水墨晕染
  · obsidian: 暗色沉稳

六、权限系统

三层权限控制：

三层权限体系:

  Layer 1: 路由守卫
  router.beforeEach → 检查 route.meta.permission
  无权限 → 重定向到 /forbidden

  Layer 2: 自定义指令
  <button v-permission="'admin:role-manage'">管理角色</button>
  无权限 → DOM元素直接移除

  Layer 3: 编程式检查
  if (userStore.hasPermission('agent:rag')) { ... }
  灵活的条件渲染和逻辑控制

  Admin角色: 绕过所有权限检查 (超级管理员)

七、小程序端同步架构

跨平台同步： 项目还有一个微信小程序端（hub-miniprogram），使用uni-app构建，与Web端共享相同的API接口、权限码、功能集。小程序支持28个页面、SSE流式通信（enableChunked）、纯CSS图表（避免引入echarts增大包体积），以及自定义导航栏和安全区适配。

八、面试高频问题

Q: 能力驱动UI是怎么实现的？
A: 后端Agent通过 getCapabilities() 返回一组 AgentCapability 枚举值（如DOCUMENT_UPLOAD、PLAN_MODE等）。前端Agent Store加载后，聊天面板根据当前Agent的能力列表，条件性地渲染对应的组件（上传按钮、模型选择器、计划模式开关等）。新增Agent只需声明能力，不需要写任何前端渲染逻辑。

Q: 14种主题切换为什么用GSAP而不是CSS transition？
A: CSS transition只能对已知属性名进行过渡，但主题切换涉及180+个CSS变量。GSAP方案可以自动发现哪些颜色值发生了变化，只对这些变量进行插值动画，还支持不同颜色格式（hex/rgba/hsl）之间的平滑过渡。此外GSAP还支持 prefers-reduced-motion 检测，对无障碍用户直接跳过动画。