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

---
module: ai-service-admin
title: "AI 中台管理界面（ai-service-admin）— Scoping（定界）结果"
status: draft
version: 0.1.0
owners:
  - product
  - frontend
  - backend
last_updated: 2026-02-24
methodology:
  - spec-driven
  - api-first
---

# AI 中台管理界面（ai-service-admin）— Scoping（定界）结果

> 本文档为“规范驱动 + 接口先行”的第 0 阶段产出：模块边界澄清 + 依赖接口盘点（Consumer-First）。
> 
> 输出完成后**停止**，等待确认；在确认前不进入 requirements/OpenAPI/Design/Tasks 的正式编写。

## 1) 模块职责（Module Responsibilities）

### 1.1 模块定位
`ai-service-admin` 是一个**独立前端管理模块**，面向运营/管理员/租户管理员，用于管理 AI 中台的知识库资产、租户级配置、RAG 调试与全局会话观测。

### 1.2 包含（In Scope）
必须覆盖以下能力（以管理与观测为主）：

1. **知识库上传/索引管理**
   - 数据源上传（文件/文本/URL 等，具体形态由后续 requirements 细化）
   - 数据源状态查看、重试、删除/下线
   - 索引构建（触发/进度/失败原因）与文档分片/向量化相关的可观测信息（仅展示，不实现算法）
   - 基础检索配置（如 topK、召回阈值、chunk 策略等）：以“配置项编辑 + 生效范围”呈现

2. **租户级 Prompt 模板配置**
   - 租户维度的 Prompt 模板 CRUD、版本管理（草案/发布）、回滚
   - 模板与使用场景（如：RAG 问答、工具调用、摘要等）的绑定（场景枚举由后端定义）
   - 变量占位符与校验提示（前端校验为体验增强，最终以后端校验为准）

3. **RAG 检索效果实验室（调试窗）**
   - 输入问题 → 触发“检索/重排/上下文构造”调试链路
   - 展示：召回文档列表（含得分/来源/片段）、重排结果、最终上下文、以及关键日志/耗时
   - 支持对比实验（如不同检索参数、不同 prompt 版本）
   - 支持保存/复用实验配置与结果快照（用于回归对比）

4. **全局会话监控**
   - 多租户维度的会话列表、筛选（时间、租户、用户标识、会话状态、模型/渠道等）
   - 查看单次会话详情：消息流、检索命中、工具调用、错误栈/错误码、耗时
   - 基础统计：会话量、失败率、平均耗时、Top 知识库/Top Prompt 版本使用情况（指标范围后续细化）

### 1.3 不包含（Out of Scope）
明确不在本模块实现范围内：

- **具体 AI 推理逻辑**（由 `ai-service` 负责），包括但不限于：LLM 调用、embedding 计算、rerank 算法、提示词编排执行引擎本体。
- **用户侧聊天界面**（由 `ai-robot` 负责），即面向终端用户的对话交互 UI。
- **底层存储/索引实现**（向量库、全文检索、对象存储等）与运维部署策略。

### 1.4 边界接口原则
- `ai-service-admin` 只作为 **Consumer（调用方）** 消费 Python 后端（`ai-service`）提供的“管理类/观测类 API”。
- 所有“调试/实验”动作也通过管理 API 触发，前端不直接连接向量库或模型。

---

## 2) 技术栈建议（Tech Stack Recommendation）

### 2.1 选型建议
优先推荐：**Vue 3 + Element Plus**（与 RuoYi-Vue 生态对齐）。
备选：React（若团队已有成熟 React 组件体系与工程基座）。

### 2.2 选择理由（面向本模块）
- RuoYi-Vue 管理后台形态与 Element Plus 组件库天然匹配（表格/表单/弹窗/权限路由）。
- 本模块以“配置管理 + 列表筛选 + 详情查看 + 调试面板”交互为主，Element Plus 现成组件覆盖度高。

### 2.3 工程与基础能力（建议纳入后续 design）
- 多租户与权限：建议前端采用**路由级权限 + 按钮级权限**（能力来源于后端返回的权限集）。
- 国际化：可选（若需要多语言运营）。
- 可观测性：前端埋点/日志仅做体验与错误上报；业务日志以服务端为准。

---

## 3) 依赖接口清单（Consumer-First，管理类接口草案）

> 说明：以下为 `ai-service-admin` 作为调用方所需的**最小管理接口能力清单**（草案）。
> - 路径以 `/admin/*` 为主。
> - 最终将以 `ai-service` 新增的 `openapi.admin.yaml` 固化。
> - 这里先列“能力/端点草案”，不写具体 schema，以便先对齐边界。

### 3.1 认证与通用能力
- `GET /admin/me`：获取当前登录信息（含租户、角色、权限点）
- `GET /admin/tenants`：租户列表（平台管理员）
- `GET /admin/enums`：获取前端需要的枚举/常量（场景枚举、状态枚举、错误码映射等）

### 3.2 知识库（KB）管理：`/admin/kb/*`
- `GET /admin/kb/spaces`：知识空间/知识库列表（按租户）
- `POST /admin/kb/spaces`：创建知识空间/知识库
- `GET /admin/kb/spaces/{kbId}`：知识库详情（含统计/配置摘要）
- `PATCH /admin/kb/spaces/{kbId}`：更新知识库元信息/配置
- `DELETE /admin/kb/spaces/{kbId}`：删除/下线知识库

- `GET /admin/kb/documents`：文档列表（支持 kbId、状态、时间、来源筛选）
- `POST /admin/kb/documents`：上传/导入文档（multipart 或任务式导入）
- `GET /admin/kb/documents/{docId}`：文档详情（含分片/索引状态）
- `DELETE /admin/kb/documents/{docId}`：删除文档

- `POST /admin/kb/index/jobs`：触发索引构建/重建（kbId/docId 维度）
- `GET /admin/kb/index/jobs`：索引任务列表（状态/时间筛选）
- `GET /admin/kb/index/jobs/{jobId}`：索引任务详情（进度、失败原因、日志摘要）
- `POST /admin/kb/index/jobs/{jobId}/retry`：失败任务重试
- `POST /admin/kb/index/jobs/{jobId}/cancel`：取消任务（若支持）

- `GET /admin/kb/search/config`：读取检索参数默认配置（租户级/KB 级）
- `PUT /admin/kb/search/config`：更新检索参数默认配置

### 3.3 Prompt 模板（租户级）配置：`/admin/config/*`
- `GET /admin/config/prompt-templates`：模板列表（支持场景筛选）
- `POST /admin/config/prompt-templates`：创建模板（草案）
- `GET /admin/config/prompt-templates/{tplId}`：模板详情（含版本历史）
- `PATCH /admin/config/prompt-templates/{tplId}`：更新模板（草案编辑）
- `POST /admin/config/prompt-templates/{tplId}/publish`：发布某版本
- `POST /admin/config/prompt-templates/{tplId}/rollback`：回滚到指定版本
- `DELETE /admin/config/prompt-templates/{tplId}`：删除模板

- `GET /admin/config/prompt-variables`：可用变量/内置函数清单（用于编辑器提示）

### 3.4 RAG 检索效果实验室（调试）：`/admin/rag/*`
- `POST /admin/rag/experiments/run`：运行一次 RAG 调试实验（输入 query + 参数集 + 可选 kbId/promptVersion）
- `GET /admin/rag/experiments`：实验记录列表（按租户/操作者/时间）
- `GET /admin/rag/experiments/{expId}`：实验详情（召回、重排、上下文、日志、耗时）
- `POST /admin/rag/experiments/{expId}/clone`：复制实验为新草案
- `DELETE /admin/rag/experiments/{expId}`：删除实验记录

- `GET /admin/rag/diagnostics/samples`：获取预置样例（用于快速回归）

### 3.5 全局会话监控：`/admin/sessions/*`
- `GET /admin/sessions`：会话列表（多维筛选）
- `GET /admin/sessions/{sessionId}`：会话详情（消息流、检索命中、工具调用、错误、耗时）

- `GET /admin/sessions/stats/overview`：概览统计（时间范围 + 租户维度）
- `GET /admin/sessions/stats/top`：Top 指标（Top KB / Top Prompt / Top 错误码等）

### 3.6 审计与运维（可选但常见）
- `GET /admin/audit/logs`：管理操作审计日志
- `GET /admin/system/health`：服务健康/版本信息（用于后台页脚或诊断）

### 3.7 统一错误模型（约定）
- 所有 `/admin/*` 接口建议返回统一错误结构（如 `code`, `message`, `requestId`, `details[]`），以支持后台调试与问题定位。

---

## 4) 产出物计划（Artifacts Plan）

> 按方法论，本模块后续应产出 4 类核心工件；本次 Scoping 仅做计划，不生成内容（等待确认）。

1. `spec/ai-service-admin/requirements.md`
   - 管理后台的用户故事与验收标准（EARS）
   - Scope/Dependencies/Traceability

2. `spec/ai-service/openapi.admin.yaml`（在 `ai-service` 下新增）
   - 作为 `ai-service` 的 **admin provider** 契约（面向本后台）
   - 标记 `info.x-contract-level`，并对关键 operationId 提供 L1/L2 所需字段

3. `spec/ai-service-admin/design.md`
   - 前端信息架构（IA）：菜单/页面/路由/权限点
   - 状态管理、缓存策略、分页/筛选模式
   - 调试实验室的交互与可观测性设计
   - 错误处理与追踪（requestId）

4. `spec/ai-service-admin/tasks.md`
   - 按页面/能力拆分的原子任务（含与 AC 的映射）
   - 并行策略：基于 admin OpenAPI 生成 Mock/SDK