Files

guxz a8e28e513d 1.修复创建多个向量库2.查看试卷没有用户答案3.向量化自动出题

2026-06-11 21:50:27 +08:00

60 KiB

Raw Permalink Blame History

知识库管理系统 - 完整接口文档

文档信息

项目	内容
文档名称	知识库管理系统完整接口文档
版本号	V2.16.0
发布日期	2026-06-05
文档状态	正式发布
接口基础路径	`/api`
认证方式	Bearer Token (JWT)

一、认证说明

1.1 认证流程

所有接口（除登录接口外）均需要在请求头中携带有效的JWT Token：

Authorization: Bearer <token>

Token获取方式：

通过 /api/auth/login 接口登录获取
Token有效期为24小时

1.2 通用请求头

请求头	类型	必填	说明
Content-Type	string	是	application/json 或 multipart/form-data
Authorization	string	是	Bearer Token认证信息

1.3 通用响应格式

{
  "code": 200,
  "message": "成功",
  "data": {},
  "timestamp": "2026-05-17 10:00:00"
}

响应状态码说明：

状态码	说明
200	成功
400	请求参数错误
401	未授权/Token无效
403	权限不足
404	资源不存在
500	服务器内部错误

二、认证接口

2.1 登录

接口路径: POST /api/auth/login

请求体:

{
  "username": "admin",
  "password": "123456"
}

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc3ODQzNDg1MCwiZXhwIjoxNzc4NDQyMDUwfQ.q38XpqBPFMrYTuupyTN-trR4p_e80yyNLw2reuybPov6A-EBvmFtXjh_l61hCrLax6Zx6KrdAVFHC9gtNQVLjg",
    "user": {
      "id": 1,
      "username": "admin",
      "role": 1
    }
  },
  "timestamp": "2026-05-17 10:00:00"
}

三、向量库管理接口

模块说明

向量库（也称知识库）是本系统的核心概念，所有向量库的管理操作都通过本模块完成。

核心设计：

创建/更新/删除向量库时，先调用AI端接口，再同步到 knowledge_base_path 表
knowledge_base_path 表存储向量库的元信息（部门、公开/私密、属于公司或个人等）

基础路径：/api/collection

3.1 获取向量库列表

接口路径: GET /api/collection

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "name": "public_kb",
      "displayName": "公开知识库",
      "documentCount": 150,
      "department": "公共部门",
      "description": "全员可访问",
      "ownerType": "department",
      "visibility": "public",
      "uploader": "1",
      "fileSize": 5242880,
      "createTime": "2026-01-01T10:00:00",
      "updateTime": "2026-01-01T10:00:00"
    }
  ],
  "timestamp": "2026-05-17 10:00:00"
}

3.2 创建向量库

接口路径: POST /api/collection

请求参数:

参数名	类型	必填	说明
name	String	是	向量库名称（唯一）
displayName	String	否	显示名称，默认使用name
department	String	否	所属部门，有值时ownerType为department
description	String	否	描述信息

请求示例:

POST /api/collection?name=dept_hr&displayName=人力资源知识库&department=人事部门&description=人力资源部专用知识库
Authorization: Bearer <token>

3.3 修改向量库

接口路径: PUT /api/collection/{name}

请求参数:

参数名	类型	必填	说明
displayName	String	否	显示名称
department	String	否	所属部门
description	String	否	描述信息

3.4 删除向量库

接口路径: DELETE /api/collection/{name}

3.5 文件向量化（单文件）

接口路径: POST /api/collection/{name}/vectorize

请求参数:

参数名	类型	必填	说明
fileId	Long	是	文件ID

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "success": true,
    "message": "文件已成功解析并存储到向量库",
    "fileId": 1,
    "fileName": "考勤制度.pdf",
    "collection": "public_kb",
    "fileSize": 1024000,
    "chunkCount": 15,
    "path": "public_kb/考勤制度.pdf"
  },
  "timestamp": "2026-05-17 10:00:00"
}

3.6 批量文件向量化

接口路径: POST /api/collection/{name}/vectorize/batch

请求参数:

参数名	类型	必填	说明
fileIds	List	是	文件ID列表

3.7 获取文档列表

接口路径: GET /api/collection/{name}/documents

3.8 删除文档

接口路径: DELETE /api/collection/{name}/documents/{filename}

请求参数:

参数	类型	必填	说明
name	String	是	向量库名称
filename	String	是	文档文件名
fileId	Long	否	文件ID（优先使用，避免同名文件删除错误）

说明: 删除文档时优先根据 fileId 查找记录，若未提供 fileId 则回退到 collection+filename 查找，避免同名文件删除错误。

3.9 废止文档

接口路径: POST /api/collection/{name}/documents/{filename}/deprecate

3.10 恢复已废止文档

接口路径: POST /api/collection/{name}/documents/{filename}/restore

3.11 获取文档版本历史

接口路径: GET /api/collection/{name}/documents/{filename}/versions

3.12 获取文档切片列表

接口路径: GET /api/collection/{name}/documents/{filename}/chunks

请求参数:

参数名	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页数量

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "chunks": [
      {
        "id": "chunk_001",
        "document": "文档内容摘要...",
        "metadata": {
          "chunk_id": "chunk_001",
          "chunk_type": "text",
          "collection": "public_kb",
          "page": 1,
          "source": "文档名.pdf",
          "status": "active"
        },
        "status": "active",
        "version": "v1"
      }
    ],
    "collection": "public_kb",
    "document_id": "public_kb/文档名.pdf",
    "total": 25
  },
  "timestamp": "2026-05-17 10:00:00"
}

3.13 新增切片

接口路径: POST /api/collection/{name}/chunks

请求参数:

参数名	类型	必填	说明
content	String	是	切片内容
section	String	否	章节信息

3.14 修改切片

接口路径: PUT /api/collection/{name}/chunks/{chunkId}

请求参数:

参数名	类型	必填	说明
content	String	否	新内容
section	String	否	章节信息

3.15 删除切片

接口路径: DELETE /api/collection/{name}/chunks/{chunkId}

四、文件管理接口

基础路径：/api/file

4.1 查询文件详情

接口路径: GET /api/file/{id}

请求参数:

参数名	类型	必填	说明
id	Long	是	文件ID

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "fileName": "test.pdf",
    "filePath": "/uploads/test.pdf",
    "fileSize": 1024000,
    "fileType": "application/pdf",
    "extension": "pdf",
    "description": "测试文件",
    "isPublic": true,
    "status": 1,
    "auditStatus": 1,
    "processStatus": "INDEXED",
    "examStatus": "COMPLETED",
    "createTime": "2026-05-17T10:00:00"
  },
  "timestamp": "2026-05-17 10:00:00"
}

4.2 文件上传

接口路径: POST /api/file/upload

请求参数:

参数名	类型	必填	说明
file	MultipartFile	是	文件内容
deptId	Long	否	部门ID（管理员上传制度文件时指定）
description	String	否	文件描述
isPublic	Boolean	否	是否公开，默认true

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "fileName": "test.pdf",
    "filePath": "/uploads/test.pdf",
    "fileSize": 1024000,
    "fileType": "application/pdf",
    "status": 1
  },
  "timestamp": "2026-05-17 10:00:00"
}

4.3 文件列表分页查询

接口路径: GET /api/file/page

请求参数:

参数名	类型	必填	默认值	说明
pageNum	Integer	否	1	页码
pageSize	Integer	否	10	每页数量
fileName	String	否	-	文件名模糊查询
status	Integer	否	-	文件状态
auditStatus	Integer	否	-	审核状态

4.4 获取文件信息

接口路径: GET /api/file/info/{id}

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "fileName": "test.pdf",
    "filePath": "/uploads/test.pdf",
    "fileSize": 1024000,
    "fileType": "application/pdf",
    "extension": "pdf",
    "description": "测试文件",
    "isPublic": true,
    "status": 1,
    "auditStatus": 1,
    "processStatus": "INDEXED",
    "examStatus": "COMPLETED",
    "createTime": "2026-05-17T10:00:00"
  },
  "timestamp": "2026-05-17 10:00:00"
}

4.5 文件下载

接口路径: GET /api/file/download/{id}

返回类型: 文件流

4.6 文件预览

接口路径: GET /api/file/preview/{id}

返回类型: 文件流（支持浏览器预览的格式）

4.7 获取文件文本内容

接口路径: GET /api/file/text/{id}

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "content": "文档文本内容...",
    "pageCount": 10
  },
  "timestamp": "2026-05-17 10:00:00"
}

4.8 获取文件内容（二进制）

接口路径: GET /api/file/content/{id}

功能说明: 获取文件的二进制内容，供后端服务使用

返回类型: byte[]

4.9 文件RAG流式问答

接口路径: POST /api/file/rag/stream

请求参数:

参数名	类型	必填	说明
message	String	是	用户提问内容

请求示例:

POST /api/file/rag/stream?message=请总结这份文档的内容
Authorization: Bearer <token>

返回类型: Server-Sent Events (SSE)

4.10 文件审核通过

接口路径: POST /api/file/audit/approve/{id}

4.11 文件审核拒绝

接口路径: POST /api/file/audit/reject/{id}

请求体:

{
  "rejectReason": "内容不符合要求"
}

4.12 获取待审核文件列表

接口路径: GET /api/file/audit/pending

请求参数:

参数名	类型	必填	默认值	说明
pageNum	Integer	否	1	页码
pageSize	Integer	否	10	每页数量

4.13 更新文件信息

接口路径: PUT /api/file/{id}

请求体:

{
  "isPublic": true,
  "description": "更新后的描述"
}

4.14 删除文件

接口路径: DELETE /api/file/{id}

五、知识库访问控制接口

基础路径：/api/collection-access

说明：此模块负责查询用户可访问的知识库列表，实现基于部门权限的访问控制。

5.1 分页查询知识库列表

接口路径: GET /api/collection-access/page

请求参数:

参数名	类型	必填	默认值	说明
pageNum	Integer	否	1	页码，从1开始
pageSize	Integer	否	10	每页记录数
name	String	否	-	知识库名称（模糊查询）
department	String	否	-	部门
ownerType	String	否	-	所有者类型：department/personal
visibility	String	否	-	可见性：public/private

5.2 获取知识库详情

接口路径: GET /api/collection-access/{id}

5.3 获取用户可访问的知识库列表

接口路径: GET /api/collection-access/accessible

功能说明：根据当前登录用户的部门信息，返回其可访问的所有知识库列表，包括：

用户所属部门的公开知识库
公共部门的知识库（所有用户都可访问）
用户个人的知识库

响应示例:

{
  "code": 200,
  "message": "成功",
  "data": {
    "collections": [
      {
        "name": "public_kb",
        "displayName": "公开知识库",
        "department": "公共部门",
        "description": "全员可访问",
        "createTime": "2026-01-01T10:00:00"
      },
      {
        "name": "dept",
        "displayName": "部门知识库",
        "department": "人事部门",
        "description": "人事部门专用",
        "createTime": "2026-05-16T13:44:10"
      }
    ],
    "total": 2
  },
  "timestamp": "2026-05-17 10:00:00"
}

六、AI流式问答接口

6.1 基本信息

属性	说明
接口名称	AI流式问答
描述	向AI服务发起流式问答请求，实时返回处理过程，完成后自动保存到数据库
请求方法	POST
URL路径	/api/ai/chat/stream
Content-Type	application/json
返回格式	Server-Sent Events (SSE)

6.2 请求参数

参数名	类型	必填	说明
message	String	是	用户提问内容
session_id	String	否	会话ID，用于多轮对话，不传则自动生成
id	String	否	自定义请求ID，用于跟踪请求

请求示例:

{
  "message": "请介绍一下这个知识库管理系统",
  "session_id": "sess_1777600000000_abc123",
  "id": "custom_req_001"
}

6.3 流式事件类型

事件类型	说明
start	对话开始事件
connected	RAG服务连接成功
thinking	AI思考中
searching	知识库检索中
sources	检索到的来源信息（仅前端展示用，不写入引用表）
chunk	流式内容片段
result/finish	最终结果（包含 answer / citations / images，将写入数据库）
error	错误信息

finish 事件核心字段说明：

字段	类型	说明
answer	String	AI生成的回答文本（含 `[ref:chunk_id]` 引用标记，前端可解析为可点击引用）
citations	Array	真正被引用的切片列表，将写入 `context_reference` 表；每个元素包含 `chunk_id`、`chunk_index`、`source`、`collection`、`doc_type`、`section`、`chunk_type`、`page` 等字段
images	Array	回答中包含的图片列表，将写入 `context_image` 表；每个元素包含 `image_id`、`url`、`source`、`page`、`section`、`description`、`score`、`collection` 等字段
duration_ms	Integer	回答耗时（毫秒），写入 `context_message.duration_ms`

重要数据流程（保存时自动执行）：

context_reference.preview 自动填充：对 citations 中每个引用，系统自动调用 RAG 预览接口 GET /documents/{path}/preview?chunk_index=N&context=0，将目标切片的完整正文写入 preview 字段，供前端定位展示。若接口失败，preview 写入失败信息。
context_message 无 sources 字段：旧版 sources 已移除，仅在流式事件中返回来源提示信息用于前端展示。
context_image 字段精简：仅保留 image_id、path、source、page、section、chunk_type、description、score、collection、create_time；已移除 filename、size_bytes、format、page_end、type、full_description 等冗余字段。

七、AI 会话管理接口

基础路径：/api/ai

7.1 获取用户会话列表

接口路径: GET /api/ai/sessions?page=1&pageSize=10

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	10	每页数量

返回结构:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "sessionId": "sess_1780410472658_9qg9a9hhp",
      "userId": 1,
      "createTime": "2026-06-02T14:27:53"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 10,
  "pages": 1
}

7.2 获取会话详情

接口路径: GET /api/ai/session/{sessionId}?page=1&pageSize=20

路径参数:

参数	类型	必填	说明
sessionId	String	是	会话ID

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页消息数

返回结构:

{
  "success": true,
  "data": [
    {
      "id": 175,
      "conversationId": 65,
      "role": "assistant",
      "content": "用户问: xxx",
      "messageType": "rag",
      "isFinished": 1,
      "answer": "根据参考资料...",
      "images": "[{\"image_id\":\"xxx\",\"url\":\"/api/image/xxx/data\"}]",
      "durationMs": 75512,
      "createTime": "2026-06-02T14:29:09"
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 20,
  "pages": 1
}

说明：context_message 无 sources 字段；图片信息在 images 字段中（JSON数组字符串）。

7.3 获取消息文件来源列表

接口路径: GET /api/ai/message/{messageId}/sources

路径参数:

参数	类型	必填	说明
messageId	Long	是	消息ID（来自 context_message.id）

返回结构（按文档名称聚合，去重显示）:

{
  "success": true,
  "data": [
    {
      "docName": "1.docx",
      "docType": "other",
      "referenceCount": 5,
      "pages": "1-86"
    },
    {
      "docName": "2.docx",
      "docType": "other",
      "referenceCount": 3,
      "pages": "1"
    }
  ],
  "total": 2
}

说明：此接口从 context_reference 表按文档聚合查询，不依赖已移除的 context_message.sources 字段。

7.4 获取消息引用信息

接口路径: GET /api/ai/message/{messageId}/references?docName=xxx

路径参数:

参数	类型	必填	说明
messageId	Long	是	消息ID

请求参数:

参数	类型	必填	说明
docName	String	否	按文档名称过滤

返回结构:

{
  "success": true,
  "data": [
    {
      "id": 440,
      "messageId": 178,
      "chunkId": "1.docx_86",
      "chunkIndex": 86,
      "collection": "dept_1_kb",
      "docName": "1.docx",
      "docType": "other",
      "page": 1,
      "section": "3.1 权重计算公式",
      "chunkType": "text",
      "excerpt": "一级指标合计权重不低于70%。",
      "preview": "完整的目标切片正文内容...",
      "score": 0.838,
      "createTime": "2026-06-04T15:52:49"
    }
  ],
  "total": 5
}

关键字段说明：

字段	说明
`chunkId`	切片唯一标识，格式：`{docName}_{chunkIndex}`
`preview`	目标切片完整正文（通过 RAG 预览接口自动获取），若接口失败则写入失败信息
`score`	相关性评分
`excerpt`	切片摘要内容

7.5 获取会话所有引用

接口路径: GET /api/ai/session/{sessionId}/references

路径参数:

参数	类型	必填	说明
sessionId	String	是	会话ID

说明：返回会话内所有消息关联的全部引用信息，结构同 7.4。

7.6 删除会话

接口路径: DELETE /api/ai/session/{sessionId}

说明：删除指定会话及其所有消息和引用数据。

7.7 批量删除会话

接口路径: DELETE /api/ai/sessions/batch?ids=1,2,3

请求参数:

参数	类型	必填	说明
ids	String	是	会话ID列表，逗号分隔

7.8 中断AI流式问答

接口路径: POST /api/ai/chat/stop?sessionId=sess_xxx

请求参数:

参数	类型	必填	说明
sessionId	String	是	会话ID

{
  "success": true,
  "message": "已中断AI回答"
}

八、AI数据接口

基础路径：/api/ai/data

8.1 获取会话消息

接口路径: GET /api/ai/data/session/{sessionId}/messages

请求参数:

参数名	类型	必填	说明
sessionId	String	是	会话ID

7.2 获取反馈列表

接口路径: GET /api/ai/data/feedbacks

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页大小

7.3 获取差评案例

接口路径: GET /api/ai/data/feedbacks/bad-cases

九、反馈管理接口

基础路径：/api/feedback

9.1 提交反馈

接口路径: POST /api/feedback

请求体:

{
  "session_id": "会话ID（可选）",
  "query": "用户问题",
  "answer": "AI回答",
  "rating": 1,
  "reason": "反馈原因（可选）",
  "sources": ["来源文档列表（可选）"]
}

8.2 获取反馈列表

接口路径: GET /api/feedback/list

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页大小

8.3 获取反馈统计

接口路径: GET /api/feedback/stats

8.4 获取差评案例

接口路径: GET /api/feedback/bad-cases

九、FAQ管理接口

基础路径：/api/faq

9.1 创建FAQ

接口路径: POST /api/faq

请求体:

{
  "question": "常见问题内容",
  "answer": "问题答案",
  "source_documents": ["来源文档列表（可选）"]
}

9.2 获取FAQ列表

接口路径: GET /api/faq

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页大小

9.3 获取FAQ详情

接口路径: GET /api/faq/{id}

9.4 更新FAQ

接口路径: PUT /api/faq/{id}

请求体:

{
  "question": "更新后的问题（可选）",
  "answer": "更新后的答案（可选）",
  "status": "approved/pending/rejected（可选）"
}

9.5 删除FAQ

接口路径: DELETE /api/faq/{id}

9.6 批量删除FAQ

接口路径: DELETE /api/faq/batch?ids=1,2,3

9.7 条件查询FAQ

接口路径: GET /api/faq/list

请求参数:

参数	类型	必填	默认值	说明
status	String	否	-	状态筛选
limit	Integer	否	100	返回数量限制

9.8 获取FAQ建议列表

接口路径: GET /api/faq/suggestions

请求参数:

参数	类型	必填	默认值	说明
page	Integer	否	1	页码
pageSize	Integer	否	20	每页大小

9.9 批准FAQ建议

接口路径: POST /api/faq/suggestions/{id}/approve

请求体:

{
  "answer": "修改后的标准答案（可选）"
}

9.10 拒绝FAQ建议

接口路径: POST /api/faq/suggestions/{id}/reject

十、图片管理接口

基础路径：/api/image

10.0 图片完整处理流程

10.0.1 整体流程说明

本系统实现了完整的AI图片处理流程，包括：

用户提问 → RAG服务返回 → 图片提取 → 下载保存 → 数据库存储 → API访问 → 前端展示

10.0.2 详细处理步骤

步骤1：用户提问

POST /api/ai/chat/stream
{
  "message": "2003—2022 年，三峡电站累计发电量是多少？最好带图片说明"
}

步骤2：RAG服务返回完整数据

{
  "type": "finish",
  "answer": "根据【参考资料】...",
  "images": [
    {
      "image_id": "ab77281e7913.jpg",
      "path": "/api/image/ab77281e7913.jpg/data",
      "source": "三峡公报_1-15页.pdf",
      "page": 12,
      "section": "3.1 数据图表",
      "chunk_type": "image",
      "description": "这是一张柱状图...",
      "score": 0.85,
      "collection": "public_kb"
    }
  ]
}

步骤3：系统自动处理

✅ 提取图片元数据（image_id, path, source, page, section, chunk_type, description, score, collection）
✅ 从AI服务下载图片到本地目录
✅ 保存图片元数据到 context_image 表
✅ 保存图片到本地文件系统

已移除的旧字段：filename、size_bytes、format、page_end、type、full_description

步骤4：前端获取图片数据

GET /api/image/ab77281e7913.jpg/data

返回：图片二进制流

10.0.3 前端展示示例

JavaScript (原生)

// 从 finish 事件获取图片数组
const images = finishEvent.images;

images.forEach(image => {
  // 创建图片元素
  const img = document.createElement('img');
  img.src = image.url;  // url = "/api/image/ab77281e7913.jpg/data"
  img.alt = image.description;
  img.style.maxWidth = '100%';
  
  // 创建描述容器
  const descDiv = document.createElement('div');
  descDiv.innerHTML = `
    <p><strong>来源：</strong>${image.source}</p>
    <p><strong>页码：</strong>第 ${image.page} 页</p>
    <p><strong>类型：</strong>${image.type}</p>
    <p><strong>描述：</strong>${image.description}</p>
  `;
  
  // 添加到页面
  document.getElementById('image-gallery').appendChild(img);
  document.getElementById('image-gallery').appendChild(descDiv);
});

React 示例

{images && images.length > 0 && (
  <div className="image-gallery">
    {images.map((image, index) => (
      <div key={index} className="image-item">
        <img 
          src={image.url} 
          alt={image.description}
          style={{ maxWidth: '100%' }}
        />
        <div className="image-info">
          <p><strong>来源：</strong>{image.source}</p>
          <p><strong>页码：</strong>第 {image.page} 页</p>
          <p><strong>类型：</strong>{image.chunk_type}</p>
          <p><strong>描述：</strong>{image.description}</p>
          <p><strong>相关性评分：</strong>{image.score}</p>
        </div>
      </div>
    ))}
  </div>
)}

Vue 示例

<template>
  <div v-if="images && images.length > 0" class="image-gallery">
    <div v-for="(image, index) in images" :key="index" class="image-item">
      <img :src="image.url" :alt="image.description" style="max-width: 100%" />
      <div class="image-info">
        <p><strong>来源：</strong>{{ image.source }}</p>
        <p><strong>页码：</strong>第 {{ image.page }} 页</p>
        <p><strong>类型：</strong>{{ image.chunk_type }}</p>
        <p><strong>描述：</strong>{{ image.description }}</p>
        <p><strong>相关性评分：</strong>{{ image.score }}</p>
      </div>
    </div>
  </div>
</template>

<script>
export default {
  props: ['images']
}
</script>

10.1 创建图片记录

接口路径: POST /api/image

请求体:

{
  "image_id": "图片唯一标识",
  "path": "存储路径/图片URL",
  "source": "来源文档（可选）",
  "page": 1,
  "section": "所在章节（可选）",
  "chunk_type": "切片类型（可选）如:image/table",
  "description": "图片描述（可选）",
  "score": 0.85,
  "collection": "所属向量库（可选）"
}

字段说明：filename、size_bytes、format、page_end、type、full_description 已移除。

10.2 获取图片列表

接口路径: GET /api/image/list

请求参数:

参数	类型	必填	默认值	说明
limit	Integer	否	50	返回数量
offset	Integer	否	0	偏移量

10.3 获取图片详情

接口路径: GET /api/image/{id}

10.4 获取图片数据

接口路径: GET /api/image/{id}/data

返回类型: 图片二进制流

10.5 更新图片记录

接口路径: PUT /api/image/{id}

请求体:

{
  "path": "更新后的路径（可选）",
  "source": "更新后的来源文档（可选）",
  "page": 2,
  "section": "更新后的章节（可选）",
  "chunk_type": "更新后的切片类型（可选）",
  "description": "更新后的描述（可选）",
  "score": 0.9,
  "collection": "更新后的向量库（可选）"
}

10.6 删除图片

接口路径: DELETE /api/image/{id}

10.7 批量删除图片

接口路径: DELETE /api/image/batch?ids=1,2,3

10.8 获取图片统计

接口路径: GET /api/image/stats

十一、报告管理接口

基础路径：/api/report

11.1 获取周报

接口路径: GET /api/report/weekly

11.2 获取月报

接口路径: GET /api/report/monthly

十二、知识检索接口

12.1 混合检索

接口路径: POST /api/search

请求体:

{
  "query": "检索关键词",
  "topK": 5,
  "collections": ["public_kb", "dept"]
}

十三、知识库路由接口

13.1 测试知识库路由

接口路径: POST /api/kb-route

请求体:

{
  "query": "财务部的报销流程是什么"
}

十四、模拟考接口 🔵 模拟考

基础路径：/api/exam

功能说明：模拟考接口，通过 AI 生成模拟试卷、题目，支持批改答案。前端可传 type 参数指定本次试卷类型（日常练习/模拟考/正式考均可）。

type 参数可选值：

值	说明
`practice`	日常练习
`mock_exam`	模拟考
`formal_exam`	正式考试

14.1 生成试卷

接口路径: POST /api/exam/paper/generate

功能说明: 根据权限范围或指定文件从题库中动态生成试卷

请求体:

{
  "single_choice_count": 5,
  "multiple_choice_count": 3,
  "true_false_count": 2,
  "fill_blank_count": 2,
  "subjective_count": 1,
  "difficulty": 3,
  "include_personal": false,
  "file_ids": [1, 2, 3]
}

请求参数说明:

参数	类型	必填	默认值	说明
single_choice_count	Integer	否	-	单选题数量
multiple_choice_count	Integer	否	-	多选题数量
true_false_count	Integer	否	-	判断题数量
fill_blank_count	Integer	否	-	填空题数量
subjective_count	Integer	否	-	简答题数量
difficulty	Integer	否	-	难度等级（1-5）
include_personal	Boolean	否	false	是否包含个人专属题目
file_ids	List	否	-	指定文件ID列表，仅从这些文件生成题目

响应示例:

{
  "code": 200,
  "message": "试卷生成成功",
  "data": {
    "paper_id": "paper_xxx",
    "paper_title": "考试试卷 - 2026-05-17T15:41:56",
    "total_score": 100.00,
    "question_count": 13,
    "generated_at": "2026-05-17T15:41:56",
    "permission_scope": "本部门",
    "questions": [
      {
        "question_id": "q_xxx",
        "question_type": "single_choice",
        "question_type_name": "单选题",
        "difficulty": 3,
        "score": 5.00,
        "content": {...}
      }
    ]
  },
  "timestamp": "2026-05-17 15:41:56"
}

14.2 开始考试（获取题目）

接口路径: POST /api/exam/paper/{paperId}/start

功能说明: 通过试卷ID开始模拟考试，系统自动查找或创建考试记录，返回试卷题目内容

路径参数:

参数	类型	必填	说明
paperId	String	是	试卷ID

响应示例: 同14.1 生成试卷的响应格式

14.3 获取考试结果

接口路径: GET /api/exam/record/{recordId}/result

功能说明: 获取模拟考试的完整结果，包括题目、答案、分数等信息

路径参数:

参数	类型	必填	说明
recordId	String	是	考试记录ID

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "record_id": "59759c40-ee4e-4ff5-ab03-4819a0499beb",
    "paper_id": "0ef70443-67d3-48cd-9309-f5088c092fe1",
    "answer_type": "practice",
    "paper_title": "考试试卷 - 2026-05-17T15:41:56",
    "user_id": 1,
    "status": "submitted",
    "total_score": 85.0,
    "answers": [
      {
        "question_id": "q_001",
        "score": 5.0,
        "is_correct": true,
        "feedback": "回答正确"
      }
    ]
  },
  "timestamp": "2026-05-17 16:05:00"
}

14.4 生成题目

接口路径: POST /api/exam/generate

功能说明: 根据指定文件生成考试题目，支持两种生成模式：

智能生成模式（推荐）：不提供 question_types 参数，系统会调用 AI 智能出题接口 /exam/generate-smart，AI 会根据文档内容自动判断题型和数量
指定题型模式：提供 question_types 参数，系统会调用传统出题接口 /exam/generate，按照指定的题型和数量生成题目

重要说明：此接口为异步接口，请求后立即返回任务提交状态，实际生成在后台执行。需通过 GET /api/file/{fileId} 接口轮询查询生成进度和结果。

支持两种方式指定文件：

通过 file_id 指定（推荐）：系统自动从 collection_file 表查询向量库信息
通过 file_path 指定：需要同时指定 collection 参数

请求体（智能生成模式）:

{
  "file_id": 1,
  "difficulty": 3,
  "request_id": "gen_req_smart_001"
}

请求体（指定题型模式）:

{
  "file_id": 1,
  "question_types": {
    "single_choice": 3,
    "multiple_choice": 2,
    "true_false": 2,
    "fill_blank": 2,
    "subjective": 1
  },
  "question_scores": {
    "single_choice": 5.00,
    "multiple_choice": 8.00
  },
  "difficulty": 3,
  "request_id": "gen_req_001"
}

请求参数说明:

参数	类型	必填	说明
file_id	Long	二选一	文件ID，系统自动查询向量库
file_path	String	二选一	文件路径
collection	String	当使用 file_path 时必填	向量库名称
question_types	Object	否	题型及数量配置（不提供则使用智能生成模式）
question_scores	Object	否	自定义题型分数配置（仅在指定题型模式下有效）
difficulty	Integer	否	难度等级（1-5），默认3
request_id	String	否	请求ID，用于幂等性

响应示例（通过 file_id）:

{
  "code": 200,
  "message": "收到请求",
  "data": {
    "requestId": "gen_req_001",
    "fileId": 1,
    "fileMatchStatus": "success",
    "matchedCollection": "public_kb",
    "matchedFilePath": "薪酬制度.docx",
    "documentName": "薪酬制度.docx",
    "collectionFilled": true,
    "collectionFillSource": "collection_file 表查询",
    "asyncTaskStarted": true,
    "nextStep": "请通过文件状态接口查询生成进度",
    "status": "success"
  },
  "timestamp": "2026-05-28 10:00:00"
}

响应示例（通过 file_path）:

{
  "code": 200,
  "message": "收到请求",
  "data": {
    "requestId": "gen_req_001",
    "fileMatchStatus": "skipped",
    "reason": "使用 file_path 直接指定文件",
    "collectionFilled": false,
    "asyncTaskStarted": true,
    "nextStep": "请通过文件状态接口查询生成进度",
    "status": "success"
  },
  "timestamp": "2026-05-28 10:00:00"
}

响应字段说明:

字段	类型	说明
requestId	String	请求ID，用于追踪
fileId	Long	文件ID
fileMatchStatus	String	文件匹配状态：success/skipped/failed
matchedCollection	String	匹配到的向量库名称
matchedFilePath	String	匹配到的文件路径
documentName	String	文档名称
collectionFilled	Boolean	向量库是否已填充
collectionFillSource	String	向量库填充来源
asyncTaskStarted	Boolean	异步任务是否已启动
nextStep	String	下一步操作提示
status	String	状态：success/error

生成状态查询：请求成功后，需通过 GET /api/file/{fileId} 接口轮询查询生成进度：

AI生成题目状态：

状态值	说明	前端处理建议
`UNGENERATED`	未生成	显示"未生成"状态
`GENERATING`	正在生成	显示加载动画，轮询状态
`GENERATED`	已生成	显示成功状态，可查看题目
`FAILED`	生成失败	显示错误信息，支持重试

文件状态查询响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "fileName": "薪酬制度.docx",
    "filePath": "public_kb/薪酬制度.docx",
    "processStatus": "INDEXED",
    "examStatus": "GENERATED",
    "processMessage": "生成成功，共5道题\n\n【AI分析结果】\n{\"summary\":\"文档摘要...\",\"questionDistribution\":{\"single_choice\":3,\"multiple_choice\":2}}",
    "createTime": "2026-05-28T10:00:00",
    "updateTime": "2026-05-28T10:00:03"
  }
}

processMessage 字段说明：

生成成功时：包含题目数量，智能模式还会包含 AI 分析结果（JSON格式）
生成失败时：包含错误原因
AI 分析结果通过 【AI分析结果】 标记标识

默认分值配置:

题型	question_type	默认分值
单选题	single_choice	2分
多选题	multiple_choice	4分
判断题	true_false	1分
填空题	fill_blank	2分
简答题	subjective	6分

分数优先级:

题目级配置（AI返回的 score 字段）
题型级配置（question_scores 参数）
默认值（上表）

轮询策略建议：

初始轮询间隔：2-3秒
超时时间：建议设置为 5-10 分钟
停止条件：examStatus 变为 GENERATED 或 FAILED

14.5 提交考试并批改（正式考试专用）

接口路径: POST /api/exam/record/{recordId}/grade

功能说明: 通过考试记录ID提交正式考试答案并批改，自动将类型设置为 formal_exam。

路径参数:

参数	类型	必填	说明
recordId	String	是	考试记录ID

请求体:

{
  "answers": [
    {"questionId": "q_001", "questionType": "single_choice", "answer": "B"},
    {"questionId": "q_002", "questionType": "multiple_choice", "answer": ["A", "C", "D"]},
    {"questionId": "q_003", "questionType": "true_false", "answer": true},
    {"questionId": "q_004", "questionType": "fill_blank", "answer": ["答案1", "答案2", "答案3"]},
    {"questionId": "q_005", "questionType": "subjective", "answer": "主观题答案内容"}
  ]
}

响应示例:

{
  "code": 200,
  "message": "提交成功",
  "data": {
    "recordId": "record_xxx",
    "paperId": "paper_xxx",
    "paperTitle": "月度考核试卷",
    "status": "submitted",
    "totalScore": 85.0,
    "totalMaxScore": 100.0,
    "scoreRate": 85.0,
    "submitTime": "2026-05-17T14:30:00",
    "answers": [
      {
        "questionId": "q_001",
        "score": 5.0,
        "maxScore": 5.0,
        "isCorrect": true,
        "feedback": "回答正确"
      }
    ]
  },
  "timestamp": "2026-05-17T14:30:00"
}

14.6 批改答案（日常练习/模拟考/正式考试通用）

接口路径: POST /api/exam/grade

功能说明: 对学生提交的答案进行批改，支持两种模式：

日常练习/模拟考模式（无 record_id）：直接批改答案，可重复提交更新记录
正式考试模式（有 record_id）：通过考试记录ID提交正式考试答案并批改

type 字段由前端传入，后端原样使用（不限值）。

请求体:

{
  "request_id": "grade_req_001",
  "type": "practice",
  "record_id": "59759c40-ee4e-4ff5-ab03-4819a0499beb",
  "answers": [
    {
      "question_id": "q_001",
      "question_type": "single_choice",
      "question_content": {
        "stem": "题目内容",
        "data": {"options": [...]},
        "answer": "B"
      },
      "student_answer": "A",
      "max_score": 5.0
    }
  ]
}

响应示例:

{
  "code": 200,
  "message": "批阅成功",
  "data": {
    "success": true,
    "total_score": 5.0,
    "total_max_score": 5.0,
    "score_rate": 100.0,
    "results": [
      {
        "question_id": "q_001",
        "question_type": "single_choice",
        "score": 5.0,
        "max_score": 5.0,
        "is_correct": true,
        "correct": true,
        "student_answer": "B",
        "correct_answer": "B",
        "feedback": "回答正确"
      }
    ]
  },
  "timestamp": "2026-05-17 10:00:00"
}

响应字段说明:

字段	类型	说明
code	Integer	状态码，200表示成功
message	String	响应消息
data.success	Boolean	批改是否成功
data.total_score	Double	总得分
data.total_max_score	Double	总满分
data.score_rate	Double	得分率（0-100）
data.results	Array	每题批改结果
data.results[].question_id	String	题目ID
data.results[].question_type	String	题型
data.results[].score	Double	本题得分
data.results[].max_score	Double	本题满分
data.results[].is_correct	Boolean	是否正确（推荐使用）
data.results[].correct	Boolean	是否正确（兼容字段）
data.results[].student_answer	String	学生答案
data.results[].correct_answer	String	正确答案
data.results[].feedback	String	反馈信息

字段兼容性说明:

字段名	说明	兼容性
`is_correct`	布尔值，表示是否正确	✅ 主字段，推荐使用
`correct`	布尔值，表示是否正确	✅ 兼容字段，与is_correct值相同
`feedback`	反馈信息	✅ 后端自动生成，确保不为空
`student_answer`	学生答案	✅ 返回前端提交的答案
`correct_answer`	正确答案	✅ 从题目信息中获取

各题型反馈生成规则:

单选题、多选题、判断题：优先使用AI返回的feedback字段，内容简单直接
填空题：优先使用AI返回的feedback，否则从details.blank_scores和details.correct_answers自动生成
主观题：优先使用details.overall_feedback，否则使用feedback，最后从details.scoring_breakdown生成

14.7 查询用户答题记录

接口路径: POST /api/exam/answers/query

功能说明: 根据试卷ID或会话ID查询用户答题记录，支持按试卷/练习维度分组展示

请求体:

{
  "paper_id": "paper_xxx"
}

或

{
  "session_id": "sess_xxx"
}

请求参数说明:

参数	类型	必填	说明
paper_id	String	二选一	试卷ID
session_id	String	二选一	会话ID（日常练习）

14.8 获取考试记录列表（统一接口）

接口路径: GET /api/exam/records?type={type}

功能说明: 根据类型获取用户的考试/练习记录，统一查询接口

请求参数:

参数	类型	必填	默认值	说明
type	String	否	practice	记录类型：practice(日常练习), mock_exam(模拟考), formal_exam(正式考)

响应示例（日常练习）:

{
  "code": 200,
  "message": "成功",
  "data": {
    "success": true,
    "totalCount": 10,
    "groups": [
      {
        "groupType": "practice",
        "groupId": "sess_xxx",
        "groupName": "2026-05-17",
        "createdAt": "2026-05-17T10:30:00"
      }
    ]
  }
}

响应示例（模拟考/正式考）:

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "recordId": "rec_xxx",
      "paperId": "paper_xxx",
      "paperTitle": "月度考核试卷",
      "answerType": "formal_exam",
      "status": "completed",
      "totalScore": 85.0,
      "submitTime": "2026-05-17T11:30:00"
    }
  ]
}

十五、正式考试接口 🟢 正式考

基础路径：/api/formal-exam

功能说明：正式考试接口，仅供被分配了正式试卷的用户使用。提交答案时 type 自动设置为 formal_exam，同一用户对同一题目只能答题一次（唯一索引防重复）。

15.1 开始考试（获取题目）

接口路径: POST /formal-exam/paper/{paperId}/start

功能说明: 直接通过试卷ID开始考试，系统自动查找或创建考试记录，返回试卷题目内容

响应示例:

{
  "code": 200,
  "message": "开始考试成功",
  "data": {
    "recordId": "record_xxx",
    "paperId": "paper_xxx",
    "paperTitle": "月度考核试卷",
    "status": "in_progress",
    "startTime": "2026-05-17T14:00:00",
    "questions": [
      {
        "questionId": "q_001",
        "questionType": "single_choice",
        "questionTypeName": "单选题",
        "score": 5.0,
        "content": {
          "stem": "题目内容...",
          "data": {"options": [...]}
        }
      }
    ]
  },
  "timestamp": "2026-05-17 14:00:00"
}

重要说明：正式考试提交接口已统一到 /api/exam/grade（推荐使用）或 /api/exam/record/{recordId}/grade`。

15.2 获取考试结果

接口路径: GET /formal-exam/record/{recordId}/result

功能说明: 获取考试结果详情，包含每题得分和反馈

十六、正式考管理接口 🟢 正式考管理

基础路径：/admin/exam

功能说明：正式考管理接口，供管理员预览、保存、发布正式考试试卷。管理员生成试卷后发布给指定部门/人员，员工在正式考试接口中答题。type 自动设置为 formal_exam。

16.1 预览试卷

接口路径: POST /admin/exam/paper/preview

请求体:

{
  "single_choice_count": 5,
  "multiple_choice_count": 3,
  "true_false_count": 2,
  "fill_blank_count": 2,
  "subjective_count": 1,
  "difficulty": 3
}

16.2 保存试卷

接口路径: POST /admin/exam/paper/save

请求体:

{
  "title": "月度考核试卷",
  "questionIds": ["q_001", "q_002", "q_003"]
}

16.3 发布试卷

接口路径: POST /admin/exam/paper/{paperId}/publish

请求体:

{
  "deptId": 1,
  "userIds": [10, 20, 30],
  "excludeUserIds": [5],
  "publishTime": "2026-05-17T00:00:00",
  "deadline": "2026-05-20T23:59:59"
}

请求参数说明:

参数	类型	必填	说明
deptId	Long	否	部门ID，发布给该部门的所有用户
userIds	List<Long>	否	指定用户ID列表
excludeUserIds	List<Long>	否	排除用户ID列表
publishTime	DateTime	否	发布时间，默认立即发布
deadline	DateTime	否	截止时间

说明：

最终考试人员 = (部门用户 + 指定用户) - 排除用户
三种组合方式：
1. 只设置 deptId：发布给整个部门
2. 只设置 userIds：只发布给指定用户
3. 同时设置：覆盖更广泛范围，可排除特定人员

响应示例:

{
  "code": 200,
  "message": "发布成功",
  "data": null,
  "timestamp": "2026-05-17 00:00:00"
}

16.4 撤销试卷

接口路径: POST /admin/exam/paper/{paperId}/revoke

16.5 删除试卷

接口路径: DELETE /admin/exam/paper/{paperId}

16.6 获取试卷详情（管理）

接口路径: GET /admin/exam/paper/{paperId}

16.7 获取试卷列表（管理）

接口路径: GET /admin/exam/paper/list

16.8 获取考试记录列表

接口路径: GET /admin/exam/records/{paperId}

16.9 获取考试记录详情

接口路径: GET /admin/exam/record/{recordId}

十七、题目管理接口

基础路径：/api/question

17.1 创建题目

接口路径: POST /api/question

请求体:

{
  "question_type": "single_choice",
  "difficulty": 3,
  "content": {"stem": "题目内容", "data": {...}, "answer": "答案"},
  "score": 5.0,
  "document_name": "来源文档"
}

17.2 分页查询题目

接口路径: GET /api/question/page

请求参数:

参数	类型	必填	默认值	说明
pageNum	Integer	否	1	页码
pageSize	Integer	否	10	每页大小
questionType	String	否	-	题型筛选
difficulty	Integer	否	-	难度筛选
status	String	否	-	状态筛选

17.3 获取题目详情

接口路径: GET /api/question/{id}

17.4 更新题目

接口路径: PUT /api/question/{id}

请求体:

{
  "question_type": "更新后的题型（可选）",
  "difficulty": 4,
  "content": {"stem": "更新后的题目内容"},
  "status": "approved"
}

17.5 删除题目

接口路径: DELETE /api/question/{id}

17.6 批量删除题目

接口路径: DELETE /api/question/batch?ids=1,2,3

17.7 条件查询题目（按权限过滤）

接口路径: GET /api/question/list

功能说明: 根据用户权限过滤，返回用户可见的题目（本人库、本部门库、公共库的题目）

请求参数:

参数	类型	必填	默认值	说明
questionType	String	否	-	题型筛选
difficulty	Integer	否	-	难度筛选
status	String	否	-	状态筛选
documentName	String	否	-	文档名称筛选
limit	Integer	否	100	返回数量限制

17.8 获取待审核题目

接口路径: GET /api/question/pending

17.9 审核题目

接口路径: PUT /api/question/review/{questionId}

请求参数:

参数	类型	必填	说明
status	String	是	审核状态：approved/rejected
reviewerComment	String	否	审核评论

17.10 获取题目统计

接口路径: POST /api/question/stats

请求体:

{
  "group_by": "question_type"
}

十八、错题管理接口

基础路径：/api/wrong-questions

18.1 获取错题列表

接口路径: POST /api/wrong-questions/list

请求体:

{
  "page": 1,
  "pageSize": 10,
  "collection": true
}

18.2 收藏/取消收藏错题

接口路径: POST /api/wrong-questions/collection/toggle

请求体:

{
  "question_id": "q_001"
}

18.3 重新做题

接口路径: POST /api/wrong-questions/redo

请求体:

{
  "question_ids": ["q_001", "q_002"]
}

18.4 导出错题

接口路径: POST /api/wrong-questions/export

请求体:

{
  "question_ids": ["q_001", "q_002"]
}

十九、数据同步接口

基础路径：/api/data-sync

19.1 验证用户数据同步

接口路径: GET /api/data-sync/validate/user/{userId}

19.2 验证当前用户数据同步

接口路径: GET /api/data-sync/validate/me

19.3 验证所有用户数据同步

接口路径: GET /api/data-sync/validate/all

19.4 验证最近用户数据同步

接口路径: GET /api/data-sync/validate/recent

二十、接口权限说明

21.1 权限层级

用户类型	类型值	权限说明
超级管理员	1	完全访问权限，可管理所有向量库和文档
部门管理员	2	可管理本部门的所有向量库和文档
普通用户	3	可管理个人上传的文档和本部门的公开文档

20.2 权限矩阵

接口	超级管理员	部门管理员	普通用户
获取向量库列表	✅	✅	✅
创建向量库	✅	✅	❌
修改向量库	✅	✅	❌
删除向量库	✅	✅	❌
文件向量化	✅	✅	✅
获取文档列表	✅	✅	✅
删除文档	✅	✅	❌
生成题目	✅	✅	✅
批改答案	✅	✅	✅
提交反馈	✅	✅	✅
获取反馈列表	✅	✅	✅
题目CRUD	✅	✅	❌
FAQ CRUD	✅	✅	❌
图片CRUD	✅	✅	❌
试卷管理	✅	✅	❌
用户考试	✅	✅	✅

二十一、错误码详解

22.1 认证相关错误

错误码	错误信息	解决方案
401	用户未登录	请先登录获取Token
401	Token无效	请重新登录获取有效Token
401	Token已过期	请重新登录
403	权限不足	联系管理员提升权限

22.2 业务逻辑错误

错误码	错误信息	解决方案
400	参数错误	检查请求参数格式和必填项
404	向量库不存在	检查向量库名称是否正确
404	文档不存在	检查文档路径是否正确
500	创建向量库失败	检查数据库连接或重试

二十二、使用限制

23.1 通用限制

限制项	限制值	说明
文件上传大小	50MB	单个文件最大50MB
批量上传文件数	20	一次最多上传20个文件
分页最大页码	1000	超过后性能下降
每页最大记录数	100	超过后建议优化查询
Token有效期	24小时	登录Token有效期

23.2 频率限制

接口类型	限制	时间窗口
文件上传	10次	60秒
其他增删改接口	30次	60秒
查询接口	100次	60秒

二十三、变更记录

版本	日期	修改内容
V2.15.0	2026-05-29	1. 新增用户管理接口(用户CRUD);2. 新增部门管理接口;3. 新增AI会话管理接口(获取会话列表、会话详情、删除会话、批量删除会话);4. 新增向量库切片管理接口(新增切片、修改切片、删除切片、获取向量库切片列表);5. 优化文档结构,添加通用请求头说明;6. 完善向量库管理接口,新增获取文档切片列表等接口。
V2.14.0	2026-05-28	1. 生成题目接口新增智能生成模式，不提供 `question_types` 参数时自动调用 AI 智能出题接口 `/exam/generate-smart`，AI 根据文档内容自动判断题型和数量；2. `question_types` 参数改为可选，仅在指定题型模式下需要提供；3. `process_message` 字段会追加 AI 分析结果（aiAnalysis），包含文档摘要和题型分布等信息；4. 更新文件详情查询接口响应示例，添加 `processMessage` 字段说明；5. 更新 `process_message` 字段类型从 varchar 改为 text，支持存储更长内容。
V2.13.0	2026-05-19	1. 生成题目接口新增 `file_id` 参数支持，系统自动从 `collection_file` 表查询向量库信息；2. 新增 `question_scores` 参数支持自定义题型分数；3. 更新默认分值配置（单选2分、多选4分、判断1分、填空2分、简答6分）；4. 添加完整的反馈信息机制，包含文件匹配状态、向量库填充进度等。
V2.12.0	2026-05-19	1. 新增图片完整处理流程说明（10.0节）；2. 新增前端图片展示示例（JavaScript/React/Vue）；3. 完善图片元数据字段说明（新增 score、type、description、full_description）；4. 新增图片自动下载和本地保存功能说明。
V2.11.0	2026-05-17	1. 控制器重命名：KnowledgeBasePathController → CollectionAccessController，路径从 /api/kb-path 改为 /api/collection-access；2. 部门字段重命名：HR_DEPT → 人事部门，PUBLIC_DEPT → 公共部门；3. 图片接口路径更新：/api/images → /api/image。
V2.10.0	2026-05-14	新增文件来源展示优化功能：1. AI流式问答 finish 事件新增 `sources`（文件来源列表）和 `images`（图片列表）字段；2. 新增 `GET /api/ai/message/{messageId}/sources` 接口获取文件来源列表（去重）；3. `GET /api/ai/message/{messageId}/references` 新增 `docName` 参数支持按文档过滤；4. 消息实体新增 `sources` 字段存储文件来源摘要；5. 图片接口新增兼容路径 `/api/images/list`；6. 修复异步题目生成问题：添加 `@EnableAsync` 配置和自定义线程池。
V2.9.3	2026-05-11	统一考试接口架构：新增 `/api/exam/record/{recordId}/grade` 接口；`/api/exam/grade` 新增 `record_id` 参数支持正式考试提交；删除冗余接口 `/formal-exam/record/{recordId}/submit` 和 `/admin/exam/record/{recordId}/submit`。
V2.9.2	2026-05-11	删除重复字段 `status_detail`，只保留 `status` 字段。`exam_record` 表新增 `answer_type` 字段，所有考试记录增加类型标识。
V2.9.1	2026-05-11	参数重命名：answer_type → type，值改为英文（practice/mock_exam/formal_exam）。删除 recordId 方式开始考试接口，统一使用 paperId。删除旧 UserExamController。数据库 answer_type 字段默认值改为 practice。
V2.8.0	2026-05-10	简化用户考试流程：删除获取试卷详情和保存答案接口，开始考试接口同时返回题目，提交试卷接口改为接收答案参数一次性提交
V2.7.0	2026-05-10	完善生成试卷权限控制：根据用户类型（超级管理员/部门管理员/普通用户）进行题目权限过滤，删除重复接口 GET /api/exam/list
V2.6.0	2026-05-10	修改 GET /api/question/list 添加用户权限过滤（本人库、本部门库、公共库）；生成试卷添加公共部门向量库支持
V2.5.0	2026-05-10	补充文件管理接口：新增查询文件详情、获取文件内容接口；更新RAG流式问答接口参数格式
V2.4.0	2026-05-10	添加文件管理接口、用户考试接口、管理员考试接口、错题管理接口、AI数据接口、数据同步接口
V2.3.0	2026-05-09	添加生成试卷接口、用户答题记录查询接口，完善考试管理模块
V2.2.0	2026-05-07	更新向量库列表和文档列表接口说明，改为从本地数据库读取
V2.1.0	2026-05-06	添加题目、FAQ、图片完整CRUD接口文档
V2.0.0	2026-05-05	整合考试管理、知识库管理、AI交互、AI流式等接口文档
V1.0.2	2026-05-02	重构向量库管理接口
V1.0.1	2026-05-02	整合向量库/知识库接口
V1.0.0	2026-04-30	初始版本

文档结束

60 KiB Raw Permalink Blame History Unescape Escape

知识库管理系统 - 完整接口文档

文档信息

一、认证说明

1.1 认证流程

1.2 通用请求头

1.3 通用响应格式

二、认证接口

2.1 登录

三、向量库管理接口

模块说明

3.1 获取向量库列表

3.2 创建向量库

3.3 修改向量库

3.4 删除向量库

3.5 文件向量化（单文件）

3.6 批量文件向量化

3.7 获取文档列表

3.8 删除文档

3.9 废止文档

3.10 恢复已废止文档

3.11 获取文档版本历史

3.12 获取文档切片列表

3.13 新增切片

3.14 修改切片

3.15 删除切片

四、文件管理接口

4.1 查询文件详情

4.2 文件上传

4.3 文件列表分页查询

4.4 获取文件信息

4.5 文件下载

4.6 文件预览

4.7 获取文件文本内容

4.8 获取文件内容（二进制）

4.9 文件RAG流式问答

4.10 文件审核通过

4.11 文件审核拒绝

4.12 获取待审核文件列表

4.13 更新文件信息

4.14 删除文件

五、知识库访问控制接口

5.1 分页查询知识库列表

5.2 获取知识库详情

5.3 获取用户可访问的知识库列表

六、AI流式问答接口

6.1 基本信息

6.2 请求参数

6.3 流式事件类型

七、AI 会话管理接口

7.1 获取用户会话列表

7.2 获取会话详情

7.3 获取消息文件来源列表

7.4 获取消息引用信息

7.5 获取会话所有引用

7.6 删除会话

7.7 批量删除会话

7.8 中断AI流式问答

八、AI数据接口

8.1 获取会话消息

7.2 获取反馈列表

7.3 获取差评案例

九、反馈管理接口

9.1 提交反馈

8.2 获取反馈列表

8.3 获取反馈统计

8.4 获取差评案例

九、FAQ管理接口

9.1 创建FAQ

9.2 获取FAQ列表

9.3 获取FAQ详情

9.4 更新FAQ

9.5 删除FAQ

9.6 批量删除FAQ

9.7 条件查询FAQ

9.8 获取FAQ建议列表

9.9 批准FAQ建议

9.10 拒绝FAQ建议

十、图片管理接口

10.0 图片完整处理流程

60 KiB

Raw Permalink Blame History