1818web-hoduan/docs/search-api.md

# 内容搜索API接口文档

## 概述

本系统提供了统一的内容搜索功能，支持搜索工作流和课程两种类型的内容。所有搜索接口均支持匿名访问，无需登录认证。

## 接口列表

### 1. 基础搜索接口

**GET** `/user/search`

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| keyword | String | 是 | - | 搜索关键词，至少2个字符 |
| type | String | 否 | all | 内容类型：all/course/workflow |
| category | String | 否 | - | 分类过滤 |
| freeOnly | Boolean | 否 | false | 是否仅显示免费内容 |
| sortBy | String | 否 | relevance | 排序方式：relevance/createTime/updateTime/viewCount/likeCount |
| sortOrder | String | 否 | desc | 排序方向：asc/desc |
| page | Integer | 否 | 1 | 页码，从1开始 |
| size | Integer | 否 | 20 | 每页数量，最大100 |

#### 请求示例

```http
GET /user/search?keyword=AI图像处理&type=all&freeOnly=false&page=1&size=20
```

#### 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "total": 156,
    "page": 1,
    "size": 20,
    "totalPages": 8,
    "keyword": "AI图像处理",
    "items": [
      {
        "id": 1,
        "type": "course",
        "title": "AI图像处理入门课程",
        "description": "学习AI图像处理的基础知识和实践技巧",
        "coverUrl": "https://example.com/cover1.jpg",
        "price": "29.99",
        "category": "人工智能",
        "isFree": false,
        "likeCount": 2300,
        "level": 1,
        "duration": "15:30",
        "viewCount": 12500,
        "commentCount": 856,
        "vipType": "normal",
        "creator": {
          "id": "17543607206742139",
          "username": "张三",
          "avatarUrl": "https://example.com/avatar1.jpg"
        },
        "createTime": "2024-01-15T10:30:00",
        "updateTime": "2024-01-15T10:30:00"
      },
      {
        "id": 2,
        "type": "workflow",
        "title": "智能图像生成工作流",
        "description": "基于AI的智能图像生成工作流，支持多种图像风格转换",
        "coverUrl": "https://example.com/cover2.jpg",
        "price": "19.99",
        "category": "人工智能",
        "isFree": false,
        "likeCount": 1250,
        "rating": 5,
        "creator": {
          "id": "17543607206742140",
          "username": "李四",
          "avatarUrl": "https://example.com/avatar2.jpg"
        },
        "createTime": "2024-01-16T14:20:00",
        "updateTime": "2024-01-16T14:20:00"
      }
    ]
  }
}
```

### 2. 高级搜索接口

**POST** `/user/search`

#### 请求体

```json
{
  "keyword": "AI图像处理",
  "type": "all",
  "category": "人工智能",
  "freeOnly": false,
  "sortBy": "relevance",
  "sortOrder": "desc",
  "page": 1,
  "size": 20
}
```

#### 响应格式

与GET接口相同。

### 3. 搜索统计接口

**GET** `/user/search/stats`

#### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| keyword | String | 是 | - | 搜索关键词 |
| type | String | 否 | all | 内容类型 |
| category | String | 否 | - | 分类过滤 |
| freeOnly | Boolean | 否 | false | 是否仅显示免费内容 |

#### 请求示例

```http
GET /user/search/stats?keyword=AI图像处理&type=all
```

#### 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "courseCount": 89,
    "workflowCount": 67,
    "totalCount": 156,
    "categoryStats": [
      {
        "categoryName": "人工智能",
        "count": 45
      },
      {
        "categoryName": "图像处理",
        "count": 32
      },
      {
        "categoryName": "机器学习",
        "count": 28
      }
    ]
  }
}
```

## 数据结构说明

### SearchResultItem

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 内容ID |
| type | String | 内容类型：course/workflow |
| title | String | 标题/名称 |
| description | String | 描述 |
| coverUrl | String | 封面图URL |
| price | String | 价格 |
| category | String | 分类 |
| isFree | Boolean | 是否免费 |
| likeCount | Integer | 点赞数 |
| level | Integer | 访问级别（仅课程） |
| duration | String | 课程时长（仅课程） |
| viewCount | Integer | 观看次数（仅课程） |
| commentCount | Integer | 评论数（仅课程） |
| vipType | String | VIP类型（仅课程） |
| rating | Integer | 评分（仅工作流） |
| creator | CreatorInfo | 创建者信息 |
| createTime | String | 创建时间 |
| updateTime | String | 更新时间 |

### CreatorInfo

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | String | 创建者ID |
| username | String | 创建者用户名 |
| avatarUrl | String | 创建者头像URL |

### VIP类型说明

| level值 | vipType | 说明 |
|---------|---------|------|
| 0 | free | 免费用户 |
| 1 | normal | 普通用户 |
| 2 | vip | VIP用户 |
| 3+ | svip | 超级VIP用户 |

## 功能特性

### 1. 多类型内容支持
- 支持同时搜索课程和工作流
- 可通过`type`参数过滤特定类型内容
- 返回结果中明确标识内容类型

### 2. 智能搜索
- 支持标题、描述、分类的模糊匹配
- 相关度排序算法优化搜索结果
- 支持多种排序方式

### 3. 高级过滤
- 分类过滤：按内容分类筛选
- 免费内容过滤：仅显示免费内容
- 创建者信息：显示内容创建者详情

### 4. 分页支持
- 灵活的分页参数控制
- 返回完整的分页信息
- 支持大数据量搜索

### 5. 统计信息
- 提供搜索结果统计
- 分类分布统计
- 各类型内容数量统计

## 使用建议

### 1. 搜索优化
- 使用具体的关键词获得更准确的结果
- 结合分类过滤提高搜索精度
- 合理使用排序参数优化用户体验

### 2. 性能考虑
- 建议使用适当的页面大小（10-50）
- 避免过于宽泛的搜索关键词
- 优先使用GET接口进行基础搜索

### 3. 前端集成
- 实现搜索建议和自动补全
- 提供搜索历史记录
- 支持搜索结果的多种展示方式

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 400 | 请求参数错误（如关键词过短、类型无效等） |
| 500 | 服务器内部错误 |

## 注意事项

1. 所有搜索接口均支持匿名访问，无需身份认证
2. 搜索关键词最少需要2个字符
3. 搜索结果仅包含已审核通过的公开内容
4. 接口返回的价格字段为字符串格式
5. 创建者信息可能为空（对于已删除的用户账户）