# Suggestion 故障排查手册（Phase 2）

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

### 排查步骤

1. 检查 alias 是否存在并有数据：

```bash
ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"
curl "$ES_HOST/$ALIAS_NAME/_count?pretty"
```

2. 直接抽样查看：

```bash
curl "$ES_HOST/$ALIAS_NAME/_search?pretty" -H 'Content-Type: application/json' -d '{
  "size": 20,
  "query": {"match_all": {}},
  "_source": ["lang", "text", "rank_score", "query_count_30d"]
}'
```

3. 确认请求租户和语言：

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

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

请求缺少 `X-Tenant-ID`（或 query `tenant_id`）。

示例：

```bash
curl "http://localhost:6002/search/suggestions?q=shirt&size=10&language=en&tenant_id=162"
```

## 3. 增量更新没有写入（`updated_terms=0`）

### 常见原因

- watermark 时间窗内没有新日志
- `overlap_minutes` 太小
- `min_query_len` 过滤过严

### 处理

```bash
./scripts/build_suggestions.sh 162 --mode incremental --overlap-minutes 60
```

并在 MySQL 中确认窗口内日志存在。

## 4. alias 未切到新索引

### 检查

```bash
ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_162_current"
curl "$ES_HOST/_alias/$ALIAS_NAME?pretty"
```

### 处理

重新执行全量发布：

```bash
./scripts/build_suggestions.sh 162 --mode full --publish-alias --keep-versions 2
```

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

ES 开启鉴权时，所有 curl 都需要 `-u "$ES_USERNAME:$ES_PASSWORD"` 或 API Key。

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

检查 `ES_HOST`、账号密码、网络连通性：

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

## 7. 首次增量执行失败：找不到 active index

说明该租户尚未完成全量构建。可直接启用 bootstrap（默认开启）：

```bash
./scripts/build_suggestions.sh 162 --mode incremental --bootstrap-if-missing
```

或先执行一次全量。