文件历史（FileHistoryController）

提供 KMS 知识管理模块「文件历史域」的能力：基于 kms_file.version 字段的文件版本历史功能，包括按文件Id查询历史版本列表、按版本号获取特定版本、获取文件当前最大版本号、还原到指定历史版本。所有端点均返回 JSON 资源。

• 接口类型：REST 资源（@RestController，方法级 produces = MediaType.APPLICATION_JSON_VALUE；类级 @RequestMapping 仅声明前缀，未带 produces）
• 基址：${myapps.context-path.kms:}/api/file-history（类级 @RequestMapping 以单元素数组形式声明单一前缀，无 /kms 备用前缀；与 file/team 控制器不同，不带 /api/kms 前缀）
• Tag：kms文件历史模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/file-history/** 不在 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。本控制器仅在 #1（列表）中通过 getUser() 计算当前用户对每个历史版本的操作权限。无 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 约定为必填。
• 路径变量：fileId 为 KMS 文件内部主键（明文 id），version 为 int 类型版本号。

---

1. 获取文件历史记录列表

按文件Id查询该文件的全部历史版本列表（按版本号倒序），并由 dataBuilder.buildFileEntityReturnData 包装为含操作权限的返回结构。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{fileId}/history（完整：{kms-context}/api/file-history/{fileId}/history）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms文件历史模块

请求参数

参数名	位置	类型	必填	说明
fileId	path	string	是	文件Id

请求示例

GET /api/file-history/__FILEID__/history?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<FileEntity> 历史版本列表（由 dataBuilder.buildFileEntityReturnData(history, getUser) 包装，包含每个版本实体与当前用户对其的操作权限集合）。

---

2. 获取特定版本的文件

按文件Id与版本号获取该版本的文件实体。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{fileId}/version/{version}（完整：{kms-context}/api/file-history/{fileId}/version/{version}）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms文件历史模块

请求参数

参数名	位置	类型	必填	说明
fileId	path	string	是	文件Id
version	path	int	是	版本号

请求示例

GET /api/file-history/__FILEID__/version/3?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：FileEntity，指定版本对应的文件实体（直接返回服务层结果，未经 dataBuilder 包装）。

---

3. 获取文件最大版本号

按文件Id查询该文件当前的最大版本号。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{fileId}/max-version（完整：{kms-context}/api/file-history/{fileId}/max-version）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms文件历史模块

请求参数

参数名	位置	类型	必填	说明
fileId	path	string	是	文件Id

请求示例

GET /api/file-history/__FILEID__/max-version?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Integer，文件当前最大版本号。

---

4. 还原到特定版本

将指定文件还原到给定版本号（基于当前用户记录还原操作）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{fileId}/restore（完整：{kms-context}/api/file-history/{fileId}/restore）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms文件历史模块

请求参数

参数名	位置	类型	必填	说明
fileId	path	string	是	文件Id
version	query	Integer	是	还原到的目标版本号

请求示例

POST /api/file-history/__FILEID__/restore?version=2&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，固定为 true（还原操作由 fileService.revertVersion(fileId, version, getUser) 完成，过程中抛出的异常由全局处理器映射）。

---