daren/apps/chat/chat.md

# Chat 模块接口文档

## 概述

Chat 模块提供了一组 API，用于创建和管理对话。这包括创建新对话、发送消息、接收回答、查询历史记录等功能。所有接口都基于 REST 风格设计。

## 认证

除特殊说明外，所有接口都需要认证。请在请求头中添加认证信息：

```
Authorization: Bearer <jwt_token>
```

或

```
Authorization: Token <token>
```

## REST API接口列表

### 1. 创建会话

创建一个新的对话会话。

- **URL**: `/api/chat-history/create_conversation/`
- **方法**: `POST`
- **认证**: 不需要认证
- **响应**:
  
```json
{
  "code": 200,
  "message": "会话创建成功",
  "data": {
    "conversation_id": "uuid-string"
  }
}
```

### 2. 发送消息并接收回答

发送用户问题并获取 AI 回答。

- **URL**: `/api/chat-history/`
- **方法**: `POST`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| conversation_id | string | 是 | 会话 ID |
| question | string | 是 | 用户问题 |
| title | string | 否 | 会话标题，默认为 "New chat" |
| stream | boolean | 否 | 是否使用流式响应，默认为 true |

- **响应** (非流式):
  
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "title": "会话标题",
    "role": "assistant",
    "content": "AI回答内容",
    "created_at": "创建时间"
  }
}
```

- **响应** (流式):
  
返回 `text/event-stream` 类型的响应，包含多个 data 事件：

```
data: {"code": 200, "message": "开始流式传输", "data": {"id": "记录ID", "conversation_id": "会话ID", "content": "", "is_end": false}}

data: {"code": 200, "message": "partial", "data": {"id": "记录ID", "conversation_id": "会话ID", "title": "标题", "content": "部分内容", "is_end": false}}

...

data: {"code": 200, "message": "完成", "data": {"id": "记录ID", "conversation_id": "会话ID", "title": "标题", "role": "assistant", "content": "完整内容", "created_at": "时间", "is_end": true}}
```

### 3. 获取对话列表

获取用户的所有对话列表。

- **URL**: `/api/chat-history/`
- **方法**: `GET`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| page | integer | 否 | 页码，默认为 1 |
| page_size | integer | 否 | 每页条数，默认为 10 |

- **响应**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 总记录数,
    "page": 当前页码,
    "page_size": 每页条数,
    "results": [
      {
        "conversation_id": "会话ID",
        "message_count": 消息数量,
        "last_message": "最后一条消息内容",
        "last_time": "最后更新时间"
      }
    ]
  }
}
```

### 4. 获取对话详情

获取特定对话的所有消息。

- **URL**: `/api/chat-history/conversation_detail/`
- **方法**: `GET`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| conversation_id | string | 是 | 会话 ID |

- **响应**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "conversation_id": "会话ID",
    "title": "会话标题",
    "created_at": "创建时间",
    "messages": [
      {
        "id": "消息ID",
        "role": "用户角色(user/assistant)",
        "content": "消息内容",
        "created_at": "创建时间"
      }
    ]
  }
}
```

### 5. 搜索聊天记录

根据关键词搜索聊天记录。

- **URL**: `/api/chat-history/search/`
- **方法**: `GET`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| keyword | string | 否 | 搜索关键词 |
| start_date | string | 否 | 开始日期，格式为 YYYY-MM-DD |
| end_date | string | 否 | 结束日期，格式为 YYYY-MM-DD |
| page | integer | 否 | 页码，默认为 1 |
| page_size | integer | 否 | 每页条数，默认为 10 |

- **响应**:

```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "total": 总记录数,
    "page": 当前页码,
    "page_size": 每页条数,
    "results": [
      {
        "id": "记录ID",
        "conversation_id": "会话ID",
        "role": "角色",
        "content": "内容",
        "created_at": "创建时间",
        "metadata": {},
        "highlights": {
          "content": "高亮后的内容"
        }
      }
    ]
  }
}
```

### 6. 删除会话

删除整个会话及其所有消息。

- **URL**: `/api/chat-history/delete_conversation/`
- **方法**: `DELETE`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| conversation_id | string | 是 | 要删除的会话 ID |

- **响应**:

```json
{
  "code": 200,
  "message": "删除成功",
  "data": {
    "conversation_id": "会话ID",
    "deleted_count": 删除的消息数量
  }
}
```

### 7. 更新消息内容

更新单条消息的内容。

- **URL**: `/api/chat-history/{id}/`
- **方法**: `PUT` 或 `PATCH`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| content | string | 否 | 更新的消息内容 |
| metadata | object | 否 | 更新的元数据 |

- **响应**:

```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "role": "角色",
    "content": "更新后的内容",
    "metadata": {},
    "updated_at": "更新时间"
  }
}
```

### 8. 删除单条消息

删除单条消息（软删除）。

- **URL**: `/api/chat-history/{id}/`
- **方法**: `DELETE`
- **响应**:

```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

### 9. 更新会话标题

设置或更新会话的标题。

- **URL**: `/api/chat-history/generate-conversation-title/`
- **方法**: `GET`
- **参数**:

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| conversation_id | string | 是 | 会话 ID |
| title | string | 是 | 新标题 |

- **响应**:

```json
{
  "code": 200,
  "message": "更新会话标题成功",
  "data": {
    "conversation_id": "会话ID",
    "title": "新标题"
  }
}
```

### 10. 获取可用知识库

获取系统中可用的知识库列表。

- **URL**: `/api/chat-history/available_datasets/`
- **方法**: `GET`
- **响应**:

```json
{
  "code": 200,
  "message": "获取成功",
  "data": []
}
```

## WebSocket API

除了REST API之外，Chat模块还提供了WebSocket接口，用于实时流式获取对话回答。

### 1. 建立WebSocket连接

- **URL**: `ws://yourdomain:port/ws/chat/stream/?token=<your_token>`
- **认证**: 需要在URL参数中提供token
- **说明**: token是用户的认证token，即登录接口获取的token，通过UserToken模型验证
- **获取token**: 通过API登录接口获取token：
  ```
  POST /api/user/login/
  {
    "email": "用户邮箱",
    "password": "用户密码"
  }
  ```
  成功登录后，响应将返回token字段值

### 2. 发送消息

连接建立后，可以向WebSocket发送JSON格式的消息：

```json
{
  "conversation_id": "会话ID",
  "question": "用户问题"
}
```

### 3. 接收响应

WebSocket会返回以下JSON格式的消息：

1. 开始流式传输：
```json
{
  "code": 200,
  "message": "开始流式传输",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "content": "",
    "is_end": false
  }
}
```

2. 部分内容：
```json
{
  "code": 200,
  "message": "partial",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "content": "部分内容",
    "is_end": false
  }
}
```

3. 完成响应：
```json
{
  "code": 200,
  "message": "完成",
  "data": {
    "id": "记录ID",
    "conversation_id": "会话ID",
    "title": "会话标题",
    "role": "assistant",
    "content": "完整内容",
    "created_at": "时间",
    "is_end": true
  }
}
```

4. 错误响应：
```json
{
  "code": 500,
  "message": "错误信息",
  "data": {
    "is_end": true
  }
}
```

## 错误响应

所有接口在出错时都会返回类似的错误响应结构：

```json
{
  "code": 错误代码,
  "message": "错误描述",
  "data": null
}
```

常见错误代码：
- 400: 请求参数错误
- 401: 未认证或认证失败
- 404: 资源不存在
- 500: 服务器内部错误