# 知识库 - E2E 测试报告（RAGFlow）

- 日期：2026-02-06
- 环境：本地（http://localhost:3000 / http://localhost:3001）
- 浏览器/设备：Playwright MCP（Chromium，Desktop）
- 执行时间：2026-02-06 19:20-20:55（本地）
- 执行方式：人工 E2E（MCP）
- storageState：复用已有登录态（管理员账号已登录）
- 测试范围：增量同步入口、策略提示、触发增量同步、跳转同步记录

## 用例明细

### E2E-06 增量同步入口与触发

- 前置条件：
  - 管理员已登录
  - 前端与后端服务运行正常
- 页面/路径：
  - `/knowledge-base`
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #8.1 `POST /knowledge-base/sync/delta`
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 打开 `/knowledge-base`
  2) 确认“增量同步”按钮与策略提示文案可见
  3) 点击“增量同步”，确认弹窗
  4) 观察成功提示（toast）
  5) 点击“同步记录”进入列表页
- 断言点：
  - 到达断言：页面标题 “Knowledge Base” 可见
  - 成功/稳定断言：
    - “Delta sync” 按钮与策略提示可见
    - toast 显示“增量同步任务已启动”
    - 同步记录列表页表格可见
- 结果：✅ 通过
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-06-delta-sync-entry-visible.png`
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-06-delta-sync-toast-success.png`
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-06-sync-history-visible.png`

### E2E-07 触发方式显示（回退验证）

- 前置条件：
  - 管理员已登录
- 页面/路径：
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 触发增量同步（若游标缺失将自动回退为全量）
  2) 进入同步记录列表页
  3) 确认“触发方式”列显示为“增量回退全量 / Delta fallback”
- 断言点：
  - 到达断言：同步记录列表页表格可见
  - 成功/稳定断言：最新任务触发方式为“Delta fallback / 增量回退全量”
- 结果：✅ 通过（触发回退全量）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-07-sync-history-trigger-fallback.png`

### E2E-08 同步状态归一化显示

- 前置条件：
  - 管理员已登录
  - 同步记录中存在已完成的任务（Processed + Failed + Skipped == Total）
- 页面/路径：
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 进入同步记录列表页
  2) 找到 `24ef0462-52f0-4546-b48e-e781af651145` 任务
  3) 检查状态列显示为 `Completed`
- 断言点：
  - 到达断言：同步记录列表页表格可见
  - 成功/稳定断言：任务状态显示为 `Completed`（归一化生效）
- 结果：✅ 通过
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-08-sync-history-normalized-status.png`

### E2E-09 全量同步触发与记录

- 前置条件：
  - 管理员已登录
  - 前端与后端服务运行正常
- 页面/路径：
  - `/knowledge-base`
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #8 `POST /knowledge-base/sync/full`
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 打开 `/knowledge-base`
  2) 点击“Full sync”，确认弹窗
  3) 观察成功提示（toast）
  4) 进入同步记录列表页
- 断言点：
  - 到达断言：页面标题 “Knowledge Base” 可见
  - 成功/稳定断言：
    - toast 显示“Full sync task triggered”
    - 同步记录列表存在最新任务（Trigger: Manual full）
- 结果：✅ 通过（任务创建成功）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-09-full-sync-toast-success.png`
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-09-sync-history-full-sync-visible.png`

### E2E-10 增量同步复测（回退提示）

- 前置条件：
  - 管理员已登录
  - SharePoint 增量游标缺失或无效
- 页面/路径：
  - `/knowledge-base`
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #8.1 `POST /knowledge-base/sync/delta`
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 打开 `/knowledge-base`
  2) 点击“Delta sync”，确认弹窗
  3) 观察回退提示（toast）
  4) 进入同步记录列表页
- 断言点：
  - 到达断言：页面标题 “Knowledge Base” 可见
  - 成功/稳定断言：
    - toast 显示“增量同步不可用，已切换为全量同步”
    - 同步记录列表出现最新任务（Trigger: Delta fallback）
- 结果：✅ 通过（自动回退全量）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-10-delta-sync-fallback-toast.png`
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-10-sync-history-delta-fallback-visible.png`

### E2E-11 全量后增量成功（不回退）

- 前置条件：
  - 管理员已登录
  - 白名单目录已完成一次全量同步，游标已建立
- 页面/路径：
  - `/knowledge-base`
  - `/knowledge-base/sync-tasks`
- 使用 API（按 `07-api.md` 编号）：
  - #8 `POST /knowledge-base/sync/full`
  - #8.1 `POST /knowledge-base/sync/delta`
  - #9 `GET /knowledge-base/sync/tasks`
- 步骤：
  1) 触发一次全量同步（Manual full）
  2) 触发一次增量同步（Manual delta）
  3) 进入同步记录列表页，确认最新两条记录状态
- 断言点：
  - 到达断言：同步记录列表页表格可见
  - 成功/稳定断言：
    - 最新全量任务状态 `Completed`
    - 最新增量任务状态 `Completed` 且 Trigger 为 `Manual delta`
- 结果：✅ 通过（增量不再回退）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-11-sync-history-full-delta-success.png`

### E2E-12 智能检索错误提示（检索服务不可用）

- 前置条件：
  - 管理员已登录
  - Ragflow 检索服务返回 `KNOWLEDGE_BASE_SEARCH_PROVIDER_ERROR`（embedding 授权/余额异常）
- 页面/路径：
  - `/knowledge-base/ask`
- 使用 API（按 `07-api.md` 编号）：
  - #6 `GET /knowledge-base/semantic-search`
- 步骤：
  1) 打开 `/knowledge-base/ask`
  2) 在 Smart Search 输入框输入“测试”
  3) 点击“Search”
- 断言点：
  - 到达断言：页面标题 “AI Q&A” 与 “Smart Search” 可见
  - 成功/稳定断言：
    - 错误态提示卡片显示 “Search provider unavailable”
    - toast 显示 “Search provider unavailable”
- 结果：✅ 通过（错误提示与页面状态一致）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-12-search-provider-error.png`

### E2E-13 首页搜索错误提示（创建按钮左侧搜索框）

- 前置条件：
  - 管理员已登录
  - Ragflow 检索服务返回 `KNOWLEDGE_BASE_SEARCH_PROVIDER_ERROR`（embedding 授权/余额异常）
- 页面/路径：
  - `/knowledge-base`
- 使用 API（按 `07-api.md` 编号）：
  - #6 `GET /knowledge-base/semantic-search`
- 步骤：
  1) 打开 `/knowledge-base`
  2) 在“Create”按钮左侧搜索框输入“测试”
  3) 按 Enter 触发搜索
- 断言点：
  - 到达断言：页面标题 “Knowledge Base” 可见
  - 成功/稳定断言：
    - 错误态提示可见（与 E2E-12 一致）
    - toast 提示可见
- 结果：✅ 通过（错误态与 toast 可见）
- 截图：
  - `testing/reports/knowledge-base-2026-02-06-e2e/E2E-13-home-search-provider-error.png`

## 失败/阻断

- 无

## 覆盖度说明

- 覆盖页面：3（知识库首页、同步记录列表、AI 问答）
- 覆盖流程：增量同步触发与记录入口、智能检索错误提示
- 未覆盖：终止任务、失败明细查看（本次未回归）、问答引用跳转

## 契约一致性

- `POST /knowledge-base/sync/delta` 与文档一致（异步触发任务，返回 taskId + message）
- UI 策略提示与 `05-ui-interaction-spec.md` 对齐（增量优先、必要时回退全量）