435 lines
7.9 KiB
Markdown
435 lines
7.9 KiB
Markdown
# 知识库页面后端接口清单
|
||
|
||
本文对应前端页面：[RagStoresPage.vue](/D:/Code/common_agent/frontend/src/pages/RagStoresPage.vue)
|
||
|
||
## 1. 页面目标
|
||
|
||
知识库页面采用：
|
||
|
||
- 顶部 4 张全局统计卡片
|
||
- 左侧知识库名称搜索与列表
|
||
- 右侧当前知识库详情
|
||
- 当前知识库级别操作：编辑、批量导入文件、重建索引
|
||
|
||
因此接口建议拆成 `全局概览`、`知识库列表/详情`、`单库动作` 三组。
|
||
|
||
## 2. 本批已实现并已用于前端联调的接口
|
||
|
||
### 2.1 查询全部知识库
|
||
|
||
- `GET /api/rag/stores`
|
||
|
||
当前返回类型：
|
||
|
||
- `RequestResult<List<RagStoreResponse>>`
|
||
|
||
当前字段：
|
||
|
||
- `id`
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `description`
|
||
- `status`
|
||
- `remark`
|
||
|
||
对应代码：
|
||
|
||
- [RagStoreController.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/controller/RagStoreController.java)
|
||
- [RagStoreResponse.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java)
|
||
|
||
### 2.2 按条件查询知识库
|
||
|
||
- `POST /api/rag/stores/query`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度",
|
||
"status": "ENABLED"
|
||
}
|
||
```
|
||
|
||
当前支持字段：
|
||
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `status`
|
||
|
||
对应代码：
|
||
|
||
- [RagStoreQueryRequest.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java)
|
||
|
||
### 2.3 查询知识库详情
|
||
|
||
- `GET /api/rag/stores/{id}`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<RagStoreResponse>`
|
||
|
||
### 2.4 新增或修改知识库
|
||
|
||
- `POST /api/rag/stores`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料",
|
||
"status": "启用",
|
||
"remark": "核心制度库"
|
||
}
|
||
```
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<Boolean>`
|
||
|
||
说明：
|
||
|
||
- `id` 为空时新增
|
||
- `id` 不为空时修改
|
||
|
||
### 2.5 删除知识库
|
||
|
||
- `DELETE /api/rag/stores/{id}`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<Boolean>`
|
||
|
||
## 3. 当前项目里已有但本批前端未联调的接口
|
||
|
||
### 3.1 查询全部知识文档
|
||
|
||
- `GET /api/rag/documents`
|
||
|
||
### 3.2 按条件查询知识文档
|
||
|
||
- `POST /api/rag/documents/query`
|
||
|
||
当前可用于按 `storeId` 查询当前知识库下文档。
|
||
|
||
对应代码：
|
||
|
||
- [RagDocumentController.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/controller/RagDocumentController.java)
|
||
- [RagDocumentQueryRequest.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java)
|
||
|
||
## 4. 下一批建议补充的接口
|
||
|
||
当前已有接口能支撑最基础的列表查询，但还不足以支撑统计卡片、右侧详情聚合和单库动作。建议补下面几个接口。
|
||
|
||
### 4.1 知识库总览统计
|
||
|
||
- `GET /api/rag/stores/overview`
|
||
|
||
用途：
|
||
|
||
- 顶部 4 张卡片数据
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"storeCount": 12,
|
||
"documentCount": 1286,
|
||
"chunkCount": 24390,
|
||
"retrievableStoreCount": 9
|
||
}
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreOverviewResponse`
|
||
|
||
字段建议：
|
||
|
||
- `storeCount`
|
||
- `documentCount`
|
||
- `chunkCount`
|
||
- `retrievableStoreCount`
|
||
|
||
### 4.2 知识库列表查询增强版
|
||
|
||
- `POST /api/rag/stores/manage/query`
|
||
|
||
用途：
|
||
|
||
- 左侧知识库列表
|
||
|
||
相比当前 `/query`，建议直接返回列表页需要的摘要字段，避免前端再额外聚合文档数据。
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"storeName": "FAQ"
|
||
}
|
||
```
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": [
|
||
{
|
||
"id": 2,
|
||
"storeCode": "FAQ",
|
||
"storeName": "FAQ知识库",
|
||
"description": "常见问题知识沉淀",
|
||
"status": "ENABLED",
|
||
"documentCount": 58,
|
||
"chunkCount": 920,
|
||
"indexStatus": "PROCESSING",
|
||
"retrievable": true,
|
||
"updateTime": "2026-05-21 11:12:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreManageListResponse`
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `description`
|
||
- `status`
|
||
- `documentCount`
|
||
- `chunkCount`
|
||
- `indexStatus`
|
||
- `retrievable`
|
||
- `updateTime`
|
||
|
||
### 4.3 查询单个知识库详情增强版
|
||
|
||
- `GET /api/rag/stores/{id}/detail`
|
||
|
||
用途：
|
||
|
||
- 右侧详情区
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"id": 1,
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料",
|
||
"status": "ENABLED",
|
||
"createTime": "2026-05-03 10:20:00",
|
||
"updateTime": "2026-05-21 16:40:00",
|
||
"documentCount": 126,
|
||
"parseSuccessCount": 120,
|
||
"parseFailedCount": 6,
|
||
"chunkCount": 3800,
|
||
"lastUploadTime": "2026-05-21 15:32:00",
|
||
"lastIndexTime": "2026-05-21 15:48:00",
|
||
"retrievalMode": "HYBRID",
|
||
"embeddingModel": "bge-large-zh",
|
||
"chunkSize": 500,
|
||
"chunkOverlap": 100,
|
||
"topK": 5,
|
||
"retrievable": true
|
||
}
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreDetailResponse`
|
||
|
||
### 4.4 新建知识库独立接口
|
||
|
||
- `POST /api/rag/stores`
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料"
|
||
}
|
||
```
|
||
|
||
返回建议：
|
||
|
||
- 返回新建后的 `id` 或完整 `RagStoreDetailResponse`
|
||
|
||
建议请求 DTO：
|
||
|
||
- `RagStoreSaveRequest`
|
||
|
||
### 4.5 编辑知识库独立接口
|
||
|
||
- `PUT /api/rag/stores/{id}`
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料",
|
||
"status": "ENABLED"
|
||
}
|
||
```
|
||
|
||
用途：
|
||
|
||
- 右侧“编辑”按钮
|
||
|
||
### 4.6 当前知识库批量导入文件
|
||
|
||
- `POST /api/rag/stores/{id}/documents/import`
|
||
|
||
用途：
|
||
|
||
- 右侧“批量导入文件”按钮
|
||
|
||
建议请求类型：
|
||
|
||
- `multipart/form-data`
|
||
|
||
表单字段建议：
|
||
|
||
- `files`: 文件数组
|
||
- `remark`: 批次备注，可选
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"taskId": 1001,
|
||
"storeId": 1,
|
||
"fileCount": 12,
|
||
"status": "PROCESSING"
|
||
}
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagImportTaskResponse`
|
||
|
||
### 4.7 发起当前知识库重建索引
|
||
|
||
- `POST /api/rag/stores/{id}/reindex`
|
||
|
||
用途：
|
||
|
||
- 右侧“重建索引”按钮
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"force": true
|
||
}
|
||
```
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"taskId": 1002,
|
||
"storeId": 1,
|
||
"status": "PROCESSING"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.8 查询当前知识库最近任务
|
||
|
||
- `GET /api/rag/stores/{id}/tasks?limit=10`
|
||
|
||
用途：
|
||
|
||
- 右侧“最近任务”区
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": [
|
||
{
|
||
"id": 1002,
|
||
"taskType": "REINDEX",
|
||
"summary": "全库索引刷新",
|
||
"status": "PROCESSING",
|
||
"startedAt": "2026-05-21 16:00:00"
|
||
},
|
||
{
|
||
"id": 1001,
|
||
"taskType": "IMPORT",
|
||
"summary": "12 个文件，制度文档增量导入",
|
||
"status": "SUCCESS",
|
||
"startedAt": "2026-05-21 15:20:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreTaskResponse`
|
||
|
||
## 5. 这页前后端最小联调顺序
|
||
|
||
如果想尽快把这页从演示版切到真实联调版，建议按下面顺序接：
|
||
|
||
1. 先复用已有：
|
||
- `POST /api/rag/stores/query`
|
||
|
||
2. 然后新增：
|
||
- `GET /api/rag/stores/overview`
|
||
- `GET /api/rag/stores/{id}/detail`
|
||
|
||
3. 再补动作接口：
|
||
- `POST /api/rag/stores`
|
||
- `PUT /api/rag/stores/{id}`
|
||
- `POST /api/rag/stores/{id}/documents/import`
|
||
- `POST /api/rag/stores/{id}/reindex`
|
||
- `GET /api/rag/stores/{id}/tasks`
|
||
|
||
## 6. 当前前端实现说明
|
||
|
||
当前前端页已经按上述页面结构实现，但由于后端尚未提供完整聚合接口，页面中的统计、详情和任务区先以演示数据承载。
|
||
|
||
后端接口齐备后，前端建议按下面方式替换：
|
||
|
||
- 统计卡片：改调 `/api/rag/stores/overview`
|
||
- 左侧列表：改调 `/api/rag/stores/manage/query`
|
||
- 右侧详情：改调 `/api/rag/stores/{id}/detail`
|
||
- 批量导入：改调 `/api/rag/stores/{id}/documents/import`
|
||
- 重建索引：改调 `/api/rag/stores/{id}/reindex`
|
||
- 最近任务：改调 `/api/rag/stores/{id}/tasks`
|