# Base Configuration Guide
  
  店匠通用配置（Base Configuration）使用指南
  
  ## 概述
  
  Base配置是店匠（Shoplazza）通用配置，适用于所有使用店匠标准表的客户。该配置采用SPU级别的索引结构，所有客户共享同一个Elasticsearch索引（`search_products`），通过`tenant_id`字段实现数据隔离。
  
  ## 核心特性
  

  - **SPU级别索引**：每个ES文档代表一个SPU，包含嵌套的skus数组

  - **统一索引**：所有客户共享`search_products`索引
  - **租户隔离**：通过`tenant_id`字段实现数据隔离
  - **配置简化**：配置只包含ES搜索相关配置，不包含MySQL数据源配置
  - **外部友好格式**：API返回格式不包含ES内部字段（`_id`, `_score`, `_source`）
  
  ## 配置说明
  
  ### 配置文件位置
  
  `config/schema/base/config.yaml`
  
  ### 配置内容
  
  Base配置**不包含**以下内容：
  - `mysql_config` - MySQL数据库配置
  - `main_table` - 主表配置
  - `extension_table` - 扩展表配置
  - `source_table` / `source_column` - 字段数据源映射
  
  Base配置**只包含**：
  - ES字段定义（字段类型、分析器、boost等）
  - 查询域（indexes）配置
  - 查询处理配置（query_config）
  - 排序和打分配置（function_score）
  - SPU配置（spu_config）
  
  ### 必需字段
  
  - `tenant_id` (KEYWORD, required) - 租户隔离字段
  
  ### 主要字段
  

  - `spu_id` - SPU ID

  - `title`, `brief`, `description` - 文本搜索字段
  - `seo_title`, `seo_description`, `seo_keywords` - SEO字段

  - `vendor`, `tags`, `category` - 分类和标签字段（HKText，支持 `.keyword` 精确匹配）

  - `min_price`, `max_price`, `compare_at_price` - 价格字段

  - `skus` (nested) - 嵌套SKU数组

  
  ## 数据导入流程
  
  ### 1. 生成测试数据
  
  ```bash
  python scripts/generate_test_data.py \
      --num-spus 100 \
      --tenant-id "1" \
      --start-spu-id 1 \
      --start-sku-id 1 \
      --output test_data.sql
  ```
  
  ### 2. 导入测试数据到MySQL
  
  ```bash
  python scripts/import_test_data.py \
      --db-host localhost \
      --db-port 3306 \
      --db-database saas \
      --db-username root \
      --db-password password \
      --sql-file test_data.sql \
      --tenant-id "1"
  ```
  
  ### 3. 导入数据到Elasticsearch
  
  ```bash
  python scripts/ingest_shoplazza.py \
      --db-host localhost \
      --db-port 3306 \
      --db-database saas \
      --db-username root \
      --db-password password \
      --tenant-id "1" \
      --config base \
      --es-host http://localhost:9200 \
      --recreate \
      --batch-size 500
  ```
  
  ## API使用
  
  ### 搜索接口
  
  **端点**: `POST /search/`
  
  **请求头**:
  ```
  X-Tenant-ID: 1
  Content-Type: application/json
  ```
  
  **请求体**:
  ```json
  {
    "query": "耳机",
    "size": 10,
    "from": 0,
    "filters": {

      "category.keyword": "电子产品"

    },

    "facets": ["category.keyword", "vendor.keyword"]

  }
  ```
  
  **响应格式**:
  ```json
  {
    "results": [
      {

        "spu_id": "1",

        "title": "蓝牙耳机 Sony",
        "handle": "product-1",
        "description": "高品质无线蓝牙耳机",
        "vendor": "Sony",

        "category": "电子产品",

        "price": 199.99,
        "compare_at_price": 299.99,
        "currency": "USD",
        "image_url": "//cdn.example.com/products/1.jpg",
        "in_stock": true,

        "skus": [

          {

            "sku_id": "1",

            "title": "黑色",
            "price": 199.99,
            "compare_at_price": 299.99,
            "sku": "SKU-1-1",
            "stock": 50,
            "options": {
              "option1": "黑色"
            }
          }
        ],
        "relevance_score": 0.95
      }
    ],
    "total": 10,
    "max_score": 1.0,
    "facets": [
      {

        "field": "category.keyword",
        "label": "category.keyword",

        "type": "terms",
        "values": [
          {
            "value": "电子产品",
            "label": "电子产品",
            "count": 5,
            "selected": false
          }
        ]
      }
    ],
    "suggestions": [],
    "related_searches": [],
    "took_ms": 15,
    "query_info": {}
  }
  ```
  
  ### 响应格式说明
  
  #### 主要变化
  
  1. **`results`替代`hits`**：返回字段从`hits`改为`results`

  2. **结构化结果**：每个结果包含`spu_id`, `title`, `skus`, `relevance_score`等字段

  3. **无ES内部字段**：不包含`_id`, `_score`, `_source`等ES内部字段

  4. **嵌套skus**：每个商品包含skus数组，每个sku包含完整的变体信息

  5. **相关性分数**：`relevance_score`是ES原始分数（不进行归一化）

  #### SpuResult字段

  - `spu_id` - SPU ID

  - `title` - 商品标题
  - `handle` - 商品handle
  - `description` - 商品描述
  - `vendor` - 供应商/品牌

  - `category` - 类目

  - `tags` - 标签
  - `price` - 最低价格（min_price）
  - `compare_at_price` - 原价
  - `currency` - 货币单位（默认USD）
  - `image_url` - 主图URL
  - `in_stock` - 是否有库存

  - `skus` - SKU列表

  - `relevance_score` - 相关性分数（ES原始分数）

  #### SkuResult字段

  - `sku_id` - SKU ID

  - `title` - 变体标题
  - `price` - 价格
  - `compare_at_price` - 原价
  - `sku` - SKU编码
  - `stock` - 库存数量
  - `options` - 选项（颜色、尺寸等）
  
  ## 测试
  
  ### 运行测试脚本
  
  ```bash
  python scripts/test_base.py \
      --api-url http://localhost:8000 \
      --tenant-id "1" \
      --test-tenant-2 "2"
  ```
  
  ### 测试内容
  
  1. **基本搜索**：测试搜索API基本功能
  2. **响应格式验证**：验证返回格式是否符合要求
  3. **Facets聚合**：测试分面搜索功能
  4. **租户隔离**：验证不同租户的数据隔离
  
  ## 常见问题
  
  ### Q: 为什么配置中没有MySQL相关配置？
  
  A: 数据源配置和数据导入流程是写死的脚本，不在搜索配置中。搜索配置只关注ES搜索相关的内容。
  
  ### Q: 如何为新的租户导入数据？
  
  A: 使用`ingest_shoplazza.py`脚本，指定不同的`--tenant-id`参数即可。
  
  ### Q: 如何验证租户隔离是否生效？
  
  A: 使用`test_base.py`脚本，指定两个不同的`--tenant-id`，检查搜索结果是否隔离。
  
  ### Q: API返回格式中为什么没有`_id`和`_score`？
  

  A: 为了提供外部友好的API格式，我们移除了ES内部字段，使用`spu_id`和`relevance_score`替代。

  
  ### Q: 如何添加新的搜索字段？
  
  A: 在`config/schema/base/config.yaml`中添加字段定义，然后重新生成索引映射并重新导入数据。
  
  ## 注意事项
  
  1. **tenant_id必需**：所有API请求必须提供`tenant_id`（通过请求头`X-Tenant-ID`或查询参数`tenant_id`）
  2. **索引共享**：所有客户共享`search_products`索引，确保`tenant_id`字段正确设置
  3. **数据导入**：数据导入脚本是写死的，不依赖配置中的MySQL设置
  4. **配置分离**：搜索配置和数据源配置完全分离，提高可维护性