# 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 | 系统内部错误 |