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

日期：2026-02-04
模块：knowledge-base
类型：E2E（MCP + 容器内验证）

## 一、环境信息
- 前端：http://localhost:3000
- 后端：http://localhost:3001/api/v1
- RAGFlow：容器 `ffoa-dev-ragflow`（HTTP 3098->9380）
- MinIO：容器 `ffoa-dev-ragflow-minio`（bucket: `ragflow`）
- 浏览器/设备：Chromium（Playwright MCP），桌面端
- 执行时间：2026-02-04 03:10-06:27（本地）
- 执行命令：MCP 手动执行（无命令）
- storageState：未单独生成，使用已有 admin 登录态（localStorage token）

## 二、测试范围
- MCP 搜索入口验证（/knowledge-base）
- MCP 问答入口验证（/knowledge-base/ask）
- MCP 同步任务跳过明细查看（/knowledge-base/sync-tasks/:taskId/skipped）
- MCP 同步任务已处理/失败明细查看（/knowledge-base/sync-tasks/:taskId/processed | /failed）
- RAGFlow 容器内文档解析状态核验（用于确认同步结果）
- MCP 触发全量同步（`POST /knowledge-base/sync/full`）
- MCP 草稿文章保存后自动索引验证（无需全量同步）

## 三、测试用例与结果

1) **MCP 搜索入口验证（空结果）**
- 操作：在 `http://localhost:3000/knowledge-base` 搜索 “zzzz-noresult-20260204”
- 结果：空状态出现（符合 E1 无结果场景）
- 断言：页面标题可见；结果区域出现“无结果”提示
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-01-search-empty-success.png`

2) **MCP 搜索入口验证（命中已发布）**
- 前置数据：已发布文章 `RAGFlow 发布测试文章`（ID: `f1fb295e-333c-47d2-a2c4-c8f13f77b1d9`）
- 操作：在 `http://localhost:3000/knowledge-base` 搜索 “发布测试”
- 结果：列表返回 Published 文章及相关结果
- 断言：结果列表出现且包含 `RAGFlow 发布测试文章` 标题
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-02-search-published-success.png`

3) **MCP 搜索入口验证（命中草稿）**
- 前置数据：草稿文章 `RAGFlow 本地 TEI 验证`、`RAGFlow 本地 TEI 端到端验证`
- 操作：在 `http://localhost:3000/knowledge-base` 搜索 “TEI”
- 结果：列表返回 Draft 文章结果
- 断言：结果列表出现且草稿条目展示 Draft 状态标签
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-03-search-draft-success.png`

4) **MCP 问答入口验证（含引用）**
- 前置数据：已发布文章 `RAGFlow 发布测试文章`（内容含关键词“RAGFlow、发布、问答、知识库”）
- 操作：在 `http://localhost:3000/knowledge-base/ask` 提问 “RAGFlow 发布测试文章里有哪些关键词？”
- 结果：返回答案与 Sources 列表
- 断言：问答输入框可见；答案区块出现；Sources 列表包含已发布文章
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-04-ask-published-success.png`

5) **MCP 问答入口验证（无可用答案）**
- 操作：在 `http://localhost:3000/knowledge-base/ask` 提问 “火星报销流程是什么？”
- 结果：返回 “No relevant content was found” 提示
- 断言：问答输入框可见；答案区块出现；无 Sources 列表
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-05-ask-no-answer.png`

6) **MCP 触发全量同步并核验任务状态**
- 操作：通过 API 触发 `POST /knowledge-base/sync/full`，并查询 `/knowledge-base/sync/tasks/:taskId`
- 结果：任务状态 `COMPLETED`，`totalItems=4`，`processedItems=3`，`failedItems=0`，`skippedItems=1`
- 说明：不支持类型（如 `env.dev.example`）已按白名单策略跳过，计入 `skippedItems`
- 断言：触发成功；任务状态可查询
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-06-sync-triggered-success.png`（UI 触发入口已验证）

7) **同步跳过明细入库验证**
- 操作：查询 `platform_knowledge.sync_task_skipped_items`（`task_id=f9e8d145-f4d1-4ff4-a2b3-1ad454362576`）
- 结果：记录 `env.dev.example`，`source_type=SP_DOCUMENT`，`mime_type=application/octet-stream`
- 断言：跳过项明细入库成功

8) **同步任务详情页验证**
- 操作：访问 `/knowledge-base/sync-tasks/8e79dc73-0ae5-4915-be7d-970cb4e0f970`
- 结果：展示任务状态与统计（Total/Processed/Failed/Skipped）
- 断言：页面标题可见；统计卡片显示数值
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-07-sync-task-detail-success.png`

9) **同步任务跳过明细页验证**
- 前置数据：存在 `skippedItems=1` 的同步任务 `f9e8d145-f4d1-4ff4-a2b3-1ad454362576`
- 操作：访问 `/knowledge-base/sync-tasks/f9e8d145-f4d1-4ff4-a2b3-1ad454362576/skipped`
- 结果：展示跳过明细列表（含 `env.dev.example` 与可读跳过原因）
- 断言：页面标题可见；跳过列表出现
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-13-sync-skipped-list-success.png`

10) **同步任务已处理明细页验证**
- 前置数据：同步任务 `f9e8d145-f4d1-4ff4-a2b3-1ad454362576`，`processedItems=3`
- 操作：访问 `/knowledge-base/sync-tasks/f9e8d145-f4d1-4ff4-a2b3-1ad454362576/processed`
- 结果：展示已处理明细列表
- 断言：页面标题可见；已处理列表出现
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-11-sync-processed-list-success.png`

11) **同步任务失败明细页验证**
- 前置数据：同步任务 `f9e8d145-f4d1-4ff4-a2b3-1ad454362576`，`failedItems=0`
- 操作：访问 `/knowledge-base/sync-tasks/f9e8d145-f4d1-4ff4-a2b3-1ad454362576/failed`
- 结果：展示空状态
- 断言：页面标题可见；空状态出现
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-12-sync-failed-empty.png`

12) **同步任务详情数值对齐验证**
- 前置数据：同步任务 `f9e8d145-f4d1-4ff4-a2b3-1ad454362576`
- 操作：访问 `/knowledge-base/sync-tasks/f9e8d145-f4d1-4ff4-a2b3-1ad454362576`
- 结果：Processed/Failed/Skipped 数值与按钮对齐
- 断言：数值列右对齐，按钮宽度一致
- 证据：`testing/reports/knowledge-base-2026-02-04-e2e/E2E-14-sync-task-detail-alignment.png`

13) **草稿文章保存后自动索引并可搜索**
- 前置数据：新建草稿文章 `自动同步草稿验证 20260204-1`（未手动全量同步）
- 操作：进入 `/knowledge-base/editor` 保存草稿 → 回到 `/knowledge-base` 搜索标题关键词
- 结果：搜索结果命中草稿文章，显示 Draft 状态
- 断言：保存提示出现；搜索结果列表出现且包含草稿状态标签
- 证据：
  - `testing/reports/knowledge-base-2026-02-04-e2e/E2E-15-article-save-success.png`
  - `testing/reports/knowledge-base-2026-02-04-e2e/E2E-16-auto-sync-search-draft.png`

## 四、流程说明
- 输入：关键字检索（“zzzz-noresult-20260204”“发布测试”“TEI”）、问答问题（“RAGFlow 发布测试文章里有哪些关键词？”、“火星报销流程是什么？”）
- 输出：搜索结果列表、问答答案与 Sources 引用列表、跳过明细列表
- 页面：`/knowledge-base`、`/knowledge-base/ask`、`/knowledge-base/sync-tasks/:taskId`、`/knowledge-base/sync-tasks/:taskId/skipped`、`/knowledge-base/sync-tasks/:taskId/processed`、`/knowledge-base/sync-tasks/:taskId/failed`
- API：`POST /knowledge-base/sync/full`、`GET /knowledge-base/sync/tasks/:taskId`、`GET /knowledge-base/sync/tasks/:taskId/skipped`、`GET /knowledge-base/sync/tasks/:taskId/processed`、`GET /knowledge-base/sync/tasks/:taskId/failed`、`POST /knowledge-base/ask`

## 五、阻断与偏离说明
- 未生成独立 storageState（使用已有 admin 登录态，localStorage token）。

## 六、覆盖度说明
- 覆盖页面：6/6（知识库首页、AI 问答页、同步任务详情、跳过明细、已处理明细、失败明细）
- 覆盖核心流程：搜索、问答（P0）、同步任务查看（含明细页）
- 未覆盖：上传文件、创建文章、权限过滤（待补）

## 七、契约一致性
- 页面输入/输出与 `07-api.md`/`05-ui-interaction-spec.md` 未发现冲突

## 八、复现命令（可复跑）

### RAGFlow 容器内上传与解析
```bash
# 1) 创建测试文件
sudo docker exec ffoa-dev-ragflow /bin/sh -c "printf 'RAGFlow test document.\n' > /tmp/ffoa-ragflow-test.md"

# 2) 上传到数据集
sudo docker exec ffoa-dev-ragflow /bin/sh -c "curl -s -H 'Authorization: Bearer <RAGFLOW_API_KEY>' -F 'file=@/tmp/ffoa-ragflow-test.md' 'http://localhost:9380/api/v1/datasets/<DATASET_ID>/documents'"

# 3) 触发解析
sudo docker exec ffoa-dev-ragflow curl -s -H "Authorization: Bearer <RAGFLOW_API_KEY>" -H "Content-Type: application/json" -d '{"document_ids":["<DOCUMENT_ID>"]}' "http://localhost:9380/api/v1/datasets/<DATASET_ID>/chunks"
```

### MCP 搜索与问答
- 搜索页：`http://localhost:3000/knowledge-base`
- 问答页：`http://localhost:3000/knowledge-base/ask`

## 九、结论
- 搜索空结果、已发布命中、草稿命中均验证通过。
- 问答入口可用：命中问题有答案与引用；无答案问题返回合理提示。
- 全量同步可触发，任务状态可查询；不支持类型已跳过且不计失败。