# 搜索API对接指南-02-搜索建议与即时搜索

本篇面向前端联想词/搜索框团队，独立阅读 `GET /search/suggestions` 与 `GET /search/instant`。

## 搜索接口

### 3.7 搜索建议接口

- **端点**: `GET /search/suggestions`
- **描述**: 返回搜索建议（自动补全/热词），支持多语言。

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `q` | string | Y | - | 查询字符串（至少 1 个字符） |
| `size` | integer | N | 10 | 返回建议数量（1-50） |
| `language` | string | N | `en` | 请求语言，如 `zh` / `en` / `ar` / `ru`，用于路由到对应语种 suggestion 索引 |
| `debug` | bool | N | `false` | 是否开启调试（目前主要用于排查 suggestion 排序与语言解析） |

> **租户标识**：同 [-01-搜索接口](./搜索API对接指南-01-搜索接口.md#31-接口信息)，通过请求头 `X-Tenant-ID` 或 query 参数 `tenant_id` 传递。

#### 响应示例

```json
{
  "query": "iph",
  "language": "en",
  "resolved_language": "en",
  "suggestions": [
    {
      "text": "iphone 15",
      "lang": "en",
      "score": 12.37,
      "rank_score": 5.1,
      "sources": ["query_log", "qanchor"],
      "lang_source": "log_field",
      "lang_confidence": 1.0,
      "lang_conflict": false
    }
  ],
  "took_ms": 12
}
```

#### 请求示例

```bash
curl "http://localhost:6002/search/suggestions?q=芭&size=5&language=zh" \
  -H "X-Tenant-ID: 162"
```

### 3.8 即时搜索接口

> ⚠️ 当前版本未开放该能力。接口会明确返回 `501 Not Implemented`，避免误用未完成实现。

- **端点**: `GET /search/instant`
- **描述**: 即时搜索预留端点，后续会在独立实现完成后开放。

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `q` | string | Y | - | 搜索查询（至少 2 个字符） |
| `size` | integer | N | 5 | 返回结果数量（1-20） |

#### 请求示例

```bash
curl "http://localhost:6002/search/instant?q=玩具&size=5"
```

#### 当前响应

```json
{
  "error": "/search/instant is not implemented yet. Use POST /search/ for production traffic.",
  "status_code": 501
}
```