文档托盘（DocumentTrayController）¶

提供 KMS 知识管理模块「文档托盘域」的能力：Word 文档可编辑状态检查/退出、上传控件预览水印获取、带水印的文件下载与打印。该控制器主要服务于 runtime 动态表单中的 Word 字段编辑与上传控件水印场景，多经 Feign 回调 runtime 接口。所有端点均不返回统一 Resource 封装，直接序列化 JSONObject/String/Map 或写 HTTP 响应流。

接口类型：REST 资源（@Component + AbstractBaseController，类级 produces = MediaType.APPLICATION_JSON_VALUE）
基址：${myapps.context-path.kms:}/api/portal/dynaform/document
Tag：文档托盘控制模块

公共说明¶

鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/portal/dynaform/document/** 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health 等；本控制器路径**不含 /tray/service 子串**，与同名字面不同——/tray/service 是另一处独立路径的豁免）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401（无响应体）。因此所有端点均需 accessToken，可通过以下任一方式传递：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser；getUserByUserId(userId) 直接按传入的 userId 经 Feign 装载。无 userCode 参数。
响应结构：本控制器**不使用统一 Resource 封装**，端点直接返回 JSONObject/String/Map/void（由 Spring 按 produces=application/json 序列化）或写 HTTP 响应流。
HTTP 状态码：成功 HTTP 200；未捕获异常由 AbstractBaseController 全局异常处理器映射（InvalidRequestException→400、UnauthorizedException/ForbiddenException→403、ResourceNotFoundException→404、其他→500），但本控制器多数方法在 catch 内 e.printStackTrace() 静默吞异常后返回默认值。
@RequestParam 默认必填：未标 required=false 的 query 参数按 Spring 约定为必填。

1. 检查 Word 文档是否可编辑（编辑状态）¶

按 wordid 检查 Word 字段的编辑占用状态。服务端从 WordEditEnv.wordFieldIsEdit 缓存中查找该 wordid：未找到占用记录（wordEdit == null）时返回 state=true（可编辑），否则返回 state=false（已被占用）。

接口类型：REST 资源
请求方式：@RequestMapping（未限定 method，匹配所有 HTTP 方法；按惯例以 GET/POST 调用）
请求路径：/wordFieldEditStatus（完整：{kms-context}/api/portal/dynaform/document/wordFieldEditStatus）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

参数名	位置	类型	必填	说明
wordid	query	string	是	Word 字段Id（由 `request.getParameter("wordid")` 读取）
userId	query	string	是	当前用户Id（用于 `getUserByUserId` 装载 KmsUser）

请求示例¶

GET /api/portal/dynaform/document/wordFieldEditStatus?wordid=__WORDID__&userId=__USERID__&accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：直接序列化的 JSONObject（produces=application/json，非统一 Resource）。字段：state: boolean，true 表示可编辑。

{ "state": true }

2. 检查 Word 文档是否可编辑（完整校验）¶

按 wordid 与 userId 调用 WordFieldHelper.checkWordFieldIsEdit 进行完整的可编辑校验，返回该 Helper 输出的 JSONObject（含编辑占用详情）。

接口类型：REST 资源
请求方式：@RequestMapping（未限定 method，匹配所有 HTTP 方法）
请求路径：/checkWordFieldIsEdit（完整：{kms-context}/api/portal/dynaform/document/checkWordFieldIsEdit）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

参数名	位置	类型	必填	说明
wordid	query	string	是	Word 字段Id
userId	query	string	是	当前用户Id

请求示例¶

GET /api/portal/dynaform/document/checkWordFieldIsEdit?wordid=__WORDID__&userId=__USERID__&accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：直接序列化的 JSONObject（非统一 Resource），具体字段由 WordFieldHelper.checkWordFieldIsEdit 决定。

3. 退出 Word 文档编辑¶

按 wordid 与 userId 调用 WordFieldHelper.doExixt 释放该 Word 字段的编辑占用。返回 void（HTTP 200，响应体为空）；内部异常被 catch 静默吞掉。

接口类型：REST 资源
请求方式：@RequestMapping（未限定 method，匹配所有 HTTP 方法）
请求路径：/doExixtWordField（完整：{kms-context}/api/portal/dynaform/document/doExixtWordField）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

参数名	位置	类型	必填	说明
wordid	query	string	是	Word 字段Id
userId	query	string	是	当前用户Id

请求示例¶

GET /api/portal/dynaform/document/doExixtWordField?wordid=__WORDID__&userId=__USERID__&accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：void（HTTP 200，无响应体）。

4. 获取预览水印¶

按上传控件的水印设置（waterMarkSetting JSON），经 Feign 回调 runtime 接口获取该上传控件对应 applicationId 的预览水印配置。会先校验当前用户（getUser()）。waterMarkSetting 先做 URL 解码（%20→%2B），再解析其中的 applicationId 用于 Feign 调用。

接口类型：REST 资源
请求方式：GET
请求路径：/previewWaterMark（完整：{kms-context}/api/portal/dynaform/document/previewWaterMark）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

参数名	位置	类型	必填	说明
waterMarkSetting	query	string	是	水印设置 JSON 字符串（URL 编码；需含字段 `applicationId`）

请求示例¶

GET /api/portal/dynaform/document/previewWaterMark?waterMarkSetting=%7B%22applicationId%22%3A%22__APPID__%22%7D&accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：直接序列化的 String（Feign 回调 runtime 返回的水印配置字符串；非统一 Resource）。异常或参数为空时返回空串 ""。

5. 带水印的文件下载¶

按文件名、相对路径、水印设置下载带水印的文件。校验文件名特殊符号通过后，将文件名后缀替换为 .pdf，再经 Feign 回调 runtime 接口生成带水印的 PDF 文件，最后以 application/octet-stream 二进制流写出。注意：方法签名有 String 返回值，但仅在异常或路径不合规时返回字符串 "none"（此时 HTTP 响应已提前 return，未写流）；正常下载时方法实际通过 response.getOutputStream() 写二进制流后由 Spring 忽略返回值序列化。

接口类型：REST 资源（直接写 HTTP 响应流）
请求方式：@RequestMapping（未限定 method，匹配所有 HTTP 方法）
请求路径：/fileDownloadWithWaterMark（完整：{kms-context}/api/portal/dynaform/document/fileDownloadWithWaterMark）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

参数名	位置	类型	必填	说明
filename	query	string	是	文件名（不含特殊符号时会被替换为 `.pdf` 后缀）
filepath	query	string	是	文件相对路径（必须以 `/uploads/` 开头，否则返回 `none`）
waterMarkSetting	query	string	是	水印设置 JSON 字符串（需含 `applicationId`）

请求示例¶

GET /api/portal/dynaform/document/fileDownloadWithWaterMark?filename=report.pdf&filepath=%2Fuploads%2Fdoc.pdf&waterMarkSetting=%7B%22applicationId%22%3A%22__APPID__%22%7D&accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：二进制文件流（非统一 Resource）。 - Content-Type: application/octet-stream;charset=ISO-8859-1 - Content-Disposition: attachment;filename="<编码后文件名>"（按 User-Agent 区分 Firefox/IE/其他浏览器的编码方式） - HTTP 200：水印 PDF 字节流

路径不合规（非 /uploads/ 开头）或文件不存在时，返回字符串 "none"。

6. 带水印的文件打印¶

按文件相对路径与水印设置，经 Feign 回调 runtime 接口生成带水印的 PDF，返回该 PDF 的相对存储路径供前端打印。请求体为 JSON 对象。

接口类型：REST 资源
请求方式：POST
请求路径：/filePrintWithWaterMark（完整：{kms-context}/api/portal/dynaform/document/filePrintWithWaterMark）
鉴权：是（需 accessToken，据源码）
Tag：文档托盘控制模块

请求参数¶

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

请求体¶

{
  "filepath": "/uploads/doc.pdf",
  "waterMarkSetting": "{\"applicationId\":\"__APPID__\"}"
}

请求示例¶

POST /api/portal/dynaform/document/filePrintWithWaterMark?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "filepath": "/uploads/doc.pdf", "waterMarkSetting": "{\"applicationId\":\"__APPID__\"}" }

响应¶

结构：直接序列化的 Map<String, String>（produces=application/json，非统一 Resource）。字段：

字段	类型	说明
status	string	`ok` 表示生成成功；`fail` 表示异常
pdfFilePath	string	成功时为 PDF 相对存储路径（去除存储根路径前缀）
message	string	失败时为异常消息

成功示例：

{ "status": "ok", "pdfFilePath": "/uploads/wm_xxx.pdf" }

失败示例：

{ "status": "fail", "message": "<异常消息>" }