tangwang · tangwang · tangwang
Showing 24 changed files Show diff stats
.cursor/plans/api-interface-analysis-42918612.plan.0.md
.cursor/plans/api-interface-analysis-42918612.plan.1.md
.cursor/plans/api-interface-analysis-42918612.plan.2.md
.cursor/plans/api-interface-analysis-42918612.plan.3.最终执行.md
ARCHITECTURE_REFACTOR.md
OPTION_VALUES_FEATURE.md
REFACTOR_SUMMARY.md
activate.sh
api/models.py
customer1_data.sql
database-config-analysis.md
docs/常用查询 - sql.sql
docs/店匠相关资料/SHOPLAZZA_INTEGRATION_GUIDE.md
docs/店匠相关资料/店匠官方参考文档.md
docs/搜索API对接指南.md
docs/竞品参考文档/prefixbox_api.md
docs/系统设计文档.md
docs/索引字段说明v2-参考表结构.md
docs/索引字段说明v2.md
frontend/index.html
@@ -632,7 +632,7 @@ def _standardize_facets(
         # 构建标准化分面结果
         facet = {
             "field": field,
-            "label": self._get_field_label(field),  # 从配置获取
+            "label": field,  # 从配置获取
             "type": facet_type,
             "values": []
         }
@@ -632,7 +632,7 @@ def _standardize_facets(
         # 构建标准化分面结果
         facet = {
             "field": field,
-            "label": self._get_field_label(field),  # 从配置获取
+            "label": field,  # 从配置获取
             "type": facet_type,
             "values": []
         }
@@ -632,7 +632,7 @@ def _standardize_facets(
         # 构建标准化分面结果
         facet = {
             "field": field,
-            "label": self._get_field_label(field),  # 从配置获取
+            "label": field,  # 从配置获取
             "type": facet_type,
             "values": []
         }
@@ -632,7 +632,7 @@ def _standardize_facets(
         # 构建标准化分面结果
         facet = {
             "field": field,
-            "label": self._get_field_label(field),
+            "label": field,
             "type": facet_type,
             "values": []
         }
@@ -0,0 +1,12 @@
+#!/bin/bash
+source /home/tw/miniconda3/etc/profile.d/conda.sh
+conda activate searchengine
+
+# 如果需要加载 .env 中的环境变量
+if [ -f .env ]; then
+    set -a  # 自动导出所有变量
+    source <(grep -v '^#' .env | grep -v '^$' | sed 's/#.*$//' | sed 's/\r$//')
+    set +a  # 关闭自动导出
+fi
+
+echo "Environment activated: searchengine"
@@ -67,7 +67,7 @@ class SearchRequest(BaseModel):
     # 基础搜索参数
     query: str = Field(..., description="搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT）")
-    size: int = Field(10, ge=1, le=100, description="返回结果数量")
+    size: int = Field(10, ge=1, le=1000, description="返回结果数量")
     from_: int = Field(0, ge=0, alias="from", description="分页偏移量")
     language: Literal["zh", "en"] = Field(
         "zh",
@@ -110,31 +110,34 @@ class SearchRequest(BaseModel):
     )
     # 排序
-    sort_by: Optional[str] = Field(None, description="排序字段名（如 'min_price', 'max_price', 'title'）")
-    sort_order: Optional[str] = Field("desc", description="排序方向: 'asc'（升序）或 'desc'（降序）")
+    sort_by: Optional[str] = Field(None, description="排序字段名。支持：'price'（价格，自动根据sort_order选择min_price或max_price）、'sales'（销量）、'create_time'（创建时间）、'update_time'（更新时间）")
+    sort_order: Optional[str] = Field("desc", description="排序方向: 'asc'（升序）或 'desc'（降序）。注意：price+asc=价格从低到高，price+desc=价格从高到低")
-    # 分面搜索 - 简化接口
-    facets: Optional[List[Union[str, FacetConfig]]] = Field(
+    # 分面搜索
+    facets: Optional[List[FacetConfig]] = Field(
         None,
-        description="分面配置。可以是字段名列表（使用默认配置）或详细的分面配置对象。支持 specifications 分面：\"specifications\"（所有name）或 \"specifications.color\"（指定name）",
+        description="分面配置对象列表。支持 specifications 分面：field=\"specifications\"（所有规格名称）或 field=\"specifications.color\"（指定规格名称）",
         json_schema_extra={
             "examples": [
-                # 简单模式：只指定字段名，使用默认配置
-                ["category1_name", "category2_name", "specifications"],
-                # 指定specifications的某个name
-                ["specifications.颜色", "specifications.尺寸"],
-                # 高级模式：详细配置
                 [
-                    {"field": "category1_name", "size": 15},
+                    {"field": "category1_name", "size": 15, "type": "terms"},
+                    {"field": "category2_name", "size": 10, "type": "terms"},
+                    {"field": "specifications.color", "size": 20, "type": "terms"},
+                    {"field": "specifications.size", "size": 15, "type": "terms"}
+                ],
+                [
+                    {"field": "category1_name", "size": 15, "type": "terms"},
                     {
                         "field": "min_price",
                         "type": "range",
                         "ranges": [
                             {"key": "0-50", "to": 50},
-                            {"key": "50-100", "from": 50, "to": 100}
+                            {"key": "50-100", "from": 50, "to": 100},
+                            {"key": "100-200", "from": 100, "to": 200},
+                            {"key": "200+", "from": 200}
                         ]
                     },
-                    "specifications"  # 所有specifications name的分面
+                    {"field": "specifications", "size": 10, "type": "terms"}
                 ]
             ]
         }
@@ -361,4 +361,191 @@ SELECT
 FROM shoplazza_product_option
 WHERE tenant_id = 162 AND deleted = 0
 GROUP BY position, name
-ORDER BY position, spu_count DESC;
 \ No newline at end of file
+ORDER BY position, spu_count DESC;
+
+
+
+-- ======================================
+-- 10. SPU原始数据完整查询
+-- ======================================
+
+-- 10.1 查询SPU表所有字段的原始数据
+-- 用于全面检查数据质量
+SELECT 
+    id,
+    shop_id,
+    shoplazza_id,
+    handle,
+    title,
+    brief,
+    description,
+    spu,
+    vendor,
+    vendor_url,
+    seo_title,
+    seo_description,
+    seo_keywords,
+    image_src,
+    image_width,
+    image_height,
+    image_path,
+    image_alt,
+    inventory_policy,
+    inventory_quantity,
+    inventory_tracking,
+    published,
+    published_at,
+    requires_shipping,
+    taxable,
+    fake_sales,
+    display_fake_sales,
+    mixed_wholesale,
+    need_variant_image,
+    has_only_default_variant,
+    tags,
+    note,
+    category,
+    category_id,
+    category_google_id,
+    category_level,
+    category_path,
+    shoplazza_created_at,
+    shoplazza_updated_at,
+    tenant_id,
+    creator,
+    create_time,
+    updater,
+    update_time,
+    deleted
+FROM shoplazza_product_spu
+WHERE tenant_id = 162 
+  AND deleted = 0
+ORDER BY id DESC
+LIMIT 10;
+
+-- 10.2 查询指定SPU的完整关联数据
+-- 包含SPU、SKU、Option的完整信息
+SELECT 
+    '=== SPU基本信息 ===' AS section,
+    spu.id AS spu_id,
+    spu.title,
+    spu.category,
+    spu.category_path,
+    spu.category_id,
+    spu.category_level,
+    spu.vendor,
+    spu.tags,
+    NULL AS sku_id,
+    NULL AS option1,
+    NULL AS option2,
+    NULL AS option3,
+    NULL AS opt_position,
+    NULL AS opt_name
+FROM shoplazza_product_spu spu
+WHERE spu.id = 64001  -- 替换为实际的spu_id
+  AND spu.deleted = 0
+
+UNION ALL
+
+SELECT 
+    '=== SKU信息 ===' AS section,
+    sku.spu_id,
+    NULL AS title,
+    NULL AS category,
+    NULL AS category_path,
+    NULL AS category_id,
+    NULL AS category_level,
+    NULL AS vendor,
+    NULL AS tags,
+    sku.id AS sku_id,
+    sku.option1,
+    sku.option2,
+    sku.option3,
+    NULL AS opt_position,
+    NULL AS opt_name
+FROM shoplazza_product_sku sku
+WHERE sku.spu_id = 64001  -- 替换为实际的spu_id
+  AND sku.deleted = 0
+
+UNION ALL
+
+SELECT 
+    '=== Option定义 ===' AS section,
+    opt.spu_id,
+    NULL AS title,
+    NULL AS category,
+    NULL AS category_path,
+    NULL AS category_id,
+    NULL AS category_level,
+    NULL AS vendor,
+    NULL AS tags,
+    NULL AS sku_id,
+    NULL AS option1,
+    NULL AS option2,
+    NULL AS option3,
+    opt.position AS opt_position,
+    opt.name AS opt_name
+FROM shoplazza_product_option opt
+WHERE opt.spu_id = 64001  -- 替换为实际的spu_id
+  AND opt.deleted = 0;
+
+-- 10.3 导出SPU数据用于分析（简化版）
+-- 适合导出到Excel进行分析
+SELECT 
+    id AS 'SPU_ID',
+    tenant_id AS '租户ID',
+    title AS '商品标题',
+    category AS '类目字段',
+    category_path AS '类目路径',
+    category_id AS '类目ID',
+    category_level AS '类目层级',
+    vendor AS '品牌',
+    tags AS '标签',
+    published AS '是否发布',
+    published_at AS '发布时间',
+    create_time AS '创建时间',
+    update_time AS '更新时间',
+    CASE 
+        WHEN category REGEXP '^[0-9]+$' THEN 'YES-需要修复'
+        ELSE 'NO-正常'
+    END AS 'Category是数字ID'
+FROM shoplazza_product_spu
+WHERE tenant_id = 162 
+  AND deleted = 0
+ORDER BY id DESC
+LIMIT 100;
+
+-- ======================================
+-- 11. 租户数据概览
+-- ======================================
+
+-- 11.1 所有租户的数据统计
+SELECT 
+    tenant_id,
+    COUNT(*) AS total_spu,
+    SUM(CASE WHEN category IS NOT NULL THEN 1 ELSE 0 END) AS has_category,
+    SUM(CASE WHEN category_path IS NOT NULL THEN 1 ELSE 0 END) AS has_category_path,
+    SUM(CASE WHEN category REGEXP '^[0-9]+$' THEN 1 ELSE 0 END) AS category_is_numeric,
+    MIN(create_time) AS earliest_data,
+    MAX(create_time) AS latest_data
+FROM shoplazza_product_spu
+WHERE deleted = 0
+GROUP BY tenant_id
+ORDER BY tenant_id;
+
+-- 11.2 查询某个租户的所有SPU（分页查看）
+-- 用于逐条检查数据
+SELECT 
+    id,
+    title,
+    category,
+    category_path,
+    vendor,
+    tags,
+    create_time
+FROM shoplazza_product_spu
+WHERE tenant_id = 162 
+  AND deleted = 0
+ORDER BY id
+LIMIT 50 OFFSET 0;  -- 修改OFFSET查看不同页
+
@@ -3111,18 +3111,6 @@ search:
     url: http://localhost:6002
     timeout: 30000
-# 向量服务配置
-embedding:
-  service:
-    url: http://localhost:6003
-    timeout: 60000
-
-# Elasticsearch 配置
-elasticsearch:
-  hosts: localhost:9200
-  username: elastic
-  password: changeme
-
 # 数据同步配置
 sync:
   enabled: true
@@ -3133,67 +3121,6 @@ sync:
     tenants: "0 0 4 * * ?"    # 每天凌晨4点
 ```
-### 12.4 故障排查
-
-#### 12.4.1 OAuth 认证失败
-
-**问题：** 授权回调时报错 "Invalid redirect_uri"
-
-**解决：**
-1. 检查 Partner 后台配置的 Redirect URI 是否与代码中一致
-2. 确保 Redirect URI 使用 HTTPS 协议
-3. 确保 Redirect URI 可公网访问
-
-#### 12.4.2 Token 过期
-
-**问题：** API 调用返回 401 Unauthorized
-
-**解决：**
-1. 检查数据库中的 `token_expires_at` 字段
-2. 使用 Refresh Token 刷新 Access Token
-3. 更新数据库中的 Token 信息
-
-#### 12.4.3 API 调用速率限制
-
-**问题：** API 返回 429 Too Many Requests
-
-**解决：**
-1. 降低请求频率
-2. 实现指数退避重试
-3. 解析响应头中的 `X-RateLimit-Reset` 字段，等待到指定时间后再重试
-
-#### 12.4.4 Webhook 接收失败
-
-**问题：** Webhook 事件未收到或签名验证失败
-
-**解决：**
-1. 检查 Webhook 地址是否可公网访问
-2. 检查签名验证逻辑是否正确使用 Client Secret
-3. 查看店匠后台的 Webhook 日志，确认发送状态
-4. 确保 Webhook 处理在 3 秒内返回 200 响应
-
-#### 12.4.5 商品搜索无结果
-
-**问题：** 搜索返回空结果
-
-**解决：**
-1. 检查 ES 索引是否存在：`GET /shoplazza_products_1/_count`
-2. 检查商品是否已索引：`GET /shoplazza_products_1/_search`
-3. 检查租户隔离参数是否正确
-4. 查看搜索服务日志，确认查询语句
-
-#### 12.4.6 向量生成失败
-
-**问题：** 图片或文本向量生成失败
-
-**解决：**
-1. 检查向量服务是否正常运行
-2. 检查向量服务的 GPU/CPU 资源是否充足
-3. 检查图片 URL 是否可访问
-4. 查看向量服务日志
-
----
-
 ## 13. 参考资料
 ### 13.1 官方文档
@@ -7,6 +7,19 @@
 店匠API文档： https://www.shoplazza.dev/reference/overview-23； 
 店匠应用市场： https://appstore.shoplazza.com/
+通过主题装修集成的话，我们有相关的cli 和 主题扩展
+https://www.shoplazza.dev/v2025.06/docs/app-command-usage-guide
+主题扩展的相关文档
+https://www.shoplazza.dev/v2025.06/docs/theme-extension-2
+
+[Quick Construction of Public Apps](https://www.shoplazza.dev/reference/quick-construction-of-public-apps)
+[1.Create a developer platform login account and register as a partner](https://www.shoplazza.dev/reference/1create-a-developer-platform-login-account-and-register-as-a-partner)
+[2.Create A Public APP](https://www.shoplazza.dev/reference/2create-a-public-app)
+[3.Develop your application service](https://www.shoplazza.dev/reference/3develop-your-application-service)
+[4.Test your app](https://www.shoplazza.dev/reference/4test-your-app)
+[5.Submit App for review](https://www.shoplazza.dev/reference/5submit-app-for-review)
+[Quick Construction of Private Apps](https://www.shoplazza.dev/reference/quick-construction-of-private-apps)
+
 ### 13.2 技术栈文档
@@ -50,7 +50,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
       "gte": "2020-01-01T00:00:00Z" 
     }
   },
-    "sort_by": "min_price",
+    "sort_by": "price",
     "sort_order": "asc"
   }'
 ```
@@ -63,7 +63,11 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   -H "X-Tenant-ID: 162" \
   -d '{
     "query": "芭比娃娃",
-    "facets": ["category1_name", "specifications.color", "specifications.size", "specifications.material"],
+    "facets": [
+      {"field": "category1_name", "size": 10, "type": "terms"},
+      {"field": "specifications.color", "size": 10, "type": "terms"},
+      {"field": "specifications.size", "size": 10, "type": "terms"}
+    ],
     "min_score": 0.2
   }'
 ```
@@ -124,8 +128,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 | `filters` | object | N | null | 精确匹配过滤器（见下文） |
 | `range_filters` | object | N | null | 数值范围过滤器（见下文） |
 | `facets` | array | N | null | 分面配置（见下文） |
-| `sort_by` | string | N | null | 排序字段名（如 `min_price`, `max_price`） |
-| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序） |
+| `sort_by` | string | N | null | 排序字段名。支持：`price`（价格）、`sales`（销量）、`create_time`（创建时间）、`update_time`（更新时间）。默认按相关性排序 |
+| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序）。注意：`price`+`asc`=价格从低到高，`price`+`desc`=价格从高到低（后端自动映射为min_price或max_price） |
 | `min_score` | float | N | null | 最小相关性分数阈值 |
 | `sku_filter_dimension` | array[string] | N | null | 子SKU筛选维度列表（店铺配置）。指定后，每个SPU下的SKU将按这些维度的组合进行分组，每个组合只返回第一个SKU。支持的值：`option1`、`option2`、`option3` 或选项名称（如 `color`、`size`）。详见下文说明 |
 | `debug` | boolean | N | false | 是否返回调试信息 |
@@ -263,14 +267,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 用于生成分面统计（分组聚合），常用于构建筛选器UI。
-**简单模式**（字符串数组）:
-```json
-{
-  "facets": ["category1_name", "category2_name", "category3_name", "specifications"]
-}
-```
+**配置格式**（对象数组）:
-**高级模式**（配置对象数组）:
 ```json
 {
   "facets": [
@@ -280,6 +278,16 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
       "type": "terms"
     },
     {
+      "field": "category2_name",
+      "size": 10,
+      "type": "terms"
+    },
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms"
+    },
+    {
       "field": "min_price",
       "type": "range",
       "ranges": [
@@ -288,8 +296,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
         {"key": "100-200", "from": 100, "to": 200},
         {"key": "200+", "from": 200}
       ]
-    },
-    "specifications"  // 规格分面（特殊处理：嵌套聚合，按name分组，然后按value聚合）
+    }
   ]
 }
 ```
@@ -298,18 +305,35 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 `specifications` 是嵌套字段，支持两种分面模式：
-**模式1：所有规格名称的分面** (`"specifications"`):
+**模式1：所有规格名称的分面**:
 ```json
 {
-  "facets": ["specifications"]
+  "facets": [
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
+  ]
 }
 ```
 返回所有规格名称（name）及其对应的值（value）列表。每个 name 会生成一个独立的分面结果。
-**模式2：指定规格名称的分面** (`"specifications.color"`):
+**模式2：指定规格名称的分面**:
 ```json
 {
-  "facets": ["specifications.color", "specifications.size", "specifications.material"]
+  "facets": [
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms"
+    },
+    {
+      "field": "specifications.size",
+      "size": 15,
+      "type": "terms"
+    }
+  ]
 }
 ```
 只返回指定规格名称的值列表。格式：`specifications.{name}`，其中 `{name}` 是规格名称（如"color"、"size"、"material"）。
@@ -564,6 +588,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 | `sku_weights` | array[integer] | 所有SKU重量列表 |
 | `sku_weight_units` | array[string] | 所有SKU重量单位列表 |
 | `total_inventory` | integer | 总库存 |
+| `sales` | integer | 销量（展示销量） |
 | `option1_name` | string | 选项1名称（如"color"） |
 | `option2_name` | string | 选项2名称（如"size"） |
 | `option3_name` | string | 选项3名称 |
@@ -605,11 +630,45 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "query": "玩具",
   "size": 20,
   "from": 0,
-  "sort_by": "min_price",
+  "sort_by": "price",
   "sort_order": "asc"
 }
 ```
+**需求**: 搜索"玩具"，按价格从高到低排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "price",
+  "sort_order": "desc"
+}
+```
+
+**需求**: 搜索"玩具"，按销量从高到低排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "sales",
+  "sort_order": "desc"
+}
+```
+
+**需求**: 搜索"玩具"，按默认（相关性）排序
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0
+}
+```
+
 ### 场景2：SKU筛选（按维度过滤）
 **需求**: 搜索"芭比娃娃"，每个SPU下按颜色筛选，每种颜色只显示一个SKU
@@ -650,7 +709,7 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
 ### 场景4：带分面的商品搜索
-**需求**: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器
+**需求**: 搜索"玩具"，获取类目和规格的分面统计，用于构建筛选器
 ```json
 {
@@ -658,9 +717,9 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "size": 20,
   "language": "zh",
   "facets": [
-    "category1_name",
-    "category2_name",
-    "specifications"
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications", "size": 10, "type": "terms"}
   ]
 }
 ```
@@ -686,7 +745,8 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "facets": [
     {
       "field": "category1_name",
-      "size": 15
+      "size": 15,
+      "type": "terms"
     },
     {
       "field": "min_price",
@@ -698,7 +758,11 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
         {"key": "200+", "from": 200}
       ]
     },
-    "specifications"
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
   ],
   "sort_by": "min_price",
   "sort_order": "asc"
@@ -768,18 +832,23 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
   "query": "手机",
   "size": 20,
   "language": "zh",
-  "facets": ["specifications"]
+  "facets": [
+    {"field": "specifications", "size": 10, "type": "terms"}
+  ]
 }
 ```
-**需求**: 只获取"color"规格的分面统计
+**需求**: 只获取"color"和"size"规格的分面统计
 ```json
 {
   "query": "手机",
   "size": 20,
   "language": "zh",
-  "facets": ["specifications.color", "specifications.size"]
+  "facets": [
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
+  ]
 }
 ```
@@ -800,10 +869,10 @@ curl -X POST &quot;http://120.76.41.98:6002/search/&quot; \
     }
   },
   "facets": [
-    "category1_name",
-    "category2_name",
-    "specifications.color",
-    "specifications.size"
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
   ]
 }
 ```
@@ -1006,6 +1075,7 @@ curl &quot;http://localhost:6002/search/12345&quot;
 | `sku_weights` | long | SKU重量列表（数组） |
 | `sku_weight_units` | keyword | SKU重量单位列表（数组） |
 | `total_inventory` | long | 总库存 |
+| `sales` | long | 销量（展示销量） |
 | `skus` | nested | SKU详细信息（嵌套对象数组） |
 | `create_time`, `update_time` | date | 创建/更新时间 |
 | `title_embedding` | dense_vector | 标题向量（1024维，仅用于搜索） |
@@ -1038,11 +1108,15 @@ curl &quot;http://localhost:6002/search/12345&quot;
 #### 排序字段
-- `min_price`: 最低价格
-- `max_price`: 最高价格
+- `price`: 价格（后端自动根据sort_order映射：asc→min_price，desc→max_price）
+- `sales`: 销量
 - `create_time`: 创建时间
 - `update_time`: 更新时间
-- `relevance_score`: 相关性分数（默认）
+- `relevance_score`: 相关性分数（默认，不指定sort_by时使用）
+
+**注意**: 前端只需传 `price`，后端会自动处理：
+- `sort_by: "price"` + `sort_order: "asc"` → 按 `min_price` 升序（价格从低到高）
+- `sort_by: "price"` + `sort_order: "desc"` → 按 `max_price` 降序（价格从高到低）
 ### 支持的分析器
@@ -0,0 +1,700 @@
+# Prefixbox Search API 完整文档
+
+*基于公开信息整理的 Prefixbox Search API 技术文档*
+
+*官方接口文档*
+https://api-docs.prefixbox.com/#search-api
+
+
+---
+
+## 概述
+
+Prefixbox Search API 是一个基于 AI 的电商搜索解决方案，提供全文搜索、向量搜索和混合搜索功能。该 API 支持自动完成、搜索建议、商品过滤、排序等核心电商搜索功能。
+
+**核心特性：**
+- 混合搜索（文本 + 向量 + GPT 技术）
+- 自然语言查询理解
+- 动态重排序
+- 同义词管理
+- 多语言支持
+
+---
+
+## 1. 基础信息
+
+### 1.1 API 端点
+
+```
+基础 URL: https://api.prefixbox.com
+版本: v1/v2 (根据集成方式不同)
+```
+
+### 1.2 认证方式
+
+**API Key 认证**
+- 在 Prefixbox API Portal 的 Profile 页面获取 Search API Key
+- 所有请求必须在 Header 中包含：`Authorization: Bearer YOUR_SEARCH_API_KEY`
+- 同时需要提供 Search Engine Identifier
+
+**Header 示例：**
+```http
+Authorization: Bearer pb_live_abc123xyz...
+X-Search-Engine-Id: your-engine-identifier
+```
+
+---
+
+## 2. 核心 API 端点
+
+### 2.1 自动完成 API (Autocomplete API)
+
+**端点：** `GET /autocomplete`
+
+**功能：** 当用户在搜索框输入时提供实时查询建议、分类建议和商品建议。
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `q` | string | 是 | 用户输入的查询字符串 |
+| `limit` | integer | 否 | 返回建议的最大数量 (默认: 10) |
+| `type` | string | 否 | 建议类型: `all`, `queries`, `categories`, `products` (默认: all) |
+| `lang` | string | 否 | ISO 639-1 语言代码 (如: en, de, fr) |
+
+**请求示例：**
+```http
+GET https://api.prefixbox.com/autocomplete?q=apple&limit=8&lang=en
+Authorization: Bearer pb_live_abc123xyz...
+X-Search-Engine-Id: your-engine-identifier
+```
+
+**响应格式：**
+```json
+{
+  "query": "apple",
+  "suggestions": {
+    "queries": [
+      {"text": "apple iphone", "count": 1250},
+      {"text": "apple watch", "count": 890},
+      {"text": "apple airpods", "count": 650}
+    ],
+    "categories": [
+      {"id": "cat_001", "name": "Smartphones", "path": "Electronics/Mobile"},
+      {"id": "cat_002", "name": "Accessories", "path": "Electronics/Accessories"}
+    ],
+    "products": [
+      {
+        "id": "prod_12345",
+        "name": "Apple iPhone 15 Pro",
+        "image": "https://cdn.example.com/iphone15.jpg",
+        "price": 999.99,
+        "currency": "USD",
+        "url": "https://store.example.com/products/iphone-15-pro"
+      }
+    ]
+  },
+  "latency_ms": 45
+}
+```
+
+---
+
+### 2.2 搜索 API (Search API)
+
+**端点：** `GET /search`
+
+**功能：** 执行完整搜索并返回商品结果、过滤器、排序选项等。
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `q` | string | 是 | 搜索查询字符串 |
+| `page` | integer | 否 | 页码 (默认: 1) |
+| `page_size` | integer | 否 | 每页商品数量 (默认: 24, 最大: 100) |
+| `sort` | string | 否 | 排序方式: `relevance`, `price_asc`, `price_desc`, `newest`, `popularity` |
+| `filters` | object | 否 | 过滤器对象 `{"brand": ["Apple", "Samsung"], "price_range": {"min": 500, "max": 1000}}` |
+| `lang` | string | 否 | 语言代码 |
+| `user_id` | string | 否 | 用户ID（用于个性化）|
+| `cdp_data` | object | 否 | 客户数据平台偏好数据 |
+
+**请求示例：**
+```http
+GET https://api.prefixbox.com/search?q=running+shoes&page=1&page_size=24&sort=relevance
+Authorization: Bearer pb_live_abc123xyz...
+X-Search-Engine-Id: your-engine-identifier
+```
+
+**完整带过滤器的请求：**
+```http
+GET https://api.prefixbox.com/search?q=running+shoes&filters={"brand":["Nike","Adidas"],"price_range":{"min":50,"max":200},"size":["8","9","10"]}
+Authorization: Bearer pb_live_abc123xyz...
+X-Search-Engine-Id: your-engine-identifier
+```
+
+**响应格式：**
+```json
+{
+  "search_id": "search_abc123xyz789",
+  "query": "running shoes",
+  "total_results": 1456,
+  "page": 1,
+  "page_size": 24,
+  "total_pages": 61,
+  "latency_ms": 120,
+  "products": [
+    {
+      "id": "prod_67890",
+      "name": "Nike Air Zoom Pegasus",
+      "description": "Responsive running shoes with Zoom Air cushioning",
+      "image": "https://cdn.example.com/nike-pegasus.jpg",
+      "price": 129.99,
+      "original_price": 159.99,
+      "currency": "USD",
+      "url": "https://store.example.com/products/nike-air-zoom-pegasus",
+      "availability": "in_stock",
+      "brand": "Nike",
+      "category": "Running Shoes",
+      "score": 0.987
+    }
+  ],
+  "filters": [
+    {
+      "name": "brand",
+      "type": "multiselect",
+      "values": [
+        {"value": "Nike", "count": 456},
+        {"value": "Adidas", "count": 389},
+        {"value": "Asics", "count": 234}
+      ]
+    },
+    {
+      "name": "price",
+      "type": "range",
+      "min": 29.99,
+      "max": 299.99
+    },
+    {
+      "name": "size",
+      "type": "multiselect",
+      "values": [
+        {"value": "7", "count": 156},
+        {"value": "8", "count": 234},
+        {"value": "9", "count": 289}
+      ]
+    }
+  ],
+  "sort_options": [
+    {"value": "relevance", "label": "Relevance"},
+    {"value": "price_asc", "label": "Price: Low to High"},
+    {"value": "price_desc", "label": "Price: High to Low"},
+    {"value": "newest", "label": "Newest First"},
+    {"value": "popularity", "label": "Most Popular"}
+  ],
+  "related_keywords": ["trail running", "marathon shoes", "lightweight trainers"],
+  "related_categories": [
+    {"id": "cat_sports", "name": "Sports & Outdoors"},
+    {"id": "cat_footwear", "name": "Footwear"}
+  ],
+  "personalized": false,
+  "ai_reranking": true
+}
+```
+
+---
+
+### 2.3 商品详情 API (Product Details API)
+
+**端点：** `GET /products/{product_id}`
+
+**功能：** 获取单个商品的详细信息。
+
+**请求示例：**
+```http
+GET https://api.prefixbox.com/products/prod_67890
+Authorization: Bearer pb_live_abc123xyz...
+X-Search-Engine-Id: your-engine-identifier
+```
+
+**响应格式：**
+```json
+{
+  "id": "prod_67890",
+  "name": "Nike Air Zoom Pegasus",
+  "description": "Responsive running shoes with Zoom Air cushioning",
+  "long_description": "Detailed product description...",
+  "images": [
+    "https://cdn.example.com/nike-pegasus-1.jpg",
+    "https://cdn.example.com/nike-pegasus-2.jpg"
+  ],
+  "price": 129.99,
+  "original_price": 159.99,
+  "currency": "USD",
+  "url": "https://store.example.com/products/nike-air-zoom-pegasus",
+  "availability": "in_stock",
+  "stock_quantity": 45,
+  "brand": "Nike",
+  "category": "Running Shoes",
+  "attributes": {
+    "color": ["Black", "White", "Blue"],
+    "size": ["7", "8", "9", "10", "11", "12"],
+    "material": "Mesh and Rubber",
+    "weight": "280g"
+  },
+  "reviews": {
+    "average_rating": 4.5,
+    "count": 234
+  },
+  "tags": ["marathon", "neutral", "cushioned"]
+}
+```
+
+---
+
+### 2.4 分类页面 API (Collection API)
+
+**端点：** `GET /collections/{collection_id}`
+
+**功能：** 获取分类页面的商品列表。
+
+**请求参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `collection_id` | string | 分类ID |
+| `page` | integer | 页码 |
+| `page_size` | integer | 每页数量 |
+| `sort` | string | 排序方式 |
+| `filters` | object | 过滤器 |
+
+**响应格式：** 与 Search API 类似，但返回的是特定分类的商品
+
+---
+
+## 3. 高级功能 API
+
+### 3.1 个性化搜索 API
+
+**端点：** `GET /search/personalized`
+
+**功能：** 基于用户偏好数据返回个性化排序结果。
+
+**请求参数：**
+```json
+{
+  "q": "running shoes",
+  "user_id": "user_12345",
+  "cdp_data": {
+    "preferred_brands": ["Nike", "Adidas"],
+    "preferred_size": "9",
+    "preferred_color": "Black",
+    "past_purchases": ["prod_111", "prod_222"]
+  }
+}
+```
+
+---
+
+### 3.2 AI 重排序 API
+
+**端点：** `POST /search/rerank`
+
+**功能：** 基于用户行为数据动态重排搜索结果。
+
+**请求参数：**
+```json
+{
+  "search_id": "search_abc123xyz789",
+  "user_interactions": {
+    "clicks": ["prod_67890", "prod_67891"],
+    "hover_time_ms": 2500,
+    "previous_searches": ["trail running"]
+  }
+}
+```
+
+---
+
+## 4. 推荐 API (AI Recommend)
+
+### 4.1 相关产品推荐
+
+**端点：** `GET /recommendations/related`
+
+**请求参数：**
+```http
+GET /recommendations/related?product_id=prod_67890&limit=6
+```
+
+**响应格式：**
+```json
+{
+  "product_id": "prod_67890",
+  "recommendations": [
+    {
+      "id": "prod_67891",
+      "name": "Nike Dri-FIT Running Socks",
+      "reason": "Frequently bought together"
+    },
+    {
+      "id": "prod_67892",
+      "name": "Nike Running Cap",
+      "reason": "Similar category"
+    }
+  ]
+}
+```
+
+---
+
+### 4.2 热门商品推荐
+
+**端点：** `GET /recommendations/trending`
+
+```http
+GET /recommendations/trending?category=running&limit=8
+```
+
+---
+
+## 5. 分析追踪 API
+
+### 5.1 搜索事件追踪
+
+**端点：** `POST /analytics/search-event`
+
+**功能：** 追踪用户搜索行为以优化搜索相关性。
+
+**事件类型：**
+- `search_impression` - 搜索结果展示
+- `search_click` - 用户点击结果
+- `search_add_to_cart` - 添加商品到购物车
+- `search_purchase` - 完成购买
+
+**请求示例：**
+```json
+{
+  "search_id": "search_abc123xyz789",
+  "event_type": "search_click",
+  "user_id": "user_12345",
+  "product_id": "prod_67890",
+  "position": 1,
+  "timestamp": "2025-01-15T10:30:00Z"
+}
+```
+
+---
+
+## 6. 实时目录更新 API
+
+**端点：** `POST /catalog/update`
+
+**功能：** 实时更新商品目录数据。
+
+**请求格式：**
+```json
+{
+  "updates": [
+    {
+      "product_id": "prod_67890",
+      "field": "stock_quantity",
+      "value": 23,
+      "action": "update"
+    },
+    {
+      "product_id": "prod_67891",
+      "action": "delete"
+    }
+  ]
+}
+```
+
+---
+
+## 7. 错误处理
+
+### 7.1 HTTP 状态码
+
+| 状态码 | 说明 |
+|--------|------|
+| `200` | 请求成功 |
+| `400` | 请求参数错误 |
+| `401` | 认证失败 - API Key 无效或缺失 |
+| `403` | 权限不足 |
+| `404` | 资源未找到 |
+| `429` | 请求频率限制 |
+| `500` | 服务器内部错误 |
+
+### 7.2 错误响应格式
+
+```json
+{
+  "error": {
+    "code": "INVALID_API_KEY",
+    "message": "The provided API key is invalid or expired.",
+    "status": 401,
+    "request_id": "req_123456789"
+  }
+}
+```
+
+---
+
+## 8. 代码集成示例
+
+### 8.1 JavaScript/Frontend 集成
+
+```javascript
+// 初始化 Prefixbox 客户端
+const prefixbox = new PrefixboxClient({
+  apiKey: 'pb_live_abc123xyz...',
+  searchEngineId: 'your-engine-identifier',
+  language: 'en'
+});
+
+// 自动完成
+const suggestions = await prefixbox.autocomplete({
+  query: 'run',
+  limit: 8
+});
+
+// 搜索
+const searchResults = await prefixbox.search({
+  query: 'running shoes',
+  page: 1,
+  pageSize: 24,
+  filters: {
+    brand: ['Nike', 'Adidas'],
+    priceRange: { min: 50, max: 200 }
+  }
+});
+
+// 追踪事件
+prefixbox.trackEvent('search_click', {
+  searchId: searchResults.searchId,
+  productId: 'prod_67890',
+  position: 1
+});
+```
+
+### 8.2 cURL 示例
+
+```bash
+# 自动完成
+curl -X GET "https://api.prefixbox.com/autocomplete?q=apple&limit=5" \
+     -H "Authorization: Bearer pb_live_abc123xyz..." \
+     -H "X-Search-Engine-Id: your-engine-identifier"
+
+# 搜索
+curl -X GET "https://api.prefixbox.com/search?q=laptop&page=1&page_size=24" \
+     -H "Authorization: Bearer pb_live_abc123xyz..." \
+     -H "X-Search-Engine-Id: your-engine-identifier"
+```
+
+### 8.3 Python 集成示例
+
+```python
+import requests
+
+class PrefixboxClient:
+    def __init__(self, api_key, search_engine_id):
+        self.base_url = "https://api.prefixbox.com"
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Search-Engine-Id": search_engine_id,
+            "Content-Type": "application/json"
+        }
+    
+    def autocomplete(self, query, limit=10):
+        endpoint = f"{self.base_url}/autocomplete"
+        params = {"q": query, "limit": limit}
+        response = requests.get(endpoint, headers=self.headers, params=params)
+        return response.json()
+    
+    def search(self, query, page=1, page_size=24, filters=None):
+        endpoint = f"{self.base_url}/search"
+        params = {
+            "q": query,
+            "page": page,
+            "page_size": page_size
+        }
+        if filters:
+            params["filters"] = filters
+        
+        response = requests.get(endpoint, headers=self.headers, params=params)
+        return response.json()
+
+# 使用示例
+client = PrefixboxClient(
+    api_key="pb_live_abc123xyz...",
+    search_engine_id="your-engine-identifier"
+)
+
+# 执行搜索
+results = client.search(
+    query="wireless headphones",
+    filters={"brand": ["Sony", "Bose"], "price_range": {"min": 100, "max": 300}}
+)
+
+print(f"找到 {results['total_results']} 个商品")
+for product in results['products']:
+    print(f"- {product['name']}: ${product['price']}")
+```
+
+---
+
+## 9. SDK 和库
+
+Prefixbox 提供以下官方 SDK：
+
+- **JavaScript SDK**: `npm install @prefixbox/search-js`
+- **React SDK**: `npm install @prefixbox/react-search`
+- **Python SDK**: `pip install prefixbox-search`
+- **PHP SDK**: `composer require prefixbox/search`
+
+---
+
+## 10. 集成方式
+
+### 10.1 API 集成
+
+**适用场景：** 需要完全自定义 UI 和用户体验
+
+**客户职责：**
+- 提供商品 Feed URL
+- 实现与 Prefixbox API 的通信
+- 实现搜索 UX 界面
+- 实现用户行为追踪
+- Bug 修复和发布
+
+**Prefixbox 职责：**
+- 在 Admin Portal 配置搜索模块
+- 定制功能需求
+- 测试和报告 Bug
+- 运行 A/B 测试
+
+### 10.2 前端 JavaScript 集成
+
+**适用场景：** 快速部署，最小化开发工作量
+
+**客户职责：**
+- 提供带 header/footer 的空搜索结果页
+- 提供商品 Feed URL
+- 在网站中插入 Prefixbox JavaScript
+
+**Prefixbox 职责：**
+- 配置搜索模块
+- 定制外观和功能
+- 测试、预览和修复 Bug
+- 发布到生产环境
+
+---
+
+## 11. 商品 Feed 格式
+
+Prefixbox 要求提供兼容的商品 Feed：
+
+**必需字段：**
+- `id` - 商品唯一标识符
+- `name` - 商品名称
+- `url` - 商品页面 URL
+- `price` - 价格
+- `currency` - 货币代码
+- `availability` - 库存状态
+
+**推荐字段：**
+- `description` - 商品描述
+- `image` - 商品图片 URL
+- `brand` - 品牌
+- `category` - 分类
+- `attributes` - 商品属性（颜色、尺寸等）
+- `created_at` - 创建日期
+- `popularity_score` - 热门度分数
+
+**支持格式：** JSON, XML, CSV
+
+---
+
+## 12. 限制和配额
+
+### 12.1 API 请求限制
+
+| 套餐 | 月请求配额 | 每分钟限制 |
+|------|-----------|-----------|
+| Starter | 20,000 | 100 |
+| Growth | 200,000 | 500 |
+| Grow+ | 600,000-900,000 | 1,000 |
+| Enterprise | 自定义 | 自定义 |
+
+### 12.2 什么算作 API 请求？
+
+- **自动完成：** 每个字符输入 = 1 次请求
+- **搜索：** 每次搜索 = 1 次请求
+- **过滤/排序：** 每次操作 = 1 次请求
+- **分页：** 每次翻页 = 1 次请求
+
+**示例：** 用户输入 "apple"（6 次自动完成请求）+ 执行搜索（1 次）+ 过滤（1 次）+ 翻页（1 次）= **共 9 次 API 请求**
+
+---
+
+## 13. 支持和资源
+
+### 13.1 官方资源
+
+- **API 文档门户：** https://api-docs.prefixbox.com
+- **开发者中心：** https://developers.prefixbox.com
+- **技术文档：** https://www.prefixbox.com/en-us/technical
+- **集成指南：** https://www.prefixbox.com/en-us/technical/integration
+
+### 13.2 支持级别
+
+| 支持级别 | 可用套餐 | 响应时间 |
+|---------|---------|---------|
+| 标准支持 | Starter, Growth | 24-48 小时 |
+| 高级支持 | Grow+ | 4 小时 |
+| 专属支持 | Enterprise | 1 小时 |
+
+---
+
+## 14. 最佳实践
+
+### 14.1 性能优化
+
+1. **缓存自动完成结果** - 减少重复请求
+2. **延迟搜索** - 用户停止输入 300ms 后再发送请求
+3. **分页加载** - 使用无限滚动或分页
+4. **图片优化** - 使用 CDN 和适当尺寸的图片
+
+### 14.2 提升搜索相关性
+
+1. **配置同义词** - 连接不同词汇（如 "sneakers" = "trainers"）
+2. **设置字段权重** - 提升重要字段的权重（如 name > description）
+3. **使用 A/B 测试** - 测试不同配置对转化率的影响
+4. **分析零结果搜索** - 识别缺失商品或查询问题
+
+### 14.3 用户体验
+
+1. **显示搜索建议** - 帮助用户快速找到相关查询
+2. **保留搜索上下文** - 支持返回搜索结果
+3. **移动端优化** - 确保触摸友好的界面
+4. **加载状态** - 提供清晰的加载指示
+
+---
+
+## 15. 常见问题
+
+### Q: API 返回 429 错误怎么办？
+A: 表示达到速率限制。实现指数退避重试策略，或升级到更高配额的套餐。
+
+### Q: 如何处理多语言搜索？
+A: 在请求中使用 `lang` 参数，并确保商品 Feed 包含翻译内容。
+
+### Q: 可以自定义搜索算法吗？
+A: 可以在 Prefixbox Admin Portal 中调整字段权重和同义词规则。
+
+### Q: 支持语音搜索吗？
+A: 是的，Prefixbox AI Agent 支持自然语言查询和语音搜索集成。
+
+### Q: 如何集成到移动应用？
+A: 通过 API 集成方式，使用 iOS/Android 原生开发或 React Native 调用 REST API。
@@ -699,45 +699,44 @@ Elasticsearch
 #### 8.3.2 Facets 配置数据流
-**输入格式**：`List[Union[str, FacetConfig]]`
+**输入格式**：`List[FacetConfig]`
-- **简单模式**：字符串列表（字段名），使用默认配置
-  ```json
-  ["category1_name", "category2_name", "specifications"]
-  ```
-
-- **Specifications分面**：
-  - 所有规格名称：`"specifications"` - 返回所有name及其value列表
-  - 指定规格名称：`"specifications.color"` - 只返回指定name的value列表
+**配置对象列表**：所有分面配置必须使用 FacetConfig 对象
+```json
+[
+  {
+    "field": "category1_name",
+    "size": 15,
+    "type": "terms"
+  },
+  {
+    "field": "specifications.color",
+    "size": 20,
+    "type": "terms"
+  },
+  {
+    "field": "min_price",
+    "type": "range",
+    "ranges": [
+      {"key": "0-50", "to": 50},
+      {"key": "50-100", "from": 50, "to": 100}
+    ]
+  }
+]
+```
-- **高级模式**：FacetConfig 对象列表，支持自定义配置
-  ```json
-  [
-    {
-      "field": "category1_name",
-      "size": 15,
-      "type": "terms"
-    },
-    {
-      "field": "min_price",
-      "type": "range",
-      "ranges": [
-        {"key": "0-50", "to": 50},
-        {"key": "50-100", "from": 50, "to": 100}
-      ]
-    },
-    "specifications.color"  // 指定规格名称的分面
-  ]
-  ```
+**Specifications 分面支持**：
+- 所有规格名称：`field: "specifications"` - 返回所有 name 及其 value 列表
+- 指定规格名称：`field: "specifications.color"` - 只返回指定 name 的 value 列表
 **数据流**：
-1. API 层：接收 `List[Union[str, FacetConfig]]`
-2. Searcher 层：透传，不做转换
-3. ES Query Builder：只接受 `str` 或 `FacetConfig`，自动处理两种格式
+1. API 层：接收 `List[FacetConfig]`，Pydantic 验证参数
+2. Searcher 层：透传 FacetConfig 对象列表
+3. ES Query Builder：解析 FacetConfig 对象
    - 检测 `"specifications"` 或 `"specifications.{name}"` 格式
-   - 构建对应的嵌套聚合查询
-4. 输出：转换为 ES 聚合查询（包括specifications嵌套聚合）
-5. Result Formatter：格式化ES聚合结果，处理specifications嵌套结构
+   - 构建对应的嵌套聚合查询或普通聚合查询
+4. 输出：转换为 ES 聚合查询（包括 specifications 嵌套聚合）
+5. Result Formatter：格式化 ES 聚合结果，处理 specifications 嵌套结构
 #### 8.3.3 Range Filters 数据流
+
+
+类目表 product_category
+id	bigint(20)	NO	PRI		auto_increment
+parent_id	bigint(20)	NO			
+name	varchar(255)	NO			
+pic_url	varchar(255)	NO			
+sort	int(11)	YES		0	
+status	tinyint(4)	NO			
+creator	varchar(64)	YES			
+create_time	datetime	NO		CURRENT_TIMESTAMP	
+updater	varchar(64)	YES			
+update_time	datetime	NO		CURRENT_TIMESTAMP	on update CURRENT_TIMESTAMP
+deleted	bit(1)	NO		b'0'	
+tenant_id	bigint(20)	NO		0	
+
+
+
 spu表 shoplazza_product_spu 全部字段
 "Field"	"Type"	"Null"	"Key"	"Default"	"Extra"
 "id"	"bigint(20)"	"NO"	"PRI"		"auto_increment"
@@ -284,11 +284,12 @@
 | `sku_weights` | long | 所有 SKU 重量列表（数组） | 从所有 SKU 重量汇总 |
 | `sku_weight_units` | keyword | 所有 SKU 重量单位列表（数组） | 从所有 SKU 重量单位汇总 |
-### 9. 库存字段
+### 9. 库存与销量字段
 | 字段名 | ES类型 | 说明 | 数据来源 |
 |--------|--------|------|----------|
 | `total_inventory` | long | 总库存（所有 SKU 库存之和） | 从所有 SKU 库存汇总 |
+| `sales` | long | 销量（展示销量） | MySQL: `shoplazza_product_spu.fake_sales` |
 ### 10. SKU 嵌套字段
@@ -363,6 +364,16 @@
 - `vendor_zh.keyword`, `vendor_en.keyword`
 - `specifications` (嵌套查询)
 - `min_price`, `max_price` (范围过滤)
+- `sales` (范围过滤)
+- `total_inventory` (范围过滤)
+
+### 排序字段
+
+- `price`: 价格（前端传入，后端自动映射：asc→min_price，desc→max_price）
+- `sales`: 销量
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+- `relevance_score`: 相关性分数（默认）
 ### 分面字段（聚合统计）
@@ -94,11 +94,18 @@
                     <span class="arrow-down" data-field="create_time" data-order="asc" onclick="sortByField('create_time', 'asc')">▼</span>
                 </span>
             </button>
-            <button class="sort-btn" data-sort="min_price">
+            <button class="sort-btn" data-sort="price">
                 By Price
                 <span class="sort-arrows">
-                    <span class="arrow-up" data-field="min_price" data-order="asc" onclick="sortByField('min_price', 'asc')">▲</span>
-                    <span class="arrow-down" data-field="min_price" data-order="desc" onclick="sortByField('min_price', 'desc')">▼</span>
+                    <span class="arrow-up" data-field="price" data-order="asc" onclick="sortByField('price', 'asc')">▲</span>
+                    <span class="arrow-down" data-field="price" data-order="desc" onclick="sortByField('price', 'desc')">▼</span>
+                </span>
+            </button>
+            <button class="sort-btn" data-sort="sales">
+                By Sales
+                <span class="sort-arrows">
+                    <span class="arrow-up" data-field="sales" data-order="desc" onclick="sortByField('sales', 'desc')">▲</span>
+                    <span class="arrow-down" data-field="sales" data-order="asc" onclick="sortByField('sales', 'asc')">▼</span>
                 </span>
             </button>
@@ -106,8 +113,8 @@
                 <select id="resultSize" onchange="performSearch()">
                     <option value="20">20 per page</option>
                     <option value="50" selected>50 per page</option>
-                    <option value="100">50 per page</option>
-                    <option value="200">50 per page</option>
+                    <option value="100">100 per page</option>
+                    <option value="200">200 per page</option>
                 </select>
             </div>
         </div>
@@ -135,6 +142,6 @@
         <p>SearchEngine © 2025 | API: <span id="apiUrl">Loading...</span></p>
     </footer>
-    <script src="/static/js/app.js?v=3.4"></script>
+    <script src="/static/js/app.js?v=3.7"></script>
 </body>
 </html>
@@ -86,10 +86,10 @@ async function performSearch(page = 1) {
     // Define facets (一级分类 + 三个属性分面)
     const facets = [
-        "category1_name",  // 一级分类
-        "specifications.color",  // 颜色属性
-        "specifications.size",   // 尺寸属性
-        "specifications.material" // 材质属性
+        { field: "category1_name", size: 15, type: "terms" },  // 一级分类
+        { field: "specifications.color", size: 20, type: "terms" },  // 颜色属性
+        { field: "specifications.size", size: 15, type: "terms" },   // 尺寸属性
+        { field: "specifications.material", size: 10, type: "terms" } // 材质属性
     ];
     // Show loading
@@ -6,11 +6,15 @@ Transforms SPU and SKU data from MySQL into SPU-level ES documents with nested s
 import pandas as pd
 import numpy as np
+import logging
 from typing import Dict, Any, List, Optional
 from sqlalchemy import create_engine, text
 from utils.db_connector import create_db_connection
 from config import ConfigLoader
+# Configure logger
+logger = logging.getLogger(__name__)
+
 class SPUTransformer:
     """Transform SPU and SKU data into SPU-level ES documents."""
@@ -38,7 +42,48 @@ class SPUTransformer:
         except Exception as e:
             print(f"Warning: Failed to load config, using default searchable_option_dimensions: {e}")
             self.searchable_option_dimensions = ['option1', 'option2', 'option3']
+        
+        # Load category ID to name mapping
+        self.category_id_to_name = self._load_category_mapping()
+    def _load_category_mapping(self) -> Dict[str, str]:
+        """
+        Load category ID to name mapping from database.
+        
+        Returns:
+            Dictionary mapping category_id to category_name
+        """
+        query = text("""
+            SELECT DISTINCT
+                category_id,
+                category
+            FROM shoplazza_product_spu
+            WHERE deleted = 0 AND category_id IS NOT NULL
+        """)
+        
+        mapping = {}
+        with self.db_engine.connect() as conn:
+            result = conn.execute(query)
+            for row in result:
+                category_id = str(int(row.category_id))
+                category_name = row.category
+                
+                if not category_name or not category_name.strip():
+                    logger.warning(f"Category ID {category_id} has empty name, skipping")
+                    continue
+                
+                mapping[category_id] = category_name
+        
+        logger.info(f"Loaded {len(mapping)} category ID to name mappings")
+        
+        # Log all category mappings for debugging
+        if mapping:
+            logger.debug("Category ID mappings:")
+            for cid, name in sorted(mapping.items()):
+                logger.debug(f"  {cid} -> {name}")
+        
+        return mapping
+    
     def load_spu_data(self) -> pd.DataFrame:
         """
         Load SPU data from MySQL.
@@ -53,6 +98,7 @@ class SPUTransformer:
                 image_src, image_width, image_height, image_path, image_alt,
                 tags, note, category, category_id, category_google_id,
                 category_level, category_path,
+                fake_sales, display_fake_sales,
                 tenant_id, creator, create_time, updater, update_time, deleted
             FROM shoplazza_product_spu
             WHERE tenant_id = :tenant_id AND deleted = 0
@@ -61,8 +107,26 @@ class SPUTransformer:
         with self.db_engine.connect() as conn:
             df = pd.read_sql(query, conn, params={"tenant_id": self.tenant_id})
-        # Debug: Check if there's any data for this tenant_id
-        if len(df) == 0:
+        logger.info(f"Loaded {len(df)} SPU records for tenant_id={self.tenant_id}")
+        
+        # Statistics
+        if len(df) > 0:
+            has_category_path = df['category_path'].notna().sum()
+            has_category = df['category'].notna().sum()
+            has_title = df['title'].notna().sum()
+            
+            logger.info(f"SPU data statistics:")
+            logger.info(f"  - Has title: {has_title}/{len(df)} ({100*has_title/len(df):.1f}%)")
+            logger.info(f"  - Has category_path: {has_category_path}/{len(df)} ({100*has_category_path/len(df):.1f}%)")
+            logger.info(f"  - Has category: {has_category}/{len(df)} ({100*has_category/len(df):.1f}%)")
+            
+            # Warn if too many SPUs don't have category_path
+            if has_category_path < len(df) * 0.5:
+                logger.warning(f"Only {100*has_category_path/len(df):.1f}% of SPUs have category_path, data quality may be low")
+        else:
+            logger.warning(f"No SPU data found for tenant_id={self.tenant_id}")
+            
+            # Debug: Check if there's any data for this tenant_id
             debug_query = text("""
                 SELECT 
                     COUNT(*) as total_count,
@@ -77,7 +141,7 @@ class SPUTransformer:
                 total = debug_df.iloc[0]['total_count']
                 active = debug_df.iloc[0]['active_count']
                 deleted = debug_df.iloc[0]['deleted_count']
-                print(f"DEBUG: tenant_id={self.tenant_id}: total={total}, active={active}, deleted={deleted}")
+                logger.debug(f"tenant_id={self.tenant_id}: total={total}, active={active}, deleted={deleted}")
             # Check what tenant_ids exist in the table
             tenant_check_query = text("""
@@ -90,9 +154,9 @@ class SPUTransformer:
             with self.db_engine.connect() as conn:
                 tenant_df = pd.read_sql(tenant_check_query, conn)
             if not tenant_df.empty:
-                print(f"DEBUG: Available tenant_ids in shoplazza_product_spu:")
+                logger.debug(f"Available tenant_ids in shoplazza_product_spu:")
                 for _, row in tenant_df.iterrows():
-                    print(f"  tenant_id={row['tenant_id']}: total={row['count']}, active={row['active']}")
+                    logger.debug(f"  tenant_id={row['tenant_id']}: total={row['count']}, active={row['active']}")
         return df
@@ -120,7 +184,26 @@ class SPUTransformer:
         with self.db_engine.connect() as conn:
             df = pd.read_sql(query, conn, params={"tenant_id": self.tenant_id})
-        print(f"DEBUG: Loaded {len(df)} SKU records for tenant_id={self.tenant_id}")
+        logger.info(f"Loaded {len(df)} SKU records for tenant_id={self.tenant_id}")
+        
+        # Statistics
+        if len(df) > 0:
+            has_price = df['price'].notna().sum()
+            has_inventory = df['inventory_quantity'].notna().sum()
+            has_option1 = df['option1'].notna().sum()
+            has_option2 = df['option2'].notna().sum()
+            has_option3 = df['option3'].notna().sum()
+            
+            logger.info(f"SKU data statistics:")
+            logger.info(f"  - Has price: {has_price}/{len(df)} ({100*has_price/len(df):.1f}%)")
+            logger.info(f"  - Has inventory: {has_inventory}/{len(df)} ({100*has_inventory/len(df):.1f}%)")
+            logger.info(f"  - Has option1: {has_option1}/{len(df)} ({100*has_option1/len(df):.1f}%)")
+            logger.info(f"  - Has option2: {has_option2}/{len(df)} ({100*has_option2/len(df):.1f}%)")
+            logger.info(f"  - Has option3: {has_option3}/{len(df)} ({100*has_option3/len(df):.1f}%)")
+            
+            # Warn about data quality issues
+            if has_price < len(df) * 0.95:
+                logger.warning(f"Only {100*has_price/len(df):.1f}% of SKUs have price")
         return df
@@ -144,7 +227,21 @@ class SPUTransformer:
         with self.db_engine.connect() as conn:
             df = pd.read_sql(query, conn, params={"tenant_id": self.tenant_id})
-        print(f"DEBUG: Loaded {len(df)} option records for tenant_id={self.tenant_id}")
+        logger.info(f"Loaded {len(df)} option records for tenant_id={self.tenant_id}")
+        
+        # Statistics
+        if len(df) > 0:
+            unique_spus_with_options = df['spu_id'].nunique()
+            has_name = df['name'].notna().sum()
+            
+            logger.info(f"Option data statistics:")
+            logger.info(f"  - Unique SPUs with options: {unique_spus_with_options}")
+            logger.info(f"  - Has name: {has_name}/{len(df)} ({100*has_name/len(df):.1f}%)")
+            
+            # Warn about missing option names
+            if has_name < len(df):
+                missing = len(df) - has_name
+                logger.warning(f"{missing} option records are missing names")
         return df
@@ -155,35 +252,61 @@ class SPUTransformer:
         Returns:
             List of SPU-level ES documents
         """
+        logger.info(f"Starting data transformation for tenant_id={self.tenant_id}")
+        
         # Load data
         spu_df = self.load_spu_data()
         sku_df = self.load_sku_data()
         option_df = self.load_option_data()
         if spu_df.empty:
+            logger.warning("No SPU data to transform")
             return []
         # Group SKUs by SPU
         sku_groups = sku_df.groupby('spu_id')
+        logger.info(f"Grouped SKUs into {len(sku_groups)} SPU groups")
         # Group options by SPU
         option_groups = option_df.groupby('spu_id') if not option_df.empty else None
+        if option_groups:
+            logger.info(f"Grouped options into {len(option_groups)} SPU groups")
         documents = []
-        for _, spu_row in spu_df.iterrows():
+        skipped_count = 0
+        error_count = 0
+        
+        for idx, spu_row in spu_df.iterrows():
             spu_id = spu_row['id']
-            # Get SKUs for this SPU
-            skus = sku_groups.get_group(spu_id) if spu_id in sku_groups.groups else pd.DataFrame()
-            
-            # Get options for this SPU
-            options = option_groups.get_group(spu_id) if option_groups and spu_id in option_groups.groups else pd.DataFrame()
-            
-            # Transform to ES document
-            doc = self._transform_spu_to_doc(spu_row, skus, options)
-            if doc:
-                documents.append(doc)
-
+            try:
+                # Get SKUs for this SPU
+                skus = sku_groups.get_group(spu_id) if spu_id in sku_groups.groups else pd.DataFrame()
+                
+                # Get options for this SPU
+                options = option_groups.get_group(spu_id) if option_groups and spu_id in option_groups.groups else pd.DataFrame()
+                
+                # Warn if SPU has no SKUs
+                if skus.empty:
+                    logger.warning(f"SPU {spu_id} (title: {spu_row.get('title', 'N/A')}) has no SKUs")
+                
+                # Transform to ES document
+                doc = self._transform_spu_to_doc(spu_row, skus, options)
+                if doc:
+                    documents.append(doc)
+                else:
+                    skipped_count += 1
+                    logger.warning(f"SPU {spu_id} transformation returned None, skipped")
+            except Exception as e:
+                error_count += 1
+                logger.error(f"Error transforming SPU {spu_id}: {e}", exc_info=True)
+
+        logger.info(f"Transformation complete:")
+        logger.info(f"  - Total SPUs: {len(spu_df)}")
+        logger.info(f"  - Successfully transformed: {len(documents)}")
+        logger.info(f"  - Skipped: {skipped_count}")
+        logger.info(f"  - Errors: {error_count}")
+        
         return documents
     def _transform_spu_to_doc(
@@ -209,7 +332,12 @@ class SPUTransformer:
         doc['tenant_id'] = str(self.tenant_id)
         # SPU ID
-        doc['spu_id'] = str(spu_row['id'])
+        spu_id = spu_row['id']
+        doc['spu_id'] = str(spu_id)
+        
+        # Validate required fields
+        if pd.isna(spu_row.get('title')) or not str(spu_row['title']).strip():
+            logger.error(f"SPU {spu_id} has no title, this may cause search issues")
         # 文本相关性相关字段（中英文双语，暂时只填充中文）
         if pd.notna(spu_row.get('title')):
@@ -237,17 +365,35 @@ class SPUTransformer:
         # Category相关字段
         if pd.notna(spu_row.get('category_path')):
             category_path = str(spu_row['category_path'])
-            doc['category_path_zh'] = category_path
-            doc['category_path_en'] = None  # 暂时设为空
-            # 解析category_path获取多层级分类名称
-            path_parts = category_path.split('/')
-            if len(path_parts) > 0:
-                doc['category1_name'] = path_parts[0].strip()
-            if len(path_parts) > 1:
-                doc['category2_name'] = path_parts[1].strip()
-            if len(path_parts) > 2:
-                doc['category3_name'] = path_parts[2].strip()
+            # 解析category_path - 这是逗号分隔的类目ID列表
+            category_ids = [cid.strip() for cid in category_path.split(',') if cid.strip()]
+            
+            # 将ID映射为名称
+            category_names = []
+            missing_category_ids = []
+            for cid in category_ids:
+                if cid in self.category_id_to_name:
+                    category_names.append(self.category_id_to_name[cid])
+                else:
+                    # 如果找不到映射，记录错误并使用ID作为备选
+                    logger.error(f"Category ID {cid} not found in mapping for SPU {spu_row['id']} (title: {spu_row.get('title', 'N/A')}), category_path={category_path}")
+                    missing_category_ids.append(cid)
+                    category_names.append(cid)  # 使用ID作为备选
+            
+            # 构建类目路径字符串（用于搜索）
+            if category_names:
+                category_path_str = '/'.join(category_names)
+                doc['category_path_zh'] = category_path_str
+                doc['category_path_en'] = None  # 暂时设为空
+                
+                # 填充分层类目名称
+                if len(category_names) > 0:
+                    doc['category1_name'] = category_names[0]
+                if len(category_names) > 1:
+                    doc['category2_name'] = category_names[1]
+                if len(category_names) > 2:
+                    doc['category3_name'] = category_names[2]
         elif pd.notna(spu_row.get('category')):
             # 如果category_path为空，使用category字段作为category1_name的备选
             category = str(spu_row['category'])
@@ -302,6 +448,15 @@ class SPUTransformer:
                 image_src = f"//{image_src}" if image_src.startswith('//') else image_src
             doc['image_url'] = image_src
+        # Sales (fake_sales)
+        if pd.notna(spu_row.get('fake_sales')):
+            try:
+                doc['sales'] = int(spu_row['fake_sales'])
+            except (ValueError, TypeError):
+                doc['sales'] = 0
+        else:
+            doc['sales'] = 0
+
         # Process SKUs and build specifications
         skus_list = []
         prices = []
@@ -519,7 +519,7 @@ class ESQueryBuilder:
         Args:
             es_query: Existing ES query
-            sort_by: Field name for sorting
+            sort_by: Field name for sorting (支持 'price' 自动映射)
             sort_order: Sort order: 'asc' or 'desc'
         Returns:
@@ -531,6 +531,13 @@ class ESQueryBuilder:
         if not sort_order:
             sort_order = "desc"
+        # Auto-map 'price' to 'min_price' or 'max_price' based on sort_order
+        if sort_by == "price":
+            if sort_order.lower() == "asc":
+                sort_by = "min_price"  # 价格从低到高
+            else:
+                sort_by = "max_price"  # 价格从高到低
+
         if "sort" not in es_query:
             es_query["sort"] = []
@@ -546,20 +553,18 @@ class ESQueryBuilder:
     def build_facets(
         self,
-        facet_configs: Optional[List[Union[str, 'FacetConfig']]] = None
+        facet_configs: Optional[List['FacetConfig']] = None
     ) -> Dict[str, Any]:
         """
         构建分面聚合。
-        支持：
-        1. 分类分面：category1_name, category2_name, category3_name, category_name
-        2. specifications分面：嵌套聚合，按name聚合，然后按value聚合
-        
         Args:
-            facet_configs: 分面配置列表（标准格式）：
-                - str: 字段名，使用默认 terms 配置
-                - FacetConfig: 详细的分面配置对象
-                - 特殊值 "specifications": 构建specifications嵌套分面
+            facet_configs: 分面配置对象列表
+            
+            支持的字段类型：
+                - 普通字段: 如 "category1_name"（terms 或 range 类型）
+                - specifications: "specifications"（返回所有规格名称及其值）
+                - specifications.{name}: 如 "specifications.color"（返回指定规格名称的值）
         Returns:
             ES aggregations 字典
@@ -570,99 +575,76 @@ class ESQueryBuilder:
         aggs = {}
         for config in facet_configs:
-            # 特殊处理：specifications嵌套分面
-            if isinstance(config, str):
-                # 格式1: "specifications" - 返回所有name的分面
-                if config == "specifications":
-                    aggs["specifications_facet"] = {
-                        "nested": {
-                            "path": "specifications"
-                        },
-                        "aggs": {
-                            "by_name": {
-                                "terms": {
-                                    "field": "specifications.name",
-                                    "size": 20,
-                                    "order": {"_count": "desc"}
-                                },
-                                "aggs": {
-                                    "value_counts": {
-                                        "terms": {
-                                            "field": "specifications.value",
-                                            "size": 10,
-                                            "order": {"_count": "desc"}
-                                        }
+            field = config.field
+            size = config.size
+            facet_type = config.type
+            
+            # 处理 specifications（所有规格名称）
+            if field == "specifications":
+                aggs["specifications_facet"] = {
+                    "nested": {"path": "specifications"},
+                    "aggs": {
+                        "by_name": {
+                            "terms": {
+                                "field": "specifications.name",
+                                "size": 20,
+                                "order": {"_count": "desc"}
+                            },
+                            "aggs": {
+                                "value_counts": {
+                                    "terms": {
+                                        "field": "specifications.value",
+                                        "size": size,
+                                        "order": {"_count": "desc"}
                                     }
                                 }
                             }
                         }
                     }
-                    continue
-                
-                # 格式2: "specifications.color" 或 "specifications.颜色" - 只返回指定name的value列表
-                if config.startswith("specifications."):
-                    name = config[len("specifications."):]
-                    agg_name = f"specifications_{name}_facet"
-                    aggs[agg_name] = {
-                        "nested": {
-                            "path": "specifications"
-                        },
-                        "aggs": {
-                            "filter_by_name": {
-                                "filter": {
-                                    "term": {"specifications.name": name}
-                                },
-                                "aggs": {
-                                    "value_counts": {
-                                        "terms": {
-                                            "field": "specifications.value",
-                                            "size": 10,
-                                            "order": {"_count": "desc"}
-                                        }
+                }
+                continue
+            
+            # 处理 specifications.{name}（指定规格名称）
+            if field.startswith("specifications."):
+                name = field[len("specifications."):]
+                agg_name = f"specifications_{name}_facet"
+                aggs[agg_name] = {
+                    "nested": {"path": "specifications"},
+                    "aggs": {
+                        "filter_by_name": {
+                            "filter": {"term": {"specifications.name": name}},
+                            "aggs": {
+                                "value_counts": {
+                                    "terms": {
+                                        "field": "specifications.value",
+                                        "size": size,
+                                        "order": {"_count": "desc"}
                                     }
                                 }
                             }
                         }
                     }
-                    continue
+                }
+                continue
+            
+            # 处理普通字段
+            agg_name = f"{field}_facet"
-            # 简单模式：只有字段名（字符串，非specifications）
-            if isinstance(config, str):
-                field = config
-                agg_name = f"{field}_facet"
+            if facet_type == 'terms':
                 aggs[agg_name] = {
                     "terms": {
                         "field": field,
-                        "size": 10,
+                        "size": size,
                         "order": {"_count": "desc"}
                     }
                 }
-                continue
-            
-            # 高级模式：FacetConfig 对象
-            else:
-                # 此时 config 应该是 FacetConfig 对象
-                field = config.field
-                facet_type = config.type
-                size = config.size
-                agg_name = f"{field}_facet"
-                
-                if facet_type == 'terms':
+            elif facet_type == 'range':
+                if config.ranges:
                     aggs[agg_name] = {
-                        "terms": {
+                        "range": {
                             "field": field,
-                            "size": size,
-                            "order": {"_count": "desc"}
+                            "ranges": config.ranges
                         }
                     }
-                
-                elif facet_type == 'range':
-                    if config.ranges:
-                        aggs[agg_name] = {
-                            "range": {
-                                "field": field,
-                                "ranges": config.ranges
-                            }
-                        }
         return aggs
@@ -17,7 +17,7 @@ from .rerank_engine import RerankEngine
 from config import SearchConfig
 from config.utils import get_match_fields_for_index
 from context.request_context import RequestContext, RequestContextStage, create_request_context
-from api.models import FacetResult, FacetValue
+from api.models import FacetResult, FacetValue, FacetConfig
 from api.result_formatter import ResultFormatter
 logger = logging.getLogger(__name__)
@@ -123,7 +123,7 @@ class Searcher:
         from_: int = 0,
         filters: Optional[Dict[str, Any]] = None,
         range_filters: Optional[Dict[str, Any]] = None,
-        facets: Optional[List[Any]] = None,
+        facets: Optional[List[FacetConfig]] = None,
         min_score: Optional[float] = None,
         context: Optional[RequestContext] = None,
         sort_by: Optional[str] = None,
@@ -651,7 +651,7 @@ class Searcher:
             # 构建 FacetResult 对象
             facet_result = FacetResult(
                 field=field,
-                label=self._get_field_label(field),
+                label=field,
                 type=facet_type,
                 values=facet_values
             )
@@ -659,14 +659,3 @@ class Searcher:
             standardized_facets.append(facet_result)
         return standardized_facets if standardized_facets else None
-
-    def _get_field_label(self, field: str) -> str:
-        """获取字段的显示标签"""
-        # 字段标签映射（简化版，不再从配置读取）
-        field_labels = {
-            "category1_name": "一级分类",
-            "category2_name": "二级分类",
-            "category3_name": "三级分类",
-            "specifications": "规格"
-        }
-        return field_labels.get(field, field)