表单执行（FormController）

表单运行时接口：获取表单数据包、判断打开权限、刷新表单、新建空文档、上传控件水印与水印文件下载。

• 接口类型：REST 资源
• 基址：${myapps.context-path.runtime:}/api/runtime/{applicationId}（produces=APPLICATION_JSON_VALUE）
• Tag：表单执行模块

公共说明

• 鉴权：基址在 /api/runtime/**（非 /rest/），需登录态 accessToken（query/header/Cookie），由前置过滤器与控制器内 Security.getUserIdFromToken(request) 校验（据源码）。
• 路径变量加密：{applicationId}、{formid}、{docid} 等路径变量均为 DES 加密密文，服务端按当前用户解密（DesUtil.decryptTextByUserId）。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）；但 获取上传控件水印、返回水印文件路径 返回 裸字符串/二进制流（非 Resource），见各自说明。

---

1. 获取表单信息

根据表单 Id 与文档 Id 获取表单数据包（FormDataPacket，含字段、文档、权限等）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/forms/{formid}/documents/{docid}
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
formid	path	string	是	表单Id（DES 加密密文）
docid	path	string	是	文档Id（DES 加密密文）
isReadonly	query	boolean	否	是否只读

请求示例

GET /api/runtime/__APPID__/forms/__FORMID__/documents/__DOCID__?isReadonly=false HTTP/1.1

响应

结构：统一 Resource（见 ../index.md）。 data：FormDataPacket（含 document、fields 等；返回的 docId/字段 id 经加密）。

成功示例：

{ "errcode":0, "errmsg":"ok", "data":{ "docId":"__SEALED__", "document":{ "id":"..." }, "fields":[...] }, "errors":null }

失败示例：

{ "errcode":404, "errmsg":"Not Found", "data":null, "errors":null }

---

2. 判断表单打开权限（按文档）

判断当前用户对指定文档所在表单的打开权限。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/forms/{formid}/documents/{docid}/openable
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
formid	path	string	是	表单Id（DES 加密密文）
docid	path	string	是	文档Id（DES 加密密文）

响应

data：boolean，是否可打开。

{ "errcode":0, "errmsg":"ok", "data":true, "errors":null }

---

3. 判断表单打开权限（按表单）

按表单定义判断当前用户是否有打开权限（公开表单恒为 true；否则按角色校验 FORM_VIEW_ALLOW_OPEN）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/forms/{formId}/openable
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
formId	path	string	是	表单Id

响应

data：boolean。

{ "errcode":0, "errmsg":"ok", "data":true, "errors":null }

---

4. 刷新表单

根据触发字段与当前文档内容刷新表单（联动重算）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/forms/{formid}/documents/{docid}/refresh
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
formid	path	string	是	表单Id（DES 加密密文）
docid	path	string	是	文档Id（DES 加密密文）
content	body	string(JSON)	是	请求包体（见下）

请求体

{
  "actField": "<触发字段名>",
  "tabId": "<页签Id>",
  "document": {
    "templateForm": "<模板表单Id>",
    "items": { "<字段名>": "<字段值>" }
  }
}

响应

data：Map，刷新后的字段结果。

{ "errcode":0, "errmsg":"ok", "data":{ "...": "..." }, "errors":null }

---

5. 新建空文档

按表单 Id 新建一个空文档（Document）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/forms/{formid}/empty
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
formid	path	string	是	表单Id（DES 加密密文）

响应

data：Document，新建的空文档对象。

{ "errcode":0, "errmsg":"ok", "data":{ "id":"...", "items":{} }, "errors":null }

---

6. 获取上传控件水印

根据水印设置获取上传控件的水印信息。

• 接口类型：REST 资源（返回裸 JSON 字符串，非 Resource）
• 请求方式：GET
• 请求路径：/getUploadFieldWaterMark
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
waterMarkSetting	query	string(JSON)	是	水印设置（含 applicationId、docId、itemId、type，均 DES 加密）

响应

类型：裸 JSON 字符串（@ResponseBody String），非 Resource。形如：

{ "waterMarkPicUrl": "<图片URL>", "waterMarkStr": "<水印文字>" }

异常或参数为空时返回 {"waterMarkPicUrl":"","waterMarkStr":""}。

---

7. 返回水印文件路径（水印 PDF 下载）

下载带水印的 PDF 文件（直接写入 HTTP 响应流）。

• 接口类型：REST 资源（二进制响应，非 Resource）
• 请求方式：GET/POST（方法级 @RequestMapping，未限定方法）
• 请求路径：/fileDownloadWithWaterMark
• 鉴权：是（需 accessToken，据源码）
• Tag：表单执行模块

请求参数

参数名	位置	类型	必填	说明
filename	query	string	是	文件名（自动改后缀为 .pdf）
filepath	query	string	是	文件路径（须以 /uploads/ 开头，否则返回 "none"）
waterMarkSetting	query	string(JSON)	是	水印设置（含 applicationId、docId、itemId，均 DES 加密）

响应

类型：application/octet-stream，PDF 字节流写入响应体；Content-Disposition: attachment; filename="<filename>.pdf"。 - 文件不存在或参数非法时返回字符串 "none"。

---