# 知识库模块 - 测试场景文档

> **版本**: v1.0  
> **最后更新**: 2026-02-25  
> **维护者**: 测试团队

> 🚧 Draft：本文件为最小占位，待与 UI/API 细化后补充。

---

## 📋 测试概述

### 测试范围

本文档定义知识库模块的核心测试场景（以 MVP 为主）。

### 测试类型

- ✅ 单元测试（Unit Test）
- ✅ 集成测试（Integration Test）
- ✅ E2E 测试（End-to-End Test）

**说明**：E2E 用例由 Agent + Playwright MCP 执行，详见 `10-e2e-test-spec.md`。

### 覆盖率目标

| 测试类型 | 目标覆盖率 | 当前覆盖率 |
|---------|-----------|-----------|
| 单元测试 | 70%+ | 0% |
| 集成测试 | 50%+ | 0% |
| E2E 测试 | 关键流程 | 0 个场景 |

---

## ✅ 功能测试场景

### 场景 1: 搜索并查看文档（MVP 核心）

**优先级**: P0

**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 索引存在可访问文档

**测试步骤**:
1. 访问知识库首页
2. 输入至少 2 个字符，观察联想建议面板
3. 使用键盘上下键切换建议项并按 Enter 选中
4. 检查首条结果标题与内容行的关键词高亮
5. 检查内容行为命中上下文片段（非固定摘要开头）
6. 点击首条结果左侧标题/内容区域
7. 返回搜索页后点击同一条结果右侧“预览”按钮
8. 观察左侧结果信息区 hover 状态光标
9. 分别验证站内文章与 SharePoint 文档的预览展示
10. 在结果中分别定位 Office、媒体、压缩、代码等文档，检查左侧图标差异

**预期结果**:
- [ ] 输入中可见联想建议面板（输入长度 >= 2）
- [ ] 建议分组顺序为：文档与文章 → 最近搜索 → 热门搜索
- [ ] 键盘可切换并选中建议项（↑/↓/Enter），Esc 可关闭面板
- [ ] 选中建议项后回填输入框并触发正式搜索
- [ ] 列表出现匹配文档
- [ ] 标题与内容命中词高亮显示
- [ ] 内容行展示关键词附近片段，长文本裁剪时包含省略号
- [ ] 结果元信息展示创建人（文档所有者/谁创建）
- [ ] 每条结果均显示相关度，且以小号标签出现在“预览”按钮左侧
- [ ] 点击左侧信息区后跳转原文（站内文章或 SharePoint）
- [ ] 点击右侧“预览”仅打开预览面板，不触发页面跳转
- [ ] 预览面板内容中命中词可见高亮（有命中时）
- [ ] 预览面板元信息展示创建人（有值时）
- [ ] 左侧信息区 hover 时显示手型光标
- [ ] Word/Excel/PPT/PDF 显示差异化图标；图片/视频/音频/压缩包/代码类文档显示对应分类图标；未知类型回退通用图标
- [ ] 站内文章预览尽量展示完整正文
- [ ] SharePoint 文档可兼容预览：优先内嵌，失败时可回退并仍可打开原文
- [ ] 记录搜索日志

---

### 场景 1.2: 最近搜索删除管理

**优先级**: P1

**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 用户存在至少 2 条最近搜索记录

**测试步骤**:
1. 输入关键词触发联想建议
2. 在“最近搜索”分组点击单条“删除”
3. 再次触发联想建议，检查该条记录
4. 点击“清空”最近搜索
5. 再次触发联想建议，检查最近搜索分组

**预期结果**:
- [ ] 单条删除后，该关键词不再出现在“最近搜索”分组
- [ ] 清空后，“最近搜索”分组为空
- [ ] 删除管理不影响“文档与文章”“热门搜索”分组
- [ ] 删除/清空操作不会触发正式搜索

---

### 场景 1.1: 输入联想降级不影响正式搜索

**优先级**: P0

**测试类型**: Integration

**前置条件**:
- [ ] 用户已登录

**测试步骤**:
1. 模拟联想接口异常或超时
2. 在搜索框输入关键词
3. 按 Enter 触发正式搜索

**预期结果**:
- [ ] 联想面板可静默失败或显示可恢复提示
- [ ] 正式搜索流程不受影响，仍返回结果或正常空状态

---

### 场景 2: 权限过滤（检索前过滤）

**优先级**: P0

**测试类型**: Integration

**前置条件**:
- [ ] 文档 A/B 权限不同
- [ ] 当前用户仅有 A 的访问权限

**测试步骤**:
1. 搜索与 A/B 相关关键词
2. 获取搜索结果

**预期结果**:
- [ ] 仅返回有权限的文档
- [ ] 无权限文档标题与片段不可见

---

### 场景 2.1: 文件夹搜索与分组展示

**优先级**: P1

**测试类型**: Integration

**前置条件**:
- [ ] SharePoint 文件夹元数据已完成同步（含 `sp_folder_index`）
- [ ] 存在可访问文件夹 `FOLDER_A` 与不可访问文件夹 `FOLDER_B`

**测试步骤**:
1. 使用 `FOLDER_A` 名称关键词触发搜索
2. 观察结果分组顺序与字段展示
3. 点击文件夹结果卡片

**预期结果**:
- [ ] 文件夹结果在“文件结果”分组下方展示
- [ ] 文件夹卡片仅展示：文件夹名、路径、更新时间
- [ ] 文件夹卡片整体可点击，点击后可直接打开 SharePoint 文件夹
- [ ] 文件夹结果不显示“预览”按钮
- [ ] 无权限文件夹 `FOLDER_B` 不出现在结果中

---

### 场景 3: AI 问答可追溯引用

**优先级**: P0

**测试类型**: E2E

**前置条件**:
- [ ] 问答功能可用
- [ ] 文档索引完整

**测试步骤**:
1. 提交问题
2. 查看回答与引用
3. 点击引用

**预期结果**:
- [ ] 引用包含标题/链接/片段/版本/时间
- [ ] 点击后跳转 SharePoint

---

### 场景 4: 上传文件到知识库（MVP）

**优先级**: P0

**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] SharePoint 默认文档库可写

**测试步骤**:
1. 进入知识库首页
2. 选择本地文件
3. 点击上传

**预期结果**:
- [ ] 显示上传成功提示
- [ ] 文件出现在 SharePoint 文档库

---

### 场景 5: 创建原生文章（单人编辑）

**优先级**: P0

**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录

**测试步骤**:
1. 进入知识库编辑页
2. 输入标题和正文
3. 点击保存

**预期结果**:
- [ ] 显示保存成功提示
- [ ] 返回文章 ID

---

### 场景 6: SharePoint 增量同步（新增/删除）

**优先级**: P0

**测试类型**: Integration

**前置条件**:
- [ ] SharePoint 白名单路径已配置
- [ ] 已至少执行一次全量同步（或增量游标已建立）

**测试步骤**:
1. 在白名单目录新增文件 A
2. 调用 `POST /knowledge-base/sync/delta`
3. 查询同步任务详情与已处理明细
4. 删除文件 A
5. 再次调用 `POST /knowledge-base/sync/delta`

**预期结果**:
- [ ] 新增文件进入已处理明细，RAGFlow 文档映射存在
- [ ] 删除文件进入已处理明细，索引与 RAGFlow 映射被清理

---

### 场景 6.1: 未变更文档远端失效自愈

**优先级**: P0

**测试类型**: Integration

**前置条件**:
- [ ] 本地 `ragflow_documents` 存在状态为 `COMPLETED` 的 SharePoint 文档映射
- [ ] 该映射对应的远端 RAGFlow 文档已失效（例如被删除或 owner 变化）
- [ ] 已到达远端健康检查时间窗口

**测试步骤**:
1. 触发 `POST /knowledge-base/sync/full`（或 `POST /knowledge-base/sync/delta`）
2. 查询同步任务详情与明细
3. 使用原关键词执行 `GET /knowledge-base/semantic-search`

**预期结果**:
- [ ] 同步任务不会因“本地未变更”直接静默跳过失效映射
- [ ] 该文档被自动重传并更新 `ragflowDocumentId`（可恢复场景）
- [ ] 搜索结果恢复可见，命中数不低于修复前基线
- [ ] 若为不可恢复错误，失败明细包含明确错误原因

---

### 场景 7: 首页快速开始入口（Getting Started / How to / FAQ）

**优先级**: P1

**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录

**测试步骤**:
1. 访问知识库首页
2. 定位“快速开始”模块
3. 检查 3 张卡片标题：Getting Started、How to、FAQ
4. 依次点击 3 张卡片

**预期结果**:
- [ ] 页面可见“快速开始”模块
- [ ] 三张卡片标题与顺序正确
- [ ] 点击后均在新标签页打开对应 SharePoint 链接

## ❌ 异常测试场景

### 场景 E1: 无搜索结果

**优先级**: P1

**测试类型**: E2E

**测试步骤**:
1. 输入不存在的关键词并搜索

**预期结果**:
- [ ] 显示空状态
- [ ] 不出现错误提示

---

### 场景 E2: 无权限访问

**优先级**: P0

**测试类型**: Integration

**测试步骤**:
1. 请求无权限文档详情

**预期结果**:
- [ ] 返回 HTTP 403
- [ ] 错误码为 `KNOWLEDGE_BASE_PERMISSION_001`