Start AI knowledge base v2 workspace

ai_knowledge_base_v2/extracted/04-AI知识库系统_API接口设计文档.md

@@ -0,0 +1,575 @@
+# 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 | 系统内部错误 |