# 搜索引擎 API 接口文档

## 概述

本文档描述了电商搜索 SaaS 系统的 RESTful API 接口。系统提供强大的搜索功能，包括：

- **多语言搜索**：支持中文、英文、俄文等多语言查询和自动翻译
- **语义搜索**：基于 BGE-M3 文本向量和 CN-CLIP 图片向量的语义检索
- **布尔表达式**：支持 AND、OR、RANK、ANDNOT 操作符
- **灵活过滤**：精确匹配过滤器和数值范围过滤器
- **分面搜索**：动态生成过滤选项，提供分组统计
- **自定义排序**：支持按任意字段排序
- **个性化排序**：可配置的相关性排序表达式

## 基础信息

- **Base URL**: `http://your-domain:6002`  (http://120.76.41.98:6002)
- **协议**: HTTP/HTTPS
- **数据格式**: JSON
- **字符编码**: UTF-8

## 搜索接口

### 1. 文本搜索

**端点**: `POST /search/`

**描述**: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索。

#### 请求参数

```json
{
  "query": "string (required)",
  "size": 10,
  "from": 0,
  "filters": {},
  "range_filters": {},
  "facets": [],
  "sort_by": "string",
  "sort_order": "desc",
  "min_score": 0.0,
  "debug": false,
  "user_id": "string",
  "session_id": "string"
}
```

#### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `query` | string | Y | - | 搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT） |
| `size` | integer | N | 10 | 返回结果数量（1-100） |
| `from` | integer | N | 0 | 分页偏移量 |
| `filters` | object | N | null | 精确匹配过滤器（见下文） |
| `range_filters` | object | N | null | 数值范围过滤器（见下文） |
| `facets` | array | N | null | 分面配置（见下文） |
| `sort_by` | string | N | null | 排序字段名 |
| `sort_order` | string | N | "desc" | 排序方向：`asc` 或 `desc` |
| `min_score` | float | N | null | 最小相关性分数阈值 |
| `debug` | boolean | N | false | 是否返回调试信息 |
| `user_id` | string | N | null | 用户ID（用于个性化，预留） |
| `session_id` | string | N | null | 会话ID（用于分析，预留） |

#### 过滤器详解

##### 精确匹配过滤器 (filters)

用于精确匹配或多值匹配（OR 逻辑）。

**格式**:
```json
{
  "filters": {
    "categoryName_keyword": "玩具",           // 单值：精确匹配
    "brandName_keyword": ["乐高", "孩之宝"],  // 数组：匹配任意值（OR）
    "in_stock": true                          // 布尔值
  }
}
```

**支持的值类型**:
- 字符串：精确匹配
- 整数：精确匹配
- 布尔值：精确匹配
- 数组：匹配任意值（OR 逻辑）

##### 范围过滤器 (range_filters)

用于数值字段的范围过滤。

**格式**:
```json
{
  "range_filters": {
    "price": {
      "gte": 50,    // 大于等于
      "lte": 200    // 小于等于
    },
    "days_since_last_update": {
      "lte": 30     // 最近30天更新
    }
  }
}
```

**支持的操作符**:
- `gte`: 大于等于 (>=)
- `gt`: 大于 (>)
- `lte`: 小于等于 (<=)
- `lt`: 小于 (<)

**注意**: 至少需要指定一个操作符。

##### 分面配置 (facets)

用于生成分面统计（分组聚合）。

**简单模式**（字符串数组）:
```json
{
  "facets": ["categoryName_keyword", "brandName_keyword"]
}
```

**高级模式**（配置对象数组）:
```json
{
  "facets": [
    {
      "field": "categoryName_keyword",
      "size": 15,
      "type": "terms"
    },
    {
      "field": "price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ]
}
```

**分面配置参数**:
- `field`: 字段名（必填）
- `size`: 返回的分组数量（默认：10，范围：1-100）
- `type`: 分面类型，`terms`（分组统计）或 `range`（范围统计）
- `ranges`: 范围定义（仅当 type='range' 时需要）

#### 响应格式

```json
{
  "hits": [
    {
      "_id": "12345",
      "_score": 8.5,
      "_custom_score": 12.3,
      "_source": {
        "name": "芭比时尚娃娃",
        "price": 89.99,
        "categoryName": "玩具",
        "brandName": "美泰",
        "imageUrl": "https://example.com/image.jpg"
      }
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "took_ms": 45,
  "facets": [
    {
      "field": "categoryName_keyword",
      "label": "商品类目",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        },
        {
          "value": "益智玩具",
          "label": "益智玩具",
          "count": 33,
          "selected": false
        }
      ]
    }
  ],
  "query_info": {
    "original_query": "芭比娃娃",
    "detected_language": "zh",
    "translations": {
      "en": "barbie doll"
    }
  },
  "related_queries": null,
  "performance_info": {
    "total_duration": 45.2,
    "stage_durations": {
      "query_parsing": 5.3,
      "elasticsearch_search": 35.1,
      "result_processing": 4.8
    }
  },
  "debug_info": null
}
```

#### 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `hits` | array | 搜索结果列表 |
| `hits[]._id` | string | 文档ID |
| `hits[]._score` | float | 相关性分数 |
| `hits[]._custom_score` | float | 自定义排序分数（如启用） |
| `hits[]._source` | object | 文档内容 |
| `total` | integer | 匹配的总文档数 |
| `max_score` | float | 最高相关性分数 |
| `took_ms` | integer | 搜索耗时（毫秒） |
| `facets` | array | 分面统计结果（标准化格式） |
| `facets[].field` | string | 字段名 |
| `facets[].label` | string | 显示标签 |
| `facets[].type` | string | 分面类型：`terms` 或 `range` |
| `facets[].values` | array | 分面值列表 |
| `facets[].values[].value` | any | 分面值 |
| `facets[].values[].label` | string | 显示标签 |
| `facets[].values[].count` | integer | 文档数量 |
| `facets[].values[].selected` | boolean | 是否已选中 |
| `query_info` | object | 查询处理信息 |
| `related_queries` | array | 相关搜索（预留） |
| `performance_info` | object | 性能信息 |
| `debug_info` | object | 调试信息（仅当 debug=true） |

#### 请求示例

**示例 1: 简单搜索**

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "芭比娃娃",
    "size": 20
  }'
```

**示例 2: 带过滤器的搜索**

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 20,
    "filters": {
      "categoryName_keyword": ["玩具", "益智玩具"],
      "in_stock": true
    },
    "range_filters": {
      "price": {
        "gte": 50,
        "lte": 200
      }
    }
  }'
```

**示例 3: 带分面搜索（简单模式）**

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 20,
    "facets": ["categoryName_keyword", "brandName_keyword"]
  }'
```

**示例 4: 带分面搜索（高级模式）**

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 20,
    "facets": [
      {
        "field": "categoryName_keyword",
        "size": 15,
        "type": "terms"
      },
      {
        "field": "brandName_keyword",
        "size": 15,
        "type": "terms"
      },
      {
        "field": "price",
        "type": "range",
        "ranges": [
          {"key": "0-50", "to": 50},
          {"key": "50-100", "from": 50, "to": 100},
          {"key": "100-200", "from": 100, "to": 200},
          {"key": "200+", "from": 200}
        ]
      }
    ]
  }'
```

**示例 5: 复杂搜索（布尔表达式+过滤+排序）**

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具 AND (乐高 OR 芭比)",
    "size": 20,
    "filters": {
      "categoryName_keyword": "玩具"
    },
    "range_filters": {
      "price": {
        "gte": 50,
        "lte": 200
      },
      "days_since_last_update": {
        "lte": 30
      }
    },
    "facets": [
      {"field": "brandName_keyword", "size": 15},
      {"field": "supplierName_keyword", "size": 10}
    ],
    "sort_by": "price",
    "sort_order": "asc",
    "debug": false
  }'
```

---

### 2. 图片搜索

**端点**: `POST /search/image`

**描述**: 基于图片相似度进行搜索，使用图片向量进行语义匹配。

#### 请求参数

```json
{
  "image_url": "string (required)",
  "size": 10,
  "filters": {},
  "range_filters": {}
}
```

#### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `image_url` | string | ✅ | - | 查询图片的 URL |
| `size` | integer | ❌ | 10 | 返回结果数量（1-100） |
| `filters` | object | ❌ | null | 精确匹配过滤器 |
| `range_filters` | object | ❌ | null | 数值范围过滤器 |

#### 响应格式

与文本搜索相同，但 `query_info` 包含图片信息：

```json
{
  "hits": [...],
  "total": 50,
  "max_score": 0.95,
  "took_ms": 120,
  "query_info": {
    "image_url": "https://example.com/image.jpg",
    "search_type": "image_similarity"
  }
}
```

#### 请求示例

```bash
curl -X POST "http://localhost:6002/search/image" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/barbie.jpg",
    "size": 20,
    "filters": {
      "categoryName_keyword": "玩具"
    },
    "range_filters": {
      "price": {
        "lte": 100
      }
    }
  }'
```

---

### 3. 搜索建议（框架）

**端点**: `GET /search/suggestions`

**描述**: 获取搜索建议（自动补全）。

**注意**: 此功能暂未实现，仅返回框架响应。

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `q` | string | ✅ | - | 搜索查询字符串（最少1个字符） |
| `size` | integer | ❌ | 5 | 建议数量（1-20） |
| `types` | string | ❌ | "query" | 建议类型（逗号分隔）：query, product, category, brand |

#### 响应格式

```json
{
  "query": "芭",
  "suggestions": [
    {
      "text": "芭比娃娃",
      "type": "query",
      "highlight": "<em>芭</em>比娃娃",
      "popularity": 850
    }
  ],
  "took_ms": 5
}
```

#### 请求示例

```bash
curl "http://localhost:6002/search/suggestions?q=芭&size=5&types=query,product"
```

---

### 4. 即时搜索（框架）

**端点**: `GET /search/instant`

**描述**: 即时搜索，边输入边搜索。

**注意**: 此功能暂未实现，调用标准搜索接口。

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `q` | string | ✅ | - | 搜索查询（最少2个字符） |
| `size` | integer | ❌ | 5 | 结果数量（1-20） |

#### 请求示例

```bash
curl "http://localhost:6002/search/instant?q=玩具&size=5"
```

---

### 5. 获取单个文档

**端点**: `GET /search/{doc_id}`

**描述**: 根据文档ID获取单个文档详情。

#### 路径参数

| 参数 | 类型 | 描述 |
|------|------|------|
| `doc_id` | string | 文档ID |

#### 响应格式

```json
{
  "id": "12345",
  "source": {
    "name": "芭比时尚娃娃",
    "price": 89.99,
    "categoryName": "玩具"
  }
}
```

#### 请求示例

```bash
curl "http://localhost:6002/search/12345"
```

---

## 管理接口

### 1. 健康检查

**端点**: `GET /admin/health`

**描述**: 检查服务健康状态。

#### 响应格式

```json
{
  "status": "healthy",
  "elasticsearch": "connected",
  "tenant_id": "tenant1"
}
```

---

### 2. 获取配置

**端点**: `GET /admin/config`

**描述**: 获取当前客户配置（脱敏）。

#### 响应格式

```json
{
  "tenant_id": "tenant1",
  "tenant_name": "Tenant1 Test Instance",
  "es_index_name": "search_tenant1",
  "num_fields": 20,
  "num_indexes": 4,
  "supported_languages": ["zh", "en", "ru"],
  "ranking_expression": "bm25() + 0.2*text_embedding_relevance()",
  "spu_enabled": false
}
```

---

### 3. 索引统计

**端点**: `GET /admin/stats`

**描述**: 获取索引统计信息。

#### 响应格式

```json
{
  "index_name": "search_tenant1",
  "document_count": 10000,
  "size_mb": 523.45
}
```

---

### 4. 查询改写规则

**端点**: `GET /admin/rewrite-rules`

**描述**: 获取当前的查询改写规则。

#### 响应格式

```json
{
  "rules": {
    "乐高": "brand:乐高 OR name:乐高",
    "玩具": "category:玩具"
  },
  "count": 2
}
```

**端点**: `POST /admin/rewrite-rules`

**描述**: 更新查询改写规则。

#### 请求格式

```json
{
  "乐高": "brand:乐高 OR name:乐高",
  "芭比": "brand:芭比 OR name:芭比"
}
```

---

## 使用示例

### Python 示例

```python
import requests

API_URL = "http://localhost:6002/search/"

# 简单搜索
response = requests.post(API_URL, json={
    "query": "芭比娃娃",
    "size": 20
})
data = response.json()
print(f"找到 {data['total']} 个结果")

# 带过滤器和分面的搜索
response = requests.post(API_URL, json={
    "query": "玩具",
    "size": 20,
    "filters": {
        "categoryName_keyword": ["玩具", "益智玩具"]
    },
    "range_filters": {
        "price": {"gte": 50, "lte": 200}
    },
    "facets": [
        {"field": "brandName_keyword", "size": 15},
        {"field": "categoryName_keyword", "size": 15}
    ],
    "sort_by": "price",
    "sort_order": "asc"
})
result = response.json()

# 处理分面结果
for facet in result.get('facets', []):
    print(f"\n{facet['label']}:")
    for value in facet['values']:
        print(f"  - {value['label']}: {value['count']}")
```

### JavaScript 示例

```javascript
// 搜索函数
async function searchProducts(query, filters, rangeFilters, facets) {
    const response = await fetch('http://localhost:6002/search/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: query,
            size: 20,
            filters: filters,
            range_filters: rangeFilters,
            facets: facets
        })
    });
    
    const data = await response.json();
    return data;
}

// 使用示例
const result = await searchProducts(
    "玩具",
    { categoryName_keyword: ["玩具"] },
    { price: { gte: 50, lte: 200 } },
    [
        { field: "brandName_keyword", size: 15 },
        { field: "categoryName_keyword", size: 15 }
    ]
);

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

// 显示搜索结果
result.hits.forEach(hit => {
    const product = hit._source;
    console.log(`${product.name} - ¥${product.price}`);
});
```

### cURL 示例

```bash
# 简单搜索
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{"query": "芭比娃娃", "size": 20}'

# 带过滤和排序
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 20,
    "filters": {"categoryName_keyword": "玩具"},
    "range_filters": {"price": {"gte": 50, "lte": 200}},
    "sort_by": "price",
    "sort_order": "asc"
  }'

# 带分面搜索
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "玩具",
    "size": 20,
    "facets": [
      {"field": "categoryName_keyword", "size": 15},
      {"field": "brandName_keyword", "size": 15}
    ]
  }'
```

---

## 布尔表达式语法

### 支持的操作符

| 操作符 | 描述 | 示例 |
|--------|------|------|
| `AND` | 所有词必须匹配 | `玩具 AND 乐高` |
| `OR` | 任意词匹配 | `芭比 OR 娃娃` |
| `ANDNOT` | 排除特定词 | `玩具 ANDNOT 电动` |
| `RANK` | 排序加权（不强制匹配） | `玩具 RANK 乐高` |
| `()` | 分组 | `玩具 AND (乐高 OR 芭比)` |

### 操作符优先级

从高到低：
1. `()` - 括号
2. `ANDNOT` - 排除
3. `AND` - 与
4. `OR` - 或
5. `RANK` - 排序

### 查询示例

```
# 简单查询
"芭比娃娃"

# AND 查询
"玩具 AND 乐高"

# OR 查询
"芭比 OR 娃娃"

# 排除查询
"玩具 ANDNOT 电动"

# 复杂查询
"玩具 AND (乐高 OR 芭比) ANDNOT 电动"

# 域查询
"brand:乐高"
"category:玩具"
"title:芭比娃娃"
```

---

## 数据模型

### 商品字段

常见的商品字段包括：

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `skuId` | long | SKU ID（主键） |
| `name` | text | 商品名称（中文） |
| `enSpuName` | text | 商品名称（英文） |
| `ruSkuName` | text | 商品名称（俄文） |
| `categoryName` | text | 类目名称 |
| `categoryName_keyword` | keyword | 类目名称（精确匹配） |
| `brandName` | text | 品牌名称 |
| `brandName_keyword` | keyword | 品牌名称（精确匹配） |
| `supplierName` | text | 供应商名称 |
| `supplierName_keyword` | keyword | 供应商名称（精确匹配） |
| `price` | double | 价格 |
| `imageUrl` | keyword | 商品图片URL |
| `create_time` | date | 创建时间 |
| `days_since_last_update` | int | 距上次更新天数 |

**注意**: 不同客户可能有不同的字段配置。

---


## 常见问题

### Q1: 如何判断一个字段应该用哪种过滤器？

**A**: 
- **精确匹配过滤器** (`filters`): 用于 KEYWORD 类型字段（如类目、品牌、标签等）
- **范围过滤器** (`range_filters`): 用于数值类型字段（如价格、库存、时间等）

### Q2: 可以同时使用多个过滤器吗？

**A**: 可以。多个过滤器之间是 AND 关系（必须同时满足）。

```json
{
  "filters": {
    "categoryName_keyword": "玩具",
    "brandName_keyword": "乐高"
  },
  "range_filters": {
    "price": {"gte": 50, "lte": 200}
  }
}
```
结果：类目是"玩具" **并且** 品牌是"乐高" **并且** 价格在50-200之间。

### Q3: 如何实现"价格小于50或大于200"的过滤？

**A**: 当前版本不支持单字段多个不连续范围。建议分两次查询或使用布尔查询。

### Q4: 分面搜索返回的 selected 字段是什么意思？

**A**: `selected` 表示该分面值是否在当前的过滤器中。前端可以用它来高亮已选中的过滤项。

### Q5: 如何使用自定义排序？

**A**: 使用 `sort_by` 和 `sort_order` 参数：

```json
{
  "query": "玩具",
  "sort_by": "price",
  "sort_order": "asc"  // 价格从低到高
}
```

常用排序字段：
- `price`: 价格
- `create_time`: 创建时间
- `days_since_last_update`: 更新时间

### Q6: 如何启用调试模式？

**A**: 设置 `debug: true`，响应中会包含 `debug_info` 字段，包含：
- 查询分析过程
- ES 查询 DSL
- ES 响应详情
- 各阶段耗时

---

## 版本历史

### v3.0 (2024-11-12)

**重大更新**：
- ✅ 移除硬编码的 `price_ranges` 逻辑
- ✅ 新增 `range_filters` 参数，支持任意数值字段的范围过滤
- ✅ 新增 `facets` 参数，替代 `aggregations`，提供简化接口
- ✅ 标准化分面搜索响应格式
- ✅ 新增 `/search/suggestions` 端点（框架）
- ✅ 新增 `/search/instant` 端点（框架）
- ❌ **移除** `aggregations` 参数（不向后兼容）

**迁移指南**：

旧接口：
```json
{
  "filters": {
    "price_ranges": ["0-50", "50-100"]
  },
  "aggregations": {
    "category_stats": {"terms": {"field": "categoryName_keyword", "size": 15}}
  }
}
```

新接口：
```json
{
  "range_filters": {
    "price": {"gte": 50, "lte": 100}
  },
  "facets": [
    {"field": "categoryName_keyword", "size": 15}
  ]
}
```

---

## 附录

### A. 支持的分析器

| 分析器 | 语言 | 描述 |
|--------|------|------|
| `chinese_ecommerce` | 中文 | Ansj 中文分词器（电商优化） |
| `english` | 英文 | 标准英文分析器 |
| `russian` | 俄文 | 俄文分析器 |
| `arabic` | 阿拉伯文 | 阿拉伯文分析器 |
| `spanish` | 西班牙文 | 西班牙文分析器 |
| `japanese` | 日文 | 日文分析器 |

### B. 字段类型

| 类型 | ES 映射 | 用途 |
|------|---------|------|
| `TEXT` | text | 全文检索 |
| `KEYWORD` | keyword | 精确匹配、聚合、排序 |
| `LONG` | long | 整数 |
| `DOUBLE` | double | 浮点数 |
| `DATE` | date | 日期时间 |
| `BOOLEAN` | boolean | 布尔值 |
| `TEXT_EMBEDDING` | dense_vector | 文本向量（1024维） |
| `IMAGE_EMBEDDING` | dense_vector | 图片向量（1024维） |