133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
---
|
||
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` 指令控制按钮显隐。
|