KMS RAG（KmsRagController）

提供 KMS 知识管理模块「RAG 域」的能力：对用户查询文本向量化后，在指定网盘的向量库中检索 top-k 相似文本片段。供 obpm-ai 通过 Feign 调用 RagService（据类 Javadoc）。本控制器共 1 个端点，响应非统一 Resource，直接返回 KmsSimilarSnippetsResponse。

• 接口类型：REST 资源（@RestController，方法级 consumes/produces = MediaType.APPLICATION_JSON_VALUE）
• 基址：${myapps.context-path.kms:}/api/kms/rag（类级 @RequestMapping 仅声明单一前缀）
• Tag：kms RAG 模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/rag/** 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken（或前置过滤器标记 pass=true 的系统 Feign 调用——obpm-ai 经 Feign 携带合法 systemToken 时会被放行，详见 index.md「鉴权说明」）。accessToken 可通过以下任一方式传递：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。
• 执行用户：控制器继承 AbstractBaseController，但本端点未调用 getUser()，按请求体 diskId 过滤。
• 响应结构：非统一 Resource。端点直接以 ResponseEntity<KmsSimilarSnippetsResponse> 返回，HTTP 200，body 为 KmsSimilarSnippetsResponse（chunks 数组）。参数有误时由全局异常处理器抛 InvalidRequestException（HTTP 400）。Resource 包装器不参与本端点。
• 请求体：JSON 对象，类型为 KmsSimilarSnippetsRequest（cn.myapps.common.dto.kms）。

---

1. 相似文本片段检索

对用户 message 向量化后在指定 disk_id 网盘向量库中检索 top-k 相似片段（据 @Operation.summary「相似文本片段检索」）。当请求体带 keywords 时改走 RagService.search(keywords, message, diskId, topK) 复合检索（关键词全部命中才保留片段），否则仅按 message embedding 检索。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/similar-snippets（完整：{kms-context}/api/kms/rag/similar-snippets）
• 鉴权：是（需 accessToken 或系统 Feign pass=true，据源码）
• Tag：kms RAG 模块

请求参数

参数名	位置	类型	必填	说明
body	body	object	是	JSON 对象，见下方请求体

请求体

字段	类型	必填	说明
message	string	是	检索查询文本（用于向量相似度 embedding）；为空抛 InvalidRequestException
disk_id	string	是	网盘Id CSV，支持英文逗号分隔多值（JSON 字段名为 disk_id，Java 形参 diskId 经 @JsonProperty("disk_id") 映射）；为空抛 InvalidRequestException
keywords	string	否	英文逗号分隔关键词，全部命中才保留片段（trim 后精确匹配）
topK	int	否	返回片段数，默认 10；源码校验上限 100（超过抛 InvalidRequestException）

{
  "message": "如何配置 OAuth2 单点登录",
  "disk_id": "__DISKID__",
  "keywords": "oauth,sso",
  "topK": 10
}

请求示例

POST /api/kms/rag/similar-snippets?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "message": "如何配置 OAuth2 单点登录", "disk_id": "__DISKID__", "topK": 10 }

响应

结构：非统一 Resource。HTTP 200，body 为 KmsSimilarSnippetsResponse，仅含字段 chunks（数组）。每项为 KmsSimilarSnippetDTO，字段如下：

字段	类型	说明
id	long	片段向量记录Id
diskId	string	所属网盘Id
content	string	片段正文
title	string	片段/文档标题（入库时写入，可为 null）
filePath	string	文件内容校验和（历史字段名为 filePath，实为 checksum）
score	float	相似度分数
keywords	string	片段关键词（多为逗号分隔）

成功示例：

{
  "chunks": [
    {
      "id": 1001,
      "diskId": "__DISKID__",
      "content": "OAuth2 单点登录需在域配置中录入 clientId/clientSecret...",
      "title": "OAuth2 集成指南",
      "filePath": "__CHECKSUM__",
      "score": 0.8732,
      "keywords": "oauth,sso,登录"
    }
  ]
}

失败示例（参数有误，HTTP 400）：

{ "errcode": 400, "errmsg": "message 不能为空", "data": null, "errors": null }

注：失败响应由全局异常处理器包装为统一 Resource（与 KMS 其他端点一致）；成功响应**不**经 Resource 包装。

---