# 架构重构文档 - 简洁版配置架构
  
  ## 重构概述
  
  本次重构实现了**索引结构与搜索行为的完全分离**，大幅简化了配置系统，提升了代码可维护性。
  
  ## 重构原则
  
  ### 1. 单一真相来源 (Single Source of Truth)
  
  - **索引结构** → `mappings/search_products.json`（ES mapping）
  - **搜索行为** → `config/config.yaml`（字段权重、搜索域）
  
  ### 2. 职责分离 (Separation of Concerns)
  
  | 配置文件 | 职责 | 内容 |
  |---------|------|------|
  | `mappings/search_products.json` | 索引结构定义 | 字段类型、analyzer、索引设置 |
  | `config/config.yaml` | 搜索行为配置 | 字段权重、搜索域、查询策略 |
  
  ### 3. 配置简化 (Configuration Simplification)
  
  移除冗余的字段定义，避免在多处维护相同信息。
  
  ## 架构变化
  
  ### Before（旧架构）
  
  ```
  config/
  ├── field_types.py          ← 定义 FieldType、AnalyzerType 枚举
  │   ├── FieldConfig 类      ← 字段配置数据类
  │   ├── get_es_mapping_for_field() ← 从配置生成mapping
  │   └── FIELD_TYPE_MAP 等映射
  ├── config.yaml             ← 包含详细的字段定义
  │   ├── fields:             ← 每个字段的类型、analyzer、boost
  │   └── indexes:            ← 搜索域配置
  └── config_loader.py        ← 解析字段定义并验证
  
  mappings/
  └── search_products.json    ← ES mapping（与config.yaml重复）
  
  问题：
  - config.yaml 和 mapping.json 需要保持同步
  - FieldConfig 等大量冗余代码
  - 修改索引结构需要同时改两个文件
  ```
  
  ### After（新架构）
  
  ```
  config/
  ├── config.yaml             ← 只配置搜索行为（简洁版）
  │   ├── field_boosts:       ← 字段权重字典
  │   └── indexes:            ← 搜索域配置
  ├── config_loader.py        ← 简化的配置加载器
  └── utils.py                ← 从field_boosts读取权重
  
  mappings/
  └── search_products.json    ← 索引结构的唯一定义
  
  优势：
  ✅ 索引结构只在mapping中定义一次
  ✅ 无需维护FieldConfig等冗余代码
  ✅ 配置文件更简洁易读
  ✅ 修改索引结构只需改mapping文件
  ```
  
  ## 删除的文件/代码
  
  ### 完全删除
  
  1. **config/field_types.py**（341行）- 整个文件删除
     - `FieldType` 枚举
     - `AnalyzerType` 枚举
     - `SimilarityType` 枚举（死代码）
     - `FieldConfig` 数据类
     - `get_es_mapping_for_field()` 函数
     - `FIELD_TYPE_MAP`、`ANALYZER_MAP` 映射字典
  
  2. **indexer/data_transformer.py**（329行）- 整个文件删除
     - 旧的数据转换器，已被 `spu_transformer.py` 替代
  
  ### 大幅简化
  
  3. **config/config_loader.py**
     - 移除字段定义解析逻辑（`_parse_field_config` 方法）
     - 移除字段验证逻辑
     - 移除 `fields: List[FieldConfig]` 字段
     - 添加 `field_boosts: Dict[str, float]` 字段
     - 从 610行 → 约480行（简化21%）
  
  4. **config/config.yaml**
     - 移除详细的字段定义（type、analyzer、store等）
     - 改为简洁的 `field_boosts` 字典
     - 从 478行 → 143行（简化70%）
  
  ## 新架构示例
  
  ### config.yaml（简洁版）
  
  ```yaml
  # 字段权重配置（用于搜索）
  field_boosts:
    title_zh: 3.0
    brief_zh: 1.5
    description_zh: 1.0
    vendor_zh: 1.5
    tags: 1.0
    option1_values: 0.5
    option2_values: 0.5
    option3_values: 0.5
  
  # 搜索域配置
  indexes:
    - name: "default"
      label: "默认搜索"
      fields:
        - "title_zh"
        - "brief_zh"
        - "description_zh"
        - "vendor_zh"
        - "tags"
        - "option1_values"
        - "option2_values"
        - "option3_values"
      boost: 1.0
  
    - name: "title"
      label: "标题搜索"
      fields: ["title_zh"]
      boost: 2.0
  
  # 查询配置
  query_config:
    supported_languages: ["zh", "en"]
    enable_translation: true
    enable_text_embedding: true
    text_embedding_field: "title_embedding"
  
  # SPU配置
  spu_config:
    enabled: true
    spu_field: "spu_id"
    searchable_option_dimensions: ['option1', 'option2', 'option3']
  ```
  
  ### mappings/search_products.json（索引结构）
  
  ```json
  {
    "mappings": {
      "properties": {
        "title_zh": {
          "type": "text",
          "analyzer": "hanlp_index",
          "search_analyzer": "hanlp_standard"
        },
        "option1_values": {
          "type": "keyword"
        }
      }
    }
  }
  ```
  
  ## 代码改动统计
  
  | 文件 | 改动类型 | 行数变化 | 说明 |
  |------|---------|---------|------|
  | `config/field_types.py` | **删除** | -341 | 整个文件删除 |
  | `indexer/data_transformer.py` | **删除** | -329 | 旧transformer删除 |
  | `config/config.yaml` | **重构** | -335 | 从478→143行 |
  | `config/config_loader.py` | **重构** | -130 | 从610→480行 |
  | `config/utils.py` | **重构** | -18 | 简化逻辑 |
  | `config/__init__.py` | **更新** | -12 | 移除旧导出 |
  | `api/routes/admin.py` | **更新** | -1 | num_fields→num_field_boosts |
  | `tests/conftest.py` | **更新** | -23 | 适配新配置 |
  | **总计** | | **-1189行** | **代码量减少约30%** |
  
  ## 功能特性
  
  ### Option值参与搜索
  
  支持子SKU的option值参与搜索，通过配置控制：
  
  ```yaml
  # 配置哪些option参与搜索
  spu_config:
    searchable_option_dimensions: ['option1', 'option2', 'option3']
  
  # 配置option值的搜索权重
  field_boosts:
    option1_values: 0.5
    option2_values: 0.5
    option3_values: 0.5
  ```
  
  **数据灌入**：`spu_transformer.py` 自动从子SKU提取option值去重后写入索引。
  
  **在线搜索**：自动将配置的option字段加入multi_match，应用配置的权重。
  
  ## 使用指南
  
  ### 1. 修改字段权重
  
  只需修改 `config/config.yaml`：
  
  ```yaml
  field_boosts:
    title_zh: 4.0  # 提高标题权重
    option1_values: 0.8  # 提高option1权重
  ```
  
  ### 2. 添加新搜索域
  
  只需在 `config/config.yaml` 中添加：
  
  ```yaml
  indexes:
    - name: "price"
      label: "价格搜索"
      fields: ["min_price", "max_price"]
      boost: 1.0
  ```
  
  ### 3. 修改索引结构
  
  只需修改 `mappings/search_products.json`，然后重建索引：
  
  ```bash
  python scripts/recreate_and_import.py --tenant-id 1 --recreate
  ```
  
  ### 4. 配置验证
  
  配置加载时自动验证：
  
  ```python
  from config import ConfigLoader
  
  loader = ConfigLoader()
  config = loader.load_config(validate=True)  # 自动验证
  ```
  
  ## 兼容性说明
  
  ### 向后兼容
  
  保留了 `load_tenant_config()` 函数，向后兼容旧代码：
  
  ```python
  # 旧代码仍然可用
  from config import load_tenant_config
  config = load_tenant_config(tenant_id="1")  # tenant_id参数被忽略
  ```
  
  ### 测试兼容
  
  更新了 `tests/conftest.py`，所有测试fixture适配新配置结构。
  
  ## 迁移指南
  
  ### 从旧架构迁移
  
  如果您有自定义配置文件，需要进行以下调整：
  
  #### 1. 简化字段定义
  
  **Before:**
  ```yaml
  fields:
    - name: "title_zh"
      type: "TEXT"
      analyzer: "hanlp_index"
      search_analyzer: "hanlp_standard"
      boost: 3.0
      index: true
      store: true
      return_in_source: true
  ```
  
  **After:**
  ```yaml
  field_boosts:
    title_zh: 3.0
  ```
  
  字段结构定义移到 `mappings/search_products.json`。
  
  #### 2. 更新代码导入
  
  **Before:**
  ```python
  from config import FieldConfig, FieldType, AnalyzerType
  ```
  
  **After:**
  ```python
  # 不再需要这些导入
  from config import SearchConfig, IndexConfig
  ```
  
  ## 优势总结
  
  ✅ **代码量减少30%**（-1189行）  
  ✅ **配置文件简化70%**（config.yaml）  
  ✅ **单一真相来源**（索引结构只在mapping定义）  
  ✅ **职责清晰**（mapping定义结构，config定义行为）  
  ✅ **更易维护**（修改索引只需改一处）  
  ✅ **更易理解**（配置文件更简洁直观）  
  ✅ **向后兼容**（保留旧API接口）  
  
  ## 技术债务清理
  
  本次重构清理了以下技术债务：
  
  1. ✅ 删除死代码（`SimilarityType`）
  2. ✅ 删除冗余代码（`FieldConfig`、`get_es_mapping_for_field`）
  3. ✅ 删除重复配置（config.yaml vs mapping.json）
  4. ✅ 删除旧transformer（`data_transformer.py`）
  5. ✅ 简化配置验证逻辑
  6. ✅ 统一配置管理接口
  
  ## 下一步改进建议
  
  1. **动态权重调整**：支持在运行时动态调整字段权重
  2. **A/B测试支持**：支持不同权重配置的A/B测试
  3. **权重优化工具**：提供工具自动优化字段权重
  4. **配置热更新**：支持配置热更新而不重启服务
  
  ---
  
  **重构日期**: 2024-12-02  
  **重构版本**: v2.0  
  **重构类型**: 架构简化 & 技术债务清理