设计时表单管理（FormController）

表单设计时资源管理：表单的增删改查、复制，表单字段/清除数据字段列表查询，表单操作（按钮 Activity）的增删改查，字段编号生成，字段数据清除，表单帮助文档与树形目录，以及数据表/列名称映射查询。

• 接口类型：REST 资源
• 基址：${myapps.context-path.designer:}/api/designtime/applications（类级 @RequestMapping，produces = APPLICATION_JSON_VALUE）
• Tag：设计时-表单模块

公共说明

• 鉴权：是（需 designerToken）。所有端点继承自 AbstractDesignTimeController（基类为 @RestController），通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
• 路径变量：{applicationId}、{moduleId}、{formId}、{activityId} 均为**明文设计时 ID**（与 designer 其他控制器一致，非 runtime 的 DES 加密密文）。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500，errmsg 为异常信息；保存类接口捕获 OBPMValidateException（重名、映射校验等）时返回 errcode=40001。
• HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
• 请求体约定：多数 POST/PUT/DELETE 接收原始 JSON 字符串（@RequestBody String content）或 JSON 字符串数组（@RequestBody String[]），由服务端用 JSONObject.fromObject/JsonPath 解析。
• 表单类型常量（来自 Form，用于 type 形参/过滤）：1=普通表单、2=标签页、256=查询表单、65536=普通（映射）、1048576=模板表单。

---

1. 获取表单列表

分页获取指定模块下的表单列表，可按名称/描述查询、按表单类型过滤。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/{moduleId}/forms（完整：{designer-context}/api/designtime/applications/{applicationId}/modules/{moduleId}/forms）
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
name	query	string	否	按名称查询关键字
description	query	string	否	按描述查询关键字
type	query	string	否	表单类型（缺省 0=不过滤；非 0 时按精确匹配过滤）
pageNo	query	string	否	当前页数（缺省 1）
linesPerPage	query	string	否	每页行数（缺省 10）

说明：description/pageNo/linesPerPage 形参未标注 @RequestParam，由 Spring MVC 按请求参数绑定，故可缺省。name/type 标注 required = false。@Parameter 中将 pageNo/linesPerPage 标记为 required=true，但实现做了缺省兜底。

请求示例

GET /api/designtime/applications/{applicationId}/modules/{moduleId}/forms?name=&type=0&pageNo=1&linesPerPage=10 HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data： - type 缺省或为 0 时为 DataPackage<Form>（含分页字段与 datas）。 - type 非 0 时为 JSONArray，每项 {id, name, description, orderno}（仅返回与该类型精确匹配的表单）。

成功示例（未传 type）：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "rowCount": 8,
    "pageNo": 1,
    "pageCount": 1,
    "datas": [
      { "id": "...", "name": "表单名称", "description": "...", "type": 1, "...": "..." }
    ]
  },
  "errors": null
}

成功示例（type=1）：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "id": "...", "name": "表单名称", "description": "...", "orderno": 1 }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

2. 获取表单详情

按表单Id获取完整表单对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/{formId}
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id

响应

data：Form 完整对象（含字段、操作、模板、表映射等）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "type": 1, "...": "..." }, "errors": null }

---

3. 新建表单

在指定模块下新建表单。请求体先经 normalizeFormPanelPayload 归一化（兼容 {fields, layout} 模板格式），再做重名/映射等保存前校验。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/{moduleId}/forms
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
content	body	string(JSON)	是	表单对象 JSON

请求体

对应 Form 对象的完整 JSON（name、type、fields/templatecontext、tableMapping 等）。

响应

data：JSONObject，仅含 id（新建表单Id）。校验失败时 errcode=40001，errmsg 为校验信息（如重名 [<名称>]{*[core.form.exist]*}）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<新表单Id>" }, "errors": null }

失败示例：

{ "errcode": 40001, "errmsg": "[<名称>]{*[core.form.exist]*}", "data": null, "errors": null }

---

4. 更新表单

按表单Id更新整个表单对象（含保存前校验）。当字段变更引发 NeedConfirmException 时返回 40001 并带确认提示文案。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/{moduleId}/forms/{formId}
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
formId	path	string	是	表单Id
content	body	string(JSON)	是	表单对象 JSON

响应

data：null（成功）。

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

失败示例：

{ "errcode": 40001, "errmsg": "<校验或确认信息>", "data": null, "errors": null }

---

5. 删除表单（可批量）

按表单Id数组批量删除表单（含路径信息收集与删除日志记录）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/forms
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	表单Id数组（JSON 数组字符串，由 JsonPath 解析为 List<String>）

请求体

["<formId1>", "<formId2>"]

响应

data：null（成功）。

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

---

6. 复制表单

按表单Id复制为同名检查通过后的新表单（重名时返回 500）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/forms/{formId}/copy
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	源表单Id
content	body	string(JSON)	是	含 name 字段（新表单名称）的对象

请求体

{ "name": "<新表单名称>" }

响应

data：null（成功）。重名时 errcode=500，errmsg 形如 [<名称>]{*[core.form.exist]*}。

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

---

7. 获取表单字段列表

获取指定表单下的字段列表。未指定 type 时排除若干特殊字段（IncludeField/TabField/CalctextField/FlowHistoryField/FileManagerField/ReminderField/FlowReminderHistoryField）；type=eventMapping 时仅返回 InputField/SuggestField。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/{formId}/fields
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id
type	query	string	否	字段过滤模式：缺省=排除特殊字段；eventMapping=仅可映射事件字段

响应

data：JSONArray，每项 {id, name, discript, type, formField, valueType?}。其中 formField 为字段实现类简名；当字段为 MapField 子类时附带 valueType。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "id": "...", "name": "字段名", "discript": "描述", "type": "VALUE_TYPE_NUMBER", "formField": "TextField", "valueType": "VALUE_TYPE_NUMBER" }
  ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

8. 获取表单清除数据字段列表

获取指定表单可用于「清除数据」的字段（即 getValueStoreFields()，仅存储值类字段）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/{formId}/clearFields
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id

响应

data：JSONArray，每项 {id, name, type}。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "id": "...", "name": "字段名", "type": "VALUE_TYPE_TEXT" } ],
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

9. 获取表单操作列表

获取指定表单下的操作（按钮 Activity）列表。实现上将表单的 activities 置空后重新加载，触发懒加载得到该表单下的全部操作。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/{formId}/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id

响应

data：List<Activity>。

{ "errcode": 0, "errmsg": "ok", "data": [ { "id": "...", "name": "...", "...": "..." } ], "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

10. 获取表单操作详情

按操作Id获取完整表单操作（按钮 Activity）对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/activitys/{activityId}
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
activityId	path	string	是	表单操作Id

响应

data：Activity 完整对象。

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

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

11. 新建表单操作

在指定表单下新建表单操作（按钮 Activity）。重名时抛出 "该按钮名称已存在"（沿用按钮校验文案）。入参携带 id 时复用其 id；不携带则生成新 id。入参为 null 时不保存，直接返回成功。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/forms/{formId}/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id
content	body	string(JSON)	是	表单操作对象 JSON

响应

data：JSONObject，含 id（新建或入参携带的操作Id）；入参为 null 时为 null。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<activityId>" }, "errors": null }

失败示例（重名等）：

{ "errcode": 500, "errmsg": "该按钮名称已存在", "data": null, "errors": null }

---

12. 更新表单操作

更新指定表单操作（按钮 Activity）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/forms/{formId}/activitys/{activityId}
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id
activityId	path	string	是	表单操作Id
content	body	string(JSON)	是	表单操作对象 JSON

响应

data：null（成功）。

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

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

13. 删除表单操作（可批量）

按操作Id数组批量删除表单操作（含路径信息收集）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/forms/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
ids	body	string	是	操作Id字符串数组（JSON 数组反序列化为 String[]）

请求体

["<activityId1>", "<activityId2>"]

响应

data：null（成功）。

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

---

14. 重置字段编号（返回随机数）

生成一个新的设计时序列号，用于表单设计器中字段编号重置。该端点路径下不含 {applicationId} 段。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/modules/forms/getSequence（完整：{designer-context}/api/designtime/applications/modules/forms/getSequence）
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

无。

请求示例

GET /api/designtime/applications/modules/forms/getSequence HTTP/1.1

响应

data：String，新生成的设计时序列号。

{ "errcode": 0, "errmsg": "ok", "data": "<序列号>", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

15. 清除表单字段数据

按字段名数组清除指定表单已存储的字段列数据（formService.doClearColumnData）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/forms/{formId}/cleardata
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	表单Id
fields	body	string	是	字段名数组（JSON 数组反序列化为 String[]）

请求体

["<fieldName1>", "<fieldName2>"]

响应

data：null（成功）。

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

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

16. 获取表单帮助

按帮助Id返回帮助主题的 href 与国际化标签（标签以 {*[...]*} 形式返回，由前端解析）。语言取自请求 Cookie 中的多语言设置。该端点路径下不含 {applicationId} 段。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/modules/forms/help（完整：{designer-context}/api/designtime/applications/modules/forms/help）
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
id	query	string	是	帮助主题Id

请求示例

GET /api/designtime/applications/modules/forms/help?id=<topicId> HTTP/1.1

响应

data：JSONObject，结构 {href, label}；主题未命中或 id 非法时返回空对象。

{ "errcode": 0, "errmsg": "ok", "data": { "href": "<帮助链接>", "label": "{*[<标签键>]*}" }, "errors": null }

---

17. 获取帮助树形目录

返回表单帮助文档的树形目录 HTML 字符串（由 HelpHelper.doHelpTreeIndex 生成）。该端点路径下不含 {applicationId} 段。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/modules/getHelpTreeIndex（完整：{designer-context}/api/designtime/applications/modules/getHelpTreeIndex）
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

无。

请求示例

GET /api/designtime/applications/modules/getHelpTreeIndex HTTP/1.1

响应

data：String，帮助树形目录的 HTML 片段。

{ "errcode": 0, "errmsg": "ok", "data": "<HTML 字符串>", "errors": null }

---

18. 获取数据表名称映射

返回指定应用下所有动态表的「表名 → 显示名」映射，供表单设计器映射配置使用。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/dataBaseTableMap
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id

响应

data：Map<String, String>（表名 → 显示名）。

{ "errcode": 0, "errmsg": "ok", "data": { "<表名>": "<显示名>" }, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

19. 获取数据库列名称映射

按表名返回该表的「列名 → 显示名」映射。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/forms/dataBaseColumnMap
• 鉴权：是（需 designerToken）
• Tag：设计时-表单模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
tableName	query	string	是	数据库表名

请求示例

GET /api/designtime/applications/{applicationId}/modules/forms/dataBaseColumnMap?tableName=<tableName> HTTP/1.1

响应

data：Map<String, String>（列名 → 显示名）。

{ "errcode": 0, "errmsg": "ok", "data": { "<列名>": "<显示名>" }, "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---