From 316c97c436a2d0edb3df85369402bf1c9b36cf76 Mon Sep 17 00:00:00 2001
From: tangwang <tangwang@essa.top>
Date: Mon, 2 Mar 2026 22:19:25 +0800
Subject: [PATCH] feat: 完整落地多租户 suggestion 能力

---
 api/routes/search.py          |   2 +-
 docs/搜索API对接指南.md |   4 ++--
 frontend/index.html           |  54 +++++++++++++++++++++++++++++++++---------------------
 main.py                       |   2 +-
 suggestion/README.md          | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 suggestion/RUNBOOK.md         | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 suggestion/TROUBLESHOOTING.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 suggestion/builder.py         |   2 +-
 suggestion/service.py         |   2 --
 9 files changed, 464 insertions(+), 28 deletions(-)
 create mode 100644 suggestion/RUNBOOK.md
 create mode 100644 suggestion/TROUBLESHOOTING.md

diff --git a/api/routes/search.py b/api/routes/search.py
index e137da1..770dfcf 100644
--- a/api/routes/search.py
+++ b/api/routes/search.py
@@ -269,7 +269,7 @@ async def search_by_image(request: ImageSearchRequest, http_request: Request):
 @router.get("/suggestions", response_model=SearchSuggestResponse)
 async def search_suggestions(
     q: str = Query(..., min_length=1, description="搜索查询"),
-    size: int = Query(10, ge=1, le=20, description="建议数量"),
+    size: int = Query(10, ge=1, le=200, description="建议数量（1-200）"),
     language: str = Query("en", description="请求语言，如 zh/en/ar/ru"),
     with_results: bool = Query(True, description="是否附带每条 suggestion 的直达商品"),
     result_size: int = Query(3, ge=1, le=10, description="每条 suggestion 直达商品数量"),
diff --git a/docs/搜索API对接指南.md b/docs/搜索API对接指南.md
index 2f4ed28..3afbbd8 100644
--- a/docs/搜索API对接指南.md
+++ b/docs/搜索API对接指南.md
@@ -129,7 +129,7 @@ curl -X POST "http://120.76.41.98:6002/search/" \
 | 接口 | HTTP Method | Endpoint | 说明 |
 |------|------|------|------|
 | 搜索 | POST | `/search/` | 执行搜索查询 |
-| 搜索建议 | GET | `/search/suggestions` | 搜索建议（框架，暂未实现） ⚠️ TODO |
+| 搜索建议 | GET | `/search/suggestions` | 搜索建议（自动补全/热词，多语言 + 结果直达） |
 | 即时搜索 | GET | `/search/instant` | 边输入边搜索（框架） ⚠️ TODO |
 | 获取文档 | GET | `/search/{doc_id}` | 获取单个文档 |
 | 全量索引 | POST | `/indexer/reindex` | 全量索引接口（导入数据，不删除索引，仅推荐自测使用） |
@@ -566,7 +566,7 @@ response = requests.post(url, headers=headers, json={"query": "芭比娃娃"})
 | 参数 | 类型 | 必填 | 默认值 | 描述 |
 |------|------|------|--------|------|
 | `q` | string | Y | - | 查询字符串（至少 1 个字符） |
-| `size` | integer | N | 10 | 返回建议数量（1-20） |
+| `size` | integer | N | 10 | 返回建议数量（1-200） |
 | `language` | string | N | `en` | 请求语言，如 `zh` / `en` / `ar` / `ru`，用于路由到对应语种 suggestion 索引 |
 | `with_results` | bool | N | `true` | 是否为每条 suggestion 返回商品列表（结果直达） |
 | `result_size` | integer | N | 3 | 每条 suggestion 返回的商品数量（1-10） |
diff --git a/frontend/index.html b/frontend/index.html
index 0895098..00855cd 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -200,8 +200,8 @@
     <script src="/static/js/tenant_facets_config.js?v=1.3"></script>
     <script src="/static/js/app.js?v=3.6"></script>
     <script>
-        // 自动补全功能
-        const SUGGEST_API = 'http://120.76.41.98:5003/suggest';
+        // 自动补全功能（使用后端 /search/suggestions 接口）
+        const SUGGEST_API = API_BASE_URL + '/search/suggestions';
         const LANG_OPTIONS = ['zh', 'en', 'ru', 'es', 'fr', 'de', 'it', 'ja'];
         let debounceTimer = null;
         let currentSuggestions = [];
@@ -235,7 +235,7 @@
             };
         }
 
-        // 获取映射后的 tenant_id（用于 suggest API）
+        // 获取映射后的 tenant_id（旧外部 suggest API 使用，当前后端自有 suggest 已不再需要）
         function getMappedTenantIdForSuggest(tenantId) {
             if (!tenantId) {
                 return null;
@@ -268,28 +268,35 @@
             abortController = new AbortController();
 
             try {
-                // 获取当前 tenant_id 并应用映射
+                // 获取当前 tenant_id（搜索后端使用真实 tenant_id）
                 let tenantId = null;
                 if (typeof getTenantId === 'function') {
                     tenantId = getTenantId();
                 }
-                const mappedTenantId = getMappedTenantIdForSuggest(tenantId);
+                // 若未选择租户，则不发起后端请求，避免 400
+                if (!tenantId) {
+                    console.warn('No tenant ID selected, skip suggestion request');
+                    hideSuggestions();
+                    return;
+                }
 
                 const url = new URL(SUGGEST_API);
-                url.searchParams.set('query', query);
-                url.searchParams.set('lang', getSelectedLang());
-                url.searchParams.set('limit', '40');
-                // 添加 tenant_id 参数
-                if (mappedTenantId) {
-                    url.searchParams.set('tenant_id', mappedTenantId);
-                }
+                url.searchParams.set('q', query);
+                url.searchParams.set('size', '40');
+                url.searchParams.set('language', getSelectedLang());
+                url.searchParams.set('with_results', 'false');
+                // 同时通过 query 参数传 tenant_id，方便在代理层丢失 header 时仍能识别租户
+                url.searchParams.set('tenant_id', tenantId);
+
+                const headers = {
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+                    'Referer': window.location.origin + '/'
+                };
+                headers['X-Tenant-ID'] = tenantId;
 
                 const response = await fetch(url.toString(), {
                     signal: abortController.signal,
-                    headers: {
-                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
-                        'Referer': window.location.origin + '/'
-                    }
+                    headers: headers
                 });
 
                 if (!response.ok) {
@@ -297,7 +304,7 @@
                 }
 
                 const data = await response.json();
-                if (data.status === 'success' && data.suggestions) {
+                if (Array.isArray(data.suggestions) && data.suggestions.length > 0) {
                     currentSuggestions = data.suggestions;
                     showSuggestions(data.suggestions);
                 } else {
@@ -324,11 +331,16 @@
                 const div = document.createElement('div');
                 div.className = 'suggestion-item';
                 div.dataset.index = index;
+                const text = item.text || '';
+                const lang = item.lang || '';
+                const score = typeof item.rank_score === 'number'
+                    ? item.rank_score.toFixed(2)
+                    : (typeof item.score === 'number' ? item.score.toFixed(2) : '');
                 div.innerHTML = `
-                    <div class="suggestion-text">${escapeHtml(item.canon)}</div>
-                    <div class="suggestion-meta">${item.entry_type} | ${item.canon_freq}</div>
+                    <div class="suggestion-text">${escapeHtml(text)}</div>
+                    <div class="suggestion-meta">${escapeHtml(lang)}${score ? ' | ' + score : ''}</div>
                 `;
-                div.onclick = () => selectSuggestion(item.canon);
+                div.onclick = () => selectSuggestion(text);
                 div.onmouseenter = () => {
                     selectedIndex = index;
                     updateHighlight();
@@ -399,7 +411,7 @@
                 updateHighlight();
             } else if (e.key === 'Enter' && selectedIndex >= 0) {
                 e.preventDefault();
-                selectSuggestion(currentSuggestions[selectedIndex].canon);
+                selectSuggestion(currentSuggestions[selectedIndex].text);
             } else if (e.key === 'Escape') {
                 hideSuggestions();
             }
diff --git a/main.py b/main.py
index 9e49725..18b7a7a 100755
--- a/main.py
+++ b/main.py
@@ -186,7 +186,7 @@ def main():
     )
     suggest_build_parser.add_argument('--tenant-id', required=True, help='Tenant ID')
     suggest_build_parser.add_argument('--es-host', default='http://localhost:9200', help='Elasticsearch host')
-    suggest_build_parser.add_argument('--days', type=int, default=30, help='Query log lookback days')
+    suggest_build_parser.add_argument('--days', type=int, default=360, help='Query log lookback days')
     suggest_build_parser.add_argument('--batch-size', type=int, default=500, help='Product scan batch size')
     suggest_build_parser.add_argument('--min-query-len', type=int, default=1, help='Minimum query length')
     suggest_build_parser.add_argument(
diff --git a/suggestion/README.md b/suggestion/README.md
index 595d7a3..887f789 100644
--- a/suggestion/README.md
+++ b/suggestion/README.md
@@ -1,5 +1,11 @@
 # Suggestion 设计文档
 
+## 文档导航
+
+- `README.md`（本文）：完整方案设计（架构、索引、构建、查询、验证）
+- `RUNBOOK.md`：日常运行手册（如何构建、如何回归、如何发布）
+- `TROUBLESHOOTING.md`：故障排查手册（空结果、tenant 丢失、ES 401、版本未生效等）
+
 本文档定义 `search_suggestions` 独立索引方案，用于支持多语言自动补全（suggestion）与结果直达。
 
 ## 1. 背景与目标
@@ -399,4 +405,124 @@ M3（优化）：
 
 ---
 
+## 13. 实验与验证建议
+
+以租户 `tenant_id=171` 为例，推荐如下验证流程（其他租户同理）：
+
+### 13.1 构建索引
+
+```bash
+./scripts/build_suggestions.sh 171 --days 30 --recreate
+```
+
+期望 CLI 输出类似：
+
+```json
+{
+  "tenant_id": "171",
+  "index_name": "search_suggestions_tenant_171",
+  "total_candidates": 61,
+  "indexed_docs": 61,
+  "bulk_result": {
+    "success": 61,
+    "failed": 0,
+    "errors": []
+  }
+}
+```
+
+含义：
+
+- `total_candidates`：聚合到的词候选总数（按 `(lang,text_norm)` 去重）
+- `indexed_docs`：实际写入 ES 的文档数（通常与 `total_candidates` 相同）
+- `bulk_result`：bulk 写入统计
+
+### 13.2 检查索引结构
+
+```bash
+curl "http://localhost:9200/search_suggestions_tenant_171/_mapping?pretty"
+curl "http://localhost:9200/search_suggestions_tenant_171/_count?pretty"
+curl "http://localhost:9200/search_suggestions_tenant_171/_search?size=5&pretty" -d '{
+  "query": { "match_all": {} }
+}'
+```
+
+重点确认：
+
+- 是否存在 `lang/text/text_norm/sources/rank_score/completion/sat` 等字段。
+- 文档中 `lang` 是否只落在租户配置的 `index_languages` 范围内。
+- 常见 query（如你期望的热词）是否有对应文档，`query_count_*` 是否大致正确。
+
+### 13.3 通过 API 验证 suggestion 行为
+
+启动后端：
+
+```bash
+python main.py serve --es-host http://localhost:9200 --port 6002
+```
+
+示例调用（中文）：
+
+```bash
+curl "http://localhost:6002/search/suggestions?q=玩具&size=5&language=zh&with_results=true" \
+  -H "X-Tenant-ID: 171"
+```
+
+示例调用（英文）：
+
+```bash
+curl "http://localhost:6002/search/suggestions?q=iph&size=5&language=en&with_results=true" \
+  -H "X-Tenant-ID: 171"
+```
+
+预期：
+
+- `resolved_language` 与传入 `language` 一致或回落到租户主语言。
+- 返回若干 `suggestions[]`，每条包含：
+  - `text/lang/score/rank_score/sources`
+  - `products[]` 为直达商品（数量由 `result_size` 控制）。
+
+如需进一步排查，可对比：
+
+- 某个 suggestion 的 `text` 与 `shoplazza_search_log.query` 的出现频次。
+- 该 suggestion 的 `products` 是否与主搜索接口 `POST /search/` 对同 query 的 topN 结果大体一致。
+
+### 13.4 语言归属与多语言检查
+
+挑选典型场景：
+
+- 纯中文 query（如商品中文标题）。
+- 纯英文 query（如品牌/型号）。
+- 混合或无明显语言的 query。
+
+验证点：
+
+- 文档 `lang` 与期望语言是否匹配。
+- `lang_source` 是否按优先级反映来源：
+  - `log_field` > `request_params` > `script/model/default`
+- 如存在 `lang_conflict=true` 的案例，采样检查日志中 `language` 与 `request_params.language` 是否存在冲突。
+
+## 14. 自动化测试建议
+
+已提供基础单元测试（见 `tests/test_suggestions.py`）：
+
+- 语言解析逻辑：
+  - `test_resolve_query_language_prefers_log_field`
+  - `test_resolve_query_language_uses_request_params_when_log_missing`
+  - `test_resolve_query_language_fallback_to_primary`
+- 在线查询逻辑：
+  - `test_suggestion_service_basic_flow`：使用 `FakeESClient` 验证 suggestion + 结果直达商品整体流程。
+
+推荐在本地环境中执行：
+
+```bash
+pytest tests/test_suggestions.py -q
+```
+
+后续可根据业务需要补充：
+
+- 排序正确性测试（构造不同 `query_count_*`、`title/qanchor_doc_count`）。
+- 多语言覆盖测试（zh/en/ar/ru 等，结合租户 `index_languages`）。
+- 简单性能回归（单次查询时延、QPS 与 P95/P99 录制）。
+
 本设计优先保证可落地与可演进：先以独立 suggestion 索引跑通主能力，再逐步增强排序与在线性能。
diff --git a/suggestion/RUNBOOK.md b/suggestion/RUNBOOK.md
new file mode 100644
index 0000000..7047646
--- /dev/null
+++ b/suggestion/RUNBOOK.md
@@ -0,0 +1,136 @@
+# 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 指南）
+
diff --git a/suggestion/TROUBLESHOOTING.md b/suggestion/TROUBLESHOOTING.md
new file mode 100644
index 0000000..72faaa5
--- /dev/null
+++ b/suggestion/TROUBLESHOOTING.md
@@ -0,0 +1,164 @@
+# Suggestion 故障排查手册
+
+本文档汇总 suggestion 常见问题与定位步骤。
+
+## 1. `suggestions` 总是空数组
+
+### 现象
+
+```json
+{"query":"shirt","language":"en","resolved_language":"en","suggestions":[],"took_ms":0}
+```
+
+### 排查步骤
+
+1. 确认索引存在且有数据：
+
+```bash
+curl -u "$ES_USERNAME:$ES_PASSWORD" \
+  "$ES_HOST/search_suggestions_tenant_171/_count?pretty"
+```
+
+2. 直接查 suggestion 索引样本：
+
+```bash
+curl -u "$ES_USERNAME:$ES_PASSWORD" \
+  "$ES_HOST/search_suggestions_tenant_171/_search?pretty" -d '{
+    "size": 20,
+    "query": {"match_all": {}},
+    "_source": ["lang","text","rank_score"]
+  }'
+```
+
+3. 确认请求语种是否匹配（`language=en` 时，索引里应有 `lang=en` 文档）。
+
+4. 检查服务版本是否为最新（重启后端）：
+
+```bash
+bash scripts/stop.sh
+bash scripts/start_backend.sh
+```
+
+### 已修复的历史问题
+
+- **重复传 `size` 导致 ES 查询异常并被吞掉**：
+  - 症状：日志里出现 `Received multiple values for 'size'`
+  - 结果：接口返回空 hits（看起来像“无数据”）
+  - 处理：确保 query body 不再携带 `size`，仅通过 client 参数传 `size`
+
+## 2. 报错：`tenant_id is required`
+
+### 现象
+
+```json
+{
+  "error": "tenant_id is required. Provide it via header 'X-Tenant-ID' or query parameter 'tenant_id'",
+  "status_code": 400
+}
+```
+
+### 原因
+
+- 请求缺少 `X-Tenant-ID`，且 URL 没有 `tenant_id`。
+
+### 处理
+
+- API 调用至少满足其一：
+  - Header：`X-Tenant-ID: 171`
+  - Query：`tenant_id=171`
+
+示例：
+
+```bash
+curl "http://localhost:6002/search/suggestions?q=shirt&size=5&language=en&with_results=false&tenant_id=171"
+```
+
+## 3. ES 401：`missing authentication credentials`
+
+### 现象
+
+```json
+{
+  "type":"security_exception",
+  "reason":"missing authentication credentials ..."
+}
+```
+
+### 原因
+
+- ES 开启了安全认证，curl/脚本未带凭证。
+
+### 处理
+
+```bash
+curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"
+```
+
+或使用 API Key：
+
+```bash
+curl -H "Authorization: ApiKey <base64_key>" "$ES_HOST/search_suggestions_tenant_171/_mapping?pretty"
+```
+
+## 4. 构建脚本报 `Cannot connect to Elasticsearch`
+
+### 原因
+
+- ES 地址不对，或账号密码未配置，或网络不可达。
+
+### 检查
+
+```bash
+echo "$ES_HOST"
+echo "$ES_USERNAME"
+curl -u "$ES_USERNAME:$ES_PASSWORD" "$ES_HOST"
+```
+
+## 5. 前端请求未携带租户参数
+
+### 现象
+
+- Network 中请求 URL 无 `tenant_id`
+- Header 里无 `X-Tenant-ID`
+
+### 处理
+
+- 确认前端最新代码已生效（清缓存后强刷）。
+- 前端应同时透传：
+  - `X-Tenant-ID`
+  - `tenant_id` query 参数（兜底，避免代理丢 header）
+
+## 6. 关键 query（如 `shirt`）没有被索引
+
+### 检查路径
+
+1. MySQL 里确认日志存在并在回溯窗口内：
+
+```sql
+SELECT query, language, create_time
+FROM shoplazza_search_log
+WHERE tenant_id = 171
+  AND query = 'shirt'
+ORDER BY create_time DESC
+LIMIT 20;
+```
+
+2. 构建命令是否使用足够大的 `--days`（例如 365）。
+3. 检查 query 是否被清洗规则过滤（空白/符号/过长等）。
+
+## 7. `Invalid HTTP request received.`
+
+### 原因
+
+- 6002 端口上跑的进程不是当前 FastAPI 服务，或请求协议与服务不匹配。
+
+### 处理
+
+```bash
+bash scripts/stop.sh
+bash scripts/start_backend.sh
+curl "http://localhost:6002/health"
+```
+
+若 `/health` 正常，再测试 `/search/suggestions`。
+
diff --git a/suggestion/builder.py b/suggestion/builder.py
index f5b06b6..43f0482 100644
--- a/suggestion/builder.py
+++ b/suggestion/builder.py
@@ -233,7 +233,7 @@ class SuggestionIndexBuilder:
     def rebuild_tenant_index(
         self,
         tenant_id: str,
-        days: int = 30,
+        days: int = 365,
         recreate: bool = True,
         batch_size: int = 500,
         min_query_len: int = 1,
diff --git a/suggestion/service.py b/suggestion/service.py
index c9411b7..88ec5f6 100644
--- a/suggestion/service.py
+++ b/suggestion/service.py
@@ -45,7 +45,6 @@ class SuggestionService:
         qanchor_field = f"qanchors.{lang}"
 
         body = {
-            "size": result_size,
             "_source": ["spu_id", "title", "min_price", "image_url", "sales", "total_inventory"],
             "query": {
                 "bool": {
@@ -99,7 +98,6 @@ class SuggestionService:
 
         sat_field = f"sat.{resolved_lang}"
         dsl = {
-            "size": size,
             "query": {
                 "function_score": {
                     "query": {
--
libgit2 0.21.2