# API v3.0 迁移指南

本文档帮助你从旧版 API 迁移到 v3.0。

---

## 重要变更概述

v3.0 是一个**不向后兼容**的版本，主要变更包括：

1. ❌ **移除** 硬编码的 `price_ranges` 参数
2. ❌ **移除** `aggregations` 参数（ES DSL）
3. ✅ **新增** `range_filters` 参数
4. ✅ **新增** `facets` 参数（简化接口）
5. ✅ **新增** 标准化的分面响应格式

---

## 迁移步骤

### 第一步：更新过滤器参数

#### 旧代码（v2.x）

```json
{
  "query": "玩具",
  "filters": {
    "price_ranges": ["0-50", "50-100"]
  }
}
```

#### 新代码（v3.0）

```json
{
  "query": "玩具",
  "range_filters": {
    "price": {
      "gte": 50,
      "lte": 100
    }
  }
}
```

#### 迁移对照表

| 旧格式 | 新格式 |
|--------|--------|
| `"price_ranges": ["0-50"]` | `"price": {"lt": 50}` |
| `"price_ranges": ["50-100"]` | `"price": {"gte": 50, "lt": 100}` |
| `"price_ranges": ["100-200"]` | `"price": {"gte": 100, "lt": 200}` |
| `"price_ranges": ["200+"]` | `"price": {"gte": 200}` |

### 第二步：更新聚合参数

#### 旧代码（v2.x）

```json
{
  "query": "玩具",
  "aggregations": {
    "category_stats": {
      "terms": {
        "field": "categoryName_keyword",
        "size": 15
      }
    },
    "brand_stats": {
      "terms": {
        "field": "brandName_keyword",
        "size": 15
      }
    }
  }
}
```

#### 新代码（v3.0）- 简单模式

```json
{
  "query": "玩具",
  "facets": ["categoryName_keyword", "brandName_keyword"]
}
```

#### 新代码（v3.0）- 高级模式

```json
{
  "query": "玩具",
  "facets": [
    {
      "field": "categoryName_keyword",
      "size": 15,
      "type": "terms"
    },
    {
      "field": "brandName_keyword",
      "size": 15,
      "type": "terms"
    }
  ]
}
```

### 第三步：更新响应解析

#### 旧代码（v2.x）

```javascript
// JavaScript
const data = await response.json();

// 解析聚合结果（ES 原始格式）
if (data.aggregations && data.aggregations.category_stats) {
    data.aggregations.category_stats.buckets.forEach(bucket => {
        console.log(bucket.key, bucket.doc_count);
    });
}
```

```python
# Python
data = response.json()

# 解析聚合结果（ES 原始格式）
if 'aggregations' in data and 'category_stats' in data['aggregations']:
    for bucket in data['aggregations']['category_stats']['buckets']:
        print(bucket['key'], bucket['doc_count'])
```

#### 新代码（v3.0）

```javascript
// JavaScript
const data = await response.json();

// 解析分面结果（标准化格式）
if (data.facets) {
    data.facets.forEach(facet => {
        console.log(`${facet.label} (${facet.type}):`);
        facet.values.forEach(value => {
            console.log(`  ${value.label}: ${value.count}`);
        });
    });
}
```

```python
# Python
data = response.json()

# 解析分面结果（标准化格式）
if 'facets' in data:
    for facet in data['facets']:
        print(f"{facet['label']} ({facet['type']}):")
        for value in facet['values']:
            print(f"  {value['label']}: {value['count']}")
```

---

## 完整迁移示例

### 示例 1：带价格过滤的搜索

#### 旧代码

```python
import requests

response = requests.post('http://localhost:6002/search/', json={
    "query": "玩具",
    "size": 20,
    "filters": {
        "categoryName_keyword": "玩具",
        "price_ranges": ["50-100", "100-200"]
    },
    "aggregations": {
        "brand_stats": {
            "terms": {
                "field": "brandName_keyword",
                "size": 15
            }
        }
    }
})

data = response.json()

# 解析聚合
for bucket in data['aggregations']['brand_stats']['buckets']:
    print(f"{bucket['key']}: {bucket['doc_count']}")
```

#### 新代码

```python
import requests

response = requests.post('http://localhost:6002/search/', json={
    "query": "玩具",
    "size": 20,
    "filters": {
        "categoryName_keyword": "玩具"
    },
    "range_filters": {
        "price": {
            "gte": 50,
            "lte": 200
        }
    },
    "facets": [
        {"field": "brandName_keyword", "size": 15}
    ]
})

data = response.json()

# 解析分面
for facet in data['facets']:
    if facet['field'] == 'brandName_keyword':
        for value in facet['values']:
            print(f"{value['label']}: {value['count']}")
```

### 示例 2：前端 JavaScript 迁移

#### 旧代码

```javascript
// 构建请求
const requestBody = {
    query: "玩具",
    filters: {
        price_ranges: ["50-100"]
    },
    aggregations: {
        category_stats: {
            terms: {
                field: "categoryName_keyword",
                size: 15
            }
        }
    }
};

// 发送请求
const response = await fetch('/search/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(requestBody)
});

const data = await response.json();

// 显示聚合结果
const buckets = data.aggregations.category_stats.buckets;
buckets.forEach(bucket => {
    console.log(`${bucket.key}: ${bucket.doc_count}`);
});
```

#### 新代码

```javascript
// 构建请求
const requestBody = {
    query: "玩具",
    range_filters: {
        price: {
            gte: 50,
            lte: 100
        }
    },
    facets: [
        {field: "categoryName_keyword", size: 15}
    ]
};

// 发送请求
const response = await fetch('/search/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(requestBody)
});

const data = await response.json();

// 显示分面结果
data.facets.forEach(facet => {
    console.log(`${facet.label}:`);
    facet.values.forEach(value => {
        console.log(`  ${value.label}: ${value.count}`);
    });
});
```

---

## 字段映射对照

### 请求字段

| v2.x | v3.0 | 说明 |
|------|------|------|
| `filters.price_ranges` | `range_filters.price` | 价格范围过滤 |
| `aggregations` | `facets` | 分面配置 |
| - | `range_filters.*` | 任意数值字段范围过滤 |

### 响应字段

| v2.x | v3.0 | 说明 |
|------|------|------|
| `aggregations` | `facets` | 分面结果 |
| `aggregations.*.buckets[].key` | `facets[].values[].value` | 分面值 |
| `aggregations.*.buckets[].doc_count` | `facets[].values[].count` | 文档数量 |
| - | `facets[].values[].label` | 显示标签 |
| - | `facets[].values[].selected` | 是否选中 |
| - | `facets[].label` | 分面名称 |
| - | `facets[].type` | 分面类型 |

---

## 常见问题

### Q1: 我的代码使用了 `price_ranges`，如何迁移？

**A**: 使用 `range_filters` 替代：

```python
# 旧
filters = {"price_ranges": ["50-100"]}

# 新
range_filters = {"price": {"gte": 50, "lte": 100}}
```

### Q2: 我使用了 ES 聚合语法，如何迁移？

**A**: 使用简化的 `facets` 配置：

```python
# 旧
aggregations = {
    "my_agg": {
        "terms": {
            "field": "categoryName_keyword",
            "size": 15
        }
    }
}

# 新（简单模式）
facets = ["categoryName_keyword"]

# 新（高级模式）
facets = [
    {"field": "categoryName_keyword", "size": 15}
]
```

### Q3: 响应中的 `aggregations` 字段去哪了？

**A**: 已改名为 `facets`，并且格式标准化了：

```python
# 旧
for bucket in data['aggregations']['category_stats']['buckets']:
    print(bucket['key'], bucket['doc_count'])

# 新
for facet in data['facets']:
    for value in facet['values']:
        print(value['value'], value['count'])
```

### Q4: 如何实现多个不连续的价格范围？

**A**: v3.0 不支持单字段多个不连续范围。请使用布尔查询或分多次查询：

```python
# 方案1：分两次查询
result1 = search(query="玩具", range_filters={"price": {"lt": 50}})
result2 = search(query="玩具", range_filters={"price": {"gte": 200}})

# 方案2：使用范围分面统计（不过滤，只统计）
facets = [{
    "field": "price",
    "type": "range",
    "ranges": [
        {"key": "低价", "to": 50},
        {"key": "高价", "from": 200}
    ]
}]
```

### Q5: 我需要继续使用旧接口，怎么办？

**A**: v3.0 不提供向后兼容。建议：
1. 尽快迁移到新接口
2. 如果暂时无法迁移，请继续使用 v2.x 版本
3. 参考本文档快速完成迁移（通常只需要 1-2 小时）

---

## 迁移检查清单

完成以下检查项，确保迁移完整：

### 后端代码

- [ ] 移除所有 `price_ranges` 参数的使用
- [ ] 将范围过滤改为 `range_filters`
- [ ] 将 `aggregations` 改为 `facets`
- [ ] 更新响应解析，使用 `facets` 而不是 `aggregations`

### 前端代码

- [ ] 更新搜索请求体，使用新参数
- [ ] 更新状态管理，添加 `rangeFilters`
- [ ] 重写分面结果显示逻辑
- [ ] 移除所有 ES DSL 聚合代码

### 测试

- [ ] 测试简单搜索功能
- [ ] 测试范围过滤功能
- [ ] 测试分面搜索功能
- [ ] 测试组合查询功能
- [ ] 测试排序功能

### 文档

- [ ] 更新 API 调用文档
- [ ] 更新代码注释
- [ ] 通知团队成员新的 API 变更

---

## 获取帮助

- **API 文档**: `API_DOCUMENTATION.md`
- **使用示例**: `API_EXAMPLES.md`
- **测试脚本**: `test_new_api.py`
- **变更日志**: `CHANGES.md`

---

**迁移难度**: ⭐⭐ (简单到中等)  
**预计时间**: 1-2 小时  
**优势**: 更灵活、更通用、更易用的 API

---

**版本**: 3.0  
**日期**: 2024-11-12