zhuiguang-ai/.trae/specs/modules/search.md

搜索增强模块

概述

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

---

搜索自动补全 🆕

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 可直接还原搜索状态