API_QUICK_REFERENCE.md

# 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