# API 快速参考 (v3.0)

## 基础搜索

```bash
POST /search/
{
  "query": "芭比娃娃",
  "size": 20
}
```

---

## 精确匹配过滤

```bash
{
  "filters": {
    "categoryName_keyword": "玩具",          // 单值
    "brandName_keyword": ["乐高", "美泰"]    // 多值（OR）
  }
}
```

---

## 范围过滤

```bash
{
  "range_filters": {
    "price": {
      "gte": 50,    // >=
      "lte": 200    // <=
    }
  }
}
```

**操作符**: `gte` (>=), `gt` (>), `lte` (<=), `lt` (<)

---

## 分面搜索

### 简单模式

```bash
{
  "facets": ["categoryName_keyword", "brandName_keyword"]
}
```

### 高级模式

```bash
{
  "facets": [
    {"field": "categoryName_keyword", "size": 15},
    {
      "field": "price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100}
      ]
    }
  ]
}
```

---

## 排序

```bash
{
  "sort_by": "min_price",
  "sort_order": "asc"    // asc 或 desc
}
```

---

## 布尔表达式

```bash
{
  "query": "玩具 AND (乐高 OR 芭比) ANDNOT 电动"
}
```

**操作符优先级**: `()` > `ANDNOT` > `AND` > `OR` > `RANK`

---

## 分页

```bash
{
  "size": 20,      // 每页数量
  "from": 0        // 偏移量（第1页=0，第2页=20）
}
```

---

## 完整示例

```bash
POST /search/
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "filters": {
    "categoryName_keyword": ["玩具", "益智玩具"]
  },
  "range_filters": {
    "price": {"gte": 50, "lte": 200}
  },
  "facets": [
    {"field": "brandName_keyword", "size": 15},
    {"field": "categoryName_keyword", "size": 15}
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}
```

---

## 响应格式

```json
{
  "hits": [
    {
      "_id": "12345",
      "_score": 8.5,
      "_source": {...}
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "took_ms": 45,
  "facets": [
    {
      "field": "categoryName_keyword",
      "label": "商品类目",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    }
  ]
}
```

---

## 其他端点

```bash
POST /search/image
{
  "image_url": "https://example.com/image.jpg",
  "size": 20
}

GET /search/suggestions?q=芭&size=5

GET /search/instant?q=玩具&size=5

GET /search/{doc_id}

GET /admin/health
GET /admin/config
GET /admin/stats
```

---

## Python 快速示例

```python
import requests

result = requests.post('http://localhost:6002/search/', json={
    "query": "玩具",
    "filters": {"categoryName_keyword": "玩具"},
    "range_filters": {"price": {"gte": 50, "lte": 200}},
    "facets": ["brandName_keyword"],
    "sort_by": "min_price",
    "sort_order": "asc"
}).json()

print(f"找到 {result['total']} 个结果")
```

---

## JavaScript 快速示例

```javascript
const result = await fetch('http://localhost:6002/search/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        query: "玩具",
        filters: {categoryName_keyword: "玩具"},
        range_filters: {price: {gte: 50, lte: 200}},
        facets: ["brandName_keyword"],
        sort_by: "min_price",
        sort_order: "asc"
    })
}).then(r => r.json());

console.log(`找到 ${result.total} 个结果`);
```

---

**详细文档**: [API_DOCUMENTATION.md](API_DOCUMENTATION.md)  
**更多示例**: [API_EXAMPLES.md](API_EXAMPLES.md)  
**在线文档**: http://localhost:6002/docs