# 知识库页面后端接口清单

本文对应前端页面：[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`