4.8 KiB

Raw Blame History

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

4.8 KiB Raw Blame History Unescape Escape