# C-07 · 全站统一搜索

| 字段 | 值 |
|---|---|
| 项目 | 可乐工具 · 后端 `search` app + `chunyu_project_react` |
| 优先级 | P1 · M3 |
| 建议模型 | deepseek-v4.1-flash（主）/ qwen3.8-flash（边界复核） |
| 依赖 | C-01（路由稳定） |
| 预估 | 2 天 |

## 一、背景（为什么做）

1. 页面健康检查发现：`/search` 路由被后端劫持且"原始 JSON 直接显示"——搜索页体验破损（C-01 修路由，本卡修体验）。
2. 后端 `search` app 已存在（INSTALLED_APPS 已注册），但前端无统一搜索页；四合一平台（工具/课程/文章/API）**没有跨模块检索**——用户找东西只能靠分模块翻页。
3. 竞品对照：菜鸟工具/掘金的搜索都是全站入口级功能。

## 二、目标（交付物）

**后端**
- 统一搜索端点：`GET /api/search/all?q=xxx&types=tool,article,course,api&page=1`
  - 分类型返回聚合结果 + 各类型命中计数
  - 复用现有各 app 的检索字段（精确优先 → 前缀 → 包含；PG 环境可用 icontains/全文；按项目现有 DB 能力落地）
  - 空结果优雅返回（不 500——参考 EnglishDrill 值收口教训，`q` 长度/类型先收口）
- 边界防护：`q` 超长截断、特殊字符转义、`types` 白名单

**前端**
- 全局搜索框升级（导航栏）：输入 → 防抖 → 下拉预览（每个类型 Top3）→ Enter 进 `/search?q=`
- `/search` 结果页：类型筛选 Tab（全部/工具/文章/课程/API）+ 分页 + 高亮命中词 + 空态

## 三、验收标准

- [ ] 一个关键词能同时命中多模块并分组展示
- [ ] 类型筛选、分页正确；命中计数准确
- [ ] `q` 为超长串/特殊字符/数组/数字等异常输入不 500（健壮性用例）
- [ ] 导航栏搜索框在全部页面可用（移动端适配）
- [ ] 既有测试全绿 + 新增 ≥8 用例

## 四、边界（不许做）

- 不引入 Elasticsearch/外部搜索服务（项目复杂度预算：PG/SQLite 能力内解决）
- 不改各模块自身列表接口
- 不做搜索词推荐/热度（另一张卡的空间）

## 五、交接

写 `PROGRESS_C-07.md`（含异常输入用例、多模块命中演示输出）。