RUNBOOK.md 2.87 KB
Edit Raw Blame History


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）


建议环境变量：
ES_HOST=http://localhost:9200
ES_USERNAME=...
ES_PASSWORD=...
DB_HOST=...
DB_PORT=3306
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...

3. 全量构建流程
3.1 构建指定租户 suggestion 索引
./scripts/build_suggestions.sh 171 --days 365 --recreate


说明：


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

3.2 预期输出
示例：
{
  "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"。

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 scripts/start_backend.sh

5.2 调用 suggestion 接口
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. 前端联调步骤

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


注意：


前端已同时透传：


Header：X-Tenant-ID
Query：tenant_id


7. 发布检查清单

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