# 架构重构文档 - 简洁版配置架构

## 重构概述

本次重构实现了**索引结构与搜索行为的完全分离**，大幅简化了配置系统，提升了代码可维护性。

## 重构原则

### 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  
**重构类型**: 架构简化 & 技术债务清理