# Suggestion 运行手册（Phase 2）

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

## 1. 适用范围

- Suggestion 全量构建（版本化索引 + alias 原子发布）
- Suggestion 增量更新（watermark）
- Suggestion 查询接口：`GET /search/suggestions`

## 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 执行

```bash
./scripts/build_suggestions.sh 163 \
  --mode full \
  --days 365 \
  --publish-alias \
  --keep-versions 2
```

### 3.2 预期输出

输出包含关键字段：

- `mode=full`
- `index_name=..._vYYYYMMDDHHMMSS`
- `alias_published=true`
- `alias_publish.current_index` 指向新索引
- `bulk_result.failed=0`

## 4. 增量更新（watermark）

### 4.1 执行

```bash
./scripts/build_suggestions.sh 163 \
  --mode incremental \
  --overlap-minutes 30
```

### 4.2 预期输出

输出包含关键字段：

- `mode=incremental`
- `target_index`（当前 alias 对应索引）
- `query_window.since/until`
- `updated_terms`
- `bulk_result.failed=0`

## 5. ES 验证步骤

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

```bash
ALIAS_NAME="${ES_INDEX_NAMESPACE:-}search_suggestions_tenant_163_current"

curl "$ES_HOST/$ALIAS_NAME/_count?pretty"

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

重点检查：

- alias 是否可查（说明发布成功）
- 文档数 > 0
- 关键字段存在：`lang/text/rank_score/completion/sat`

## 6. API 回归步骤

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

curl "http://localhost:6002/search/suggestions?q=玩具&size=10&language=zh" \
  -H "X-Tenant-ID: 163"
```

通过标准：

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

## 7. 一键验证脚本

```bash
./scripts/rebuild_suggestions.sh 163
```

该脚本执行：

1. 全量重建并发布 alias
2. 增量更新
3. ES `_count` 与样例 `_search`
4. API `/search/suggestions` 冒烟请求

## 8. 发布检查清单

- [ ] 全量构建 `bulk_result.failed=0`
- [ ] alias 指向新版本索引
- [ ] 增量更新成功（`mode=incremental`）
- [ ] API 冒烟通过
- [ ] 文档与脚本已同步