pj0235-eai_agentplatform/docs/02_Architecture/AR02_Frontend_Arch.md

AR02 — 前端架构设计

版本：V1.1 | 左导航 + 中间工作区 + 右 AI 侧栏 | Vue3 + Vite + Element Plus 参考：pj006-zhilianyuan2 frontend-orgadmin 三栏布局模式

2026-09-16 口径同步说明： 本文档记录的是 V1 三栏前端架构基线。 当前正式产品导航与对象化工作台口径，请以 docs/01_System_Overall/SY22_Role_Skill_App_Unified_Task_Architecture.md 为准： 新建任务 / 项目 / 专员·技能·APP·连接器 / 长程APP / 知识库 / 后台管理 / 我的 另外，当前前端命名已明确拆分为： pageRoute = 普通页面导航，objectEntryRoute = 业务对象入口，ai_route_* = AI 模型路由。

---

1. 目录结构

frontend/
├── public/
│   └── static-lib/            # 本地 pdf.js（无 CDN）
├── src/
│   ├── api/                   # API 调用层（axios 封装）
│   │   ├── auth.js
│   │   ├── product.js
│   │   ├── course.js
│   │   ├── exam.js
│   │   ├── media.js
│   │   ├── aiChat.js
│   │   └── system.js
│   ├── components/            # 通用组件
│   │   └── MaterialSuggestUpload.vue  # 员工提交素材弹窗
│   ├── layout/                # 全局布局
│   │   ├── MainLayout.vue     # 三栏布局（左导航 + 内容 + AI 侧栏）
│   │   ├── SideNav.vue        # 左边栏导航（含品牌 + 菜单 + 用户信息）
│   │   └── PathCoachPanel.vue # 右侧 AI 聊天框
│   ├── router/                # 路由
│   │   ├── index.js           # 路由定义
│   │   └── guards.js          # 路由守卫（角色/认证）
│   ├── store/                 # 状态管理（Pinia）
│   │   ├── auth.js            # 用户认证状态
│   │   └── aiChat.js          # AI 聊天会话
│   ├── views/                 # 页面视图
│   │   ├── home/              # 首页
│   │   ├── companyTrain/      # 公司介绍培训
│   │   ├── product/           # 产品知识
│   │   ├── salesTrain/        # 产品销售培训
│   │   ├── exam/              # 考试
│   │   ├── knowledge/         # 管理员-知识管理
│   │   └── system/            # 管理员-系统管理
│   ├── App.vue
│   └── main.js
├── index.html
├── vite.config.js
└── package.json

2. 布局结构

┌──────┬───────────────────────────────────────┬────────────────┐
│ 导航  │                                       │                │
│ ───── │         主工作区                      │  AI PathCoach  │
│ 品牌  │   <router-view />                    │  ────────────  │
│       │                                       │  消息列表      │
│ 首页  │                                       │                │
│ 公司  │                                       │  [输入] [发送]  │
│ 产品  │                                       │                │
│ 销售  │                                       │  [情景演练]    │
│ 考试▼ │                                       │  [查佣金]      │
│       │                                       │  [产品对比]    │
│ ───── │                                       │                │
│ 知识▼ │  ← admin only                         │                │
│ 系统▼ │  ← admin only                         │                │
│       │                                       │                │
│ ───── │                                       │                │
│ 用户  │  [退出]                               │                │
└──────┴───────────────────────────────────────┴────────────────┘

收起 AI 面板状态：左边导航不变，主内容区占满剩余宽度，右下角浮动 [🤖 展开AI] 按钮。

3. 路由设计

路径	视图	角色	说明
/	Home	all	首页
/company-train	CompanyTrain	all	公司介绍培训
/products	ProductList	all	产品列表
/products/:id	ProductDetail	all	产品详情
/courses	CourseList	all	课程列表
/courses/:id	CourseDetail	all	课程详情
/exam/self-test	ExamSelfTest	all	自测练习
/exam/formal	ExamFormal	all	正式结业考试
/exam/my-records	ExamMyRecord	all	我的考试记录
/exam/questions	ExamQuestionBank	admin	题库管理
/knowledge/materials	MaterialManage	admin	课件素材管理
/knowledge/audit	MaterialAuditList	admin	素材审批列表
/system/users	UserManage	admin	用户账号管理
/system/exam-records	ExamRecordManage	admin	全部考试成绩
/system/config	SystemConfig	admin	系统参数配置

4. 路由守卫

// router/guards.js
import { useAuthStore } from '@/store/auth'

router.beforeEach((to, from, next) => {
  if (to.path === '/login') {
    next()
    return
  }

  const authStore = useAuthStore()

  // 未登录 → 跳转登录页
  if (!authStore.isLoggedIn) {
    return next('/login')
  }

  // 管理员路由校验（前端仅作 UX 隐藏，非安全边界）
  if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') {
    return next('/')
  }

  next()
})

5. API 调用模式

// api/http.js — axios 封装
import axios from 'axios'
import { ElMessage } from 'element-plus'

const http = axios.create({ baseURL: '/api' })

http.interceptors.request.use(config => {
  const token = localStorage.getItem('token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

http.interceptors.response.use(
  res => res.data.data,       // 解包 Envelope
  err => {
    const resp = err.response
    if (resp?.status === 401) {
      localStorage.removeItem('token')
      window.location.href = '/login'
    } else if (resp?.status === 501) {
      // LLM 未配置等服务器配置错误
      ElMessage.error(resp.data?.message || '服务未配置，请联系管理员')
    }
    return Promise.reject(resp?.data)
  }
)

export default http

6. AI 聊天状态管理

// store/aiChat.js
import { defineStore } from 'pinia'

export const useAiChatStore = defineStore('aiChat', {
  state: () => ({
    visible: true,           // 是否展开
    messages: [],            // 对话历史
    context: null,           // 当前页面上下文（productId/courseId）
    isStreaming: false,      // 是否正在流式响应
  }),
  actions: {
    toggle() { this.visible = !this.visible },
    setContext(ctx) { this.context = ctx },
    clearMessages() { this.messages = [] },
  }
})