KMS Wiki RAG（KmsWikiRagController）

提供 KMS 知识管理模块「Wiki RAG 域」的能力：对用户查询文本向量化后，在 Wiki 向量索引（含概念词条编辑正文入库，disk_id 固定为 wiki）中检索 top-k 相似片段。供 obpm-ai 通过 Feign 调用 WikiRagService（据类 Javadoc）。本控制器共 1 个端点，响应非统一 Resource，直接返回 KmsSimilarSnippetsResponse。

• 接口类型：REST 资源（@RestController，方法级 consumes/produces = MediaType.APPLICATION_JSON_VALUE）
• 基址：${myapps.context-path.kms:}/api/kms/wiki/rag 与 ${myapps.context-path.kms:}/kms/wiki/rag（类级 @RequestMapping 同时声明两个前缀，同一端点可经任一前缀访问；下文示例统一采用 /api/kms/wiki/rag）
• Tag：kms Wiki RAG 模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/wiki/rag/**、/kms/wiki/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()，固定对 wiki 向量库检索。
• 响应结构：非统一 Resource。端点直接以 ResponseEntity<KmsSimilarSnippetsResponse> 返回，HTTP 200，body 为 KmsSimilarSnippetsResponse（chunks 数组）。参数有误时由全局异常处理器抛 InvalidRequestException（HTTP 400）。
• 请求体：JSON 对象，类型为 KmsWikiRagSearchRequest（cn.myapps.common.dto.kms）。
• content 截断（据源码常量 CONTENT_PREVIEW_CHARS=300）：与 KmsRagController 不同，本端点对每条片段的 content 截取前 300 个字符返回（previewContent）。

---

1. Wiki 相似片段检索

对 message 向量化后在 wiki 向量索引中检索 top-k（disk_id 固定 wiki，含概念词条编辑正文入库）；返回每条含 title、keywords、filePath、score，content 至多前 300 个字符（据 @Operation.summary「Wiki 相似片段检索」）。

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

请求参数

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

请求体

字段	类型	必填	说明
message	string	是	检索查询文本（用于向量相似度 embedding）；为空抛 InvalidRequestException
topK	int	否	返回片段数，默认 10；源码校验上限 100（常量 TOPK_MAX=100，超过抛 InvalidRequestException）

{
  "message": "什么是 OAuth2 授权码模式",
  "topK": 10
}

请求示例

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

{ "message": "什么是 OAuth2 授权码模式", "topK": 10 }

响应

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

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

成功示例：

{
  "chunks": [
    {
      "id": 2001,
      "diskId": "wiki",
      "content": "授权码模式（Authorization Code）是 OAuth2 四种流程中最常用的一种...",
      "title": "OAuth2 授权码模式",
      "filePath": "__CHECKSUM__",
      "score": 0.8915,
      "keywords": "oauth,授权码,授权"
    }
  ]
}

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

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

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

---