SKU image_src 字段为空问题诊断报告

问题描述

返回结果的每条结果中，多款式字段 skus 下面每个 SKU 的 image_src 为空。

问题分析

1. ES 数据检查

通过查询 ES 数据，发现：

• ES 中确实有 skus 数据（不是空数组）
• 但是 skus 数组中的每个 SKU 对象都没有 image_src 字段

示例 ES 文档：

{
  "spu_id": "68238",
  "skus": [
    {
      "sku_id": "3568395",
      "price": 329.61,
      "compare_at_price": 485.65,
      "sku_code": "3468269",
      "stock": 57,
      "weight": 0.26,
      "weight_unit": "kg",
      "option1_value": "",
      "option2_value": "",
      "option3_value": ""
      // 注意：这里没有 image_src 字段
    }
  ]
}

2. 代码逻辑检查

在 indexer/document_transformer.py 的 _transform_sku_row 方法中（第558-560行），原有逻辑为：

# Image src
if pd.notna(sku_row.get('image_src')):
    sku_data['image_src'] = str(sku_row['image_src'])

问题根源：

• 只有当 MySQL 中的 image_src 字段非空时，才会将其添加到 sku_data 字典中
• 如果 MySQL 中的 image_src 是 NULL 或空字符串，这个字段就不会出现在返回的字典中
• 导致 ES 文档中缺少 image_src 字段
• API 返回时，sku_entry.get('image_src') 返回 None，前端看到的就是空值

3. MySQL 数据情况

根据代码逻辑推断：

• MySQL 的 shoplazza_product_sku 表中，image_src 字段可能为 NULL 或空字符串
• 这导致索引时该字段没有被写入 ES

解决方案

修复方案

修改 indexer/document_transformer.py 中的 _transform_sku_row 方法，始终包含 image_src 字段，即使值为空也设置为 None：

# Image src - always include this field, even if empty
# This ensures the field is present in ES documents and API responses
image_src = sku_row.get('image_src')
if pd.notna(image_src) and str(image_src).strip():
    sku_data['image_src'] = str(image_src).strip()
else:
    # Set to None (will be serialized as null in JSON) instead of omitting the field
    sku_data['image_src'] = None

修复效果

修复后：

1. 即使 MySQL 中 image_src 为 NULL 或空字符串，ES 文档中也会包含该字段（值为 null）
2. API 返回时，前端可以明确知道该字段存在但值为空
3. 符合 API 模型定义：image_src: Optional[str] = Field(None, ...)

问题分类

问题类型：本项目填充的问题

• ✅ 不是 MySQL 原始数据的问题：MySQL 中 image_src 字段可能确实为 NULL，但这是正常的业务数据
• ✅ 不是 ES 数据的问题：ES mapping 中 image_src 字段定义正确
• ❌ 是本项目填充的问题：代码逻辑导致当 MySQL 中 image_src 为空时，该字段没有被写入 ES 文档

后续操作

1. 重新索引数据：修复代码后，需要重新索引数据才能生效

   # 重新索引指定租户的数据
   ./scripts/ingest.sh <tenant_id> true
   

2. 验证修复：重新索引后，查询 ES 验证 image_src 字段是否已包含：

   curl -u 'essa:4hOaLaf41y2VuI8y' -X GET 'http://localhost:9200/search_products/_search?pretty' \
    -H 'Content-Type: application/json' \
    -d '{
      "size": 1,
      "query": {"nested": {"path": "skus", "query": {"exists": {"field": "skus"}}}},
      "_source": ["spu_id", "skus"]
    }'
   

3. 可选优化：如果业务需要，可以考虑当 SKU 的 image_src 为空时，使用 SPU 的主图（image_url）作为默认值

相关文件

• indexer/document_transformer.py - 已修复
• api/models.py - SkuResult.image_src: Optional[str] - 模型定义正确
• api/result_formatter.py - image_src=sku_entry.get('image_src') - 读取逻辑正确
• mappings/search_products.json - skus.image_src mapping 定义正确