# 搜索增强模块

## 概述
搜索增强模块提供自动补全、搜索历史、键盘导航和搜索结果高亮，全面提升搜索体验和效率。

---

## 搜索自动补全 🆕

### API

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/search/autocomplete | GET | 搜索自动补全建议 |

- Query: `q` (搜索关键词), `type` (tool/skill/all)
- 返回: `{ suggestions: [{ text, type, slug }] }`
- 基于工具名称、技能名称、标签前缀匹配
- 最多返回 8 条建议
- 响应时间 < 100ms（内存缓存）

### 前端组件

#### SearchBox 重写 🆕
- **文件**: `src/components/common/SearchBox.tsx`
- **功能**:
  - 输入时实时显示自动补全下拉
  - 键盘导航: ↑↓ 移动高亮 / Enter 选择 / ESC 关闭
  - 搜索防抖（300ms）
  - 搜索结果高亮匹配文本
  - 支持工具/技能分类筛选

---

## 搜索历史 🆕

### 存储
- localStorage 存储: `zhuiguang-search-history`
- 最多保留 20 条历史记录
- 按最近使用排序
- 去重（同一查询只保留最新一条）

### 交互
- 搜索框聚焦时显示历史记录下拉
- 点击历史记录直接搜索
- 支持单条删除和清空全部
- 历史记录带搜索类型图标

---

## 高亮文本组件 🆕

### HighlightText
- **文件**: `src/components/common/HighlightText.tsx`
- Props: `{ text: string, keyword: string, className?: string }`
- 功能: 将文本中匹配的关键词包裹在 `<mark>` 标签中
- 样式: 黄色高亮背景 `bg-yellow-200 dark:bg-yellow-800`
- 不区分大小写匹配

### 使用场景
- 搜索结果列表中的工具名称/描述
- 自动补全下拉中的建议文本
- 评论/话题搜索

---

## 搜索框语义化

### WCAG 合规
- `<form role="search">` 包裹搜索表单
- `<label>` 关联搜索输入框（视觉隐藏）
- `<input type="search" name="search">` 语义输入
- `aria-label="搜索AI工具"` 辅助标签
- 自动补全列表 `role="listbox"` + `aria-activedescendant`

---

## 搜索参数规范

### 标准搜索参数
| 参数 | 类型 | 说明 |
|------|------|------|
| search | string | 搜索关键词 |
| page | number | 页码（默认1） |
| pageSize | number | 每页条数（默认20） |
| categoryId | number | 分类筛选 |
| pricingModel | string | 定价筛选 |
| sort | string | 排序（latest/popular/rating） |

### URL 搜索参数同步
- 搜索关键词同步到 URL query string
- 支持浏览器前进/后退导航
- 分享搜索结果 URL 可直接还原搜索状态