876 lines
27 KiB
Markdown
876 lines
27 KiB
Markdown
# AI对话链接跳转与引用高亮优化 - 技术设计文档
|
||
|
||
**文档版本**: v1.0
|
||
**创建日期**: 2026-05-30
|
||
**状态**: ✅ 已批准，待实施
|
||
**方案选择**: 方案B - 统一搜索引擎重构
|
||
|
||
---
|
||
|
||
## 1. 项目背景与问题定义
|
||
|
||
### 1.1 当前问题
|
||
|
||
在AI智能问答模块（QAModule.vue）中，用户点击对话消息中的引用来源或[ref:xxx]标签后：
|
||
|
||
1. **PDF文件**：只能跳转到指定页码，**无法高亮显示关键词位置**
|
||
2. **Word/Excel等文件**：使用`indexOf精确匹配`，关键词截断后容易匹配失败
|
||
3. **时序问题**：文件DOM未完全渲染就执行搜索，导致定位失败
|
||
4. **用户体验差**：无搜索结果反馈、无导航控件、高亮效果短暂
|
||
|
||
### 1.2 业务影响
|
||
|
||
- ❌ 用户无法快速定位到引用的具体内容位置
|
||
- ❌ 需要手动翻页查找，效率低下
|
||
- ❌ 多个匹配项时无法逐个浏览
|
||
- ❌ 降低知识管理系统的易用性和专业性
|
||
|
||
### 1.3 目标用户
|
||
|
||
- 企业员工（制度文件查阅者）
|
||
- HR/行政人员（制度发布者）
|
||
- 管理员（系统维护者）
|
||
|
||
### 1.4 成功标准
|
||
|
||
✅ 点击任意格式的引用 → 自动跳转 + 持续高亮显示
|
||
✅ 支持模糊匹配（容错率≥90%）
|
||
✅ 提供上/下一处导航功能
|
||
✅ 高亮效果美观且持久（手动关闭前不消失）
|
||
✅ 响应时间 < 2秒
|
||
|
||
---
|
||
|
||
## 2. 解决方案架构
|
||
|
||
### 2.1 整体架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ QAModule.vue │
|
||
│ [引用点击] → navigateToFileReader(ref) │
|
||
│ ↓ │
|
||
│ 提取: { fileId, filename, page, context, rawData } │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
↓ router.push(query参数)
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ReaderPage.vue │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────┐ │
|
||
│ │ UniversalSearchEngine (新增) │ │
|
||
│ │ │ │
|
||
│ │ ┌─────────┐ ┌─────────┐ ┌────────────┐ │ │
|
||
│ │ │ Text │ │ Fuzzy │ │ Highlight │ │ │
|
||
│ │ │Extractor│ │ Search │ │ Renderer │ │ │
|
||
│ │ │ (提取) │ │ Engine │ │ (渲染) │ │ │
|
||
│ │ └────┬────┘ └────┬────┘ └─────┬──────┘ │ │
|
||
│ │ └──────────┼──────────┘ │ │
|
||
│ │ ↓ │ │
|
||
│ │ ┌──────────────────┐ │ │
|
||
│ │ │ SearchCoordinator │ │ │
|
||
│ │ │ (流程协调器) │ │ │
|
||
│ │ └────────┬─────────┘ │ │
|
||
│ └───────────────┼───────────────────────┘ │
|
||
│ ↓ │
|
||
│ SearchResult[] + UI Navigation Bar │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 核心技术选型
|
||
|
||
| 组件 | 技术方案 | 版本 | 选型理由 |
|
||
|------|---------|------|---------|
|
||
| **模糊搜索引擎** | Fuse.js | 7.0.0 | 轻量(10KB)、支持中文、零依赖 |
|
||
| **文本提取** | DOM TreeWalker API | 原生 | 无需依赖、浏览器原生支持 |
|
||
| **高亮渲染** | Range + Custom Elements | 原生 | 精确控制、性能优秀 |
|
||
| **PDF处理** | PDF.js textLayer | 已集成 | 复用现有pdfjs-viewer |
|
||
|
||
---
|
||
|
||
## 3. 模块详细设计
|
||
|
||
### 3.1 模块一：TextExtractor（文本提取器）
|
||
|
||
**职责**：从不同格式文件的DOM中提取结构化文本数据
|
||
|
||
**文件路径**：`src/utils/textExtractor.js`
|
||
|
||
**核心方法**：
|
||
```typescript
|
||
class TextExtractor {
|
||
// 主入口：根据fileType分发到不同的提取策略
|
||
async extract(fileType: string, container: HTMLElement): Promise<Document[]>
|
||
|
||
// PDF文本提取（从iframe的.textLayer提取）
|
||
async extractPdfText(iframe: HTMLIFrameElement): Promise<PdfPage[]>
|
||
|
||
// DOCX/DOC文本提取（从.docx-wrapper提取分页）
|
||
extractDocxText(container: HTMLElement): DocxPage[]
|
||
|
||
// Excel/CSV文本提取（从表格单元格提取）
|
||
extractExcelText(container: HTMLElement): TableCell[]
|
||
|
||
// 通用DOM文本提取（TreeWalker遍历）
|
||
extractDomText(container: HTMLElement): TextNode[]
|
||
}
|
||
```
|
||
|
||
**数据结构**：
|
||
```typescript
|
||
interface Document {
|
||
text: string // 纯文本内容
|
||
type: 'text' | 'page' | 'cell'
|
||
location?: {
|
||
page?: number // 页码（PDF/DOCX）
|
||
cellIndex?: [number, number] // 单元格坐标 [row, col]
|
||
}
|
||
element: HTMLElement // 对应的DOM元素引用
|
||
}
|
||
```
|
||
|
||
**关键实现细节**：
|
||
- PDF：遍历`.textLayer > span`元素，按`data-page`属性分组
|
||
- DOCX：查找`.docx-wrapper > div`作为页面容器
|
||
- Excel：遍历`table tr td`，记录行列索引
|
||
- 通用：使用`TreeWalker(SHOW_TEXT)`过滤有意义的文本节点（长度≥2）
|
||
|
||
---
|
||
|
||
### 3.2 模块二：FuzzySearchEngine（模糊搜索引擎）
|
||
|
||
**职责**：基于Fuse.js实现智能模糊匹配和相关性排序
|
||
|
||
**文件路径**：`src/utils/fuzzySearchEngine.js`
|
||
|
||
**核心配置**：
|
||
```javascript
|
||
const fuseConfig = {
|
||
threshold: 0.4, // 匹配阈值（0=精确, 1=宽松）
|
||
distance: 100, // 模式匹配的最大距离
|
||
includeScore: true, // 返回评分
|
||
includeMatches: true, // 返回匹配位置信息
|
||
minMatchCharLength: 2, // 最小匹配字符数
|
||
tokenize: true, // 启用分词模式
|
||
tokenSeparator: /[\s\p{P}]+/u, // 中英文分词正则
|
||
keys: ['text'] // 搜索字段
|
||
}
|
||
```
|
||
|
||
**核心方法**：
|
||
```typescript
|
||
class FuzzySearchEngine {
|
||
// 初始化索引（每次加载新文档时调用）
|
||
initIndex(documents: Document[]): void
|
||
|
||
// 执行搜索
|
||
search(keyword: string, options?: SearchOptions): SearchResult[]
|
||
|
||
// 关键词预处理（提升中文匹配率）
|
||
preprocessKeyword(keyword: string): string
|
||
|
||
// 格式化原始结果为统一格式
|
||
formatResult(rawResult: FuseResult, index: number): SearchResult
|
||
}
|
||
```
|
||
|
||
**输出数据结构**：
|
||
```typescript
|
||
interface SearchResult {
|
||
id: string // 唯一标识
|
||
type: 'text' | 'pdf' | 'table'
|
||
score: number // 相似度评分 (0-1, 越高越匹配)
|
||
matchedText: string // 匹配到的文本片段
|
||
context: string // 上下文（前后各50字符）
|
||
location: {
|
||
container?: HTMLElement
|
||
startOffset?: number
|
||
endOffset?: number
|
||
pageNumber?: number // PDF专用
|
||
rect?: { x, y, width, height } // PDF专用
|
||
cellIndex?: [number, number] // 表格专用
|
||
}
|
||
originalData: Document // 原始文档数据（用于高亮渲染）
|
||
}
|
||
```
|
||
|
||
**中文优化策略**：
|
||
1. 预处理阶段去除中文标点符号（""''【】《》（））
|
||
2. 使用Unicode属性转义`\p{P}`匹配所有标点
|
||
3. 分词时按空格和标点切分
|
||
4. 设置合理的threshold（0.4）平衡精准度和召回率
|
||
|
||
---
|
||
|
||
### 3.3 模块三：HighlightRenderer（高亮渲染器）
|
||
|
||
**职责**：在文档DOM中创建、管理和销毁高亮标记
|
||
|
||
**文件路径**：`src/utils/highlightRenderer.js`
|
||
|
||
**核心能力**：
|
||
```typescript
|
||
class HighlightRenderer {
|
||
// 渲染所有搜索结果的高亮
|
||
renderAll(results: SearchResult[]): number
|
||
|
||
// 创建单个高亮（根据type分发）
|
||
private createHighlight(result: SearchResult, index: number): Highlight
|
||
|
||
// DOM类型高亮（text/docx/markdown/html等）
|
||
private createDomHighlight(result, index): DomHighlight
|
||
|
||
// PDF类型高亮（在iframe中创建overlay层）
|
||
private createPdfHighlight(result, index): PdfHighlight
|
||
|
||
// 表格类型高亮（Excel/CSV单元格）
|
||
private createTableHighlight(result, index): TableHighlight
|
||
|
||
// 导航控制
|
||
navigateTo(index: number): void
|
||
next(): void
|
||
prev(): void
|
||
|
||
// 清除所有高亮
|
||
clearAll(): void
|
||
}
|
||
```
|
||
|
||
**高亮样式规范**：
|
||
|
||
#### DOM高亮（.search-highlight）
|
||
```css
|
||
.search-highlight {
|
||
background: linear-gradient(135deg, #fff3cd 0%, #ffe69c 100%);
|
||
border-bottom: 2px solid #ffc107;
|
||
border-radius: 2px;
|
||
padding: 1px 2px;
|
||
box-shadow: 0 1px 3px rgba(255, 193, 7, 0.3);
|
||
cursor: pointer;
|
||
}
|
||
|
||
.search-highlight.active {
|
||
background: linear-gradient(135deg, #ffd43b 0%, #fab005 100%);
|
||
border-bottom: 3px solid #f59f00;
|
||
animation: highlight-glow 2s ease-in-out infinite;
|
||
}
|
||
```
|
||
|
||
#### PDF高亮（.pdf-highlight-overlay）
|
||
- 使用绝对定位的div覆盖在文本上方
|
||
- 背景色：`rgba(255, 235, 59, 0.3)`
|
||
- 边框：`2px solid #ffc107`
|
||
- 包含角标显示序号
|
||
|
||
#### 表格高亮（.table-highlight）
|
||
- 绿色系配色（区别于文本黄色）
|
||
- 背景：`linear-gradient(135deg, #d4edda 0%, #c3e6cb 100%)`
|
||
- 边框：`2px solid #28a745`
|
||
|
||
**交互特性**：
|
||
- ✅ 点击高亮标记可跳转到该位置
|
||
- ✅ 当前激活项带脉冲发光动画
|
||
- ✅ 序号标签（1, 2, 3...）便于识别
|
||
- ✅ hover效果（轻微放大+阴影加深）
|
||
|
||
---
|
||
|
||
### 3.4 模块四：SearchCoordinator（协调控制器）
|
||
|
||
**职责**：编排整个搜索→定位→高亮的完整流程，处理异常和重试
|
||
|
||
**文件路径**：`src/utils/searchCoordinator.js`
|
||
|
||
**核心流程**：
|
||
```
|
||
execute(params)
|
||
↓
|
||
Step 1: 文本提取 (withRetry, 最多重试3次)
|
||
↓
|
||
Step 2: 页码过滤（如果指定了targetPage）
|
||
↓
|
||
Step 3: 初始化Fuse.js索引 → 执行搜索
|
||
↓
|
||
Step 4: 渲染高亮 → 导航到第一个结果
|
||
↓
|
||
返回: { success, resultCount, stats }
|
||
```
|
||
|
||
**重试机制**：
|
||
```typescript
|
||
async withRetry<T>(fn: () => T, maxRetries: number, delayMs: number): Promise<T> {
|
||
for (let i = 0; i < maxRetries; i++) {
|
||
try {
|
||
return await fn()
|
||
} catch (error) {
|
||
if (i < maxRetries - 1) {
|
||
await sleep(delayMs) // 等待DOM渲染完成
|
||
} else {
|
||
throw error // 最后一次重试失败则抛出异常
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误处理**：
|
||
- 文本提取失败 → 返回友好提示"无法提取文档内容"
|
||
- 未找到匹配 → 返回"未找到XXX相关内容"
|
||
- 高亮渲染部分失败 → 记录警告日志，继续渲染其他结果
|
||
- 全局异常 → 显示错误提示，不阻断用户操作
|
||
|
||
**性能统计**：
|
||
```typescript
|
||
interface SearchStats {
|
||
totalTime: number // 总耗时(ms)
|
||
extractionTime: number // 文本提取耗时
|
||
searchTime: number // 搜索耗时
|
||
renderTime: number // 高亮渲染耗时
|
||
resultCount: number // 结果数量
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 集成方案
|
||
|
||
### 4.1 QAModule.vue修改点
|
||
|
||
**文件路径**：`src/components/QAModule.vue`
|
||
|
||
**修改函数**：`navigateToFileReader()` (第1126行)
|
||
|
||
**改动内容**：
|
||
```javascript
|
||
// 优化关键词提取逻辑（第1159-1175行）
|
||
const keyword = ''
|
||
|
||
// 优先级1: ref.context（引用上下文）
|
||
if (ref.context) {
|
||
keyword = ref.context.substring(0, 150) // 增加长度限制至150字符
|
||
}
|
||
// 优先级2: ref.rawData中的多个字段
|
||
else if (ref.rawData) {
|
||
const raw = ref.rawData
|
||
keyword = raw.content || raw.context || raw.preview ||
|
||
raw.excerpt || raw.query || raw.question || ''
|
||
if (keyword) keyword = keyword.substring(0, 150)
|
||
}
|
||
// 优先级3: ref.location中的文本描述
|
||
if (!keyword && ref.location && ref.location.length > 4) {
|
||
const locText = ref.location.replace(/第\d+页|page\s*\d+/gi, '').trim()
|
||
if (locText.length >= 4) keyword = locText.substring(0, 120)
|
||
}
|
||
|
||
// 清洗关键词
|
||
if (keyword) {
|
||
keyword = cleanSearchKeyword(keyword)
|
||
if (keyword.length < 4) keyword = '' // 最小长度要求降至4字符
|
||
}
|
||
```
|
||
|
||
**改动理由**：
|
||
- 增加关键词长度限制（100→150），提高匹配成功率
|
||
- 扩展rawData字段检查范围
|
||
- 降低最小长度要求（4字符），适应短文本场景
|
||
|
||
---
|
||
|
||
### 4.2 ReaderPage.vue集成
|
||
|
||
**文件路径**：`src/views/ReaderPage.vue`
|
||
|
||
#### 4.2.1 新增imports
|
||
|
||
```javascript
|
||
import searchCoordinator from '@/utils/searchCoordinator'
|
||
|
||
// 新增响应式变量
|
||
const showNavigationControls = ref(false)
|
||
const searchResultCount = ref(0)
|
||
const currentHighlightIndex = ref(0)
|
||
const searchKeywordPreview = ref('')
|
||
```
|
||
|
||
#### 4.2.2 修改onMounted逻辑
|
||
|
||
```javascript
|
||
onMounted(async () => {
|
||
// ... 现有代码保持不变 ...
|
||
|
||
if (fileId) {
|
||
await loadFile(fileId, fileTitle, fileExtension, page)
|
||
|
||
// ✨ 新增：自动执行搜索高亮
|
||
if (keyword?.trim()) {
|
||
const renderDelays = {
|
||
pdf: 1000,
|
||
docx: 1500,
|
||
pptx: 1200,
|
||
xlsx: 800,
|
||
default: 500
|
||
}
|
||
|
||
const delay = renderDelays[fileType.value] || renderDelays.default
|
||
|
||
setTimeout(async () => {
|
||
const container = scrollContainerRef.value
|
||
if (!container) return
|
||
|
||
const result = await searchCoordinator.execute({
|
||
keyword,
|
||
fileType: fileType.value,
|
||
container,
|
||
targetPage: page
|
||
})
|
||
|
||
if (result.success) {
|
||
showNavigationControls.value = true
|
||
searchResultCount.value = result.resultCount
|
||
searchKeywordPreview.value = keyword.substring(0, 20) + '...'
|
||
|
||
message.success({
|
||
content: `找到 ${result.resultCount} 处匹配内容`,
|
||
duration: 3
|
||
})
|
||
} else {
|
||
message.warning({
|
||
content: result.message || '未找到相关内容',
|
||
duration: 3
|
||
})
|
||
}
|
||
}, delay)
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
#### 4.2.3 新增UI模板（搜索导航栏）
|
||
|
||
```html
|
||
<!-- 在reader-container内部、底部添加 -->
|
||
<Transition name="slide-up">
|
||
<div v-if="showNavigationControls" class="search-nav-bar">
|
||
<div class="nav-info">
|
||
<SearchOutlined class="nav-icon" />
|
||
<span>找到 <strong>{{ searchResultCount }}</strong> 处匹配</span>
|
||
<span class="keyword-preview">"{{ searchKeywordPreview }}"</span>
|
||
</div>
|
||
|
||
<div class="nav-actions">
|
||
<button
|
||
class="nav-btn"
|
||
@click="prevHighlight"
|
||
:disabled="currentHighlightIndex <= 0"
|
||
>
|
||
<UpOutlined /> 上一处
|
||
</button>
|
||
|
||
<span class="nav-counter">
|
||
{{ currentHighlightIndex + 1 }} / {{ searchResultCount }}
|
||
</span>
|
||
|
||
<button
|
||
class="nav-btn"
|
||
@click="nextHighlight"
|
||
:disabled="currentHighlightIndex >= searchResultCount - 1"
|
||
>
|
||
下一处 <DownOutlined />
|
||
</button>
|
||
|
||
<button class="nav-btn close-btn" @click="closeSearch">
|
||
<CloseOutlined />
|
||
</button>
|
||
</div>
|
||
</div>
|
||
</Transition>
|
||
```
|
||
|
||
#### 4.2.4 新增事件监听
|
||
|
||
```javascript
|
||
// 监听高亮导航事件（由HighlightRenderer触发）
|
||
onMounted(() => {
|
||
window.addEventListener('highlightNavigate', (e) => {
|
||
const { currentIndex, total } = e.detail
|
||
currentHighlightIndex.value = currentIndex
|
||
searchResultCount.value = total
|
||
})
|
||
})
|
||
|
||
onUnmounted(() => {
|
||
window.removeEventListener('highlightNavigate')
|
||
searchCoordinator.clearAllHighlights() // 清理高亮
|
||
})
|
||
```
|
||
|
||
#### 4.2.5 新增方法
|
||
|
||
```javascript
|
||
// 导航控制方法
|
||
const nextHighlight = () => {
|
||
searchCoordinator.nextHighlight()
|
||
}
|
||
|
||
const prevHighlight = () => {
|
||
searchCoordinator.prevHighlight()
|
||
}
|
||
|
||
const closeSearch = () => {
|
||
searchCoordinator.clearAllHighlights()
|
||
showNavigationControls.value = false
|
||
currentHighlightIndex.value = 0
|
||
searchResultCount.value = 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. CSS样式规范
|
||
|
||
### 5.1 高亮基础样式
|
||
|
||
已在"3.3 HighlightRenderer"章节详细定义，此处补充动画和导航栏样式。
|
||
|
||
### 5.2 动画效果
|
||
|
||
```css
|
||
/* 脉冲发光动画（当前激活项） */
|
||
@keyframes highlight-glow {
|
||
0%, 100% { box-shadow: 0 3px 8px rgba(245, 159, 0, 0.6); }
|
||
50% { box-shadow: 0 4px 16px rgba(245, 159, 0, 0.9), 0 0 20px rgba(245, 159, 0, 0.4); }
|
||
}
|
||
|
||
/* 缩放脉冲（首次出现） */
|
||
@keyframes highlight-pulse {
|
||
0% { transform: scale(1); opacity: 1; }
|
||
50% { transform: scale(1.05); opacity: 0.8; }
|
||
100% { transform: scale(1); opacity: 1; }
|
||
}
|
||
```
|
||
|
||
### 5.3 搜索导航栏
|
||
|
||
固定在阅读器底部中央，包含：
|
||
- 左侧：搜索图标 + 匹配数量 + 关键词预览
|
||
- 中间：当前位置计数器（如 "2 / 5"）
|
||
- 右侧：上一处 / 下一处 / 关闭按钮
|
||
|
||
详见设计文档第3.3节的CSS代码。
|
||
|
||
---
|
||
|
||
## 6. 数据流与时序
|
||
|
||
### 6.1 完整交互时序图
|
||
|
||
```
|
||
用户点击引用来源组件
|
||
↓
|
||
[QAModule.vue] navigateToFileReader(ref)
|
||
├─ 提取 filename, page, context/rawData
|
||
├─ 清洗生成 keyword (≤150字符)
|
||
└─ router.push({ query: { id, title, extension, page, keyword, from: 'qa' } })
|
||
↓
|
||
[Vue Router] 路由跳转到 /reader
|
||
↓
|
||
[ReaderPage.vue] onMounted()
|
||
├─ 解析路由参数 (id, page, keyword...)
|
||
├─ loadFile(id, title, extension, page)
|
||
│ ├─ 调用API获取文件Blob
|
||
│ ├─ 根据fileType渲染文档 (PDF/Word/Excel/...)
|
||
│ └─ hasFileLoaded = true
|
||
│
|
||
└─ setTimeout(delay) ← 等待DOM渲染完成
|
||
↓
|
||
[searchCoordinator.execute()]
|
||
│
|
||
├─ Step 1: textExtractor.extract(fileType, container)
|
||
│ ├─ withRetry(fn, 3, 200ms) ← 重试机制
|
||
│ └─ 返回 documents[]
|
||
│
|
||
├─ Step 2: 过滤目标页码（可选）
|
||
│
|
||
├─ Step 3: fuzzySearchEngine
|
||
│ ├─ initIndex(documents)
|
||
│ ├─ preprocessKeyword(keyword)
|
||
│ └─ search() → results[]
|
||
│
|
||
├─ Step 4: highlightRenderer.renderAll(results)
|
||
│ ├─ 遍历results创建高亮mark/overlay
|
||
│ ├─ navigateTo(0) ← 跳转到第一个结果
|
||
│ └─ 返回 highlightCount
|
||
│
|
||
└─ 返回 { success, resultCount, stats }
|
||
↓
|
||
更新UI状态:
|
||
├─ showNavigationControls = true
|
||
├─ searchResultCount = N
|
||
└─ 显示成功提示Toast
|
||
```
|
||
|
||
### 6.2 时间估算
|
||
|
||
| 步骤 | 耗时 | 说明 |
|
||
|------|------|------|
|
||
| 文本提取 | 50-200ms | 取决于文档大小 |
|
||
| Fuse.js索引构建 | 10-50ms | 取决于文本块数量 |
|
||
| 搜索执行 | 5-20ms | Fuse.js高效算法 |
|
||
| 高亮渲染 | 30-100ms | DOM操作 |
|
||
| **总计** | **95-370ms** | **< 400ms，用户体验流畅** |
|
||
|
||
加上等待DOM渲染的delay（500-1500ms），总响应时间约**0.6-2秒**。
|
||
|
||
---
|
||
|
||
## 7. 边界情况处理
|
||
|
||
### 7.1 异常场景
|
||
|
||
| 场景 | 处理策略 |
|
||
|------|---------|
|
||
| **关键词为空** | 不执行搜索，仅跳转到指定页码 |
|
||
| **文档内容为空** | 提示"无法提取文档内容"，仍完成页面跳转 |
|
||
| **无匹配结果** | 提示"未找到XXX相关内容"，保持在目标页面 |
|
||
| **部分高亮失败** | 记录警告日志，成功渲染的其他高亮正常显示 |
|
||
| **PDF iframe跨域受限** | 降级为仅页码跳转，提示"PDF高亮暂不可用" |
|
||
| **大文档（>10MB）** | 文本提取限流，只提取前1000个文本块 |
|
||
| **用户快速连续点击** | 防抖处理（300ms），取消上一次搜索 |
|
||
| **网络请求失败** | 显示错误提示，保留已渲染的高亮 |
|
||
|
||
### 7.2 兼容性保障
|
||
|
||
- **浏览器兼容**：Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
||
- **Vue版本**：Vue 3.2+ (Composition API)
|
||
- **移动端适配**：导航栏响应式布局，触摸友好的按钮尺寸
|
||
- **无障碍访问**：高亮元素添加aria-label，键盘导航支持（Tab/Enter）
|
||
|
||
---
|
||
|
||
## 8. 性能优化策略
|
||
|
||
### 8.1 文本提取优化
|
||
|
||
- **懒加载**：只在需要搜索时才提取文本（非页面加载时）
|
||
- **分批处理**：大文档分段提取，避免阻塞主线程
|
||
- **缓存机制**：相同文档不重复提取（基于fileId + hash缓存）
|
||
|
||
### 8.2 搜索引擎优化
|
||
|
||
- **增量更新**：文档内容变化时只更新受影响的索引条目
|
||
- **结果限制**：默认返回Top 20结果，避免过多DOM操作
|
||
- **Web Worker**：（可选）将Fuse.js搜索移至Worker线程（针对超大文档）
|
||
|
||
### 8.3 高亮渲染优化
|
||
|
||
- **虚拟滚动**：只渲染可视区域内的高亮（针对超多匹配项）
|
||
- **批量DOM操作**：使用DocumentFragment减少reflow
|
||
- **防抖清除**：快速切换时延迟清理旧高亮
|
||
|
||
### 8.4 内存管理
|
||
|
||
- **及时清理**：离开页面时调用`clearAllHighlights()`
|
||
- **引用释放**：断开DOM元素与JavaScript对象的循环引用
|
||
- **事件解绑**：onUnmounted时移除所有事件监听器
|
||
|
||
---
|
||
|
||
## 9. 测试计划
|
||
|
||
### 9.1 单元测试
|
||
|
||
| 测试模块 | 测试用例数 | 覆盖率目标 |
|
||
|---------|-----------|-----------|
|
||
| TextExtractor | 15 | ≥90% |
|
||
| FuzzySearchEngine | 20 | ≥95% |
|
||
| HighlightRenderer | 25 | ≥85% |
|
||
| SearchCoordinator | 18 | ≥90% |
|
||
|
||
**关键测试场景**：
|
||
- PDF文本提取（含多页、空页、特殊字符）
|
||
- 中文模糊匹配（同义词、错别字、截断关键词）
|
||
- DOM高亮创建/销毁（内存泄漏检测）
|
||
- 重试机制验证（模拟DOM未就绪）
|
||
|
||
### 9.2 集成测试
|
||
|
||
- **E2E测试**：使用Cypress自动化测试完整流程
|
||
1. 打开AI对话页面
|
||
2. 发送问题获得带引用的回答
|
||
3. 点击引用来源
|
||
4. 验证：页面跳转 + 高亮显示 + 导航栏出现
|
||
5. 点击"下一处"，验证高亮切换
|
||
|
||
- **兼容性测试**：BrowserStack云测试平台
|
||
- Chrome/Firefox/Safari/Edge 最新3个版本
|
||
- Windows/macOS/Linux 桌面端
|
||
- iOS/Android 移动端（可选）
|
||
|
||
### 9.3 性能测试
|
||
|
||
- **加载性能**：Lighthouse Performance Score ≥ 90
|
||
- **搜索响应时间**：P99 < 2秒
|
||
- **内存占用**：高亮渲染后内存增长 < 50MB
|
||
- **CPU占用**：搜索过程中CPU峰值 < 60%
|
||
|
||
---
|
||
|
||
## 10. 实施路线图
|
||
|
||
### Phase 1：核心引擎开发（Day 1-2）
|
||
|
||
**Day 1上午**：
|
||
- [ ] 安装依赖：`npm install fuse.js@7.0.0`
|
||
- [ ] 创建`src/utils/textExtractor.js`
|
||
- [ ] 实现PDF/DOCX/Excel/DOM文本提取方法
|
||
- [ ] 编写单元测试（TextExtractor）
|
||
|
||
**Day 1下午**：
|
||
- [ ] 创建`src/utils/fuzzySearchEngine.js`
|
||
- [ ] 配置Fuse.js中文优化参数
|
||
- [ ] 实现`preprocessKeyword`和`search`方法
|
||
- [ ] 编写单元测试（FuzzySearchEngine）
|
||
|
||
**Day 2上午**：
|
||
- [ ] 创建`src/utils/highlightRenderer.js`
|
||
- [ ] 实现DOM/PDF/表格三种高亮类型
|
||
- [ ] 添加导航控制逻辑
|
||
- [ ] 编写单元测试（HighlightRenderer）
|
||
|
||
**Day 2下午**：
|
||
- [ ] 创建`src/utils/searchCoordinator.js`
|
||
- [ ] 实现编排逻辑和重试机制
|
||
- [ ] 集成测试（4个模块联调）
|
||
|
||
### Phase 2：UI集成与调试（Day 3）
|
||
|
||
**Day 3上午**：
|
||
- [ ] 修改`QAModule.vue`的`navigateToFileReader`
|
||
- [ ] 修改`ReaderPage.vue`的`onMounted`
|
||
- [ ] 添加搜索导航栏UI模板
|
||
- [ ] 编写CSS样式（高亮+导航栏+动画）
|
||
|
||
**Day 3下午**：
|
||
- [ ] 本地开发环境调试
|
||
- [ ] 测试PDF高亮功能（重点）
|
||
- [ ] 测试Word/Excel/TXT等多种格式
|
||
- [ ] 修复发现的bug
|
||
|
||
### Phase 3：打磨与优化（Day 4）
|
||
|
||
**Day 4上午**：
|
||
- [ ] 错误处理完善（边界情况）
|
||
- [ ] 性能优化（内存/CPU）
|
||
- [ ] 用户反馈收集（内部测试）
|
||
|
||
**Day 4下午**：
|
||
- [ ] 代码审查和重构
|
||
- [ ] 文档编写（使用指南）
|
||
- [ ] 准备发布
|
||
|
||
---
|
||
|
||
## 11. 风险评估与应对
|
||
|
||
### 11.1 技术风险
|
||
|
||
| 风险项 | 概率 | 影响 | 应对措施 |
|
||
|--------|------|------|---------|
|
||
| **PDF iframe跨域限制** | 中 | 高 | 降级方案：仅页码跳转 + Toast提示 |
|
||
| **Fuse.js中文分词不准** | 低 | 中 | 自定义tokenizer或引入jieba分词 |
|
||
| **大文档性能问题** | 中 | 中 | 分批处理 + Web Worker + 虚拟滚动 |
|
||
| **DOM高亮破坏文档结构** | 低 | 高 | 使用Range API + 异常捕获回滚 |
|
||
|
||
### 11.2 进度风险
|
||
|
||
- **风险**：Phase 2集成调试超出预期
|
||
- **应对**：预留1天buffer time，优先保证核心功能可用
|
||
|
||
---
|
||
|
||
## 12. 成功验收标准
|
||
|
||
### 功能完整性 ✅
|
||
|
||
- [ ] 点击PDF引用 → 跳转页码 + overlay高亮显示
|
||
- [ ] 点击Word引用 → DOM高亮 + 持续显示
|
||
- [ ] 点击Excel引用 → 单元格高亮 + 角标序号
|
||
- [ ] 模糊匹配成功率 ≥ 90%（测试集验证）
|
||
- [ ] 导航栏正确显示匹配数量和当前位置
|
||
- [ ] 上/下一处按钮工作正常
|
||
|
||
### 性能指标 ⚡
|
||
|
||
- [ ] 搜索+高亮总耗时 < 2秒（P99）
|
||
- [ ] 内存增长 < 50MB（相对于无高亮状态）
|
||
- [ ] CPU峰值 < 60%（搜索过程中）
|
||
- [ ] Lighthouse Performance Score ≥ 90
|
||
|
||
### 用户体验 😊
|
||
|
||
- [ ] 高亮视觉效果醒目但不刺眼
|
||
- [ ] 动画流畅（60fps）
|
||
- [ ] 错误提示友好清晰
|
||
- [ ] 移动端触摸操作顺畅
|
||
- [ ] 键盘可访问（Tab/Enter导航）
|
||
|
||
### 代码质量 🔧
|
||
|
||
- [ ] 单元测试覆盖率 ≥ 85%
|
||
- [ ] 无console警告（生产环境）
|
||
- [ ] ESLint检查通过（0 error, 0 warning）
|
||
- [ ] 代码注释完整（JSDoc标准）
|
||
|
||
---
|
||
|
||
## 13. 后续迭代方向（可选）
|
||
|
||
### Phase 4：增强功能（v2.0）
|
||
|
||
- [ ] **多关键词同时高亮**：支持AND/OR逻辑组合
|
||
- [ ] **高亮导出**：将高亮标注导出为PDF注释
|
||
- [ ] **历史记录**：保存用户的搜索历史和高亮偏好
|
||
- [ ] **快捷键支持**：Ctrl+F唤起搜索框，F3跳转下一个
|
||
- [ ] **AI语义搜索**：升级为向量相似度匹配（需后端支持）
|
||
|
||
### Phase 5：平台扩展（v3.0）
|
||
|
||
- [ ] **Web Worker迁移**：将搜索引擎移至Worker线程
|
||
- [ ] **IndexedDB缓存**：离线缓存文本提取结果
|
||
- [ ] **PWA支持**：离线模式下仍可使用基本搜索功能
|
||
- [ ] **插件机制**：允许第三方开发者自定义高亮样式
|
||
|
||
---
|
||
|
||
## 附录A：关键技术参考
|
||
|
||
### A.1 Fuse.js官方文档
|
||
https://fusejs.io/
|
||
|
||
### A.2 Range API（MDN）
|
||
https://developer.mozilla.org/en-US/docs/Web/API/Range
|
||
|
||
### A.3 TreeWalker API（MDN）
|
||
https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
|
||
|
||
### A.4 PDF.js textLayer
|
||
https://github.com/nickmoss/pdfjs-viewer-textlayer
|
||
|
||
---
|
||
|
||
## 附录B：术语表
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| **RAG** | Retrieval-Augmented Generation（检索增强生成） |
|
||
| **SSE** | Server-Sent Events（服务器推送事件） |
|
||
| **Fuse.js** | 轻量级模糊搜索库 |
|
||
| **TreeWalker** | DOM树遍历API |
|
||
| **Range** | DOM范围选择API |
|
||
| **Overlay** | 覆盖层（用于PDF高亮） |
|
||
|
||
---
|
||
|
||
**文档维护者**：AI Code Assistant
|
||
**最后更新**：2026-05-30
|
||
**下次评审日期**：实施完成后3天内
|