lxy/hs-end
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first

Browse Source 
demo
This commit is contained in:
lxy
2025-08-25 16:01:26 +08:00
commit 5a671c4233
93 changed files with 26892 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

458
api.md Normal file
View File

@ -0,0 +1,458 @@
# 海角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
}
```