# Knowledge Base 搜索高亮验证报告（2026-02-25）

## 1. 变更目标
- 在知识库搜索结果中展示与关键词相关的内容片段。
- 在搜索结果标题与内容中高亮命中关键词。

## 2. 测试类型与范围
- 类型：手动 + 静态检查（frontend）
- 范围：
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx`

## 3. 执行记录
- 命令：
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx'
```
- 结果：通过（0 error，3 warning）
- 说明：3 个 warning 为 `page.tsx` 既有未使用导入（`Star`、`Grid3X3`、`List`），非本次改动引入。

## 4. 最小复现步骤
1. 打开知识库页面 `/knowledge-base`。
2. 在顶部搜索框输入关键词（例如：`测试`），按 Enter。
3. 观察“搜索结果”卡片：
   - 标题中命中词为黄色高亮。
   - “内容”一行显示围绕命中词的片段（前后有上下文，必要时省略号）。
4. 切换到语义搜索组件（若页面入口启用），重复步骤 2-3，预期一致。

## 5. 结论
- 目标达成：搜索结果内容展示已聚焦关键词上下文，且命中词高亮可见。

## 6. MCP 复测补充（2026-02-25）
- 使用 Playwright MCP 登录后访问 `http://localhost:3000/knowledge-base`。
- 输入关键词 `测试` 执行搜索。
- 结果验证：
  - 标题与内容命中词高亮可见。
  - `选题.xlsx` 条目内容行出现命中高亮（命中字符“测”），不再是“完全无高亮”。
- 说明：高亮策略包含中文单字兜底与无命中弱高亮片段，避免语义检索结果出现全空高亮。

## 7. 创建文章入口移除验证（2026-02-25）
- 需求：在知识库中去掉“创建文章”按钮入口。
- 变更文件：
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_components/KBAnalyticsPanel.tsx`

### 7.1 验证命令
```bash
cd frontend
npm run lint
npm run build
```

### 7.2 验证结果
- `npm run lint`：失败。
  - 失败为仓库现存全局 ESLint 问题（大量历史 `no-explicit-any` 等），非本次改动引入。
- `npm run build`：通过。
  - Next.js 生产构建成功，`/knowledge-base`、`/knowledge-base/editor` 等路由正常生成。

### 7.3 手工最小冒烟步骤
1. 打开 `/knowledge-base`。
2. 检查页面右上角操作区：不再显示“创建”按钮。
3. 检查“最近访问”区域右侧：不再显示“创建文章”虚线按钮。
4. 检查“统计面板”底部：不再显示“创建文章”按钮。

### 7.4 结论
- 本次目标达成：知识库页面内所有“创建文章”可见入口已移除。
- 未改动编辑页面路由与创建接口能力，仅移除入口按钮。

## 8. 搜索结果“左侧跳转 + 右侧预览”验证（2026-02-25）
- 需求：搜索结果左侧信息区点击跳转原文；右侧按钮改为“预览”，在当前页打开预览内容并支持关键词高亮。
- 变更文件：
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx`
  - `frontend/src/locales/knowledgeBase/zh.ts`
  - `frontend/src/locales/knowledgeBase/en.ts`
  - `docs/modules/knowledge-base/01-prd.md`
  - `docs/modules/knowledge-base/02-user-journey.md`
  - `docs/modules/knowledge-base/05-ui-interaction-spec.md`
  - `docs/modules/knowledge-base/09-test-scenarios.md`
  - `docs/modules/knowledge-base/99-changelog.md`

### 8.1 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx' 'src/locales/knowledgeBase/zh.ts' 'src/locales/knowledgeBase/en.ts'
npm run build
```

### 8.2 验证结果
- ESLint 通过（0 error, 0 warning）。
- `npm run build` 通过（知识库相关路由构建成功）。
- 构建期间出现 `baseline-browser-mapping` 数据过期提示，仅为依赖提醒，不影响本次功能正确性。

### 8.3 手工最小冒烟步骤
1. 访问 `/knowledge-base`，输入关键词并执行搜索。
2. 点击任一结果左侧标题/内容区域，预期直接打开原文（文章详情页或 SharePoint）。
3. 返回搜索页，点击同一结果右侧“预览”按钮，预期打开右侧预览面板且不触发页面跳转。
4. 观察预览面板正文/摘要，预期命中关键词有高亮（若有命中）。
5. 在 `/knowledge-base/ask` 页面重复步骤 2-4，预期一致。

### 8.4 结论
- 目标达成：搜索结果主次动作已分离，预览能力与高亮规则已在知识库首页和语义搜索组件中统一。

## 9. 预览增强验证（多文件类型 + 尽量全量展示 + 手型光标）（2026-02-25）
- 需求：预览兼容不同文件类型并尽量展示所有内容；左侧可点击区域悬停显示手型光标。
- 变更文件：
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx`
  - `frontend/src/locales/knowledgeBase/zh.ts`
  - `frontend/src/locales/knowledgeBase/en.ts`
  - `docs/modules/knowledge-base/01-prd.md`
  - `docs/modules/knowledge-base/02-user-journey.md`
  - `docs/modules/knowledge-base/05-ui-interaction-spec.md`
  - `docs/modules/knowledge-base/09-test-scenarios.md`
  - `docs/modules/knowledge-base/99-changelog.md`

### 9.1 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx' 'src/locales/knowledgeBase/zh.ts' 'src/locales/knowledgeBase/en.ts'
npm run build
```

### 9.2 验证结果
- ESLint 通过（0 error, 0 warning）。
- `npm run build` 通过（知识库相关路由构建成功）。
- 构建期间存在 `baseline-browser-mapping` 依赖数据过期提示，不影响本次功能。

### 9.3 手工最小冒烟步骤
1. 在 `/knowledge-base` 搜索任意关键词。
2. 鼠标悬停到结果左侧信息区，确认显示手型光标。
3. 点击右侧“预览”：
   - 文章类型：确认预览正文为可用全文（非固定截断片段）。
   - 文档类型：确认优先尝试内嵌预览；若内嵌失败，展示回退提示与文本预览。
4. 点击预览面板底部“查看”，确认可打开原文。
5. 在 `/knowledge-base/ask` 语义搜索结果中复测步骤 2-4，确认一致。

### 9.4 结论
- 目标达成：预览已具备分类型兼容策略，正文展示改为可用全量优先；左侧可点击区域具备明确手型光标反馈。

## 10. MCP 在线验证（Playwright，2026-02-25）

### 10.1 执行环境
- 入口：`http://localhost:3000`
- 账号：`itadmin / Admin@2024`
- 模块页面：`/knowledge-base`、`/knowledge-base/ask`

### 10.2 关键断言与结果
1. 首页搜索结果左侧信息区 hover 可见手型光标  
   - 结果：通过（MCP 快照中左侧结果按钮为 `[cursor=pointer]`）。
2. 首页左侧信息区点击跳转原文  
   - 结果：通过（点击后进入 `/knowledge-base/articles/{id}`）。
3. 首页右侧 `Preview` 打开预览且不跳转  
   - 结果：通过（URL 维持 `/knowledge-base`，弹出 `Result preview`）。
4. 首页文档预览兼容（内嵌 + 文本）  
   - 结果：通过（预览弹窗内出现 `iframe`，同时显示文本预览与高亮）。
5. `/knowledge-base/ask` 智能搜索行为一致  
   - 结果：通过（左侧结果区为可点击手型；点击左侧跳转原文；点击 `Preview` 在 `/knowledge-base/ask` 打开弹窗且出现 `iframe`+文本）。

### 10.3 过程说明
- 首次 MCP 启动受 Chrome 单例锁影响，清理 `~/.cache/ms-playwright/mcp-chrome/Singleton*` 后恢复正常。
- 未发现本次需求相关阻断。

## 11. 预览面板可用性修复验证（2026-02-25）
- 反馈问题：
  - 预览面板标题“结果预览”语义不佳；
  - 面板出现两个预览块；
  - 第一个预览块无内容（第三方页面 file not found）；
  - 第二个块仅部分内容，体验混乱。

### 11.1 修复策略
1. 预览统一为单块正文展示，移除 iframe 预览块，避免双块冲突。
2. 面板标题改为当前文档标题，副标题显示“已为你定位到可预览内容”。
3. 对文档类型增加说明：当前展示为检索可用摘要，完整内容通过“查看”打开原文。

### 11.2 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/locales/knowledgeBase/zh.ts' 'src/locales/knowledgeBase/en.ts'
npm run build
```

### 11.3 预期
- 面板内只存在一个内容预览块；
- 不再出现空白 iframe 预览块；
- 面板标题显示当前文档标题；
- 文档类结果显示“摘要说明”，并可通过“查看”打开原文。

## 13. 搜索结果/预览去除 HTML 标签痕迹验证（2026-02-25）
- 需求：搜索结果摘要与预览文本中去除 `<table> <caption> <tr> <td>` 等标签痕迹，仅展示可读文本。
- 变更文件：
  - `frontend/src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx`
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`

### 13.1 验证命令
```bash
cd frontend
npm run lint -- 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx'
```

### 13.2 验证结果
- ESLint 通过（0 error, 0 warning）。

### 13.3 手工最小冒烟步骤
1. 访问 `/knowledge-base`，搜索包含表格内容的文档（如含 Service/Description 字段的文档）。
2. 检查搜索结果摘要行，预期不出现 `<table> <caption> <tr> <td>` 等标签文本。
3. 点击“预览”，检查预览正文文本，预期同样不出现上述标签文本。
4. 在 `/knowledge-base/ask` 的语义搜索结果重复步骤 2-3，预期一致。

### 13.4 结论
- 目标达成：搜索结果与预览文本统一经过清洗，HTML 标签痕迹已移除。

## 14. MCP 复核（预览面板收敛，2026-02-25）

### 14.1 背景

## 15. 搜索结果文件类型图标验证（Word/PPT/PDF，2026-02-25）

### 15.1 变更范围
- `frontend/src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx`
- `frontend/src/app/(modules)/knowledge-base/page.tsx`
- `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`
- `docs/modules/knowledge-base/05-ui-interaction-spec.md`
- `docs/modules/knowledge-base/09-test-scenarios.md`
- `docs/modules/knowledge-base/99-changelog.md`

### 15.2 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx'
npm run build
```

### 15.3 验证结果
- ESLint 通过（0 error, 0 warning）。
- `npm run build` 通过（知识库相关路由构建成功）。
- 构建期间出现 `baseline-browser-mapping` 数据过期提示，为依赖提醒，不影响本次功能正确性。

### 15.4 最小冒烟步骤
1. 进入 `/knowledge-base`，搜索包含 `*.docx`、`*.pptx`、`*.pdf` 的关键词。
2. 检查结果左侧图标：Word / PPT / PDF 显示不同图标。
3. 对无法识别扩展名的结果，确认显示通用文档图标。
4. 进入 `/knowledge-base/ask`，执行搜索并复核同样图标规则。

### 15.5 结论
- 目标达成：知识库搜索结果已按文件类型显示差异化图标，并在两个搜索入口保持一致。

## 16. 搜索结果文件类型图标方案升级验证（MIME 优先 + 多分类，2026-02-25）

### 16.1 变更范围
- `frontend/src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx`
- `frontend/src/app/(modules)/knowledge-base/_lib/api.ts`
- `docs/modules/knowledge-base/05-ui-interaction-spec.md`
- `docs/modules/knowledge-base/09-test-scenarios.md`
- `docs/modules/knowledge-base/99-changelog.md`

### 16.2 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx' 'src/app/(modules)/knowledge-base/_lib/api.ts' 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
npm run build
```

### 16.3 验证结果
- ESLint 通过（0 error, 0 warning）。
- `npm run build` 通过（知识库相关路由构建成功）。
- 构建中 `baseline-browser-mapping` 过期提示为依赖提醒，不影响本次功能。

### 16.4 最小冒烟步骤
1. 进入 `/knowledge-base`，分别搜索包含以下类型的文档：Word、Excel、PPT、PDF、图片、视频、音频、压缩包、代码文本。
2. 检查结果左侧图标：
   - Office（Word/Excel/PPT/PDF）均显示对应分类图标；
   - 媒体（图片/视频/音频）显示对应分类图标；
   - 压缩包、代码文本显示对应分类图标；
   - 未知类型回退通用文档图标。
3. 进入 `/knowledge-base/ask` 执行同类搜索，确认图标规则一致。

### 16.5 结论
- 目标达成：图标识别策略已升级为“`mimeType` 优先 + 扩展名兜底 + 未知回退”，并支持多类型兼容。
- 用户反馈预览面板存在“标题不合适 + 双预览块 + 首块空白 + 内容不完整”的体验问题。

### 14.2 本轮确认点
1. 右侧预览弹窗标题显示当前文档标题（不再显示“结果预览”）。
2. 预览内容区仅保留 1 个正文预览块（移除 iframe 双块并行）。
3. 文档类型仅保留 1 条底部说明文案（避免重复说明造成“两个块”错觉）。
4. 左侧结果信息区 hover 为手型（`cursor: pointer`）。
5. 左侧结果信息区点击直接打开原文链接；右侧 `Preview` 只打开预览弹窗。

## 16. 搜索输入联想建议验证（2026-02-25）

### 16.1 变更范围
- 后端：
  - `backend/src/modules/knowledge-base/services/search-suggestion.service.ts`
  - `backend/src/modules/knowledge-base/knowledge-base.controller.ts`
  - `backend/src/modules/knowledge-base/knowledge-base.module.ts`
- 前端：
  - `frontend/src/app/(modules)/knowledge-base/page.tsx`
  - `frontend/src/app/(modules)/knowledge-base/_lib/api.ts`
  - `frontend/src/locales/knowledgeBase/zh.ts`
  - `frontend/src/locales/knowledgeBase/en.ts`
- 文档：
  - `docs/modules/knowledge-base/01-prd.md`
  - `docs/modules/knowledge-base/05-ui-interaction-spec.md`
  - `docs/modules/knowledge-base/07-api.md`
  - `docs/modules/knowledge-base/09-test-scenarios.md`

### 16.2 测试类型与策略
- 单元测试：新增后端建议聚合服务测试文件（去重/排序规则）。
- 静态检查：对本次改动文件执行 ESLint/Prettier。
- 手工验证：覆盖输入联想、键盘交互、选择后触发正式搜索。

### 16.3 执行命令
```bash
# backend（新增文件）
cd backend
npx prettier --write src/modules/knowledge-base/services/search-suggestion.service.ts test/modules/knowledge-base/unit/search-suggestion.service.spec.ts
npx eslint src/modules/knowledge-base/services/search-suggestion.service.ts src/modules/knowledge-base/knowledge-base.module.ts test/modules/knowledge-base/unit/search-suggestion.service.spec.ts

# frontend（本次改动文件）
cd ../frontend
npx eslint src/app/'(modules)'/knowledge-base/page.tsx src/app/'(modules)'/knowledge-base/_lib/api.ts src/locales/knowledgeBase/zh.ts src/locales/knowledgeBase/en.ts
```

### 16.4 执行结果
- `backend` 新增文件 ESLint 通过（0 error）。
- `frontend` 改动文件 ESLint 通过（0 error）。
- 新增单元测试文件已创建：
  - `backend/test/modules/knowledge-base/unit/search-suggestion.service.spec.ts`
- 阻断说明（仓库现状）：
  - 直接运行 `npx jest ...spec.ts` 失败，原因是当前后端仓库未配置可直接执行 TypeScript 单测的 Jest transform（会按 Babel 解析 TS）。
  - 该阻断不由本次改动引入，已在本报告记录。

### 16.5 最小冒烟步骤
1. 访问 `/knowledge-base`。
2. 在顶部搜索框输入 2 个以上字符（如 `请假`）。
3. 观察联想建议面板：
   - 按分组显示（最近搜索 / 热门搜索 / 文档与文章）。
   - 可用键盘 `↑/↓` 切换、`Enter` 选中、`Esc` 关闭。
4. 点击任一建议项，或按 `Enter` 选中：
   - 输入框回填建议词。
   - 自动触发正式搜索并展示结果。

### 16.6 结论
- 本次“搜索输入联想建议”能力已按方案落地：
  - 建议请求与 RAGFlow 正式搜索分层；
  - 前端具备防抖、分组展示、键盘交互与基本无障碍语义；
  - 不改数据库结构，风险可控、可持续扩展。

### 16.7 顺序调整补充（2026-02-25）
- 用户追加要求：建议列表优先显示“文档与文章”，再显示“最近搜索”“热门搜索”。
- 已调整：
  - 后端聚合顺序：`TITLE -> RECENT_SEARCH -> TOP_QUERY`
  - 前端分组展示顺序：`文档与文章 -> 最近搜索 -> 热门搜索`

### 16.8 最近搜索删除管理补充（2026-02-25）
- 用户追加要求：最近搜索支持删除管理。
- 已新增能力：
  - 后端 `DELETE /knowledge-base/search-history`
    - 传 `query`：删除当前用户单条最近搜索
    - 不传 `query`：清空当前用户全部最近搜索
  - 前端“最近搜索”分组：
    - 分组级“清空”按钮
    - 单条建议右侧“删除”按钮
- 验证命令：
```bash
cd backend
npx eslint src/modules/knowledge-base/services/search-suggestion.service.ts test/modules/knowledge-base/unit/search-suggestion.service.spec.ts
npm run build

cd ../frontend
npx eslint src/app/'(modules)'/knowledge-base/page.tsx src/app/'(modules)'/knowledge-base/_lib/api.ts src/locales/knowledgeBase/zh.ts src/locales/knowledgeBase/en.ts
```
- 结果：上述命令全部通过。

### 16.9 MCP 实测结果（2026-02-25）
- 测试入口：`http://localhost:3000/knowledge-base`
- 关键断言：
  1. 输入 `abc` 后联想分组顺序为 `Documents & articles -> Recent searches`（当前数据下无热门搜索）。
  2. 单条删除：点击最近搜索项右侧删除按钮后，`abcy` 从建议列表消失，`abcx` 保留。
  3. 清空最近：点击“Recent searches”分组的 `Clear` 后，最近搜索分组消失，仅保留 `Documents & articles`。
  4. 后端复核：`GET /knowledge-base/search-suggestions?q=abc` 返回只剩 `TITLE` 来源项，确认未影响标题建议。
- 结论：最近搜索删除管理（单条/清空）行为符合预期，且不影响“文档与文章”分组。

### 16.10 过程修复（2026-02-25）
- 在 MCP 过程中发现并修复一个前端隐患：
  - 问题：点击“搜索”后，下一次输入会被跳过一次联想请求。
  - 修复：将“抑制联想请求”从“所有搜索触发”收敛到“仅选择建议项触发”，保证普通输入始终正常触发联想。

### 14.3 MCP 执行记录（Playwright）
- 访问：`http://localhost:3000/knowledge-base`
- 搜索关键词：`FX`
- 断言结果：
  - 通过：结果左侧按钮在快照中为 `[cursor=pointer]`。
  - 通过：点击左侧结果后新增外部标签页（SharePoint 登录页），说明为“直接打开原文”。
  - 通过：点击右侧 `Preview` 后在当前页弹出预览弹窗。
  - 通过：弹窗标题为具体文档名 `为什么FX要成为AIEV时代下的丰田.docx`。
  - 通过：弹窗正文仅 1 个文本预览块，且关键词高亮可见。
  - 通过：弹窗底部仅 1 条文案：`The current view shows searchable excerpt content...`（英文环境）。

### 14.4 结论
- 本轮问题已闭环：标题语义、双块冲突、交互分工（左侧打开原文/右侧预览）均符合预期。

## 15. 中断恢复后的继续验证（2026-02-25）

### 15.1 本轮补充修复
- 统一预览面板底部说明为单条 `previewDocumentExcerptHint`，移除“文档/非文档”分支文案差异，避免重复提示造成误解。

### 15.2 定向验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
```

### 15.3 验证结果
- ESLint 通过（0 error, 0 warning）。

### 15.4 MCP 状态
- 本轮尝试继续执行 MCP 复核时，语义搜索接口出现 `ERR_CONNECTION_REFUSED`（`/knowledge-base/semantic-search`），导致无法在当前会话复现“有结果”的全链路验证。
- 代码静态核查确认：
  - 预览 iframe 相关逻辑已移除；
  - 预览标题为文档标题；
  - 预览说明仅保留单条；
  - 左侧结果点击区保留 `cursor: pointer`。

## 16. 预览全文能力修复验证（2026-02-25）

### 16.1 问题复现
- 用户反馈：预览弹窗内容仍是“摘要片段”，未达到“尽量展示所有内容”。

### 16.2 根因
- 前端文档预览读取的是 `semantic-search` 返回的 `snippet`（摘要字段），即使 UI 不裁剪，数据本身仍为短摘要。

### 16.3 修复方案
1. 后端 `GET /knowledge-base/semantic-search` 新增可选字段 `previewContent`：对同一文档的多个命中分片做去重聚合。
2. 前端预览逻辑改为：文档类型优先渲染 `previewContent`，缺失时回退 `snippet`。
3. 保持既有 `snippet` 字段不变，避免破坏现有列表摘要契约。

### 16.4 验证命令
```bash
cd backend
npm run build

cd ../frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/api.ts'
npm run build
```

### 16.5 MCP 验证（Playwright）
- 页面：`/knowledge-base`
- 搜索词：`FX`
- 操作：点击首条结果右侧 `Preview`
- 断言结果：
  - 通过：预览内容块数量 = `1`（无双块）。
  - 通过：预览正文长度 `previewTextLength = 2936`（明显大于摘要长度）。
  - 通过：标题仍为当前文档标题。

### 16.6 结论
- 已修复：预览不再仅显示短摘要，而是优先展示聚合后的扩展正文内容；满足“尽量展示所有内容”的实现目标（受数据源可用分片上限约束）。

## 17. 预览长内容滚动修复验证（2026-02-25）

### 17.1 问题
- 预览抽屉打开长内容时，内容可见区无法向下滚动，导致尾部内容不可达。

### 17.2 修复
1. 抽屉容器强约束为视口高度：`h-[100dvh] max-h-[100dvh] overflow-hidden`。
2. 抽屉内部主容器补 `min-h-0 overflow-hidden`，避免 `flex` 子项被内容撑开。
3. 预览滚动区保留 `min-h-0 flex-1 overflow-y-auto`，确保滚动发生在内容区。

### 17.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
```

### 17.4 MCP 验证（Playwright）
- 在预览弹窗执行滚动容器检测：
  - `dialog.height = 960`，`inner.height = 960`（容器不再溢出视口）
  - `scroller.clientHeight = 808`，`scroller.scrollHeight = 1114`
  - `scrollTop: 0 -> 306`，`canScroll = true`，`reachedBottom = true`

### 17.5 结论
- 已修复：长内容可在预览面板内正常滚动并到达底部。

## 18. 预览来源与长度标识验证（2026-02-25）

### 18.1 目标
- 在预览面板增加“来源 + 长度”元信息，帮助用户判断当前内容是否为文章正文或检索分片聚合。

### 18.2 实现点
1. 新增 i18n 文案：`previewMetaSource`、`previewMetaLength`、`previewSourceType`（zh/en）。
2. 预览面板新增元信息展示：
   - 来源：`Article body / Aggregated retrieval chunks / Snippet fallback`
   - 长度：当前预览文本字符数

### 18.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/locales/knowledgeBase/zh.ts' 'src/locales/knowledgeBase/en.ts'
```

### 18.4 MCP 验证（Playwright）
- 搜索词：`测试`
- 打开结果“中美安全碰撞测试的区别与挑战.docx”预览
- 断言结果：
  - 通过：面板显示 `Source: Aggregated retrieval chunks`
  - 通过：面板显示 `Length: 1331`
  - 通过：原有相关度/正文/高亮仍正常

### 18.5 结论
- 已完成：预览面板具备可解释的“来源 + 长度”信息，满足新增可视化需求。

## 19. 高亮词状态一致性修复验证（2026-02-25）

### 19.1 问题
- 当用户在搜索输入框修改关键词但未点击“搜索”时，结果列表与预览中的高亮词会提前切换为新输入词，和当前结果集不一致。

### 19.2 修复
1. 首页搜索页新增 `appliedSearchQuery`（已执行搜索词）状态。
2. 语义搜索组件新增 `appliedQuery`（已执行搜索词）状态。
3. 高亮关键词统一从“已执行搜索词”派生，而非实时输入值。
4. 仅在真正执行搜索成功后更新已执行搜索词，未触发搜索时保持旧高亮不变。

### 19.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
```

### 19.4 MCP 验证（Playwright）
- 页面：`/knowledge-base`
- 步骤：
  1. 输入 `测试` 并点击 `Search`，得到结果列表与高亮；
  2. 不点击 `Search`，将输入框改为 `自动同步`；
  3. 点击任一结果 `Preview` 打开预览抽屉。
- 断言结果：
  - 通过：结果列表高亮仍为 `测试`（未提前切换）。
  - 通过：预览抽屉高亮仍为 `测试`（与当前结果集一致）。
  - 通过：左侧结果条目保持 `cursor=pointer`，交互反馈正常。

### 19.5 结论
- 已修复：高亮词与“已执行搜索结果”保持一致，避免输入态和结果态串扰。

## 20. 搜索结果误高亮修复验证（2026-02-25）

### 20.1 问题
- 搜索关键词为 `电动` 时，部分未命中该词的结果仍出现蓝色高亮（由“无命中兜底高亮前缀”导致），容易误导用户。

### 20.2 修复
1. 移除搜索结果摘要渲染中的 `fallbackLeadingChars` 兜底高亮参数。
2. 首页搜索结果与语义搜索组件统一改为“仅真实命中关键词时高亮”。

### 20.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
```

### 20.4 最小复测步骤
1. 在 `/knowledge-base` 输入 `电动` 并搜索。
2. 检查第三条等未包含 `电动` 的结果：不应出现蓝色高亮。
3. 检查包含 `电动` 的结果：仍应正常高亮。

### 20.5 结论
- 已修复：高亮只反映真实关键词命中，避免误高亮。

## 21. 命中片段展示修复验证（2026-02-25）

### 21.1 问题
- 某些搜索结果摘要使用了固定 `snippet`，导致摘要中不包含当前关键词命中片段。

### 21.2 修复
1. 新增 `buildRelevantSnippetFromSources()`：从多个文本源中优先选择包含关键词命中的文本，再截取上下文片段。
2. 首页与语义搜索结果摘要改为按优先级选择：`previewContent -> snippet -> title`。
3. 高亮继续仅基于真实命中词，不引入兜底误高亮。

### 21.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx'
```

### 21.4 结论
- 已修复：结果摘要将优先展示包含关键词的命中上下文，降低“摘要不含关键词”的情况。

## 22. 摘要回退为标题的回归修复（2026-02-25）

### 22.1 问题
- 搜索结果摘要候选源包含 `title`，导致部分条目摘要展示为“标题重复”，正文信息丢失。

### 22.2 修复
1. 首页结果摘要候选源改为仅正文相关：`previewContent -> snippet`。
2. 语义搜索组件结果摘要同样去掉 `title` 候选。

### 22.3 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx' 'src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx'
```

### 22.4 结论
- 已修复：摘要区域不再退化为标题重复，优先展示正文命中片段。

## 23. 搜索结果显示创建人验证（2026-02-25）

### 23.1 变更范围
- `frontend/src/app/(modules)/knowledge-base/page.tsx`
- `docs/modules/knowledge-base/05-ui-interaction-spec.md`
- `docs/modules/knowledge-base/09-test-scenarios.md`
- `docs/modules/knowledge-base/99-changelog.md`

### 23.2 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx'
```

### 23.3 最小复测步骤
1. 打开 `/knowledge-base`。
2. 输入任意关键词并执行搜索。
3. 在结果卡片元信息行检查是否展示“创建人 {姓名}”。

### 23.4 结论
- 目标达成：知识库首页搜索结果已展示文档创建人（所有者/谁创建）。

## 24. 预览面板显示创建人验证（2026-02-25）

### 24.1 变更范围
- `frontend/src/app/(modules)/knowledge-base/page.tsx`
- `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx`
- `docs/modules/knowledge-base/05-ui-interaction-spec.md`
- `docs/modules/knowledge-base/09-test-scenarios.md`
- `docs/modules/knowledge-base/99-changelog.md`

### 24.2 验证命令
```bash
cd frontend
npx eslint 'src/app/(modules)/knowledge-base/page.tsx' 'src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx'
```

### 24.3 最小复测步骤
1. 打开 `/knowledge-base`，执行任意搜索。
2. 点击任一结果的“预览”按钮。
3. 在预览面板元信息区域检查是否展示“创建人: {姓名}”（当 `createdBy` 有值时）。
4. 在语义搜索页入口（若启用）重复步骤 2-3，预期一致。

### 24.4 结论
- 目标达成：两个预览面板均已支持展示创建人（有值时显示）。