ai-saas / saas-search

Blame view

docs/搜索API对接指南-05-索引接口（Indexer）.md 21.2 KB
Edit Raw Normal View History
0342d897   tangwang   搜索API对接指南 拆分 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
  # 搜索API对接指南-05-索引接口（Indexer）
  
  本篇覆盖数据同步/索引构建相关的所有接口（原文第 5 章），用于 `external indexer` 和 `Indexer 服务` 的对接。
  
  ## 索引接口
  
  本节内容与 `api/routes/indexer.py` 中的索引相关服务一致，包含以下接口：
  
  | 接口 | 方法 | 路径 | 说明 |
  |------|------|------|------|
  | 全量重建索引 | POST | `/indexer/reindex` | 将指定租户所有 SPU 导入 ES（不删现有索引） |
  | 增量索引 | POST | `/indexer/index` | 按 SPU ID 列表索引/删除，支持自动检测删除与显式删除 |
  | 查询文档 | POST | `/indexer/documents` | 按 SPU ID 列表查询 ES 文档，不写入 ES |
  | 构建 ES 文档（正式） | POST | `/indexer/build-docs` | 由上游提供 MySQL 行数据，返回 ES-ready 文档，不写 ES |
  | 构建 ES 文档（测试） | POST | `/indexer/build-docs-from-db` | 由本服务查库并构建文档，仅测试/调试用 |
0342d897   tangwang   搜索API对接指南 拆分 
16
17
18
19
20
21
22
23
 
  | 索引健康检查 | GET | `/indexer/health` | 检查索引服务与数据库连接状态 |
  
  #### 5.0 支撑外部 indexer 的三种方式
  
  本服务对**外部 indexer 程序**（如 Java 索引系统）提供三种对接方式，可按需选择：
  
  | 方式 | 说明 | 适用场景 |
  |------|------|----------|
a3275468   tangwang   已把本仓库里的 `/indexer... 
24
25
 
  | **1）doc 填充接口** | 调用 `POST /indexer/build-docs` 或 `POST /indexer/build-docs-from-db`，由本服务基于 MySQL 行数据构建 ES 文档（含多语言、向量、规格等），**不写入 ES**，由调用方自行写入。 | 希望一站式拿到 ES-ready doc，由己方控制写 ES 的时机与索引名。 |
  | **2）微服务组合** | 单独调用**翻译**、**向量化**、**外部内容理解服务**等能力，由 indexer 程序自己组装 doc 并写入 ES。翻译与向量化见第 7 节；内容理解字段生成已迁移到独立项目，不再由本仓库维护。 | 需要灵活编排、或希望将 LLM/向量等耗时步骤与主链路解耦（如异步补齐 qanchors/tags）。 |
0342d897   tangwang   搜索API对接指南 拆分 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
 
  | **3）本服务直接写 ES** | 调用全量索引 `POST /indexer/reindex`、增量索引 `POST /indexer/index`（指定 SPU ID 列表），由本服务从 MySQL 拉数并直接写入 ES。 | 自建运维、联调或不需要由 Java 写 ES 的场景。 |
  
  - **方式 1** 与 **方式 2** 下，ES 的写入方均为外部 indexer（或 Java），职责清晰。
  - **方式 3** 下，本服务同时负责读库、构建 doc 与写 ES。
  
  ### 5.1 为租户创建索引
  
  为租户创建索引需要两个步骤：
  
  1. **创建索引结构**（可选，仅在需要更新 mapping 或在新环境首次创建时执行）
     - 使用脚本创建 ES 索引结构（基于 `mappings/search_products.json`）
     - 如果索引已存在，会提示用户确认（会删除现有数据）
  
  2. **导入数据**（必需）
     - 使用全量索引接口 `/indexer/reindex` 导入数据
  
  **创建索引结构（支持多环境 namespace）**：
  
  ```bash
  # 以 UAT 环境为例：
  # 1. 准备 UAT 环境的 .env（包含 UAT 的 ES_HOST/DB_HOST 等）
  # 2. 设置环境前缀（也可以直接在 .env 中配置）：
  export RUNTIME_ENV=uat
  export ES_INDEX_NAMESPACE=uat_
  
  # 3. 为 tenant_id=170 创建索引结构
  ./scripts/create_tenant_index.sh 170
  ```
  
  脚本会自动从项目根目录的 `.env` 文件加载 ES 配置，并根据 `ES_INDEX_NAMESPACE` 创建：
  
  - prod 环境（ES_INDEX_NAMESPACE 为空）：`search_products_tenant_170`
  - UAT 环境（ES_INDEX_NAMESPACE=uat_）：`uat_search_products_tenant_170`
  
  **注意事项**：
  - ⚠️ 如果索引已存在，脚本会提示确认，确认后会删除现有数据
  - 创建索引后，**必须**调用 `/indexer/reindex` 导入数据
  - 如果只是更新数据而不需要修改索引结构，直接使用 `/indexer/reindex` 即可
  
  ---
  
  ### 5.2 全量索引接口
  
  - **端点**: `POST /indexer/reindex`
  - **描述**: 全量索引，将指定租户的所有SPU数据导入到ES索引（不会删除现有索引）。**推荐仅用于自测/运维场景**；生产环境下更推荐由 Java 等上游控制调度与写 ES。
  
  #### 请求参数
  
  ```json
  {
    "tenant_id": "162",
    "batch_size": 500
  }
  ```
  
  | 参数 | 类型 | 必填 | 默认值 | 说明 |
  |------|------|------|--------|------|
  | `tenant_id` | string | Y | - | 租户ID |
  | `batch_size` | integer | N | 500 | 批量导入大小 |
  
  #### 响应格式
  
  **成功响应（200 OK）**（示例，实际 `index_name` 会带上 tenant 和环境前缀）:
  
  ```json
  {
    "success": true,
    "total": 1000,
    "indexed": 1000,
    "failed": 0,
    "elapsed_time": 12.34,
    "index_name": "search_products_tenant_162",
    "tenant_id": "162"
  }
  ```
  
  **错误响应**:
  - `400 Bad Request`: 参数错误
  - `503 Service Unavailable`: 服务未初始化
  
  #### 请求示例
  
  **全量索引（不会删除现有索引）**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/reindex" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "batch_size": 500
    }'
  ```
  
  **查看日志**:
  
  ```bash
  # 查看API日志（包含索引操作日志）
  tail -f logs/api.log
  
  # 或者查看所有日志文件
  tail -f logs/*.log
  ```
  
  > ⚠️ **重要提示**：如需 **创建索引结构**，请参考 [5.1 为租户创建索引](#51-为租户创建索引) 章节，使用 `./scripts/create_tenant_index.sh <tenant_id>`。创建后需要调用 `/indexer/reindex` 导入数据。
  
  **查看索引日志**:
  
  索引操作的所有关键信息都会记录到 `logs/indexer.log` 文件中（JSON 格式），包括：
  - 请求开始和结束时间
  - 租户ID、SPU ID、操作类型
  - 每个SPU的处理状态
  - ES批量写入结果
  - 成功/失败统计和详细错误信息
  
  ```bash
  # 实时查看索引日志（包含全量和增量索引的所有操作）
  tail -f logs/indexer.log
  
  # 使用 grep 查询（简单方式）
  # 查看全量索引日志
  grep "\"index_type\":\"bulk\"" logs/indexer.log | tail -100
  
  # 查看增量索引日志
  grep "\"index_type\":\"incremental\"" logs/indexer.log | tail -100
  
  # 查看特定租户的索引日志
  grep "\"tenant_id\":\"162\"" logs/indexer.log | tail -100
  
  # 使用 jq 查询（推荐，更精确的 JSON 查询）
  # 安装 jq: sudo apt-get install jq 或 brew install jq
  
  # 查看全量索引日志
  cat logs/indexer.log | jq 'select(.index_type == "bulk")' | tail -100
  
  # 查看增量索引日志
  cat logs/indexer.log | jq 'select(.index_type == "incremental")' | tail -100
  
  # 查看特定租户的索引日志
  cat logs/indexer.log | jq 'select(.tenant_id == "162")' | tail -100
  
  # 查看失败的索引操作
  cat logs/indexer.log | jq 'select(.operation == "request_complete" and .failed_count > 0)'
  
  # 查看特定SPU的处理日志
  cat logs/indexer.log | jq 'select(.spu_id == "123")'
  
  # 查看最近的索引请求统计
  cat logs/indexer.log | jq 'select(.operation == "request_complete") | {timestamp, index_type, tenant_id, total_count, success_count, failed_count, elapsed_time}'
  ```
  
  ### 5.3 增量索引接口
  
  - **端点**: `POST /indexer/index`
  - **描述**: 增量索引接口，根据指定的SPU ID列表进行索引，直接将数据写入ES。用于增量更新指定商品。**推荐仅作为内部/调试入口**；正式对接建议改用 `/indexer/build-docs`，由上游写 ES。
  
  **删除说明**：
  - `spu_ids`中的SPU：如果数据库`deleted=1`，自动从ES删除，响应状态为`deleted`
  - `delete_spu_ids`中的SPU：直接删除，响应状态为`deleted`、`not_found`或`failed`
  
  #### 请求参数
  
  ```json
  {
    "tenant_id": "162",
    "spu_ids": ["123", "456", "789"],
    "delete_spu_ids": ["100", "101"]
  }
  ```
  
  | 参数 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `tenant_id` | string | Y | 租户ID |
  | `spu_ids` | array[string] | N | SPU ID列表（1-100个），要索引的SPU。如果为空，则只执行删除操作 |
  | `delete_spu_ids` | array[string] | N | 显式指定要删除的SPU ID列表（1-100个），可选。无论数据库状态如何，都会从ES中删除这些SPU |
  
  **注意**：
  - `spu_ids` 和 `delete_spu_ids` 不能同时为空
  - 每个列表最多支持100个SPU ID
  - 如果SPU在`spu_ids`中且数据库`deleted=1`，会自动从ES删除（自动检测删除）
  
  #### 响应格式
  
  ```json
  {
    "spu_ids": [
      {
        "spu_id": "123",
        "status": "indexed"
      },
      {
        "spu_id": "456",
        "status": "deleted"
      },
      {
        "spu_id": "789",
        "status": "failed",
        "msg": "SPU not found (unexpected)"
      }
    ],
    "delete_spu_ids": [
      {
        "spu_id": "100",
        "status": "deleted"
      },
      {
        "spu_id": "101",
        "status": "not_found"
      },
      {
        "spu_id": "102",
        "status": "failed",
        "msg": "Failed to delete from ES: Connection timeout"
      }
    ],
    "total": 6,
    "success_count": 4,
    "failed_count": 2,
    "elapsed_time": 1.23,
    "index_name": "search_products",
    "tenant_id": "162"
  }
  ```
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `spu_ids` | array | spu_ids对应的响应列表，每个元素包含 `spu_id` 和 `status` |
  | `spu_ids[].status` | string | 状态：`indexed`（已索引）、`deleted`（已删除，自动检测）、`failed`（失败） |
  | `spu_ids[].msg` | string | 当status为`failed`时，包含失败原因（可选） |
  | `delete_spu_ids` | array | delete_spu_ids对应的响应列表，每个元素包含 `spu_id` 和 `status` |
  | `delete_spu_ids[].status` | string | 状态：`deleted`（已删除）、`not_found`（ES中不存在）、`failed`（失败） |
  | `delete_spu_ids[].msg` | string | 当status为`failed`时，包含失败原因（可选） |
  | `total` | integer | 总处理数量（spu_ids数量 + delete_spu_ids数量） |
  | `success_count` | integer | 成功数量（indexed + deleted + not_found） |
  | `failed_count` | integer | 失败数量 |
  | `elapsed_time` | float | 耗时（秒） |
  | `index_name` | string | 索引名称 |
  | `tenant_id` | string | 租户ID |
  
  **状态说明**：
  - `spu_ids` 的状态：
    - `indexed`: SPU已成功索引到ES
    - `deleted`: SPU在数据库中被标记为deleted=1，已从ES删除（自动检测）
    - `failed`: 处理失败，会包含`msg`字段说明失败原因
  - `delete_spu_ids` 的状态：
    - `deleted`: SPU已从ES成功删除
    - `not_found`: SPU在ES中不存在（也算成功，可能已经被删除过）
    - `failed`: 删除失败，会包含`msg`字段说明失败原因
  
  #### 请求示例
  
  **示例1：普通增量索引（自动检测删除）**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/index" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": ["123", "456", "789"]
    }'
  ```
  
  说明：如果SPU 456在数据库中`deleted=1`，会自动从ES删除，在响应中`spu_ids`列表里456的状态为`deleted`。
  
  **示例2：显式删除（批量删除）**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/index" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": ["123", "456"],
      "delete_spu_ids": ["100", "101", "102"]
    }'
  ```
  
  说明：SPU 100、101、102会被显式删除，无论数据库状态如何。
  
  **示例3：仅删除（不索引）**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/index" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": [],
      "delete_spu_ids": ["100", "101"]
    }'
  ```
  
  说明：只执行删除操作，不进行索引。
  
  **示例4：混合操作（索引+删除）**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/index" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": ["123", "456", "789"],
      "delete_spu_ids": ["100", "101"]
    }'
  ```
  
  说明：同时执行索引和删除操作。
  
  #### 日志说明
  
  增量索引操作的所有关键信息都会记录到 `logs/indexer.log` 文件中（JSON格式），包括：
  - 请求开始和结束时间
  - 每个SPU的处理状态（获取、转换、索引、删除）
  - ES批量写入结果
  - 成功/失败统计
  - 详细的错误信息
  
  日志查询方式请参考[5.1节查看索引日志](#51-全量重建索引接口)部分。
  
  ### 5.4 查询文档接口
  
  - **端点**: `POST /indexer/documents`
  - **描述**: 查询文档接口，根据SPU ID列表获取ES文档数据（**不写入ES**）。用于查看、调试或验证SPU数据。
  
  #### 请求参数
  
  ```json
  {
    "tenant_id": "162",
    "spu_ids": ["123", "456", "789"]
  }
  ```
  
  | 参数 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `tenant_id` | string | Y | 租户ID |
  | `spu_ids` | array[string] | Y | SPU ID列表（1-100个） |
  
  #### 响应格式
  
  ```json
  {
    "success": [
      {
        "spu_id": "123",
        "document": {
          "tenant_id": "162",
          "spu_id": "123",
          "title": {
            "zh": "商品标题"
          },
          ...
        }
      },
      {
        "spu_id": "456",
        "document": {...}
      }
    ],
    "failed": [
      {
        "spu_id": "789",
        "error": "SPU not found or deleted"
      }
    ],
    "total": 3,
    "success_count": 2,
    "failed_count": 1
  }
  ```
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `success` | array | 成功获取的SPU列表，每个元素包含 `spu_id` 和 `document`（完整的ES文档数据） |
  | `failed` | array | 失败的SPU列表，每个元素包含 `spu_id` 和 `error`（失败原因） |
  | `total` | integer | 总SPU数量 |
  | `success_count` | integer | 成功数量 |
  | `failed_count` | integer | 失败数量 |
  
  #### 请求示例
  
  **单个SPU查询**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/documents" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": ["123"]
    }'
  ```
  
  **批量SPU查询**:
  
  ```bash
  curl -X POST "http://localhost:6004/indexer/documents" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "162",
      "spu_ids": ["123", "456", "789"]
    }'
  ```
  
  #### 与 `/indexer/index` 的区别
  
  | 接口 | 功能 | 是否写入ES | 返回内容 |
  |------|------|-----------|----------|
  | `/indexer/documents` | 查询SPU文档数据 | 否 | 返回完整的ES文档数据 |
  | `/indexer/index` | 增量索引 | 是 | 返回成功/失败列表和统计信息 |
  
  **使用场景**：
  - `/indexer/documents`：用于查看、调试或验证SPU数据，不修改ES索引
  - `/indexer/index`：用于实际的增量索引操作，将更新的SPU数据同步到ES
  
  ### 5.5 索引健康检查接口
  
  - **端点**: `GET /indexer/health`
  - **描述**: 检查索引服务健康状态（与 `api/routes/indexer.py` 中 `indexer_health_check` 一致）
  
  #### 响应格式
  
  ```json
  {
    "status": "available",
    "database": "connected",
    "preloaded_data": {
      "category_mappings": 150
    }
  }
  ```
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `status` | string | `available`（服务可用）、`unavailable`（未初始化）、`error`（异常） |
  | `database` | string | 数据库连接状态，如 `connected` 或 `disconnected: ...` |
  | `preloaded_data.category_mappings` | integer | 已加载的分类映射数量 |
  
  #### 请求示例
  
  ```bash
  curl -X GET "http://localhost:6004/indexer/health"
  ```
  
  ### 5.6 文档构建接口（正式对接推荐）
  
  #### 5.6.1 `POST /indexer/build-docs`
  
  - **描述**:  
    基于调用方（通常是 Java 索引程序）提供的 **MySQL 行数据** 构建 ES 文档（doc），**不写入 ES**。  
    由本服务负责“如何构建 doc”（多语言、翻译、向量、规格聚合等），由调用方负责“何时调度 + 如何写 ES”。
  
  #### 请求参数
  
  ```json
  {
    "tenant_id": "170",
    "items": [
      {
        "spu": { "id": 223167, "tenant_id": 170, "title": "..." },
        "skus": [
          { "id": 3988393, "spu_id": 223167, "price": 25.99, "compare_at_price": 25.99 }
        ],
        "options": []
      }
    ]
  }
  ```
  
  | 参数 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `tenant_id` | string | Y | 租户 ID |
  | `items` | array | Y | 需构建 doc 的 SPU 列表（每项含 `spu`、`skus`、`options`），**单次最多 200 条** |
  
  > `spu` / `skus` / `options` 字段应当直接使用从 `shoplazza_product_spu` / `shoplazza_product_sku` / `shoplazza_product_option` 查询出的行字段。
  
  #### 请求示例（完整 curl）
3abbc95a   tangwang   重构(scripts): 整理sc... 
500
 
  > 完整请求体参考 `tests/manual/test_build_docs_api.py` 中的 `build_sample_request()`。
0342d897   tangwang   搜索API对接指南 拆分 
501
502
503
504
505
506
507
508
509
510
511
 
  
  ```bash
  # 单条 SPU 示例（含 spu、skus、options）
  curl -X POST "http://localhost:6004/indexer/build-docs" \
    -H "Content-Type: application/json" \
    -d '{
    "tenant_id": "162",
    "items": [
      {
        "spu": {
          "id": 10001,
0342d897   tangwang   搜索API对接指南 拆分 
512
513
514
515
516
517
518
519
520
521
 
          "title": "测试T恤 纯棉短袖",
          "brief": "舒适纯棉，多色可选",
          "description": "这是一款适合日常穿着的纯棉T恤，透气吸汗。",
          "vendor": "测试品牌",
          "category": "服装/上衣/T恤",
          "category_id": 100,
          "category_level": 2,
          "category_path": "服装/上衣/T恤",
          "fake_sales": 1280,
          "image_src": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg",
d350861f   tangwang   索引结构修改 
522
 
          "enriched_tags": ["T恤", "纯棉"],
0342d897   tangwang   搜索API对接指南 拆分 
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
 
          "create_time": "2024-01-01T00:00:00Z",
          "update_time": "2024-01-01T00:00:00Z"
        },
        "skus": [
          {
            "id": 20001,
            "spu_id": 10001,
            "price": 99.0,
            "compare_at_price": 129.0,
            "sku": "SKU-TSHIRT-001",
            "inventory_quantity": 50,
            "option1": "黑色",
            "option2": "M",
            "option3": null
          },
          {
            "id": 20002,
            "spu_id": 10001,
            "price": 99.0,
            "compare_at_price": 129.0,
            "sku": "SKU-TSHIRT-002",
            "inventory_quantity": 30,
            "option1": "白色",
            "option2": "L",
            "option3": null
          }
        ],
        "options": [
          {"id": 1, "position": 1, "name": "颜色"},
          {"id": 2, "position": 2, "name": "尺码"}
        ]
      }
    ]
  }'
  ```
  
  生产环境替换 `localhost:6004` 为实际 Indexer 地址，如 `http://43.166.252.75:6004`。
  
  #### 响应示例（节选）
  
  ```json
  {
    "tenant_id": "170",
    "docs": [
      {
        "tenant_id": "170",
        "spu_id": "223167",
        "title": { "en": "...", "zh": "..." },
d350861f   tangwang   索引结构修改 
571
 
        "enriched_tags": ["Floerns", "Clothing", "Shoes & Jewelry"],
0342d897   tangwang   搜索API对接指南 拆分 
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
 
        "skus": [
          {
            "sku_id": "3988393",
            "price": 25.99,
            "compare_at_price": 25.99,
            "stock": 100
          }
        ],
        "min_price": 25.99,
        "max_price": 25.99,
        "compare_at_price": 25.99,
        "total_inventory": 100,
        "title_embedding": [/* 1024 维向量 */]
        // 其余字段与 mappings/search_products.json 一致
      }
    ],
    "total": 1,
    "success_count": 1,
    "failed_count": 0,
    "failed": []
  }
  ```
  
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `tenant_id` | string | 租户 ID |
  | `docs` | array | 构建成功的 ES 文档列表，与 `mappings/search_products.json` 一致 |
  | `total` | integer | 请求的 items 总数 |
  | `success_count` | integer | 成功构建数量 |
  | `failed_count` | integer | 失败数量 |
  | `failed` | array | 失败项列表，每项含 `spu_id`、`error` |
  
  #### 使用建议
  
  - **生产环境推荐流程**：
    1. Java 根据业务逻辑决定哪些 SPU 需要（全量/增量）处理；
    2. Java 从 MySQL 查询 SPU/SKU/Option 行，拼成 `items`；
    3. 调用 `/indexer/build-docs` 获取 ES-ready `docs`；
    4. Java 使用自己的 ES 客户端写入 `search_products_tenant_{tenant_id}`。
  
  ### 5.7 文档构建接口（测试 / 自测）
  
  #### 5.7.1 `POST /indexer/build-docs-from-db`
  
  - **描述**:  
    仅用于测试/调试：调用方只提供 `tenant_id` 和 `spu_ids`，由 indexer 服务内部从 MySQL 查询 SPU/SKU/Option，然后调用与 `/indexer/build-docs` 相同的文档构建逻辑，返回 ES-ready doc。**生产环境请使用 `/indexer/build-docs`，由上游查库并写 ES。**
  
  #### 请求参数
  
  ```json
  {
    "tenant_id": "170",
    "spu_ids": ["223167", "223168"]
  }
  ```
  
  | 参数 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `tenant_id` | string | Y | 租户 ID |
  | `spu_ids` | array[string] | Y | SPU ID 列表，**单次最多 200 个** |
  
  #### 响应格式
  
  与 `/indexer/build-docs` 相同：`tenant_id`、`docs`、`total`、`success_count`、`failed_count`、`failed`。
  
  #### 请求示例
  
  ```bash
  curl -X POST "http://127.0.0.1:6004/indexer/build-docs-from-db" \
    -H "Content-Type: application/json" \
    -d '{"tenant_id": "170", "spu_ids": ["223167"]}'
  ```
  
  返回结构与 `/indexer/build-docs` 相同，可直接用于对比 ES 实际文档或调试字段映射问题。
a3275468   tangwang   已把本仓库里的 `/indexer... 
647
 
  ### 5.8 内容理解字段生成能力（已迁出）
dabd52a5   tangwang   feat(indexer): 支持... 
648
a3275468   tangwang   已把本仓库里的 `/indexer... 
649
 
  `/indexer/enrich-content` 已迁移到独立项目，本仓库当前的 Indexer 服务（默认端口 `6004`）**不再暴露该接口**，也**不再在** `/indexer/build-docs`、`/indexer/build-docs-from-db`、`/indexer/reindex`、`/indexer/index` 的构建链路里内置生成 `qanchors`、`enriched_attributes`、`enriched_tags`、`enriched_taxonomy_attributes`。
0342d897   tangwang   搜索API对接指南 拆分 
650
a3275468   tangwang   已把本仓库里的 `/indexer... 
651
 
  当前建议的对接方式：
0342d897   tangwang   搜索API对接指南 拆分 
652
a3275468   tangwang   已把本仓库里的 `/indexer... 
653
654
655
 
  1. 调用本仓库的 `POST /indexer/build-docs` 或 `POST /indexer/build-docs-from-db` 生成基础 ES 文档。
  2. 调用独立内容理解服务生成 `qanchors` / `enriched_*` 字段。
  3. 由上游索引程序自行合并字段后写入 ES。
d350861f   tangwang   索引结构修改 
656
a3275468   tangwang   已把本仓库里的 `/indexer... 
657
 
  补充说明：
d350861f   tangwang   索引结构修改 
658
a3275468   tangwang   已把本仓库里的 `/indexer... 
659
660
661
 
  - `search_products` mapping 仍保留上述字段，便于独立内容理解服务继续产出并写入。
  - `suggestion` 等消费侧仍可读取 ES 中已有的 `qanchors` 字段；迁移的是“生成实现”，不是字段模型本身。
  - 本文档不再维护独立内容理解服务的请求/响应细节，请以对应独立项目的文档为准。
0342d897   tangwang   搜索API对接指南 拆分 
662
663
 
  
  ---