KMS AI（KmsAiController）

提供 KMS 知识管理模块「AI 域」的能力：基于向量检索获取与指定文件相似的文件列表。本控制器共 1 个端点，返回 JSON 资源。

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

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/ai/** 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health 等）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken，可通过以下任一方式传递（据 Security.getUserIdFromToken）：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
• 执行用户：控制器继承 AbstractBaseController，但本端点未调用 getUser()，直接按路径 diskId/fileId 处理。
• 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。注意：KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码。
• 路径变量：diskId、fileId 均为 KMS 内部主键（明文 id）。

---

1. 获取相似文件

基于 KMS 向量检索获取与指定文件相似的文件列表（据 @Operation.summary「获取相似文件」）。流程：按 fileId 取源文件 → 优先用 FileTags.autoTags 作为查询文本（无标签时退回文件名）→ 经 RagService.search 在指定网盘内做向量检索 → 按 checksum 去重并剔除源文件 → 按 score 降序取前 topK 个文件实体。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/disks/{diskId}/files/{fileId}/similar-files（完整：{kms-context}/api/ai/disks/{diskId}/files/{fileId}/similar-files）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms AI 模块

请求参数

参数名	位置	类型	必填	说明
diskId	path	string	是	网盘Id（源文件须属于该网盘，否则抛 InvalidRequestException）
fileId	path	string	是	文件Id
topK	query	int	否	返回相似文件数量，默认 10；源码校验范围 1–50（不在范围内抛 InvalidRequestException）

请求示例

GET /api/ai/disks/__DISKID__/files/__FILEID__/similar-files?topK=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：List<FileEntity>，按相关度降序排列的相似文件实体列表；向量检索未命中时返回空数组，errmsg 为「未找到相似文件」。

成功示例：

{
  "errcode": 0,
  "errmsg": "获取相似文件成功",
  "data": [
    { "id": "__FILEID2__", "name": "相似文档.docx", "type": "docx", "checksum": "__CHECKSUM__", "diskId": "__DISKID__" }
  ],
  "errors": null
}

失败示例（参数有误）：

{ "errcode": 400, "errmsg": "topK参数必须在1-50之间", "data": null, "errors": null }

注：服务层异常时（非参数校验类）端点在 catch 内抛出 new Exception(...)，由全局异常处理器映射为 HTTP 500 / errcode=500。

---