576 lines
5.2 KiB
Markdown
576 lines
5.2 KiB
Markdown
# 04-AI知识库系统_API接口设计文档.docx
|
||
|
||
《04-AI知识库系统 API 接口设计文档》
|
||
|
||
版本：V1.0
|
||
|
||
规范：RESTful API
|
||
|
||
数据格式：JSON
|
||
|
||
认证方式：JWT Token（Bearer）
|
||
|
||
字符集：UTF-8
|
||
|
||
## 第一章 接口规范
|
||
|
||
### 1.1 请求规范
|
||
|
||
Base URL
|
||
|
||
https://api.xxx.com/api/v1
|
||
|
||
Header
|
||
|
||
Content-Type: application/json
|
||
|
||
Authorization: Bearer {token}
|
||
|
||
成功返回
|
||
|
||
{
|
||
|
||
"code": 0,
|
||
|
||
"message": "success",
|
||
|
||
"data": {}
|
||
|
||
}
|
||
|
||
失败返回
|
||
|
||
{
|
||
|
||
"code": 40001,
|
||
|
||
"message": "账号已禁用",
|
||
|
||
"data": null
|
||
|
||
}
|
||
|
||
## 第二章 用户认证接口
|
||
|
||
### 2.1 发送短信验证码
|
||
|
||
POST /auth/sms/send
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"phone":"13800138000"
|
||
|
||
}
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"message":"发送成功"
|
||
|
||
}
|
||
|
||
校验规则
|
||
|
||
手机号：
|
||
|
||
必填
|
||
|
||
中国大陆手机号
|
||
|
||
限制：
|
||
|
||
60 秒内不能重复发送
|
||
|
||
每日发送次数限制（后台可配置）
|
||
|
||
### 2.2 登录
|
||
|
||
POST /auth/login
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"phone":"13800138000",
|
||
|
||
"code":"123456"
|
||
|
||
}
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"data":{
|
||
|
||
"token":"xxxxx",
|
||
|
||
"expiredAt":"2026-08-01",
|
||
|
||
"user":{
|
||
|
||
"id":1,
|
||
|
||
"name":"张三"
|
||
|
||
}
|
||
|
||
}
|
||
|
||
}
|
||
|
||
系统执行：
|
||
|
||
验证码校验
|
||
|
||
↓
|
||
|
||
首次登录？
|
||
|
||
↓
|
||
|
||
自动创建用户
|
||
|
||
↓
|
||
|
||
账号状态
|
||
|
||
↓
|
||
|
||
账号有效期
|
||
|
||
↓
|
||
|
||
登录成功
|
||
|
||
### 2.3 退出登录
|
||
|
||
POST /auth/logout
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0
|
||
|
||
}
|
||
|
||
Token：立即失效。
|
||
|
||
## 第三章 用户接口
|
||
|
||
### 3.1 获取当前用户
|
||
|
||
GET /user/profile
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"data":{
|
||
|
||
"phone":"",
|
||
|
||
"name":"",
|
||
|
||
"nickname":"",
|
||
|
||
"dailyLimit":100,
|
||
|
||
"todayUsed":35
|
||
|
||
}
|
||
|
||
}
|
||
|
||
### 3.2 修改会话标题
|
||
|
||
PUT /chat/session/title
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"sessionId":1,
|
||
|
||
"title":"直播运营技巧"
|
||
|
||
}
|
||
|
||
### 3.3 删除会话
|
||
|
||
DELETE /chat/session/{id}
|
||
|
||
系统：is_deleted=1
|
||
|
||
## 第四章 AI 对话接口
|
||
|
||
### 4.1 创建会话
|
||
|
||
POST /chat/session
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"data":{
|
||
|
||
"sessionId":1001
|
||
|
||
}
|
||
|
||
}
|
||
|
||
### 4.2 获取会话列表
|
||
|
||
GET /chat/session/list
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"data":[
|
||
|
||
{
|
||
|
||
"id":1,
|
||
|
||
"title":"直播运营",
|
||
|
||
"updatedAt":"..."
|
||
|
||
}
|
||
|
||
]
|
||
|
||
}
|
||
|
||
### 4.3 获取聊天记录
|
||
|
||
GET /chat/history
|
||
|
||
参数：sessionId
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"code":0,
|
||
|
||
"data":[
|
||
|
||
{
|
||
|
||
"role":"user",
|
||
|
||
"content":"..."
|
||
|
||
},
|
||
|
||
{
|
||
|
||
"role":"assistant",
|
||
|
||
"content":"..."
|
||
|
||
}
|
||
|
||
]
|
||
|
||
}
|
||
|
||
### 4.4 AI 问答（Streaming）
|
||
|
||
POST /chat/completions
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"sessionId":1,
|
||
|
||
"message":"直播间没人怎么办？"
|
||
|
||
}
|
||
|
||
处理流程：
|
||
|
||
次数校验
|
||
|
||
↓
|
||
|
||
账号校验
|
||
|
||
↓
|
||
|
||
权限校验
|
||
|
||
↓
|
||
|
||
飞书检索
|
||
|
||
↓
|
||
|
||
Prompt
|
||
|
||
↓
|
||
|
||
模型
|
||
|
||
↓
|
||
|
||
Streaming
|
||
|
||
Response
|
||
|
||
text/event-stream
|
||
|
||
Server Sent Events：
|
||
|
||
data:你好
|
||
|
||
data:直播间
|
||
|
||
data:可以
|
||
|
||
...
|
||
|
||
结束：
|
||
|
||
data:[DONE]
|
||
|
||
### 4.5 停止生成
|
||
|
||
POST /chat/stop
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"sessionId":1
|
||
|
||
}
|
||
|
||
系统：立即取消模型请求。
|
||
|
||
## 第五章 管理员接口
|
||
|
||
### 5.1 登录
|
||
|
||
POST /admin/login
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"username":"admin",
|
||
|
||
"password":"******"
|
||
|
||
}
|
||
|
||
### 5.2 获取首页统计
|
||
|
||
GET /admin/dashboard
|
||
|
||
参数：today, week, custom
|
||
|
||
Response
|
||
|
||
{
|
||
|
||
"totalUser":1200,
|
||
|
||
"todayUser":35,
|
||
|
||
"todayChat":560,
|
||
|
||
"token":980000
|
||
|
||
}
|
||
|
||
## 第六章 用户管理接口
|
||
|
||
获取用户列表
|
||
|
||
GET /admin/user/list
|
||
|
||
参数：phone, name, status, page, size
|
||
|
||
获取用户详情
|
||
|
||
GET /admin/user/{id}
|
||
|
||
新增用户
|
||
|
||
POST /admin/user
|
||
|
||
修改用户
|
||
|
||
PUT /admin/user
|
||
|
||
删除用户
|
||
|
||
DELETE /admin/user/{id}
|
||
|
||
批量授权知识库
|
||
|
||
POST /admin/user/kb
|
||
|
||
Request
|
||
|
||
{
|
||
|
||
"userIds":[1,2],
|
||
|
||
"knowledgeIds":[3,5],
|
||
|
||
"effectiveAt":"2026-01-01",
|
||
|
||
"expiredAt":"2027-01-01"
|
||
|
||
}
|
||
|
||
批量修改聊天次数
|
||
|
||
POST /admin/user/chat-limit
|
||
|
||
批量启用
|
||
|
||
POST /admin/user/enable
|
||
|
||
批量禁用
|
||
|
||
POST /admin/user/disable
|
||
|
||
批量删除
|
||
|
||
POST /admin/user/delete
|
||
|
||
## 第七章 知识库接口
|
||
|
||
GET /admin/knowledge/list
|
||
|
||
POST /admin/knowledge
|
||
|
||
PUT /admin/knowledge
|
||
|
||
DELETE /admin/knowledge/{id}
|
||
|
||
字段：名称, SpaceID, NodeID, 状态, 备注
|
||
|
||
## 第八章 Prompt 接口
|
||
|
||
获取：GET /admin/prompt
|
||
|
||
保存：PUT /admin/prompt
|
||
|
||
恢复默认：POST /admin/prompt/reset
|
||
|
||
## 第九章 模型接口
|
||
|
||
获取模型：GET /admin/model/list
|
||
|
||
新增模型：POST /admin/model
|
||
|
||
启用模型：POST /admin/model/enable
|
||
|
||
删除模型：DELETE /admin/model/{id}
|
||
|
||
## 第十章 系统配置接口
|
||
|
||
获取配置：GET /admin/config
|
||
|
||
修改配置：PUT /admin/config
|
||
|
||
包含：
|
||
|
||
登录有效期
|
||
|
||
每日聊天次数
|
||
|
||
AI 超时
|
||
|
||
飞书重试次数
|
||
|
||
上下文长度
|
||
|
||
是否显示引用来源
|
||
|
||
是否允许联网（一期固定关闭）
|
||
|
||
## 第十一章 操作日志接口
|
||
|
||
获取：GET /admin/log/list
|
||
|
||
查询条件：操作人, 模块, 类型, 时间范围
|
||
|
||
## 第十二章 聊天记录接口
|
||
|
||
查询：GET /admin/chat/list
|
||
|
||
详情：GET /admin/chat/{id}
|
||
|
||
导出：POST /admin/chat/export
|
||
|
||
导出字段：用户, 手机号, 会话标题, 提问, AI 回答, 提问时间, 回复时间
|
||
|
||
## 第十三章 错误码规范
|
||
|
||
《API 接口设计文档》第一版完成
|
||
|
||
这份文档定义了前后端联调所需的核心接口，包括：
|
||
|
||
登录认证
|
||
|
||
用户端接口
|
||
|
||
AI 对话（SSE 流式）
|
||
|
||
管理后台
|
||
|
||
用户管理
|
||
|
||
知识库管理
|
||
|
||
Prompt 管理
|
||
|
||
模型管理
|
||
|
||
系统配置
|
||
|
||
聊天记录
|
||
|
||
操作日志
|
||
|
||
错误码规范
|
||
|
||
## Table 1
|
||
| Code | 含义 |
|
||
| --- | --- |
|
||
| 0 | 成功 |
|
||
| 40001 | 账号禁用 |
|
||
| 40002 | 账号已过期 |
|
||
| 40003 | 验证码错误 |
|
||
| 40004 | 验证码过期 |
|
||
| 40005 | 登录失效 |
|
||
| 40006 | 今日聊天次数已用完 |
|
||
| 40007 | 无知识库权限 |
|
||
| 50001 | 飞书接口异常 |
|
||
| 50002 | AI 模型超时 |
|
||
| 50003 | AI 服务异常 |
|
||
| 50004 | 系统内部错误 |
|