@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-bpm/references/api//346/224/273/347/225/245-01-/346/265/201/347/250/213API-/347/253/240/350/212/20208_/346/237/245/347/234/213/350/277/275/350/270/252/346/216/245/345/217/243.md

@@ -0,0 +1,492 @@
+---
+name: 攻略-01-流程API-章节08_查看追踪接口
+description: 查看追踪接口 — 美林平台 BPM 流程 HTTP API 接口全集（启动流程、完成任务、追踪、阅知、退回等）
+keywords: [BPM, 流程API, 工作流, 启动流程, 完成任务, 追踪, 退回, 阅知, Camunda, 查看追踪接口]
+use-cases: [BPM 流程 API 调用, 流程审批集成, 流程追踪, 流程退回]
+source-section: 7. 查看追踪接口
+source-file: 应用开发平台-流程管理-使用攻略（一）：流程API接口.md
+---
+
+# 7. 查看追踪接口
+
+## 📋 API 契约（机器可读）
+
+```json
+{
+  "apiName": "step",
+  "method": "POST",
+  "urlPattern": "/api/bpm/core/step",
+  "signature": "Result getGraphTrack()",
+  "functionDesc": "任务跟踪接口分为三部分内容",
+  "module": "bpm.process",
+  "pathParameters": [
+    {
+      "name": "procInstId",
+      "type": "String",
+      "required": true,
+      "desc": "流程实例id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "mainFormId",
+      "type": "String",
+      "required": false,
+      "desc": "mainform的Id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "procDefId",
+      "type": "String",
+      "required": false,
+      "desc": "流程定义id",
+      "constraint": "非空字符串"
+    }
+  ],
+  "requestParameters": [
+    {
+      "name": "procInstId",
+      "type": "String",
+      "required": true,
+      "desc": "流程实例id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "mainFormId",
+      "type": "String",
+      "required": false,
+      "desc": "mainform的Id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "procDefId",
+      "type": "String",
+      "required": false,
+      "desc": "流程定义id",
+      "constraint": "非空字符串"
+    }
+  ],
+  "returnType": "ProcTrackDTO的集合对象",
+  "returnFields": [
+    "timestamp",
+    "status",
+    "message",
+    "data",
+    "success"
+  ],
+  "exceptionList": [
+    "BusinessException",
+    "SystemException"
+  ],
+  "exampleCall": "bpmEngine.getPage(...)",
+  "bestPractice": "传入 bpmOperName 和 bpmOperValue 必须匹配流程定义中的按钮配置"
+}
+```
+
+说明：任务跟踪接口分为三部分内容
+文字追踪,图表追踪,审批意见
+
+### 7.1 文字追踪
+说明:查询某个流程实例的文字追踪数据
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/step`
+
+* PathVariables
+    ```
+    无
+    ```
+* RequestParams:
+    | 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+    | ---------- |-------- |-------- | ----------- | ---- |
+    | procInstId | String |是| 流程实例id   |  |
+    |mainFormId|String|否|mainform的Id|不需要该参数|
+    |procDefId|String|否|流程定义id|不需要该参数|
+* ResponseBody
+    返回数据类型：ProcTrackDTO的集合对象
+
+<b>Postman样例:</b>
+适用于前端直接调用
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/step?procInstId=da94441c-75a7-11eb-bf67-00d861edd189
+```json
+   {
+       "procInstId":"da94441c-75a7-11eb-bf67-00d861edd189"
+   }
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1614145310290,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/step",
+    "data": [
+        {
+            "id": "3f28824f77cd8c4f0177cdc46e040007",
+            //流程实例id
+            "procInstId": "da94441c-75a7-11eb-bf67-00d861edd189",
+            //流程定义id
+            "procDefId": "Process_Demo1:1:00078c50-74b1-11eb-bd66-00d861edd189",
+            //流程key
+            "procDefKey": "Process_Demo1",
+            //任务id
+            "taskId": "da94445b-75a7-11eb-bf67-00d861edd189",
+            //发送节点id
+            "nodeId": "Activity_1el7wyo",
+            //发送节点名称
+            "nodeName": "部门审批",
+            //接收节点id,有可能是多个,按,拼接
+            "nextNodeIds": "Activity_0vjczzn",
+            //接收节点名称,有可能是多个,按,拼接
+            "nextNodeNames": "总监审批",
+            "mainFormId": "3f28824f77cd8c4f0177cdc462060005",
+            // 发送人id
+            "senderId": "test1",
+            //发送人名称
+            "senderName": "测试1",
+            //发送人所在部门id
+            "deptId": "3f28824f77c763dc0177c768b6ba0009",
+            //发送人所在部门名称
+            "deptName": "技术研发部",
+            //操作名称
+            "operate": "发送",
+            "receiveTime": 1614064935000,
+            "dealTime": 1614064938000,
+            //接收人id
+            "receiverIds": ",test1,",
+            //接收人名称
+            "receiverNames": "测试1",
+            "receiverDepts": null,
+            "x": "506",
+            "y": "293",
+            "width": "168",
+            "height": "55",
+            "superProcInstId": null
+        }
+    ],
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "任务跟踪-文字追踪", notes = "任务跟踪-文字追踪")
+    @PostMapping(value = "/step")
+    @ResponseBody
+    public ResultBody<List<ProcTrackDTO>> getPage() {
+        String procInstId = "da94441c-75a7-11eb-bf67-00d861edd189";
+        // 调用 任务跟踪-文字追踪
+        return  bpmEngine.getPage(procInstId, null,null);
+    }
+
+ ```
+
+
+### 7.2 图表追踪
+说明:查询某个流程实例的文字追踪数据
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/graph`
+
+* PathVariables
+    ```
+    无
+    ```
+* RequestParams:
+    | 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+    | ---------- |-------- |-------- | ----------- | ---- |
+    | procInstId | String |是| 流程实例id   |  |
+    |mainFormId|String|否|mainform的Id|不需要该参数|
+    |procDefId|String|是|流程定义id||
+* ResponseBody
+    返回数据类型：Map
+
+<b>Postman样例:</b>
+适用于前端直接调用
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/graph?procInstId=da94441c-75a7-11eb-bf67-00d861edd189&procDefId=Process_Demo1:1:00078c50-74b1-11eb-bd66-00d861edd189
+```json
+   {
+       "procInstId":"da94441c-75a7-11eb-bf67-00d861edd189",
+       "procDefId":"Process_Demo1:1:00078c50-74b1-11eb-bd66-00d861edd189"
+   }
+```
+返回数据如下:
+```json
+    {
+    "timestamp": 1614147183892,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/graph",
+    "data": {
+        // 返回是每个节点的状态 //0正在处理 //1已处理 //2未处理
+        "taskDefKeys": {
+            "Activity_0vjczzn": "0",
+            "Activity_1el7wyo": "1"
+        },
+        // 返回流程文件
+        "bpmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\" xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\" xmlns:di=\"http://www.omg.org/spec/DD/20100524/DI\" xmlns:dc=\"http://www.omg.org/spec/DD/20100524/DC\" xmlns:camunda=\"http://camunda.org/schema/1.0/bpmn\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" id=\"Definitions_02dbze3\" targetNamespace=\"http://bpmn.io/schema/bpmn\" exporter=\"Camunda Modeler\" exporterVersion=\"3.7.1\">  <bpmn:process id=\"Process_Demo1\" name=\"Process_Demo1\" isExecutable=\"true\">    <bpmn:documentation>{\"formLink\":\"/bpm-demo/example/index.html#/formEdit?id=businessId\",\"appModuleName\":\"差旅费\",\"appModuleId\":\"报销\",\"appSystemName\":\"BPM系统\",\"appSystemId\":\"BPM\",\"portalMode\":\"default\",\"portalUrl\":\"\"}</bpmn:documentation>    <bpmn:startEvent id=\"Event_0e2d76k\" name=\"开始\">      <bpmn:outgoing>Flow_147uzda</bpmn:outgoing>    </bpmn:startEvent>    <bpmn:userTask id=\"Activity_1el7wyo\" name=\"部门审批\" camunda:assignee=\"${Activity_1el7wyo_onlyApprove}\">      <bpmn:extensionElements>        <camunda:meritdata>          <camunda:editStatus type=\"1\" />          <camunda:isretprenode type=\"\" />          <camunda:isretfirnode type=\"\" />          <camunda:regainStatus type=\"\" />          <camunda:retRandomNodeStatus type=\"\" />          <camunda:formLink name=\"部门审批\" sort=\"0\">            <camunda:link>/bpm-demo/example/index.html#/formEdit?id=businessId</camunda:link>          </camunda:formLink>          <camunda:formVars />          <camunda:actors>            <camunda:actor type=\"1\" ids=\"drafterCode\" name=\"起草人\" />          </camunda:actors>          <camunda:sendRead>            <camunda:issendread type=\"0\" />          </camunda:sendRead>          <camunda:approve type=\"onlyApprove\" />          <camunda:route type=\"1\" operName=\"发送\" returnName=\"\" returnValue=\"\" operImgPath=\"\" />          <camunda:seluserwin display=\"yes@@@@@【本环节需要选人】\" noseluser=\"no@@@@@【本环节不需要自动选人】\" />          <camunda:opinion display=\"\" type=\"1\" must=\"\" isOpiDisplay=\"\" isOpiMust=\"\" regionName=\"\" regionSort=\"0\" opinionField=\"\" opinionYesNo=\"\" opinionDeptStatus=\"\" opinionUserImgStatus=\"\" autoOpinion=\"\" autoOpiContent=\"\" routeName=\"\" routeValue=\"\" routeOpiMust=\"\" routeCommentMust=\"\" />        </camunda:meritdata>        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"create\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"assignment\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"complete\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"update\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"delete\" />      </bpmn:extensionElements>      <bpmn:incoming>Flow_147uzda</bpmn:incoming>      <bpmn:outgoing>Flow_0u9dqba</bpmn:outgoing>    </bpmn:userTask>    <bpmn:userTask id=\"Activity_0vjczzn\" name=\"总监审批\" camunda:assignee=\"${Activity_0vjczzn_onlyApprove}\">      <bpmn:extensionElements>        <camunda:meritdata>          <camunda:editStatus type=\"1\" />          <camunda:isretprenode type=\"1\" />          <camunda:isretfirnode type=\"1\" />          <camunda:regainStatus type=\"\" />          <camunda:retRandomNodeStatus type=\"1\" />          <camunda:formLink name=\"总监审批\" sort=\"0\">            <camunda:link>/bpm-demo/example/index.html#/formRead?id=businessId</camunda:link>          </camunda:formLink>          <camunda:formVars />          <camunda:actors>            <camunda:actor type=\"1\" ids=\"drafterCode\" name=\"起草人\" />          </camunda:actors>          <camunda:sendRead>            <camunda:issendread type=\"0\" />          </camunda:sendRead>          <camunda:approve type=\"onlyApprove\" />          <camunda:route type=\"1\" operName=\"发送\" returnName=\"\" returnValue=\"\" operImgPath=\"\" />          <camunda:seluserwin display=\"yes@@@@@【本环节需要选人】\" noseluser=\"no@@@@@【本环节不需要自动选人】\" />          <camunda:opinion display=\"\" type=\"1\" must=\"\" isOpiDisplay=\"\" isOpiMust=\"\" regionName=\"\" regionSort=\"0\" opinionField=\"\" opinionYesNo=\"\" opinionDeptStatus=\"\" opinionUserImgStatus=\"\" autoOpinion=\"\" autoOpiContent=\"\" routeName=\"\" routeValue=\"\" routeOpiMust=\"\" routeCommentMust=\"\" />        </camunda:meritdata>        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"create\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"assignment\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"complete\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"update\" />        <camunda:taskListener delegateExpression=\"${userTaskListener}\" event=\"delete\" />      </bpmn:extensionElements>      <bpmn:incoming>Flow_0u9dqba</bpmn:incoming>      <bpmn:outgoing>Flow_1vp7uq3</bpmn:outgoing>    </bpmn:userTask>    <bpmn:endEvent id=\"Event_1f641s8\" name=\"结束\">      <bpmn:incoming>Flow_1vp7uq3</bpmn:incoming>    </bpmn:endEvent>    <bpmn:sequenceFlow id=\"Flow_147uzda\" sourceRef=\"Event_0e2d76k\" targetRef=\"Activity_1el7wyo\">      <bpmn:extensionElements>        <camunda:executionListener delegateExpression=\"${lineListener}\" event=\"take\" />      </bpmn:extensionElements>    </bpmn:sequenceFlow>    <bpmn:sequenceFlow id=\"Flow_0u9dqba\" sourceRef=\"Activity_1el7wyo\" targetRef=\"Activity_0vjczzn\">      <bpmn:extensionElements>        <camunda:executionListener delegateExpression=\"${lineListener}\" event=\"take\" />      </bpmn:extensionElements>    </bpmn:sequenceFlow>    <bpmn:sequenceFlow id=\"Flow_1vp7uq3\" sourceRef=\"Activity_0vjczzn\" targetRef=\"Event_1f641s8\">      <bpmn:extensionElements>        <camunda:executionListener delegateExpression=\"${lineListener}\" event=\"take\" />      </bpmn:extensionElements>    </bpmn:sequenceFlow>  </bpmn:process>  <bpmndi:BPMNDiagram id=\"BpmnDiagram_1\">    <bpmndi:BPMNPlane id=\"BpmnPlane_1\" bpmnElement=\"Process_Demo1\">      <bpmndi:BPMNEdge id=\"Flow_147uzda_di\" bpmnElement=\"Flow_147uzda\">        <di:waypoint x=\"369\" y=\"220\" />        <di:waypoint x=\"438\" y=\"220\" />        <di:waypoint x=\"438\" y=\"321\" />        <di:waypoint x=\"506\" y=\"321\" />      </bpmndi:BPMNEdge>      <bpmndi:BPMNEdge id=\"Flow_0u9dqba_di\" bpmnElement=\"Flow_0u9dqba\">        <di:waypoint x=\"674\" y=\"321\" />        <di:waypoint x=\"740\" y=\"321\" />        <di:waypoint x=\"740\" y=\"322\" />        <di:waypoint x=\"806\" y=\"322\" />      </bpmndi:BPMNEdge>      <bpmndi:BPMNEdge id=\"Flow_1vp7uq3_di\" bpmnElement=\"Flow_1vp7uq3\">        <di:waypoint x=\"974\" y=\"322\" />        <di:waypoint x=\"1133\" y=\"322\" />        <di:waypoint x=\"1133\" y=\"460\" />        <di:waypoint x=\"1291\" y=\"460\" />      </bpmndi:BPMNEdge>      <bpmndi:BPMNShape id=\"Event_0e2d76k_di\" bpmnElement=\"Event_0e2d76k\">        <dc:Bounds x=\"331\" y=\"201\" width=\"38\" height=\"38\" />        <bpmndi:BPMNLabel>          <dc:Bounds x=\"339\" y=\"242\" width=\"22\" height=\"14\" />        </bpmndi:BPMNLabel>      </bpmndi:BPMNShape>      <bpmndi:BPMNShape id=\"Activity_1el7wyo_di\" bpmnElement=\"Activity_1el7wyo\">        <dc:Bounds x=\"506\" y=\"293\" width=\"168\" height=\"55\" />      </bpmndi:BPMNShape>      <bpmndi:BPMNShape id=\"Activity_0vjczzn_di\" bpmnElement=\"Activity_0vjczzn\">        <dc:Bounds x=\"806\" y=\"294\" width=\"168\" height=\"55\" />      </bpmndi:BPMNShape>      <bpmndi:BPMNShape id=\"Event_1f641s8_di\" bpmnElement=\"Event_1f641s8\">        <dc:Bounds x=\"1291\" y=\"441\" width=\"38\" height=\"38\" />        <bpmndi:BPMNLabel>          <dc:Bounds x=\"1299\" y=\"482\" width=\"22\" height=\"14\" />        </bpmndi:BPMNLabel>      </bpmndi:BPMNShape>    </bpmndi:BPMNPlane>  </bpmndi:BPMNDiagram></bpmn:definitions>"
+    },
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "任务跟踪-图表追踪", notes = "任务跟踪-图表追踪")
+    @PostMapping(value = "/graph")
+    @ResponseBody
+    public ResultBody<Map> getGraphTrack() {
+        String procInstId = "da94441c-75a7-11eb-bf67-00d861edd189";
+        String procDefId = "Process_Demo1:1:00078c50-74b1-11eb-bd66-00d861edd189";
+        // 任务跟踪-图表追踪
+        return  bpmEngine.getGraphTrack(procInstId,null,procDefId);
+    }
+ ```
+说明:图表追踪中点击某个节点，返回节点的提示信息。正在处理，已处理，未处理状态的人员
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/tip`
+
+* PathVariables
+    ```
+    无
+    ```
+* RequestParams:
+    | 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+    | ---------- |-------- |-------- | ----------- | ---- |
+    | procInstId | String |是| 流程实例id   |  |
+    |mainFormId|String|否|mainform的Id|不需要该参数|
+    |taskDefKey|String|是|任务节点key||
+* ResponseBody
+    返回数据类型：List
+
+<b>Postman样例:</b>
+适用于前端直接调用
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/tip?procInstId=7f050a06-7680-11eb-9b5e-00d861edd189&taskDefKey=Activity_0vjczzn
+```json
+   {
+       "procInstId":"7f050a06-7680-11eb-9b5e-00d861edd189",
+       "taskDefKey":"Activity_0vjczzn"
+   }
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1614161060238,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/tip",
+    "data": [
+        //节点名称
+        "总监审批",
+        //已处理人
+        "已处理：",
+        //未处理人
+        "未处理：测试1",
+        //处理状态
+        "处理状态：正在处理"
+    ],
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+
+    @Autowired
+    BpmEngine bpmEngine;
+
+   @ApiOperation(value = "任务跟踪-图表追踪-节点提示信息", notes = "图表追踪中点击某个节点，返回节点的提示信息。正在处理，已处理，未处理状态的人员")
+    @PostMapping(value = "/tip")
+    @ResponseBody
+    public ResultBody<List> getNodeTip() {
+        String taskDefKey = "Activity_0vjczzn";
+        String procInstId = "7f050a06-7680-11eb-9b5e-00d861edd189";
+        //调用任务跟踪-图表追踪-节点提示信息
+        return  bpmEngine.getNodeTip(taskDefKey,procInstId,null);
+    }
+
+ ```
+
+
+### 7.3 审批意见
+说明:查询某个流程实例的所有审批意见信息
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/getOpinions`
+
+* PathVariables
+    ```
+    无
+    ```
+* RequestParams:
+    | 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+    | ---------- |-------- |-------- | ----------- | ---- |
+    | procInstId | String |是| 流程实例id   |  |
+    | isContainsApprover | String |否| 是否是获取当前用户审批的意见 |默认1 自己的和其他人已发布的，0 自己填写的  |
+* ResponseBody
+    返回数据类型：ProcOpinionDTO的集合对象
+
+<b>Postman样例:</b>
+适用于前端直接调用
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/getOpinions?procInstId=db512fbe-7689-11eb-ac36-00d861edd189
+
+```json
+   {
+       "procInstId":"db512fbe-7689-11eb-ac36-00d861edd189"
+   }
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1614217620220,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/getOpinions",
+    "data": [
+        {
+            "tenantId": "",
+            "createTime": 1614162017000,
+            "updateTime": 1614162017000,
+            "creatorId": null,
+            "reviserId": null,
+            "id": "3f28824f77d386b00177d38dbd560003",
+            //流程实例id
+            "procInstId": "db512fbe-7689-11eb-ac36-00d861edd189",
+            //流程key
+            "procDefKey": "Process_Demo1",
+            //任务id
+            "taskId": "db559ccd-7689-11eb-ac36-00d861edd189",
+            //流程节点id
+            "nodeId": "Activity_1el7wyo",
+            //流程节点名称
+            "nodeName": "部门审批",
+            //流程主表id
+            "wfMainFormId": "3f28824f77d386b00177d38d84470002",
+            //意见内容
+            "content": "测试数据",
+            //发布时间，当前任务处理完成后，发布时间才有值
+            "publishTime": 1614162020000,
+            //意见类型：（新增的意见是覆盖，或者覆盖又新增，删除已发布意见）0、新增1、覆盖2、自动新增3
+            "type": "1",
+            //意见区域名称
+            "regionName": null,
+            //意见区域排序号
+            "regionSort": "0",
+            //填写意见人用户信息编码
+            "userId": "test1",
+            //填写意见人用户名称
+            "userName": "测试1",
+            //填写意见人部门编码
+            "deptId": "3f28824f77c763dc0177c768b6ba0009",
+            //填写意见人部门名称
+            "deptName": "技术研发部",
+            //是否同意：2同意、0不同意、1中立
+            "isApprove": null,
+            //意见域
+            "opinionField": null,
+            //临时变量【是否批量处理】
+            "isBatchDeal": null,
+            //临时变量【待办ids】
+            "undoIds": null,
+            //意见是否按部门分类显示
+            "opinionDeptStatus": null,
+            //意见列表是否显示
+            "opinionListStatus": null,
+            //意见展现中是否显示用户图像
+            "opinionUserImgStatus": null
+        }
+    ],
+    "extraInfo": {},
+    "success": true
+}
+```
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+
+ ```java
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "任务跟踪-审批意见", notes = "任务跟踪-审批意见")
+    @RequestMapping(value = "/getOpinions", method = RequestMethod.POST)
+    public @ResponseBody
+    ResultBody<List<ProcOpinionDTO>> getOpinions() {
+        Map map = new HashMap();
+        map.put("procInstId","db512fbe-7689-11eb-ac36-00d861edd189");
+        return  bpmEngine.getOpinions(map);
+    }
+ ```
+
+### 7.4 获取端口
+
+说明:获取网页的端口 来自common.properties中的meritdata.cloud.web-server中的端口
+
+* method : `POST`
+
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/port`
+
+* PathVariables
+
+  ```
+  无
+  ```
+
+* RequestParams:
+
+  无
+
+* ResponseBody
+  返回数据类型：String
+
+<b>Postman样例:</b>
+适用于前端直接调用
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/port
+
+返回数据如下：
+
+```json
+{
+    "timestamp": 1629255129461,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/port",
+    "data": "8080",
+    "extraInfo": {},
+    "success": true
+}
+```
+
+<b>java测试样例:</b>
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+
+```java
+  @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "获取端口", notes = "获取端口")
+    @RequestMapping(value = "/port", method = RequestMethod.POST)
+    public @ResponseBody
+    ResultBody<String> getPort() {
+        return  bpmEngine.getPort();
+    }
+```

package/skills/meritdata-platform-bpm/references/api//346/224/273/347/225/245-01-/346/265/201/347/250/213API-/347/253/240/350/212/20209_/351/200/200/345/233/236/346/213/237/347/250/277/344/272/272/346/216/245/345/217/243.md

@@ -0,0 +1,187 @@
+---
+name: 攻略-01-流程API-章节09_退回拟稿人接口
+description: 退回拟稿人接口 — 美林平台 BPM 流程 HTTP API 接口全集（启动流程、完成任务、追踪、阅知、退回等）
+keywords: [BPM, 流程API, 工作流, 启动流程, 完成任务, 追踪, 退回, 阅知, Camunda, 退回拟稿人接口]
+use-cases: [BPM 流程 API 调用, 流程审批集成, 流程追踪, 流程退回]
+source-section: 8. 退回拟稿人接口
+source-file: 应用开发平台-流程管理-使用攻略（一）：流程API接口.md
+---
+
+# 8.  退回拟稿人接口
+
+## 📋 API 契约（机器可读）
+
+```json
+{
+  "apiName": "retfirnode",
+  "method": "POST",
+  "urlPattern": "/api/bpm/core/retfirnode/{businessId}",
+  "signature": "Result processRetfirnode()",
+  "functionDesc": "退回拟稿人功能 当前任务实例退回到第一个任务节点，状态为起草状态",
+  "module": "bpm.process",
+  "pathParameters": [
+    {
+      "name": "businessId",
+      "type": "String",
+      "required": true,
+      "desc": "业务id",
+      "constraint": "非空字符串"
+    }
+  ],
+  "requestParameters": [
+    {
+      "name": "procInstId",
+      "type": "String",
+      "required": true,
+      "desc": "流程实例id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "businessId",
+      "type": "String",
+      "required": true,
+      "desc": "业务id",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "bpmOperName",
+      "type": "String",
+      "required": true,
+      "desc": "操作名称",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "bpmOperValue",
+      "type": "String",
+      "required": true,
+      "desc": "操作值",
+      "constraint": "字符串"
+    },
+    {
+      "name": "bpmSubject",
+      "type": "String",
+      "required": false,
+      "desc": "待办标题",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "bpmUrgent",
+      "type": "String",
+      "required": false,
+      "desc": "紧急程度",
+      "constraint": "非空字符串"
+    },
+    {
+      "name": "bpmSecret",
+      "type": "String",
+      "required": false,
+      "desc": "密级程度",
+      "constraint": "非空，加密字符串"
+    },
+    {
+      "name": "runtime[taskId]",
+      "type": "String",
+      "required": true,
+      "desc": "当前任务id",
+      "constraint": "非空字符串"
+    }
+  ],
+  "returnType": "String",
+  "returnFields": [
+    "timestamp",
+    "status",
+    "message",
+    "data",
+    "success"
+  ],
+  "exceptionList": [
+    "BusinessException",
+    "SystemException"
+  ],
+  "exampleCall": "bpmEngine.processRetfirnode(...)",
+  "bestPractice": "子流程中暂不支持"
+}
+```
+说明：退回拟稿人功能 当前任务实例退回到第一个任务节点，状态为起草状态
+子流程中暂不支持退回拟稿人
+
+* method : `POST`
+* url : `http://IP:端口/gateway/服务名/api/bpm/core/retfirnode/{businessId}`
+
+
+* PathVariables
+
+| 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+| ---------- |-------- |-------- | -----------| ---- |
+| businessId | String  |是       | 业务id      |      |
+
+
+* RequestParams:
+  
+| 参数       | 参数类型 | 是否必须 | 释义        | 备注 |
+| ---------- |-------- |-------- | ----------- | ---- |
+| procInstId | String      |是       | 流程实例id   |      |
+| businessId | String      |是       | 业务id   |      |
+| bpmOperName |String      | 是      | 操作名称| 流程按钮name值 |
+| bpmOperValue| String    | 是       | 操作值 | 流程按钮id值 |
+| bpmSubject | String      |否       | 待办标题   |      |
+| bpmUrgent | String      |否       | 紧急程度   |      |
+| bpmSecret | String      |否       | 密级程度   |      |
+|runtime[taskId]|String|是|当前任务id|
+
+* ResponseBody
+    返回数据类型：String
+
+Postman测试样例:
+适用于前端直接调用
+案例使用 
+127.0.0.1 IP
+8080 端口号
+cloud-system-bpm-demo 服务
+http://127.0.0.1:8080/gateway/cloud-system-bpm-demo/api/bpm/core/retfirnode/3f28824f77c764f00177c774d8bb0000
+
+```json
+     {
+        "procInstId":"57f63abb-74b1-11eb-bd66-00d861edd189",
+        "businessId":"3f28824f77c764f00177c774d8bb0000",
+        "bpmOperName":"退回拟稿人",
+        "bpmOperValue":"bpmRetfirnodeBtn",
+        "runtime[taskId]":"ccec2073-8604-11eb-aa34-00d861edd189"
+    }
+```
+返回数据如下:
+```json
+{
+    "timestamp": 1613972972863,
+    "status": 1,
+    "message": "成功",
+    "stackmessage": null,
+    "path": "/api/bpm/core/retfirnode/3f28824f77c764f00177c774d8bb0000",
+    "data": "退回拟稿人成功",
+    "extraInfo": {},
+    "success": true
+}
+```
+java 样例
+适用于后端调用
+ 注入com.meritdata.cloud.bpm.core.BpmEngine类
+ ```java
+
+    @Autowired
+    BpmEngine bpmEngine;
+
+    @ApiOperation(value = "退回拟稿人", notes = "退回拟稿人")
+    @RequestMapping(value = "/retfirnode",method = RequestMethod.POST)
+    public ResultBody<String> processRetfirnode() {
+        String businessId = "3f28824f77c764f00177c774d8bb0000";
+        Map map = new HashMap();
+        map.put("procInstId","57f63abb-74b1-11eb-bd66-00d861edd189");
+        map.put("businessId","3f28824f77c764f00177c774d8bb0000");
+        map.put("bpmOperName","退回拟稿人");
+        map.put("bpmOperValue","bpmRetfirnodeBtn");
+        map.put("runtime[taskId]","ccec2073-8604-11eb-aa34-00d861edd189");
+        // 调用退回拟稿人方法
+        return bpmEngine.processRetfirnode(businessId,map);
+    }
+
+ ```