水印（WatermarkController）

提供 KMS 知识管理模块「水印域」的管理能力：获取水印配置、获取水印内容（按文件与类型计算）、保存水印配置、生成水印 PDF 文件。所有端点均返回 JSON 资源。

• 接口类型：REST 资源（@RestController；类级与方法级均**未**显式声明 produces，由 Spring 默认内容协商按对象返回类型序列化为 JSON）
• 基址：${myapps.context-path.kms:}/api/kms（类级 @RequestMapping 仅声明单一前缀，无 /kms 备用前缀；与 TeamController/FolderController 一致）
• Tag：kms水印模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/watermark/** 均不在 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 参数。水印内容计算时会用到当前用户的 name、defaultDepartment。
• 响应结构：统一 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 参数（含未加注解的简单类型形参，如 type）按 Spring 约定为必填。

---

1. 获取水印配置文件

返回当前 KMS 模块的水印配置对象（从 watermarkService.getWatermarkConfig() 读取）。

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

请求参数

无。

请求示例

GET /api/kms/watermark/config?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：WatermarkConfig，水印配置对象。

---

2. 获取水印内容

按文件 Id 与水印类型，结合当前用户、文件创建者、所属部门、所属网盘等信息，经 IRunner 执行水印脚本（$WEB 为 WebJsUtil）后计算实际水印内容字符串。

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

请求参数

参数名	位置	类型	必填	说明
fileId	query	string	是	文件Id
type	query	string	是	水印类型（无 @RequestParam 注解，按形参名绑定 query 参数）

请求示例

GET /api/kms/watermark/content?fileId=__FILEID__&type=pdf&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，计算得到的水印内容。

---

3. 保存水印配置文件

保存传入的水印配置（覆盖写入 WatermarkConfig.watermarkConfigPath 指向的配置文件，以单元素数组形式落盘）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/watermark/config（完整：{kms-context}/api/kms/watermark/config）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms水印模块

请求参数

参数名	位置	类型	必填	说明
body	body	object	是	WatermarkConfig 对象 JSON

请求体

{
  "content": "用户：{username}，时间：{date}",
  "enabled": true
}

上述字段仅为示例，实际字段集以 WatermarkConfig 模型为准。

请求示例

PUT /api/kms/watermark/config?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "content": "用户：{username}，时间：{date}", "enabled": true }

响应

结构：统一 Resource。 data：回传的 WatermarkConfig（即请求体）。

---

4. 生成水印文件

按文件 Id 与水印类型，计算水印内容并生成水印 PDF 文件，返回该 PDF 文件相对存储根目录的路径。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/watermark/pdf（完整：{kms-context}/api/kms/watermark/pdf）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms水印模块

请求参数

参数名	位置	类型	必填	说明
fileId	query	string	是	文件Id
type	query	string	是	水印类型（无 @RequestParam 注解，按形参名绑定 query 参数）

请求示例

POST /api/kms/watermark/pdf?fileId=__FILEID__&type=pdf&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，生成的水印 PDF 文件**相对存储根目录**的路径（据源码：file.getAbsolutePath().substring(realPath.length())，即剥离 Environment.getInstance().getStorageRootPath() 前缀后的相对路径）。

据源码：本端点使用 JavaScriptFactory.getInstance(request.getRequestedSessionId()) 获取脚本运行器（与 #2 使用 getInstance("kms") 略有差异），最终同样向 $WEB 注入 WebJsUtil。

---