@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-dev-docs-file-finder/references/dev-docs//346/224/273/347/225/245-01-/346/265/201/347/250/213API-/347/253/240/350/212/20215_/344/270/232/345/212/241/347/233/270/345/205/263/346/216/245/345/217/243.md

@@ -0,0 +1,637 @@
+---
+name: 攻略-01-流程API-章节15_业务相关接口
+description: 业务相关接口 — 美林平台 BPM 流程 HTTP API 接口全集（启动流程、完成任务、追踪、阅知、退回等）
+keywords: [BPM, 流程API, 工作流, 启动流程, 完成任务, 追踪, 退回, 阅知, Camunda, 业务相关接口]
+use-cases: [BPM 流程 API 调用, 流程审批集成, 流程追踪, 流程退回]
+source-section: 14. 业务相关接口
+source-file: 应用开发平台-流程管理-使用攻略（一）：流程API接口.md
+---
+
+# 14. 业务相关接口
+
+## 📋 API 契约（机器可读）
+
+```json
+{
+  "apiName": "procinsts",
+  "method": "POST",
+  "urlPattern": "/api/bpm/core/api/engine/bpm/delete/procinsts",
+  "signature": "Result deleteProcInsts()",
+  "functionDesc": "该接口只会删除流程实例数据,结合删除业务数据使用。",
+  "module": "bpm.process",
+  "pathParameters": [
+    {
+      "name": "businessIds",
+      "type": "是",
+      "required": false,
+      "desc": "",
+      "constraint": "正整数"
+    }
+  ],
+  "requestParameters": [
+    {
+      "name": "businessIds",
+      "type": "是",
+      "required": false,
+      "desc": "",
+      "constraint": "正整数"
+    }
+  ],
+  "returnType": "Boolean",
+  "returnFields": [
+    "timestamp",
+    "status",
+    "message",
+    "data",
+    "success"
+  ],
+  "exceptionList": [
+    "BusinessException",
+    "SystemException"
+  ],
+  "exampleCall": "bpmEngine.deleteProcInsts(...)",
+  "bestPractice": "传入 bpmOperName 和 bpmOperValue 必须匹配流程定义中的按钮配置"
+}
+```
+
+### 14.1 删除流程实例接口
+说明：该接口只会删除流程实例数据,结合删除业务数据使用。
+* method : `POST`
+* url : `http://IP:端口号/gateway/服务名/api/bpm/core/api/engine/bpm/delete/procinsts`
+* RequestParams：
+
+```json
+无
+```
+
+* PathVariables
+
+```json
+无
+```
+
+* RequestBody
+
+| 参数        | 是否必须 | 释义       | 备注 |
+| ----------- | -------- | ---------- | ---- |
+| businessIds | 是       | 业务id集合 |      |
+
+* ResponseBody
+  返回数据类型：Boolean
+
+<b>Postman测试样例：</b>
+适用于前端直接调用
+
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/api/engine/bpm/delete/procinsts
+
+```json
+    ["3f28824f77c764f00177c8e789e20003","3f28824f77c764f00177c8e7722a0002"]
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1613984939628,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/api/engine/bpm/delete/procinsts",
+    "data": true,
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+     /**
+     * 删除流程实例
+     */
+    @ApiOperation(value = "删除流程实例", notes = "根据流程实例Ids删除流程实例")
+    @RequestMapping(value = "/delete/procinsts", method = RequestMethod.POST)
+    public ResultBody<Boolean> deleteProcInsts(){
+        List<String> businessIds = new ArrayList<>();
+        businessIds.add("3f28824f77cd7c0a0177cd89902a0001");
+        businessIds.add("3f28824f77cd7c0a0177cd89591d0000");
+        // 删除流程实例
+        return bpmEngine.deleteProcInsts(businessIds);
+    }
+ ```
+
+### 14.2 查询流程实例接口
+说明: 根据流程状态获取流程实例数据和业务数据结合使用
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/query/mainforms`
+* RequestParams：
+  
+  | 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+  | ---------- |-------- |-------- | ----------- | ---- |
+  | mainFormQueryDtoJson | String      |是       | 参数   |   {"subject":"标题模糊查询","bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]}   |
+  | procDefKey | String      |是       | 流程key   |      |
+  | page |Long      | 否      | 页数| 默认是0|
+  | rows| Long    | 否       | 行数 | 默认是20|
+
+  |bpmStatus 状态| 说明|
+  |-------------|-----|
+  |my|我的工作（所有自己起草的流程和当前处理人是自己的,包含跟踪，拟稿，办结）|
+  |myAllDraft|所有我发起的流程|
+  |mydraft|我的拟稿 只查询自己起草的拟稿状态|
+  |mytrack|我的跟踪 只查询自己起草的跟踪状态|
+  |myover|我的办结 只查询自己起草的办结状态|
+  |all|所有工作（根据权限情况。包含跟踪，拟稿，办结）|
+  |alltrack|所有跟踪 根据权限情况，查询所有跟踪状态|
+|allover|所有办结 根据权限情况，查询所有办结状态|
+  
+* PathVariables
+
+  ```json
+  无
+  ```
+
+* RequestBody
+
+  ```json
+  无
+  ```
+
+* ResponseBody
+  返回数据类型：MainFormDTO对象
+
+Postman测试样例：
+
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/query/mainforms
+
+```json
+    {
+        "mainFormQueryDtoJson":"{"bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]}",
+        "procDefKey":"Process_Demo1"
+    }
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1614066616047,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/query/mainforms",
+    "data": {
+        "rows": [
+            {
+                "page": null,
+                "rows": null,
+                "order": null,
+                "sort": null,
+                "id": "3f28824f77cd8c4f0177cdc462060005",
+                //应用模块名称
+                "appModuleName": "差旅费",
+                //所属系统
+                "appSystemName": "BPM系统",
+                //流程定义id
+                "procDefId": "Process_Demo1:1:00078c50-74b1-11eb-bd66-00d861edd189",
+                //流程实例Id
+                "procInstId": "da94441c-75a7-11eb-bf67-00d861edd189",
+                //流程定义key
+                "procDefKey": "Process_Demo1",
+                //流程读者名称
+                "flowReaderNames": "测试1",
+                //流程作者名称，即流程处理人
+                "flowAuthorNames": "测试1",
+                //流程处理状态: draft草稿箱、track跟踪、over办结
+                "procDealStatus": "track",
+                //拟稿人名称
+                "drafterName": "测试1",
+                //拟稿部门名称
+                "drafterDeptName": "技术研发部",
+                //标题
+                "subject": "测试1_2021-02-23 15:22_出差报销",
+                //紧急程度
+                "urgent": "普通",
+                //密级
+                "secret": "高级",
+                //当前处理节点名
+                "nodeNames": "总监审批",
+                //锁定用户名称
+                "lockUserName": "测试1",
+                //锁定是否启用 1：启用
+                "lockStatus": null,
+                //流程设计版本号
+                "version": 0,
+                //业务id
+                "businessId": "3f28824f77cd8c600177cdc460940001",
+                "createTime": 1614064935000,
+                "updateTime": 1614236639000,
+                //操作类型 1 表示驳回
+                "operationType":"1"
+
+            }
+        ],
+        //总共条数
+        "total": 1,
+        "pageSize": 0,
+        "pageNumber": 0,
+        "totalPages": 0,
+        "records": 0
+    },
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java样例</b>
+适用于后端调用,结合业务数据筛选使用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "流程实例获取", notes = "根据流程key和人员编码，获取所有流程实例")
+    @RequestMapping(value = "/query/mainforms", method = RequestMethod.POST)
+    public @ResponseBody ResultBody<GridView> queryMainForms() {
+
+        MainFormQueryDTO formQuery = new MainFormQueryDTO();
+        // 流程状态
+        formQuery.setBpmStatus("all");
+        formQuery.setOrderFields(Lists.newArrayList(formQuery.new Field(MainFormQueryDTO.SORT_BY_UPDATE_TIME, true)));
+
+        String mainFormQueryDtoJson = JSON.toJSONString(formQuery);
+
+        String procDefKey = "Process_Demo1";
+        Long page = Long.parseLong("0");
+        Long rows = Long.parseLong("10");
+        // 调用查询流程实例
+        ResultBody<GridView> processInstanceVos = bpmEngine.queryMainForms(mainFormQueryDtoJson, procDefKey, page, rows);
+        return processInstanceVos;
+    }
+ ```
+
+### 14.3 查询我的申请实例接口
+
+说明: 根据流程状态获取流程实例数据和业务数据结合使用
+
+- method : `POST`
+
+- url : `http://IP:端口/gateway/服务名/api/bpm/core/query/my-apply`
+
+- RequestParams：
+
+  | 参数                 | 参数类型 | 是否必须 | 释义    | 备注                                                         |
+  | -------------------- | -------- | -------- | ------- | ------------------------------------------------------------ |
+  | mainFormQueryDtoJson | String   | 是       | 参数    | {"subject":"标题模糊查询","bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]} |
+  | procDefKey           | String   | 是       | 流程key |                                                              |
+  | page                 | Long     | 否       | 页数    | 默认是0                                                      |
+  | rows                 | Long     | 否       | 行数    | 默认是20                                                     |
+
+  | bpmStatus 状态 | 说明                                                 |
+  | -------------- | ---------------------------------------------------- |
+  | all            | 我的工作（所有自己起草的流程。包含跟踪，拟稿，办结） |
+  | draft          | 拟稿 只查询自己起草的拟稿状态不包含退回的拟稿状态    |
+  | track          | 审批中 只查询自己起草的跟踪状态                      |
+  | over           | 我的办结 只查询自己起草的办结状态                    |
+  | reject         | 驳回 自己起草的被退回的                              |
+
+- PathVariables
+
+```json
+无
+```
+
+- RequestBody
+
+```json
+无
+```
+
+- ResponseBody
+
+返回数据类型：MainFormDTO对象
+
+Postman测试样例：
+
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/query/my-apply
+
+```json
+{
+    "mainFormQueryDtoJson":"{"bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]}",
+    "procDefKey":"Process_Demo1"
+ }
+```
+
+返回数据如下:
+
+```json
+{
+    "timestamp": 1622103221862,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/query/my-apply",
+    "data": {
+        "rows": [
+            {
+                "page": null,
+                "rows": null,
+                "order": null,
+                "sort": null,
+                "id": "3f28830b79ac8c780179ac9830610014",
+                "appModuleName": "demo",
+                "appModuleId": "demo",
+                "appSystemId": "BPM",
+                "appSystemName": "BPM系统",
+                "procDefId": "Process_Demo1:9:fadf49cb-beb4-11eb-8ed4-70b5e84e90b6",
+                "procInstId": "0c4e4d28-beb8-11eb-aae4-70b5e84e90b6",
+                "procDefKey": "Process_Demo1",
+                "flowReaderIds": ",lisi,",
+                "flowReaderNames": "李四",
+                "flowAuthorIds": ",zs,",
+                "flowAuthorNames": "张三",
+                "procDealStatus": "draft",
+                "drafterName": "李四",
+                "drafterId": "lisi",
+                "drafterDeptId": "dashuju",
+                "drafterDeptName": "大数据",
+                "subject": "张三_2021-05-27 14:52_出差报销",
+                "urgent": "普通",
+                "secret": "高级",
+                "formLink": "/bpm-demo/example/index.html#/formEdit?id=3f28830b79ac8cb80179ac982f790003",
+                "preActDealerId": "",
+                "preDealerId": "ohh",
+                "preActId": "",
+                "nodeIds": "Activity_01y0xh8",
+                "nodeNames": "起草",
+                "lockUserName": "张三",
+                "lockStatus": null,
+                "version": 0,
+                "businessId": "3f28830b79ac8cb80179ac982f790003",
+                "bpmVersion": 2,
+                "portalMode": "default",
+                "portalUrl": "",
+                "createTime": 1622098325000,
+                "updateTime": 1622098325000,
+                "operationType": null,
+                "approveUserIds": null,
+                "rejectUserId": null
+            }],
+        "total": 1,
+        "pageSize": 0,
+        "pageNumber": 0,
+        "totalPages": 0,
+        "records": 0
+    },
+    "extraInfo": {},
+    "success": true
+}
+```
+
+<b>java样例</b>
+适用于后端调用,结合业务数据筛选使用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+
+```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "流程实例获取", notes = "根据流程key和人员编码，获取所有流程实例")
+    @RequestMapping(value = "/query/mainforms", method = RequestMethod.POST)
+    public @ResponseBody ResultBody<GridView> queryMainForms() {
+
+        MainFormQueryDTO formQuery = new MainFormQueryDTO();
+        // 流程状态
+        formQuery.setBpmStatus("all");
+        formQuery.setOrderFields(Lists.newArrayList(formQuery.new Field(MainFormQueryDTO.SORT_BY_UPDATE_TIME, true)));
+
+        String mainFormQueryDtoJson = JSON.toJSONString(formQuery);
+
+        String procDefKey = "Process_Demo1";
+        Long page = Long.parseLong("1");
+        Long rows = Long.parseLong("10");
+        // 调用查询流程实例
+        ResultBody<GridView> processInstanceVos = bpmEngine.queryMyApply(mainFormQueryDtoJson, procDefKey, page, rows);
+        return processInstanceVos;
+    }
+```
+
+### 14.4 查询我的审核实例接口
+
+说明: 根据流程状态获取流程实例数据和业务数据结合使用
+
+- method : `POST`
+
+- url : `http://IP:端口/gateway/服务名/api/bpm/core/query/my-approve`
+
+- RequestParams：
+
+  | 参数                 | 参数类型 | 是否必须 | 释义    | 备注                                                         |
+  | -------------------- | -------- | -------- | ------- | ------------------------------------------------------------ |
+  | mainFormQueryDtoJson | String   | 是       | 参数    | {"subject":"标题模糊查询","bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]} |
+  | procDefKey           | String   | 是       | 流程key |                                                              |
+  | page                 | Long     | 否       | 页数    | 默认是0                                                      |
+  | rows                 | Long     | 否       | 行数    | 默认是20                                                     |
+
+  | bpmStatus 状态 | 说明                                                  |
+  | -------------- | ----------------------------------------------------- |
+  | all            | 我的工作（所有自己参与的审核包括待办，已办，驳回）    |
+  | approving      | 待审核                                                |
+  | approved       | 已审核通过的                                          |
+  | reject         | 驳回 （退回拟稿人的，退回上一节点的，退回任意节点的） |
+
+- PathVariables
+
+```json
+无
+```
+
+- RequestBody
+
+```json
+无
+```
+
+- ResponseBody
+
+返回数据类型：MainFormDTO对象
+
+Postman测试样例：
+
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/query/my-approve
+
+```json
+{
+    "mainFormQueryDtoJson":"{"bpmStatus":"all","orderFields":[{"desc":true,"field":"updateTime"}]}",
+    "procDefKey":"Process_Demo1"
+ }
+```
+
+返回数据如下:
+
+```json
+{
+    "timestamp": 1622103221862,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/query/my-apply",
+    "data": {
+        "rows": [
+            {
+                "page": null,
+                "rows": null,
+                "order": null,
+                "sort": null,
+                "id": "3f28830b79ac8c780179ac9830610014",
+                "appModuleName": "demo",
+                "appModuleId": "demo",
+                "appSystemId": "BPM",
+                "appSystemName": "BPM系统",
+                "procDefId": "Process_Demo1:9:fadf49cb-beb4-11eb-8ed4-70b5e84e90b6",
+                "procInstId": "0c4e4d28-beb8-11eb-aae4-70b5e84e90b6",
+                "procDefKey": "Process_Demo1",
+                "flowReaderIds": ",lisi,",
+                "flowReaderNames": "李四",
+                "flowAuthorIds": ",zs,",
+                "flowAuthorNames": "张三",
+                "procDealStatus": "draft",
+                "drafterName": "李四",
+                "drafterId": "lisi",
+                "drafterDeptId": "dashuju",
+                "drafterDeptName": "大数据",
+                "subject": "张三_2021-05-27 14:52_出差报销",
+                "urgent": "普通",
+                "secret": "高级",
+                "formLink": "/bpm-demo/example/index.html#/formEdit?id=3f28830b79ac8cb80179ac982f790003",
+                "preActDealerId": "",
+                "preDealerId": "ohh",
+                "preActId": "",
+                "nodeIds": "Activity_01y0xh8",
+                "nodeNames": "起草",
+                "lockUserName": "张三",
+                "lockStatus": null,
+                "version": 0,
+                "businessId": "3f28830b79ac8cb80179ac982f790003",
+                "bpmVersion": 2,
+                "portalMode": "default",
+                "portalUrl": "",
+                "createTime": 1622098325000,
+                "updateTime": 1622098325000,
+                "operationType": null,
+                "approveUserIds": null,
+                "rejectUserId": null
+            }],
+        "total": 1,
+        "pageSize": 0,
+        "pageNumber": 0,
+        "totalPages": 0,
+        "records": 0
+    },
+    "extraInfo": {},
+    "success": true
+}
+```
+
+<b>java样例</b>
+适用于后端调用,结合业务数据筛选使用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+
+```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "流程实例获取", notes = "根据流程key和人员编码，获取所有流程实例")
+    @RequestMapping(value = "/query/mainforms", method = RequestMethod.POST)
+    public @ResponseBody ResultBody<GridView> queryMainForms() {
+
+        MainFormQueryDTO formQuery = new MainFormQueryDTO();
+        // 流程状态
+        formQuery.setBpmStatus("all");
+        formQuery.setOrderFields(Lists.newArrayList(formQuery.new Field(MainFormQueryDTO.SORT_BY_UPDATE_TIME, true)));
+
+        String mainFormQueryDtoJson = JSON.toJSONString(formQuery);
+
+        String procDefKey = "Process_Demo1";
+        Long page = Long.parseLong("1");
+        Long rows = Long.parseLong("10");
+        // 调用查询流程实例
+        ResultBody<GridView> processInstanceVos = bpmEngine.queryMyApprove(mainFormQueryDtoJson, procDefKey, page, rows);
+        return processInstanceVos;
+    }
+```
+
+### 14.5 通过业务id获取流程实例
+
+说明: 根据业务id获取流程实例
+
+- method : `POST`
+
+- url : `http://IP:端口/gateway/服务名/api/bpm/core/query/mainform`
+
+- RequestParams：
+
+  | 参数       | 参数类型 | 是否必须 | 释义       | 备注 |
+  | ---------- | -------- | -------- | ---------- | ---- |
+  | businessId | String   | 是       | 业务表单Id |      |
+
+- PathVariables
+
+```json
+无
+```
+
+- RequestBody
+
+```json
+无
+```
+
+- ResponseBody
+
+返回数据类型：MainFormDTO对象
+
+Postman测试样例：
+
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/query/mainform
+
+```json
+{
+    "businessId": '3f28830b7b3d4163017b3d688eb00000'
+ }
+```
+
+返回数据如下:
+
+```json
+{
+    "timestamp": 1629254481659,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/query/mainform",
+    "data": {
+        "procDefId": "Process_Demo1:57:d2cda2b0-fbe0-11eb-b6c0-70b5e84e90b6",
+        "procInstId": "d7de05b1-fbe0-11eb-b6c0-70b5e84e90b6",
+        "procDefKey": null
+    },
+    "extraInfo": {},
+    "success": true
+}
+```
+
+<b>java样例</b>
+适用于后端调用,结合业务数据筛选使用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+
+```java
+ @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "通过业务id获取实例", notes = "通过业务id获取实例")
+    @RequestMapping(value = "/query/mainforms", method = RequestMethod.POST)
+    public @ResponseBody ResultBody<MainFormDTO> queryMainForm(@RequestParam String businessId) {
+
+        // 调用查询流程实例
+        ResultBody<MainFormDTO> mainformDTO = bpmEngine.queryMainFormsByBusinessId(businessId);
+        return mainformDTO;
+    }
+```