common_agent/rag-store-page-apis.md

知识库页面后端接口清单

本文对应前端页面：RagStoresPage.vue

1. 页面目标

知识库页面采用：

• 顶部 4 张全局统计卡片
• 左侧知识库名称搜索与列表
• 右侧当前知识库详情
• 当前知识库级别操作：编辑、批量导入文件、重建索引

因此接口建议拆成 全局概览、知识库列表/详情、单库动作 三组。

2. 本批已实现并已用于前端联调的接口

2.1 查询全部知识库

• GET /api/rag/stores

当前返回类型：

• RequestResult<List<RagStoreResponse>>

当前字段：

• id
• storeCode
• storeName
• description
• status
• remark

对应代码：

• RagStoreController.java
• RagStoreResponse.java

2.2 按条件查询知识库

• POST /api/rag/stores/query

请求体：

{
  "storeCode": "PROD_DOC",
  "storeName": "产品制度",
  "status": "ENABLED"
}

当前支持字段：

• storeCode
• storeName
• status

对应代码：

• RagStoreQueryRequest.java

2.3 查询知识库详情

• GET /api/rag/stores/{id}

返回类型：

• RequestResult<RagStoreResponse>

2.4 新增或修改知识库

• POST /api/rag/stores

请求体：

{
  "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
• RagDocumentQueryRequest.java

4. 下一批建议补充的接口

当前已有接口能支撑最基础的列表查询，但还不足以支撑统计卡片、右侧详情聚合和单库动作。建议补下面几个接口。

4.1 知识库总览统计

• GET /api/rag/stores/overview

用途：

• 顶部 4 张卡片数据

返回建议：

{
  "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，建议直接返回列表页需要的摘要字段，避免前端再额外聚合文档数据。

请求体建议：

{
  "storeName": "FAQ"
}

返回建议：

{
  "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

用途：

• 右侧详情区

返回建议：

{
  "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

请求体建议：

{
  "storeCode": "PROD_DOC",
  "storeName": "产品制度库",
  "description": "产品制度、业务规范、流程材料"
}

返回建议：

• 返回新建后的 id 或完整 RagStoreDetailResponse

建议请求 DTO：

• RagStoreSaveRequest

4.5 编辑知识库独立接口

• PUT /api/rag/stores/{id}

请求体建议：

{
  "storeCode": "PROD_DOC",
  "storeName": "产品制度库",
  "description": "产品制度、业务规范、流程材料",
  "status": "ENABLED"
}

用途：

• 右侧“编辑”按钮

4.6 当前知识库批量导入文件

• POST /api/rag/stores/{id}/documents/import

用途：

• 右侧“批量导入文件”按钮

建议请求类型：

• multipart/form-data

表单字段建议：

• files: 文件数组
• remark: 批次备注，可选

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": {
    "taskId": 1001,
    "storeId": 1,
    "fileCount": 12,
    "status": "PROCESSING"
  }
}

建议响应 DTO：

• RagImportTaskResponse

4.7 发起当前知识库重建索引

• POST /api/rag/stores/{id}/reindex

用途：

• 右侧“重建索引”按钮

请求体建议：

{
  "force": true
}

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": {
    "taskId": 1002,
    "storeId": 1,
    "status": "PROCESSING"
  }
}

4.8 查询当前知识库最近任务

• GET /api/rag/stores/{id}/tasks?limit=10

用途：

• 右侧“最近任务”区

返回建议：

{
  "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