ai-robot-core/spec/ai-service-admin/design.md

module	title	status	version	owners	last_updated
ai-service-admin	AI 中台管理界面（ai-service-admin）前端技术设计	draft	0.1.0	frontend backend	2026-02-24

AI 中台管理界面前端技术设计（Design）

1. 架构概览（Architecture Overview）

本模块作为 AI 中台（ai-service）的管理侧前端，基于 Vue 3 + Pinia + Element Plus 构建，旨在提供一套高效、响应式的 AI 资产管理与调试工具。

1.1 核心技术栈

• 框架：Vue 3 (Composition API)
• 状态管理：Pinia
• 组件库：Element Plus
• 网络请求：Axios + OpenAPI Generated SDK
• 工程基座：RuoYi-Vue-Plus 前端基座（复用权限与布局）

---

2. 页面布局与交互设计（UI/UX Design）

2.1 知识库管理（KB Management）

• 布局：列表页 + 抽屉/详情页。
• 核心功能：
  • 文档列表：支持文件名称、上传时间、索引状态筛选。
  • 上传组件：
    • 集成 Element Plus el-upload，支持多文件并发。
    • 列表展示文件切片与向量化进度条（基于任务轮询）。
  • 任务轮询策略：
    • 进入详情页或上传后，每 3s 调用 /admin/kb/index/jobs/{jobId}。
    • 状态流转：pending (排队) -> processing (处理中) -> completed (完成) / failed (失败)。
    • 失败任务点击“错误详情”展示后端返回的 errorMsg。

2.2 RAG 实验室（RAG Lab）

• 布局：双栏对比视图。
  • 左侧：调试输入。
    • 输入 Query 文本框。
    • 参数配置面板（Top-K, Score Threshold, Prompt Version 选择）。
  • 右侧：实验结果（分屏或页签）。
    • 召回片段栏：展示 retrievalResults 列表，高亮显示 Score 分值与来源。
    • 最终 Prompt 栏：代码块展示（Read-only），直观呈现变量替换后的上下文效果。
• 交互：点击“运行实验”按钮，Loading 状态锁定右侧视图，完成后平滑更新数据。支持保存实验快照进行历史对比。

2.3 会话监控（Session Monitoring）

• 列表页：
  • 支持多字段过滤：租户 ID、会话 ID、时间范围、模型/场景、是否包含错误。
  • 列表展示：会话摘要、首字耗时、总消息数、状态码。
• 详情详情弹窗：
  • 全链路追踪视图：采用 Timeline 或消息气泡流。
  • Trace 信息排查：点击单条回复，展开展示对应的检索命中、工具调用参数及结果。

---

3. 状态管理与拦截器设计（State & Security）

3.1 租户状态管理（Pinia）

创建 tenant store，用于持久化维护当前操作的租户上下文。

// store/modules/tenant.ts
export const useTenantStore = defineStore('tenant', {
  state: () => ({
    currentTenantId: localStorage.getItem('X-Tenant-Id') || 'default'
  }),
  actions: {
    setTenant(id: string) {
      this.currentTenantId = id;
      localStorage.setItem('X-Tenant-Id', id);
    }
  }
});

3.2 Axios 自动注入（Interceptor）

在全局请求拦截器中，自动从 Store 读取并注入 X-Tenant-Id。

// utils/request.ts
service.interceptors.request.use(config => {
  const tenantStore = useTenantStore();
  if (tenantStore.currentTenantId) {
    config.headers['X-Tenant-Id'] = tenantStore.currentTenantId;
  }
  return config;
}, error => {
  return Promise.reject(error);
});

---

4. 组件封装（Component Design）

4.1 基础封装

• BaseTable：二次封装 el-table，内置分页逻辑与 X-Tenant-Id 联动。
• BaseForm：统一的字段校验与错误反馈提示。

4.2 业务专用组件

• RagResultCard：用于展示 RAG 召回片段，支持预览原始文档。
• PromptEditor：基于 Monaco Editor 或简易 Textarea，集成 {{variable}} 语法高亮提示。

---

5. 异常处理策略（Exception Handling）

5.1 统一拦截机制

在 Axios 响应拦截器中对 401 与 403 进行分流处理：

• 401 Unauthorized：
  • 清除本地 Token 与缓存。
  • 引导用户重定向至登录页（Login Page）。
  • 提示信息：“登录已失效，请重新登录”。
• 403 Forbidden：
  • 非阻塞提示：使用 el-message 报错“当前操作无权限”。
  • 阻塞处理：若为页面初始化失败，展示“403 无权访问”占位图。

5.2 统一错误模型映射

后端返回的错误结构（如 code, message, requestId）将被映射到 UI 层，便于管理员复制 requestId 进行后端日志追溯。

---

6. 数据流设计（Data Flow）

• 数据获取：组件挂载 -> 注入 X-Tenant-Id -> 调用 SDK -> 更新本地状态。
• 权限控制：基于后端返回的 permissions 数组，通过 v-hasPermi 指令控制按钮显隐。