# 搜索API接口对接指南

本文档为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。

## 目录

1. [快速开始](#快速开始)
2. [接口概览](#接口概览)
3. [搜索接口](#搜索接口)
4. [响应格式说明](#响应格式说明)
5. [常见场景示例](#常见场景示例)

---

## 快速开始

### 基础信息

- **Base URL**: `http://your-domain:6002` 或 `http://120.76.41.98:6002`
- **协议**: HTTP/HTTPS
- **数据格式**: JSON
- **字符编码**: UTF-8
- **请求方法**: POST（搜索接口）

### 最简单的搜索请求

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

### curl示例：带过滤与分页

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃 AND 配件",
    "size": 5,
    "from": 10,
    "filters": {
      "vendor_keyword": ["乐高", "孩之宝"]
    },
    "sort_by": "min_price",
    "sort_order": "asc"
  }'
```

### curl示例：开启调试与分面

```bash
curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃",
    "facets": ["category_keyword", "vendor_keyword"],
    "min_score": 0.2,
    "debug": true
  }'
```

---

## 接口概览

| 接口 | HTTP Method | Endpoint | 
|------|------|------|
| 搜索 | POST | `/search/` | 
| 搜索建议（框架，暂未实现） | GET | `/search/suggestions` | 
| 获取文档 | GET | `/search/{doc_id}` | 
| 健康检查 | GET | `/admin/health` | 

---

## 搜索接口

### 接口信息

- **端点**: `POST /search/`
- **描述**: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索

### 请求参数

#### 完整请求体结构

```json
{
  "tenant_id": "string (required)",
  "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"
}
```

#### 参数详细说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `tenant_id` | string | Y | - | 租户ID，用于隔离不同站点或客户的数据 |
| `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 | 排序字段名（如 `min_price`, `max_price`, `title`） |
| `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（用于分析，预留） |

### 过滤器详解

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

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

**格式**:
```json
{
  "filters": {
    "category_keyword": "玩具",                    // 单值：精确匹配
    "vendor_keyword": ["乐高", "孩之宝"],          // 数组：匹配任意值（OR）
    "product_type_keyword": "益智玩具"              // 单值：精确匹配
  }
}
```

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

**常用过滤字段**:
- `category_keyword`: 类目
- `vendor_keyword`: 品牌/供应商
- `product_type_keyword`: 商品类型
- `tags_keyword`: 标签

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

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

**格式**:
```json
{
  "range_filters": {
    "min_price": {
      "gte": 50,    // 大于等于
      "lte": 200    // 小于等于
    },
    "max_price": {
      "gt": 100     // 大于
    },
    "create_time": {
      "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
    }
  }
}
```

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

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

**常用范围字段**:
- `min_price`: 最低价格
- `max_price`: 最高价格
- `compare_at_price`: 原价
- `create_time`: 创建时间
- `update_time`: 更新时间

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

用于生成分面统计（分组聚合），常用于构建筛选器UI。

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

**高级模式**（配置对象数组）:
```json
{
  "facets": [
    {
      "field": "category_keyword",
      "size": 15,
      "type": "terms"
    },
    {
      "field": "min_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' 时需要）

### 布尔表达式语法

搜索查询支持布尔表达式，提供更灵活的搜索能力。

**支持的操作符**:

| 操作符 | 描述 | 示例 |
|--------|------|------|
| `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 芭比)"      // 复杂查询
```

---

## 响应格式说明

### 标准响应结构

```json
{
  "results": [
    {
      "product_id": "12345",
      "title": "芭比时尚娃娃",
      "handle": "barbie-doll",
      "description": "高品质芭比娃娃",
      "vendor": "美泰",
      "product_type": "玩具",
      "tags": "娃娃, 玩具, 女孩",
      "price": 89.99,
      "compare_at_price": 129.99,
      "currency": "USD",
      "image_url": "https://example.com/image.jpg",
      "in_stock": true,
      "variants": [
        {
          "variant_id": "67890",
          "title": "粉色款",
          "price": 89.99,
          "compare_at_price": 129.99,
          "sku": "BARBIE-001",
          "stock": 100,
          "options": {
            "option1": "粉色",
            "option2": "标准款"
          }
        }
      ],
      "relevance_score": 8.5
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "facets": [
    {
      "field": "category_keyword",
      "label": "category_keyword",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    }
  ],
  "query_info": {
    "original_query": "芭比娃娃",
    "detected_language": "zh",
    "translations": {
      "en": "barbie doll"
    }
  },
  "suggestions": [],
  "related_searches": [],
  "took_ms": 45,
  "performance_info": null,
  "debug_info": null
}
```

### 响应字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `results` | array | 搜索结果列表（ProductResult对象数组） |
| `results[].product_id` | string | 商品ID |
| `results[].title` | string | 商品标题 |
| `results[].price` | float | 价格（min_price） |
| `results[].variants` | array | 变体列表（SKU列表） |
| `results[].relevance_score` | float | 相关性分数 |
| `total` | integer | 匹配的总文档数 |
| `max_score` | float | 最高相关性分数 |
| `facets` | array | 分面统计结果 |
| `query_info` | object | 查询处理信息 |
| `took_ms` | integer | 搜索耗时（毫秒） |

### ProductResult字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `product_id` | string | 商品ID（SPU ID） |
| `title` | string | 商品标题 |
| `handle` | string | 商品URL handle |
| `description` | string | 商品描述 |
| `vendor` | string | 供应商/品牌 |
| `product_type` | string | 商品类型 |
| `tags` | string | 标签 |
| `price` | float | 价格（min_price） |
| `compare_at_price` | float | 原价 |
| `currency` | string | 货币单位（默认USD） |
| `image_url` | string | 主图URL |
| `in_stock` | boolean | 是否有库存（任意变体有库存即为true） |
| `variants` | array | 变体列表 |
| `relevance_score` | float | 相关性分数 |

### VariantResult字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `variant_id` | string | 变体ID（SKU ID） |
| `title` | string | 变体标题 |
| `price` | float | 价格 |
| `compare_at_price` | float | 原价 |
| `sku` | string | SKU编码 |
| `stock` | integer | 库存数量 |
| `options` | object | 选项（颜色、尺寸等） |

---

## 常见场景示例

### 场景1：商品列表页搜索

**需求**: 搜索"玩具"，按价格从低到高排序，显示前20个结果

```json
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "min_price",
  "sort_order": "asc"
}
```

### 场景2：带筛选的商品搜索

**需求**: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间

```json
{
  "query": "玩具",
  "size": 20,
  "filters": {
    "category_keyword": "益智玩具"
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  }
}
```

### 场景3：带分面的商品搜索

**需求**: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器

```json
{
  "query": "玩具",
  "size": 20,
  "facets": [
    "category_keyword",
    "vendor_keyword"
  ]
}
```

### 场景4：多条件组合搜索

**需求**: 搜索"玩具"，筛选多个品牌，价格范围，并获取分面统计

```json
{
  "query": "玩具",
  "size": 20,
  "filters": {
    "vendor_keyword": ["乐高", "孩之宝", "美泰"]
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  },
  "facets": [
    {
      "field": "category_keyword",
      "size": 15
    },
    {
      "field": "min_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}
      ]
    }
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}
```

### 场景5：布尔表达式搜索

**需求**: 搜索包含"玩具"和"乐高"的商品，排除"电动"

```json
{
  "query": "玩具 AND 乐高 ANDNOT 电动",
  "size": 20
}
```

### 场景6：分页查询

**需求**: 获取第2页结果（每页20条）

```json
{
  "query": "玩具",
  "size": 20,
  "from": 20
}
```

---

---

## 其他接口

### 搜索建议（框架）

- **端点**: `GET /search/suggestions`
- **描述**: 返回搜索建议（自动补全/热词）。当前为框架实现，接口和响应格式已经固定，可平滑扩展。

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `q` | string | Y | - | 查询字符串（至少 1 个字符） |
| `size` | integer | N | 5 | 返回建议数量（1-20） |
| `types` | string | N | `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"
```

---

### 即时搜索（框架）

- **端点**: `GET /search/instant`
- **描述**: 边输入边搜索，采用轻量参数响应当前输入。底层复用标准搜索能力。

#### 查询参数

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

#### 请求示例

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

---

### 获取单个文档

- **端点**: `GET /search/{doc_id}`
- **描述**: 根据文档 ID 获取单个商品详情，用于点击结果后的详情页或排查问题。

#### 路径参数

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

#### 响应示例

```json
{
  "id": "12345",
  "source": {
    "title": "芭比时尚娃娃",
    "min_price": 89.99,
    "category_keyword": "玩具"
  }
}
```

#### 请求示例

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

---

## 管理接口

### 健康检查

- **端点**: `GET /admin/health`
- **描述**: 检查服务与依赖（如 Elasticsearch）状态。

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

---

### 获取配置

- **端点**: `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
}
```

---

### 索引统计

- **端点**: `GET /admin/stats`
- **描述**: 获取索引文档数量与磁盘大小，方便监控。

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

---

## 数据模型

### 商品字段

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `product_id` | keyword | 商品 ID（SPU） |
| `sku_id` | keyword/long | SKU ID（主键） |
| `title` | text | 商品名称（中文） |
| `en_title` | text | 商品名称（英文） |
| `ru_title` | text | 商品名称（俄文） |
| `category_keyword` | keyword | 类目（精确匹配） |
| `vendor_keyword` | keyword | 品牌/供应商（精确匹配） |
| `product_type_keyword` | keyword | 商品类型 |
| `tags_keyword` | keyword | 标签 |
| `min_price` | double | 最低价格 |
| `max_price` | double | 最高价格 |
| `compare_at_price` | double | 原价 |
| `create_time` | date | 创建时间 |
| `update_time` | date | 更新时间 |
| `in_stock` | boolean | 是否有库存 |
| `text_embedding` | dense_vector | 文本向量（1024 维） |
| `image_embedding` | dense_vector | 图片向量（1024 维） |

> 不同租户可自定义字段名称，但最佳实践是对可过滤字段建立 `*_keyword` 版本，对可排序字段显式建 keyword/数值映射。

---

## 附录

### 常用字段列表

#### 过滤字段（使用 `*_keyword` 后缀）

- `category_keyword`: 类目
- `vendor_keyword`: 品牌/供应商
- `product_type_keyword`: 商品类型
- `tags_keyword`: 标签

#### 范围字段

- `min_price`: 最低价格
- `max_price`: 最高价格
- `compare_at_price`: 原价
- `create_time`: 创建时间
- `update_time`: 更新时间

#### 排序字段

- `min_price`: 最低价格
- `max_price`: 最高价格
- `title`: 标题（字母序）
- `create_time`: 创建时间
- `update_time`: 更新时间
- `relevance_score`: 相关性分数（默认）

### 支持的分析器

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

### 字段类型速查

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