# Suggestion 故障排查手册

本文档汇总 suggestion 常见问题与定位步骤。

## 1. `suggestions` 总是空数组

### 现象

```json
{"query":"shirt","language":"en","resolved_language":"en","suggestions":[],"took_ms":0}
```

### 排查步骤

1. 确认索引存在且有数据：

```bash
curl -u "$ES_USERNAME:$ES_PASSWORD" \
  "$ES_HOST/search_suggestions_tenant_171/_count?pretty"
```

2. 直接查 suggestion 索引样本：

```bash
curl -u "$ES_USERNAME:$ES_PASSWORD" \
  "$ES_HOST/search_suggestions_tenant_171/_search?pretty" -d '{
    "size": 20,
    "query": {"match_all": {}},
    "_source": ["lang","text","rank_score"]
  }'
```

3. 确认请求语种是否匹配（`language=en` 时，索引里应有 `lang=en` 文档）。

4. 检查服务版本是否为最新（重启后端）：

```bash
bash scripts/stop.sh
bash scripts/start_backend.sh
```

### 已修复的历史问题

- **重复传 `size` 导致 ES 查询异常并被吞掉**：
  - 症状：日志里出现 `Received multiple values for 'size'`
  - 结果：接口返回空 hits（看起来像“无数据”）
  - 处理：确保 query body 不再携带 `size`，仅通过 client 参数传 `size`

## 2. 报错：`tenant_id is required`

### 现象

```json
{
  "error": "tenant_id is required. Provide it via header 'X-Tenant-ID' or query parameter 'tenant_id'",
  "status_code": 400
}
```

### 原因

- 请求缺少 `X-Tenant-ID`，且 URL 没有 `tenant_id`。

### 处理

- API 调用至少满足其一：
  - Header：`X-Tenant-ID: 171`
  - Query：`tenant_id=171`

示例：

```bash
curl "http://localhost:6002/search/suggestions?q=shirt&size=5&language=en&with_results=false&tenant_id=171"
```

## 3. ES 401：`missing authentication credentials`

### 现象

```json
{
  "type":"security_exception",
  "reason":"missing authentication credentials ..."
}
```

### 原因

- ES 开启了安全认证，curl/脚本未带凭证。

### 处理

```bash
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"
```

或使用 API Key：

```bash
curl -H "Authorization: ApiKey <base64_key>" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"
```

## 4. 构建脚本报 `Cannot connect to Elasticsearch`

### 原因

- ES 地址不对，或账号密码未配置，或网络不可达。

### 检查

```bash
echo "$ES_HOST"
echo "$ES_USERNAME"
curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST"
```

## 5. 前端请求未携带租户参数

### 现象

- Network 中请求 URL 无 `tenant_id`
- Header 里无 `X-Tenant-ID`

### 处理

- 确认前端最新代码已生效（清缓存后强刷）。
- 前端应同时透传：
  - `X-Tenant-ID`
  - `tenant_id` query 参数（兜底，避免代理丢 header）

## 6. 关键 query（如 `shirt`）没有被索引

### 检查路径

1. MySQL 里确认日志存在并在回溯窗口内：

```sql
SELECT query, language, create_time
FROM shoplazza_search_log
WHERE tenant_id = 171
  AND query = 'shirt'
ORDER BY create_time DESC
LIMIT 20;
```

2. 构建命令是否使用足够大的 `--days`（例如 365）。
3. 检查 query 是否被清洗规则过滤（空白/符号/过长等）。

## 7. `Invalid HTTP request received.`

### 原因

- 6002 端口上跑的进程不是当前 FastAPI 服务，或请求协议与服务不匹配。

### 处理

```bash
bash scripts/stop.sh
bash scripts/start_backend.sh
curl "http://localhost:6002/health"
```

若 `/health` 正常，再测试 `/search/suggestions`。