5.2 KiB
04-AI知识库系统_API接口设计文档.docx
《04-AI知识库系统 API 接口设计文档》
版本：V1.0
规范：RESTful API
数据格式：JSON
认证方式：JWT Token（Bearer）
字符集：UTF-8
第一章 接口规范
1.1 请求规范
Base URL
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 | 系统内部错误 |