From 60953a14c5ec5669b1f1afa138001edc41b22c87 Mon Sep 17 00:00:00 2001
From: MerCry <jiong1114>
Date: Tue, 24 Feb 2026 14:09:53 +0800
Subject: [PATCH] docs(spec): add frontend design for ai-service-admin
 [AC-ASA-01]

---
 spec/ai-service-admin/design.md | 132 ++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 spec/ai-service-admin/design.md

diff --git a/spec/ai-service-admin/design.md b/spec/ai-service-admin/design.md
new file mode 100644
index 0000000..831a250
--- /dev/null
+++ b/spec/ai-service-admin/design.md
@@ -0,0 +1,132 @@
+---
+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` 指令控制按钮显隐。