设计时流程定义管理（BillDefiController）

流程定义（BillDefiVO / .flow）设计时资源管理：流程的增删改查、复制，按当前节点获取前置节点（流程编辑器），子流程获取父流程表单，流程编辑器获取所有流程与模块清单，以及流程参数（FlowParameter）的列表查询与批量保存。

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

公共说明

• 鉴权：是（需 designerToken）。所有端点继承自 AbstractDesignTimeController，通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
• 路径变量：{applicationId}、{moduleId}、{flowId}、{nodeId} 均为**明文设计时 ID**（与 designer 其他控制器一致，非 runtime 的 DES 加密密文）。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500，errmsg 为异常信息；新建/更新流程时捕获 OBPMValidateException（主题为空、流程重名等）返回 errcode=40001。
• HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
• 请求体约定：POST/PUT 多接收原始 JSON 字符串（@RequestBody String content）或 JSON 字符串数组（@RequestBody String[]），由服务端用 JSONObject.fromObject 解析为 BillDefiVO；批量保存流程参数接收 @RequestBody List<FlowParameter>。
• 流程状态约定：新建/更新流程时强制 checkout=true、checkoutHandler=getUser().getId()（编辑期占位，留待流程保存发布时再释放）。

---

1. 新建流程

在指定模块下新建流程定义。请求体反序列化为 BillDefiVO 后做主题非空与重名校验（doSaveValidate），通过则分配设计时序列号并保存。HTTP 状态码固定 201 Created。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
moduleId	path	string	是	模块Id
content	body	string(JSON)	是	流程对象 JSON

请求体

对应 BillDefiVO 对象 JSON（name、subject、flow、uri 等）。subject（主题）不能为空，否则 errcode=40001、errmsg="{*[workflow.subject.notempty]*}"；同模块内 name 重名时 errmsg="{*[workflow.subject.exist]*}"。

响应

data：JSONObject，仅含 id（新建流程Id）。校验失败时 errcode=40001。

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

失败示例（主题为空）：

{ "errcode": 40001, "errmsg": "{*[workflow.subject.notempty]*}", "data": null, "errors": null }

失败示例（其他异常）：

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

---

2. 获取流程列表

分页获取指定模块下的流程列表，可按流程名称过滤。返回精简字段（id、name）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/{moduleId}/workflows
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
moduleId	path	string	是	模块Id
pageNo	query	string	否	页码（缺省 1，经 ParamsTable.getParameterAsString 读取）
linesPerPage	query	string	否	每页条数（缺省 10）
name	query	string	否	流程名称关键字

说明：分页与 name 参数通过 getParams() 读取，未在方法签名上声明，由请求参数绑定。

请求示例

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

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：JSONObject，含 pageNo/linesPerPage/rowCount 与 data（流程精简数组，每项 {id, name}）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "pageNo": 1,
    "linesPerPage": 10,
    "rowCount": 2,
    "data": [ { "id": "...", "name": "请假流程" } ]
  },
  "errors": null
}

失败示例：

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

---

3. 获取流程详情

按流程Id查询单个流程，返回 id、name、authorname、lastmodify、subject、flow、uri 等字段。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/workflows/{flowId}（注意：路径中 workflows 前为 /modules/，无 {moduleId}）
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
flowId	path	string	是	流程Id

请求示例

GET /api/designtime/applications/{applicationId}/modules/workflows/{flowId} HTTP/1.1

响应

data：JSONObject，含 id、name、authorname、lastmodify、subject、flow、uri。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "id": "...",
    "name": "请假流程",
    "authorname": "...",
    "lastmodify": "2026-08-04 12:34:56",
    "subject": "...",
    "flow": "<流程图 JSON/XML>",
    "uri": ""
  },
  "errors": null
}

失败示例：

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

---

4. 复制流程（可批量）

按流程Id数组批量复制流程（billDefiDesignTimeService.doCopyFlow）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/workflows/copy（注意：路径中无 {moduleId}，使用 /modules/workflows/copy）
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
ids	body	string	是	流程Id数组（@RequestBody String[]）

请求体

["<flowId1>", "<flowId2>"]

响应

data：String，成功时为 "复制成功"。

{ "errcode": 0, "errmsg": "ok", "data": "复制成功", "errors": null }

失败示例：

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

---

5. 更新流程

按流程Id更新流程定义。强制覆盖 id=flowId、applicationid=applicationId，并重置 lastmodify、checkout=true、checkoutHandler。校验失败（主题为空/重名）时 errcode=40001。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/workflows/{flowId}
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
flowId	path	string	是	流程Id
content	body	string(JSON)	是	流程对象 JSON

请求体

对应 BillDefiVO 对象 JSON（name、subject、flow、uri 等）。

响应

data：JSONObject，仅含 id（即 flowId）。校验失败时 errcode=40001，errmsg 为 {*[workflow.subject.notempty]*} 或 {*[workflow.subject.exist]*}。

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

失败示例（重名）：

{ "errcode": 40001, "errmsg": "{*[workflow.subject.exist]*}", "data": null, "errors": null }

---

6. 删除流程（可批量）

按流程Id数组批量删除流程。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
ids	body	string	是	流程Id数组（@RequestBody String[]）

请求体

["<flowId1>", "<flowId2>"]

响应

data：String，成功时为 "删除流程"。

{ "errcode": 0, "errmsg": "ok", "data": "删除流程", "errors": null }

失败示例：

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

---

7. 根据当前节点获取其他节点

按流程Id + 节点Id 获取流程编辑器中需要的关联节点列表（当前实现仅返回 type=0 分支的所有前置节点 getAllBeforeNode，并强制转换为 ManualNode）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/workflows/{flowId}/node/{nodeId}
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
flowId	path	string	是	流程Id
nodeId	path	string	是	当前节点Id
type	query	string	否	节点查询类型（经 ParamsTable 读取；0=获取所有前置节点，其他值当前实现返回空数组）

请求示例

GET /api/designtime/applications/{applicationId}/modules/workflows/{flowId}/node/{nodeId}?type=0 HTTP/1.1

响应

data：JSONArray，每项 {id, name}（仅 type=0 时返回前置 ManualNode 列表）。

说明：方法捕获异常后仅 e.printStackTrace() 并 return null（响应体为空，HTTP 200），调用方需按 body 是否为空判断成败。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "id": "<nodeId>", "name": "<节点名>" } ],
  "errors": null
}

---

8. 流程编辑器子流程获取父流程表单

分页查询当前应用下指定模块/名称关键字的表单，并附带每个表单的全部字段（用于子流程映射父流程字段）。每页固定 10 条。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/workflows/flexGetForms
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
pageNo	query	string	否	页码（缺省 1）
formName	query	string	否	表单名称关键字
moduleName	query	string	否	模块名称关键字

说明：上述形参未标注 @RequestParam，由 Spring MVC 按请求参数绑定。

请求示例

GET /api/designtime/applications/{applicationId}/modules/workflows/flexGetForms?pageNo=1&formName=&moduleName= HTTP/1.1

响应

data：JSONObject，含分页字段（linesPerPage/pageCount/pageNo/rowCount）与 data（表单数组）。每项表单 {id, formName, moduleName, formFields}，formFields 首项固定为 {name:"--select--", valuetype:""}，其余为字段对象 {name, valuetype}。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "pageCount": 1,
    "pageNo": 1,
    "rowCount": 1,
    "data": [
      {
        "id": "...",
        "formName": "请假表单",
        "moduleName": "考勤",
        "formFields": [
          { "name": "--select--", "valuetype": "" },
          { "name": "字段名", "valuetype": "VALUE_TYPE_TEXT" }
        ]
      }
    ]
  },
  "errors": null
}

失败示例：

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

---

9. 流程编辑器获取所有流程

分页查询当前应用下指定模块/名称关键克的流程，并附带应用下所有模块名称集合（用于流程编辑器下拉过滤）。每页固定 10 条。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/workflows/flexGetBillDefiVOs
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
pageNo	query	string	否	页码（缺省 1）
flowName	query	string	否	流程名称关键字
moduleName	query	string	否	模块名称关键字

请求示例

GET /api/designtime/applications/{applicationId}/modules/workflows/flexGetBillDefiVOs?pageNo=1&flowName=&moduleName= HTTP/1.1

响应

data：JSONObject，含分页字段、data（流程数组，每项 {id, flowName, moduleName}）与 modulearray（模块名称字符串数组，首项固定为 ""）。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "pageCount": 1,
    "pageNo": 1,
    "rowCount": 1,
    "data": [ { "id": "...", "flowName": "请假流程", "moduleName": "考勤" } ],
    "modulearray": [ "", "考勤", "报销" ]
  },
  "errors": null
}

失败示例：

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

---

10. 获取流程参数列表

按流程Id返回该流程的全部流程参数（FlowParameter）列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/workflows/{flowId}/parameters（注意：路径前缀为 /{applicationId}/workflows/...，无 /modules/）
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
flowId	path	string	是	流程Id

请求示例

GET /api/designtime/applications/{applicationId}/workflows/{flowId}/parameters HTTP/1.1

响应

data：List<FlowParameter>。

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

失败示例：

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

---

11. 批量保存流程参数

按流程Id批量保存流程参数（增量更新：保留请求体中携带的参数，删除库中存在但请求体中已移除的参数），并基于新旧参数表单差异同步动态表（createOrUpdateDynaTable）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/workflows/{flowId}/parameters/batch（注意：路径前缀为 /{applicationId}/workflows/...，无 /modules/）
• 鉴权：是（需 designerToken）
• Tag：设计时-流程定义模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id
flowId	path	string	是	流程Id
flowParameters	body	array(JSON)	是	流程参数数组（@RequestBody List<FlowParameter>；服务端会强制 parentId=flowId、applicationid=applicationId）

请求体

[
  { "id": "<保留则携带>", "name": "参数1", "fieldtype": "VALUE_TYPE_TEXT", "...": "..." }
]

响应

data：List<FlowParameter>，保存后重新查询的参数列表。

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

失败示例：

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

---