# 知识库模块测试报告（手工/构建校验）

- 模块: knowledge-base
- 日期: 2026-02-28
- 测试类型: manual
- 执行人: Codex

## 1. 测试范围与类型选择

- 本次变更包含:
  - 数据模型新增 `sp_folder_index`
  - SharePoint 同步链路新增文件夹索引
  - 搜索结果新增 `folder` 类型
  - 前端搜索结果新增“文件夹结果”分组展示（位于文件结果下方）
- 选择:
  - 构建校验（后端 + 前端）
  - 单元测试文件补充（`ragflow-search.service.spec.ts`）

## 2. 执行环境

- 工作目录: `/home/chentao/Code/ffworkspace`
- Node / npm: 使用仓库当前环境
- 环境变量: 使用项目本地 `.env`

## 3. 执行命令与结果

1. `cd backend && npm run prisma:generate`
- 结果: 通过
- 说明: Prisma Client 已根据新增模型生成。

2. `cd backend && npm run build`
- 结果: 通过
- 说明: 后端 TypeScript 编译通过。

3. `cd frontend && npm run build`
- 结果: 通过
- 说明: 前端编译、类型检查、静态页面生成通过。

4. `cd backend && npx jest test/modules/knowledge-base/unit/search-suggestion.service.spec.ts test/modules/knowledge-base/unit/ragflow-search.service.spec.ts --runInBand`
- 结果: 失败（阻断）
- 原因: 当前仓库未提供可直接用于 TS 单测的 Jest transform 配置，`npx jest` 按 Babel 解析 TS 导致语法错误（`Missing semicolon`）。
- 影响范围: 仅影响本地命令级单测执行方式，不影响后端/前端构建产物。

## 4. 最小冒烟复现步骤

1. 打开知识库首页 `/knowledge-base`
2. 输入已存在的 SharePoint 文件夹名称（例如 `Policies`）并搜索
3. 验证“文件结果”分组在上方
4. 验证“文件夹结果”分组在下方
5. 验证文件夹卡片展示字段仅有：文件夹名、路径、更新时间
6. 点击文件夹卡片，验证新标签页打开对应 SharePoint 文件夹

## 5. 结论

- 代码级实现已完成并通过后端/前端构建校验。
- 单测执行存在仓库级 Jest TS 配置阻断，已记录并可后续补齐测试命令配置后复跑。

## 6. 二次回归（搜索拆词与MCP复测）

### 6.1 变更目的

- 修复“`测试` 无法召回 `关于自动驾驶的趋势预测 以及号召.docx`，但 `测` 可以召回”的不一致问题。
- 保持“关键词拆分后可召回”的历史行为。

### 6.2 新增/调整点

- 后端 `ragflow-search.service.ts`：`extractSearchTokens` 增加中文短词（长度 <= 6）单字回退拆分。
- 前端 `searchHighlight.tsx`：`extractSearchKeywords` 增加同样的中文短词单字回退，避免前端二次过滤误删后端返回结果。

### 6.3 执行命令与结果

1. `cd backend && npm run build`
- 结果: 通过

2. `cd frontend && npm run build`
- 结果: 通过

3. MCP（Playwright）实测：
- 用例A：查询 `测试`
  - 结果: `Results (4)`，包含 `关于自动驾驶的趋势预测 以及号召.docx`
- 用例B：查询 `测`
  - 结果: `Results (2)`，包含 `关于自动驾驶的趋势预测 以及号召.docx`
- 用例C：查询 `FX`
  - 结果: `Results (2)`，可稳定返回 `为什么FX要成为AIEV时代下的丰田.docx` 等文件

### 6.4 结论

- 现已恢复“拆词召回”行为，`测试` 与 `测` 的结果表现不再冲突。
- 未修改 API 契约字段与路径，仅修复检索拆词与前端过滤一致性。

## 7. 三次回归（高亮与预览回退）

### 7.1 问题描述

- 查询 `FX` 时，标题为 `为什么F X要成为...` 的结果未高亮。
- 文档预览在缺少正文片段时，正文区回退显示标题文本，造成误导。

### 7.2 修复点

- `searchHighlight.tsx`：松散匹配最小长度阈值由 `3` 调整为 `2`，支持 `FX` 这类短词在 `F X` 场景高亮。
- `page.tsx`：文件结果标题高亮启用 `enableLooseMatching`。
- `page.tsx`：文档预览正文仅使用 `previewContent`，不再回退到 `snippet/title`。

### 7.3 验证结果（MCP）

- 查询 `FX`：
  - 第二条标题 HTML 出现 `<mark>F X</mark>`，高亮正确。
- 打开该条目预览：
  - 正文区为空时显示“无可预览内容”提示，不再显示标题文本。

## 8. 契约回归（移除文件元数据兜底）

### 8.1 背景

- 按模块 API 文档约定，`semantic-search` 应为：
  - RAGFlow 检索（文档/文章）
  - SharePoint 文件夹元数据检索（文件夹）
- 本地实现中曾额外引入 `sp_document_index` 文件元数据兜底，属于超出契约行为。

### 8.2 本次处理

- 移除 `ragflow-search.service.ts` 中 `searchDocumentsByMetadata` 合并逻辑。
- 保留：
  - 文档/文章：RAGFlow 召回
  - 文件夹：`sp_folder_index` 召回

### 8.3 验证

1. `cd backend && npm run build`：通过
2. `cd frontend && npm run build`：通过
3. 直接 API 验证：
   - `q=FX` 返回仅文档结果（来自 RAGFlow）
   - `q=UP2U` 返回文件夹结果（来自 `sp_folder_index`）

## 9. 同步自愈修复（未变更文档远端失效）

### 9.1 问题与目标

- 问题：本地映射为 `COMPLETED` 且 SharePoint 元数据未变更时，会直接跳过；若远端 RAGFlow 文档已失效（`not found` / `don't own the document`），不会被修复。
- 目标：保持“未变更跳过”效率，同时引入低频健康检查实现自动自愈，避免长期检索缺失。

### 9.2 实现摘要

- `ragflow-sync.service.ts`
  - 在 `syncSharePointDocument` 增加“按间隔远端健康检查”。
  - 对 `COMPLETED` 映射：
    - 未到检查窗口：继续跳过；
    - 到窗口：检查远端状态。
  - 远端失效且可恢复时，强制重传（绕过条件下载分支的直接跳过路径）。
  - 新增配置读取：`RAGFLOW_REMOTE_HEALTH_CHECK_INTERVAL_MINUTES`（默认 1440 分钟）。
- `ragflow.service.ts`
  - `isRecoverableDocumentFailure` 增加 ownership 失效识别（`don't own the document` 等）。

### 9.3 执行命令与结果

1. `cd backend && npm run build`
- 结果：通过

### 9.4 备注

- 本次未变更外部 API 路径/字段/错误码，仅增强同步内部容错与自愈能力。

## 10. MCP 回归验证（2026-02-28）

### 10.1 搜索结果验证

- MCP 查询 `FX`：返回 `Results (4)`，包含：
  - `为什么FX要成为AIEV时代下的丰田.docx`
  - `中美安全碰撞测试的区别与挑战.docx`
  - `YT IP- Cocreation 1017.docx`
  - `选题.xlsx`
- MCP 查询 `sales/communicationplanning`：返回 `Folders (2)`，文件夹卡片为整卡可点击（cursor=pointer），标题与路径命中均高亮。
- MCP 查询 `测试`：返回文件结果，包含 `中美安全碰撞测试的区别与挑战.docx` 与 `选题.xlsx` 命中片段；`关于自动驾驶的趋势预测 以及号召.docx`未单独成条目，但在 `选题.xlsx` 命中片段中可见被引用文本。

### 10.2 同步自愈逻辑验证

- 通过 MCP 触发全量同步，最新任务：`b45b1e9e-344e-410e-af37-f35f5c1f47d5`（Completed, total=10, processed=3, skipped=7, failed=0）。
- 为验证“远端健康检查”分支，先将 `为什么FX要成为AIEV时代下的丰田.docx` 对应映射的 `lastSyncedAt` 回拨为历史时间，再触发一次全量同步。
- MCP 在跳过明细中确认该文件出现原因：`未变更（远端健康），跳过下载与嵌入`，说明新逻辑已实际生效。

### 10.3 结论

- `FX` 搜索结果恢复，不再出现“仅 1 条”的问题。
- 文件夹搜索展示与交互（整卡点击、手型光标、高亮）正常。
- 未变更文档的远端健康检查分支已验证命中，符合“零技术债”下的可自愈设计目标。