搜索（SearchController）

提供 KMS 知识管理模块的文件检索与「最新/最热」榜单能力：向量语义检索（与 RagService 同源逻辑，不走 Lucene 全文索引）、最新浏览/上传/分享/搜索榜单、最热浏览榜单、当前用户最近的上传/编辑/预览/搜索榜单，以及删除搜索记录。所有端点均返回 JSON 资源。

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

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/search/**、/kms/search/** 均不在 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「鉴权说明」。
• 执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。无 userCode 参数。
• 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故 data 中的 HTML 特殊字符会被转义。
• HTTP 状态码与错误码（据源码 AbstractBaseController 全局异常处理）：成功默认 HTTP 200；InvalidRequestException → HTTP 400 / errcode=400；UnauthorizedException → HTTP 403 / errcode=403；ForbiddenException → HTTP 403 / errcode=403；ResourceNotFoundException → HTTP 404 / errcode=404；其他 Exception → HTTP 500 / errcode=500。
• @RequestParam 默认必填：未标 required=false 且无 defaultValue 的 query 参数按 Spring 约定为必填。
• 路径变量：id（搜索记录 Id）为 KMS 内部主键（明文 id）。
• 网盘类型常量（据源码 Disk）：TYPE_DEPARTMENT（部门网盘）、TYPE_TEAM（团队网盘）、TYPE_PERSON（个人网盘）。多数榜单默认检索部门 + 团队网盘；「我的最近」系列额外纳入个人网盘。

---

1. 文件搜索列表

按关键词进行向量语义检索（与 RagService 向量检索逻辑一致，不经 Lucene 全文索引）。searchword 与 keyword 至少其一非空，否则抛 InvalidRequestException（HTTP 400）。

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

请求参数

参数名	位置	类型	必填	说明
searchword	query	string	否	语义检索关键词（trim 后判断非空；与 keyword 至少填一项）
keyword	query	string	否	关键词（trim 后判断非空；与 searchword 至少填一项）
selectTitle	query	boolean	否	是否检索标题，默认 true
selectContent	query	boolean	否	是否检索正文，默认 true
creator	query	string	否	创建者名称（单值）
creatorIds	query	array(string)	否	创建者 Id 列表
fileTypes	query	array(string)	否	文件类型过滤列表
categoryIds	query	array(string)	否	标签（分类）Id 列表
beginTime	query	string	否	起始时间戳（毫秒，字符串型）
endTime	query	string	否	截止时间戳（毫秒，字符串型；服务端会将其延展到当天 23:59:59.999）
scope	query	array(int)	否	网盘类型范围；缺省时按 [TYPE_DEPARTMENT, TYPE_TEAM] 检索
pageNo	query	int	否	页码，默认 1；<1 抛 400
linesPerPage	query	int	否	每页条数，默认 10；须在 1～100 之间，否则抛 400

请求示例

GET /api/kms/search/files?searchword=季度报告&pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<SearchFile>（由 dataBuilder.buildSearchFileReturnData 构造，含当前页数据与分页信息，并附带当前用户视角的权限/收藏标记）。

失败示例（参数有误）：

{ "errcode": 400, "errmsg": "searchword 与 keyword 至少填写一项", "data": null, "errors": null }

---

2. 最新浏览文件列表

分页查询当前用户企业域下、按最新浏览时间倒序的文件榜单（部门网盘 + 团队网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/lastest_view（完整：{kms-context}/api/kms/search/files/lastest_view）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/lastest_view?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造，数据类型标记 DATA_TYPE_COLLECTED）。

---

3. 最新上传文件列表

分页查询当前用户企业域下、按最新上传时间倒序的文件榜单（部门网盘 + 团队网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/lastest_upload（完整：{kms-context}/api/kms/search/files/lastest_upload）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/lastest_upload?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造，数据类型标记 DATA_TYPE_COLLECTED；服务层未限定创建者，返回企业域全量）。

---

4. 用户最近上传文件列表

分页查询**当前用户**最近上传的文件榜单（部门网盘 + 团队网盘 + 个人网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/myLastest_upload（完整：{kms-context}/api/kms/search/files/myLastest_upload）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/myLastest_upload?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（直接返回服务层结果，未经 dataBuilder 包装）。

---

5. 用户最近编辑的 word 文档列表

分页查询**当前用户**最近编辑的 word 文档榜单（部门网盘 + 团队网盘 + 个人网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/myRecent_edit（完整：{kms-context}/api/kms/search/files/myRecent_edit）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/myRecent_edit?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（直接返回服务层结果）。

---

6. 用户最近预览文档列表

分页查询**当前用户**最近预览的文件榜单（部门网盘 + 团队网盘 + 个人网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/myRecent_preview（完整：{kms-context}/api/kms/search/files/myRecent_preview）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/myRecent_preview?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（直接返回服务层结果）。

---

7. 最热浏览次数文件列表

分页查询当前用户企业域下、按浏览次数倒序的「最热」文件榜单（部门网盘 + 团队网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/hot_view（完整：{kms-context}/api/kms/search/files/hot_view）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/hot_view?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造，数据类型标记 DATA_TYPE_VIEWS）。

---

8. 最新分享文件列表

分页查询当前用户企业域下、按最新分享时间倒序的文件榜单（部门网盘 + 团队网盘）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/lastest_share（完整：{kms-context}/api/kms/search/files/lastest_share）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/lastest_share?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造，数据类型标记 DATA_TYPE_COLLECTED）。

---

9. 最新搜索文件列表

分页查询当前用户企业域下、按最新搜索时间倒序的「搜索词记录」榜单（不区分用户，全企业域）。返回的是搜索词记录列表而非文件列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/lastest_search（完整：{kms-context}/api/kms/search/files/lastest_search）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/lastest_search?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<Searchword>（搜索词记录分页数据；服务层以 userId=null 调用，返回企业域全量记录）。

---

10. 用户最近搜索文件列表

分页查询**当前用户**最近的「搜索词记录」榜单。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/search/files/myLastest_search（完整：{kms-context}/api/kms/search/files/myLastest_search）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	是	页码
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/search/files/myLastest_search?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<Searchword>（当前用户的搜索词记录分页数据）。

---

11. 删除搜索记录

按搜索记录 Id 删除单条搜索词记录。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/search/{id}（完整：{kms-context}/api/kms/search/{id}）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms搜索模块

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	搜索记录Id

请求示例

DELETE /api/kms/search/__SEARCHID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：null（操作完成后返回 success("ok", null)）。

---