# 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 162 \
    --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 162 \
    --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_162_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: 162"

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

  ```
  
  通过标准：
  
  - 接口返回 `200`

  - `suggestions` 非空（针对已知存在 query）
  - `took_ms` 合理

  ## 7. 一键验证脚本

  ```bash
  ./scripts/rebuild_suggestions.sh 162
  ```

  该脚本执行：

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

  ## 8. 发布检查清单

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