hs-end/api.md

# 海角AI - API接口文档

## 用户认证模块

### 用户登录

**功能描述**: 用户通过邮箱和密码进行登录认证，登录成功后返回token和用户基本信息

**入参**:
- `email`: string - 用户邮箱地址
- `password`: string - 用户密码

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.token`: string - 访问令牌
- `body.user`: object - 用户信息对象
- `body.user.id`: int - 用户ID
- `body.user.nickname`: string - 用户昵称
- `body.user.email`: string - 用户邮箱
- `body.user.avatar`: string - 用户头像URL
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/auth/login  
**请求方式**: POST

---

### 用户注册

**功能描述**: 新用户注册，创建账户并返回用户信息

**入参**:
- `email`: string - 用户邮箱地址
- `password`: string - 用户密码
- `nickname`: string - 用户昵称

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.user_id`: int - 新创建的用户ID
- `body.token`: string - 访问令牌
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/auth/register  
**请求方式**: POST

---

### 用户登出

**功能描述**: 用户登出，使当前token失效

**入参**: 无

**返回参数**:
- `error`: int - 错误码，0表示成功
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/auth/logout  
**请求方式**: POST

---

### 获取用户信息

**功能描述**: 获取当前登录用户的详细信息

**入参**: 无（通过Authorization Header传递token）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.user_id`: int - 用户ID
- `body.nickname`: string - 用户昵称
- `body.email`: string - 用户邮箱
- `body.avatar`: string - 用户头像URL
- `body.created_at`: int - 注册时间戳
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/user/info  
**请求方式**: GET

---

## 聊天模块

### 创建会话

**功能描述**: 创建新的聊天会话，用于组织对话

**入参**:
- `title`: string - 会话标题

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.session_id`: string - 会话ID
- `body.title`: string - 会话标题
- `body.created_at`: int - 创建时间戳
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/session  
**请求方式**: POST

---

### 发送消息

**功能描述**: 向指定会话发送消息，AI会根据消息内容和配置参数生成回复

**入参**:
- `session_id`: string - 会话ID
- `content`: string - 消息内容
- `model`: string - 使用的AI模型，默认为"Hunyuan"
- `deep_thinking`: bool - 是否启用深度思考模式
- `web_search`: bool - 是否启用联网搜索

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.user_message_id`: string - 用户消息ID
- `body.ai_response`: object - AI回复对象
- `body.ai_response.id`: string - AI消息ID
- `body.ai_response.content`: string - AI回复内容
- `body.ai_response.timestamp`: int - 回复时间戳
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/send  
**请求方式**: POST

---

### 获取会话列表

**功能描述**: 获取用户的所有聊天会话列表，支持分页和关键词搜索

**入参**:
- `page`: int - 页码（默认1）
- `page_size`: int - 每页数量（默认20）
- `keyword`: string - 搜索关键词（可选）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.sessions`: array - 会话列表
- `body.sessions[].id`: string - 会话ID
- `body.sessions[].title`: string - 会话标题
- `body.sessions[].message_count`: int - 消息数量
- `body.sessions[].last_message_time`: int - 最后消息时间戳
- `body.total`: int - 总数量
- `body.has_more`: bool - 是否还有更多
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/sessions  
**请求方式**: GET

---

### 获取会话消息

**功能描述**: 获取指定会话的消息历史记录，支持分页

**入参**:
- `session_id`: string - 会话ID
- `page`: int - 页码（默认1）
- `page_size`: int - 每页数量（默认50）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.messages`: array - 消息列表
- `body.messages[].id`: string - 消息ID
- `body.messages[].role`: string - 消息角色（user/assistant）
- `body.messages[].content`: string - 消息内容
- `body.messages[].timestamp`: int - 消息时间戳
- `body.messages[].is_favorited`: bool - 是否已收藏
- `body.total`: int - 总数量
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/messages  
**请求方式**: GET

---

### 删除会话

**功能描述**: 删除指定的聊天会话及其所有消息

**入参**: 无（会话ID通过URL路径传递）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/session/{session_id}  
**请求方式**: DELETE

---

### 清空会话

**功能描述**: 清空指定会话的所有消息，但保留会话本身

**入参**: 无（会话ID通过URL路径传递）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/chat/session/{session_id}/clear  
**请求方式**: POST

---

## 收藏模块

### 收藏消息

**功能描述**: 将指定消息添加到收藏列表

**入参**:
- `message_id`: string - 消息ID
- `session_id`: string - 会话ID

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.favorite_id`: string - 收藏记录ID
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/favorites/add  
**请求方式**: POST

---

### 取消收藏

**功能描述**: 从收藏列表中移除指定消息

**入参**:
- `message_id`: string - 消息ID

**返回参数**:
- `error`: int - 错误码，0表示成功
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/favorites/remove  
**请求方式**: DELETE

---

### 获取收藏列表

**功能描述**: 获取用户的所有收藏消息列表，支持分页

**入参**:
- `page`: int - 页码（默认1）
- `page_size`: int - 每页数量（默认20）

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.favorites`: array - 收藏列表
- `body.favorites[].id`: string - 收藏记录ID
- `body.favorites[].message_id`: string - 消息ID
- `body.favorites[].content`: string - 消息内容
- `body.favorites[].session_title`: string - 所属会话标题
- `body.favorites[].created_at`: int - 收藏时间戳
- `body.total`: int - 总数量
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/favorites/list  
**请求方式**: GET

---

## 文件上传模块

### 上传文件

**功能描述**: 上传文件（支持txt、pdf、md等格式）用于AI分析和处理

**入参**:
- `file`: file - 上传的文件
- `session_id`: string - 关联的会话ID

**返回参数**:
- `error`: int - 错误码，0表示成功
- `body`: object - 响应数据
- `body.file_id`: string - 文件ID
- `body.filename`: string - 文件名
- `body.file_size`: int - 文件大小（字节）
- `body.file_type`: string - 文件类型
- `body.upload_time`: int - 上传时间戳
- `message`: string - 响应消息
- `success`: bool - 是否成功

**url地址**: /api/files/upload  
**请求方式**: POST

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | 用户不存在 |
| 1003 | 密码错误 |
| 1004 | 邮箱已存在 |
| 1005 | Token无效或已过期 |
| 2001 | 会话不存在 |
| 2002 | 消息发送失败 |
| 2003 | 文件上传失败 |
| 2004 | 文件格式不支持 |
| 2005 | 文件大小超出限制 |
| 3001 | 收藏失败 |
| 3002 | 收藏记录不存在 |
| 5000 | 服务器内部错误 |
| 5001 | AI服务不可用 |
| 5002 | 网络搜索服务不可用 |

---

## 通用响应格式

所有API接口都采用统一的响应格式：

```json
{
  "error": 0,
  "body": {
    // 具体的响应数据
  },
  "message": "操作成功",
  "success": true
}
```

## 认证说明

除了登录和注册接口外，其他接口都需要在请求头中携带Authorization：

```
Authorization: Bearer <token>
```

## 基础信息

- **基础URL**: http://localhost:8080
- **超时时间**: 10秒
- **默认Content-Type**: application/json
- **支持的AI模型**: Hunyuan、基础模型、增强模型

## 请求示例

### 登录请求示例

```javascript
// 请求
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

// 响应
{
  "error": 0,
  "body": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "nickname": "用户昵称",
      "email": "user@example.com",
      "avatar": "https://example.com/avatar.jpg"
    }
  },
  "message": "登录成功",
  "success": true
}
```

### 发送消息请求示例

```javascript
// 请求
POST /api/chat/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "session_id": "session_123",
  "content": "你好，请帮我解释一下Vue3的组合式API",
  "model": "Hunyuan",
  "deep_thinking": true,
  "web_search": false
}

// 响应
{
  "error": 0,
  "body": {
    "user_message_id": "msg_456",
    "ai_response": {
      "id": "msg_789",
      "content": "Vue3的组合式API是一种新的组织组件逻辑的方式...",
      "timestamp": 1692345678
    }
  },
  "message": "消息发送成功",
  "success": true
}
```

### 文件上传请求示例

```javascript
// 请求
POST /api/files/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

FormData:
- file: [选择的文件]
- session_id: "session_123"

// 响应
{
  "error": 0,
  "body": {
    "file_id": "file_456",
    "filename": "document.pdf",
    "file_size": 1024000,
    "file_type": "application/pdf",
    "upload_time": 1692345678
  },
  "message": "文件上传成功",
  "success": true
}
```