---
module: ai-service-admin
title: "AI 中台管理界面（ai-service-admin）前端技术设计"
status: "draft"
version: "0.1.0"
owners:
  - "frontend"
  - "backend"
last_updated: "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，用于持久化维护当前操作的租户上下文。

```typescript
// 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`。

```typescript
// 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` 指令控制按钮显隐。