# Suggestion 运行手册（Runbook）

本文档面向研发/测试/运维，提供 suggestion 功能的标准操作流程。

## 1. 适用范围

- Suggestion 索引构建：`search_suggestions_tenant_{tenant_id}`
- Suggestion 查询接口：`GET /search/suggestions`
- 前端自动补全（`frontend/index.html`）联调

## 2. 依赖前置

确保以下服务和配置可用：

- Elasticsearch（开启鉴权时需提供账号密码）
- MySQL（表 `shoplazza_search_log` 可访问）
- API 服务（端口默认 6002）

建议环境变量：

```bash
ES_HOST=http://localhost:9200
ES_USERNAME=...
ES_PASSWORD=...
DB_HOST=...
DB_PORT=3306
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...
```

## 3. 全量构建流程

### 3.1 构建指定租户 suggestion 索引

```bash
./scripts/build_suggestions.sh 171 --days 365 --recreate
```

说明：

- `--days`：日志回溯窗口
- `--recreate`：删除旧索引并重建

### 3.2 预期输出

示例：

```json
{
  "tenant_id": "171",
  "index_name": "search_suggestions_tenant_171",
  "total_candidates": 336,
  "indexed_docs": 336,
  "bulk_result": {
    "success": 336,
    "failed": 0,
    "errors": []
  }
}
```

判定标准：

- `indexed_docs > 0`
- `bulk_result.failed = 0`

## 4. ES 验证步骤

> 若 ES 开启鉴权，请使用 `-u "$ES_USERNAME:$ES_PASSWORD"`。

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

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

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

重点检查：

- 字段是否齐全（`lang/text/sat/completion/rank_score`）
- 文档是否覆盖预期语种（如 `zh/en`）

## 5. API 回归步骤

### 5.1 启动后端

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

### 5.2 调用 suggestion 接口

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

curl "http://localhost:6002/search/suggestions?q=2025&size=5&language=zh&with_results=false" \
  -H "X-Tenant-ID: 171"
```

通过标准：

- 接口返回 `200`
- `resolved_language` 合理
- `suggestions` 非空（针对已知存在的 query）

## 6. 前端联调步骤

1. 打开 `http://localhost:6002/`
2. 选择租户（例如 `171`）
3. 输入已知前缀词（如 `shirt` / `Ekouaer` / `2025`）
4. 观察下拉 suggestion 是否出现

注意：

- 前端已同时透传：
  - Header：`X-Tenant-ID`
  - Query：`tenant_id`

## 7. 发布检查清单

- [ ] 全量构建输出 `failed=0`
- [ ] ES `_count` 与 `indexed_docs` 一致
- [ ] 关键 query（中/英）接口有返回
- [ ] 前端下拉正常
- [ ] 文档已更新（`README.md` / 本 Runbook / API 指南）