FlowInterventionController（流程干预/流程监控）

提供流程监控与干预能力：流程监控列表查询、流程实例详情/删除、流程节点耗时/占比/排序等统计分析、批量改签当前节点审批人、获取可干预节点与节点历史审批人、干预流程（强制推进/回退/重启已终止流程）、流程指定审批人用户选择框列表分页查询。

• 类级基址：${myapps.context-path.manager:}/api/authtime（完整路径：{manager-context}/api/authtime<相对路径>）
• Tag：流程监控模块
• 控制器源码：obpm-manager/src/main/java/cn/myapps/manager/authtime/controller/flow/FlowInterventionController.java
• 公共说明：
• 类继承 BaseAuthTimeController，通过其 success(errmsg, data) / error(errcode, errmsg, errors) 返回统一 Resource（字段 errcode/errmsg/data/errors，结构见 ../index.md「统一响应结构」）。
• 多数端点在 try/catch 内捕获 Exception 并 e.printStackTrace() 后返回 errcode=500、errmsg=e.getMessage()、data=null（HTTP 状态码 200）。
• doFlow 单独再捕获 OBPMValidateException，异常文案取 e.getValidateMessage()。
• getOtherNodeList / getHisApprovers / doSelectByFlow 方法签名 throws Exception，未捕获异常时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。
• 鉴权说明见 index.md「鉴权说明」（adminToken JWT）。
• 路径变量 / 查询参数：domainid 为企业域 id；applicationid / applicationId 为软件 id；docId 为文档 id；flowId 为流程定义 id；id 在不同端点语义不同（流程实例 id 或文档 id），见各端点说明。
• 控制器内通过 AuthTimeServiceManager.getAdminUser(request) 获取当前管理员，再用 getFakeUser(user, domainId) 构造一个 id 固定为 FLOW_ADMIN_ID 的临时 WebUser 作为流程引擎执行人。

---

1. 查询流程监控列表

按企业域分页查询流程监控（FlowIntervention）列表，支持按软件、流程名、状态标签、发起人、首次/最后处理时间、最后审批人、摘要过滤。application（软件 id）非空时仅查该软件；为空时遍历企业域绑定的所有已启用软件（跳过 KM）合并分页。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/workflow/flowstaterts（完整：{manager-context}/api/authtime/domain/{domainid}/workflow/flowstaterts）
• 鉴权：是（需管理员 adminToken，详见 index.md「鉴权说明」）
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	JSON	是	过滤条件包体（字段见下）
_pagelines	query	string	否	每页条数，缺省 10
_currpage	query	string	否	当前页码，缺省 1

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
application	string	否	软件 id；为空时遍历企业域下所有已启用软件（跳过 KM）合并查询
_flowName	string	否	流程名称过滤
_stateLabel	string	否	状态标签过滤
_initiator	string	否	发起人过滤
_firstProcessTime	string	否	首次处理时间过滤
_lastProcessTime	string	否	最后处理时间过滤
_lastAuditor	string	否	最后审批人过滤
_summary	string	否	摘要过滤
_orderby	string	否	排序字段，缺省 LASTPROCESSTIME DESC

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/workflow/flowstaterts?_currpage=1&_pagelines=20 HTTP/1.1
Content-Type: application/json

{
  "application": "__APP01",
  "_flowName": "报销",
  "_initiator": "",
  "_summary": ""
}

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<FlowInterventionVO>，字段：

字段	类型	说明
linesPerPage	int	每页条数
pageCount	int	总页数
pageNo	int	当前页码
rowCount	int	总记录数
datas	array\<FlowInterventionVO>	流程监控记录数组

注：当 application 为空、跨软件合并查询时，rowCount 与 datas 由控制器在内存中累加合并（每软件查回的结果按 _pagelines 截断后塞入 datas，rowCount 为各软件 rowCount 之和），与单软件分页语义不完全一致。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 20,
    "pageCount": 1,
    "pageNo": 1,
    "rowCount": 1,
    "datas": [
      { "id": "__FS001", "flowName": "报销流程", "state": "运行中" }
    ]
  },
  "errors": null
}

失败示例：

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

---

2. 批量更新当前流程节点审批人

对一批文档的当前流程节点统一改签审批人。请求体给出统一的 userIds（新审批人列表）与 docs（待处理的文档数组，每个元素含 docId / applicationId）。逐条处理，单条失败不影响其他条目；全部成功 data 为 null，部分失败 data 为错误信息字符串列表。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/workflow/approvers/batch（完整：{manager-context}/api/authtime/domain/workflow/approvers/batch）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
content	body	JSON	是	批量改签包体（字段见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
userIds	string[]	是	新审批人用户 id 列表
docs	array\<object>	是	待处理文档列表，元素字段见下

docs 元素字段：

字段	类型	必填	说明
docId	string	是	文档 id
applicationId	string	是	文档所属软件 id

请求示例

PUT /api/authtime/domain/workflow/approvers/batch HTTP/1.1
Content-Type: application/json

{
  "userIds": ["__U001", "__U002"],
  "docs": [
    { "docId": "__DOC001", "applicationId": "__APP01" },
    { "docId": "__DOC002", "applicationId": "__APP01" }
  ]
}

响应

结构：统一 Resource。 data：全部成功时为 null；部分失败时为错误信息字符串列表（如 ["第1条处理失败。原因：数据不存在!"]）。

条件	errcode	errmsg	data
全部成功	0	ok	null
部分失败	0	ok	错误信息列表
整体异常（如 JSON 解析失败）	500	<异常信息>	null

注：单条失败始终追加到 errorMsg，外层不会因此抛异常；只有进入方法体前的整体异常（请求包体非法等）才返回 errcode=500。errmsg 恒为 ok 不能用于判错，调用方须按 data 是否为非空列表判错。

成功示例：

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

失败示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": ["第1条处理失败。原因：当前流程已结束或流程实例数据丢失!"],
  "errors": null
}

---

3. 删除流程实例

按文档 id 数组与软件 id 批量删除文档（DocumentProcess.doRemove），实际删除的是文档记录（含其流程实例关联数据）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/applicationid/{applicationid}/workflow/flowstaterts（完整：{manager-context}/api/authtime/domain/applicationid/{applicationid}/workflow/flowstaterts）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	软件 id
ids	body	string[]	是	待删除的文档 id 数组

请求体

application/json，字符串数组：

[ "__DOC001", "__DOC002" ]

请求示例

DELETE /api/authtime/domain/applicationid/__APP01/workflow/flowstaterts HTTP/1.1
Content-Type: application/json

[ "__DOC001" ]

响应

结构：统一 Resource。 data：字符串 "删除成功"。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "删除成功", "errors": null }

失败示例：

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

---

4. 查看流程实例信息

按软件 id 与流程实例 id 查询单条流程监控记录（FlowInterventionProcess.doView）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/applicationid/{applicationid}/workflow/flowstatert（完整：{manager-context}/api/authtime/domain/applicationid/{applicationid}/workflow/flowstatert）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	软件 id
id	query	string	是	流程实例 id

请求示例

GET /api/authtime/domain/applicationid/__APP01/workflow/flowstatert?id=__FS001 HTTP/1.1

响应

结构：统一 Resource。 data：FlowInterventionVO（流程监控记录对象，结构由 FlowInterventionVO 决定）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "id": "__FS001", "flowName": "报销流程", "state": "运行中" },
  "errors": null
}

失败示例：

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

---

5. 流程节点耗时

按日期范围、显示模式统计指定软件下流程及各节点耗时（AnalyzerProcess.doAnalyzerFlowAndNodeTimeConsuming），返回 FlowAnalyzerVO 集合。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/applicationid/{applicationid}/workflow/flowAndNodeTimeConsuming（完整：{manager-context}/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/flowAndNodeTimeConsuming）
• 鉴权：是
• Tag：流程监控模块

注：源码 @Parameter 描述里把 applicationid 注为「企业域id」、domainid 注为「软件id」，与路径变量名语义相反。实际逻辑以 application 参数传给 AnalyzerProcess、domain 写入 paramsTable，applicationid 路径变量是软件 id，domainid 路径变量是企业域 id。

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
daterange	query	string	是	统计日期范围
showmode	query	string	是	显示模式（控制是否展示所有用户）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/applicationid/__APP01/workflow/flowAndNodeTimeConsuming?daterange=2026-01-01~2026-08-01&showmode=all HTTP/1.1

响应

结构：统一 Resource。 data：Collection<FlowAnalyzerVO>（统计分析结果，元素含分组列与耗时聚合数据）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "groupColumns": [ { "name": "FLOWNAME", "value": "报销流程" } ], "duration": 3600 }
  ],
  "errors": null
}

失败示例：

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

---

6. 流程耗时占比

按日期范围、显示模式统计指定软件下各流程的耗时占比（AnalyzerProcess.doAnalyzerFlowTimeConsumingAccounting）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/applicationid/{applicationid}/workflow/flowTimeConsumingAccounting（完整：{manager-context}/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/flowTimeConsumingAccounting）
• 鉴权：是
• Tag：流程监控模块

同上，「5. 流程节点耗时」中关于 @Parameter 注释错位、路径变量语义的说明同样适用。

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
daterange	query	string	是	统计日期范围
showmode	query	string	是	显示模式

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/applicationid/__APP01/workflow/flowTimeConsumingAccounting?daterange=2026-01-01~2026-08-01&showmode=all HTTP/1.1

响应

结构：统一 Resource。 data：Collection<FlowAnalyzerVO>。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "groupColumns": [ { "name": "FLOWNAME", "value": "报销流程" } ], "ratio": 0.65 } ],
  "errors": null
}

失败示例：

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

---

7. 流程实例占比

按日期范围、显示模式统计指定软件下各流程的实例数占比（AnalyzerProcess.doAnalyzerFlowAccounting）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/applicationid/{applicationid}/workflow/flowAccounting（完整：{manager-context}/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/flowAccounting）
• 鉴权：是
• Tag：流程监控模块

同上，「5. 流程节点耗时」中关于 @Parameter 注释错位、路径变量语义的说明同样适用。

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
daterange	query	string	是	统计日期范围
showmode	query	string	是	显示模式

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/applicationid/__APP01/workflow/flowAccounting?daterange=2026-01-01~2026-08-01&showmode=all HTTP/1.1

响应

结构：统一 Resource。 data：Collection<FlowAnalyzerVO>。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "groupColumns": [ { "name": "FLOWNAME", "value": "报销流程" } ], "count": 120, "ratio": 0.42 } ],
  "errors": null
}

失败示例：

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

---

8. 流程耗时排序

按日期范围、显示模式统计指定软件下审批人耗时 Top10 排序（doAnalyzerActorTimeConsumingTopX，固定 Top 数为 10），并为每条结果追加审批人姓名列（NAME，由 UserUtil.findUserName 解析）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/applicationid/{applicationid}/workflow/doAnalyzerActorTimeConsumingTopX（完整：{manager-context}/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/doAnalyzerActorTimeConsumingTopX）
• 鉴权：是
• Tag：流程监控模块

同上，「5. 流程节点耗时」中关于 @Parameter 注释错位、路径变量语义的说明同样适用。

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
applicationid	path	string	是	软件 id
daterange	query	string	是	统计日期范围
showmode	query	string	是	显示模式

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/applicationid/__APP01/workflow/doAnalyzerActorTimeConsumingTopX?daterange=2026-01-01~2026-08-01&showmode=all HTTP/1.1

响应

结构：统一 Resource。 data：Collection<FlowAnalyzerVO>，每个元素的 groupColumns 中追加 NAME 列（审批人姓名）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "groupColumns": [
        { "name": "AUDITOR", "value": "__U001" },
        { "name": "NAME", "value": "张三" }
      ],
      "duration": 7200
    }
  ],
  "errors": null
}

失败示例：

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

---

9. 干预流程

按文档 id 与目标节点 id 强制推进/回退流程。submitTo（包体）可指定每个目标节点的审批人；针对流程实例的不同状态（已终止 terminated、已完成 complete、运行中、无状态）走不同分支：已终止时取首节点重启为 RUNNING2RUNNING_INTERVENTION；已完成时从完成节点的 endnodeid 推进；运行中时遍历当前节点逐一推进；无状态时重建瞬态流程实例后再推进，并恢复历史关系（recoveryRelations）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/applicationid/{applicationid}/workflow/intervention/flowstatert/doflow（完整：{manager-context}/api/authtime/domain/applicationid/{applicationid}/workflow/intervention/flowstatert/doflow）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	软件 id
id	query	string	是	文档 id（DocumentProcess.doView 的主键）
nextnodeids	query	string	是	干预目标节点 id 列表（逗号分隔）
content	body	JSON 文本	是	干预包体，主要承载 submitTo

请求体

JSON 对象（application/json，控制器以字符串接收后用 JsonPath 解析）：

字段	类型	必填	说明
submitTo	array\<object>	否	每个目标节点的审批人指定，元素字段见下；非空时控制器把 userids 内的分号 ; 转为 ',' 并拼成 ['id1','id2'] 字符串写入 paramsTable.submitTo

submitTo 元素字段：

字段	类型	必填	说明
nodeid	string	是	目标节点 id
userids	string	是	该节点的审批人 id 列表（分号 ; 分隔）

请求示例

POST /api/authtime/domain/applicationid/__APP01/workflow/intervention/flowstatert/doflow?id=__DOC001&nextnodeids=2,3 HTTP/1.1
Content-Type: application/json

{
  "submitTo": [
    { "nodeid": "2", "userids": "__U001;__U002" },
    { "nodeid": "3", "userids": "__U003" }
  ]
}

响应

结构：统一 Resource。 data：字符串 "干预成功"。

条件	errcode	errmsg	data
成功	0	ok	干预成功
业务校验异常（OBPMValidateException）	500	e.getValidateMessage()	null
其他异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "干预成功", "errors": null }

失败示例：

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

---

10. 获取可干预的节点

按文档 id（从 id 去掉末尾 -xxx 段后的前缀）查询该文档流程下可干预的节点列表（除当前节点和开始节点外的所有节点）。返回节点 id、节点类型（节点子类简单类名）与状态标签。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/applicationid/{applicationid}/workflow/intervention/othernodes（完整：{manager-context}/api/authtime/domain/applicationid/{applicationid}/workflow/intervention/othernodes）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	软件 id
id	query	string	是	流程实例 id（控制器取 id.substring(0, id.lastIndexOf("-")) 作为文档 id）

请求示例

GET /api/authtime/domain/applicationid/__APP01/workflow/intervention/othernodes?id=__DOC001-__FS001 HTTP/1.1

响应

结构：统一 Resource。 data：JSONArray，元素字段：

字段	类型	说明
id	string	节点 id
type	string	节点类型（节点类的简单类名，如 ManualNode、AutoNode 等）
statelabel	string	节点状态标签

注：id 为空时返回空数组；文档不存在时返回空数组。本端点方法签名 throws Exception，未捕获异常时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "id": "2", "type": "ManualNode", "statelabel": "部门审批" },
    { "id": "3", "type": "ManualNode", "statelabel": "财务审批" }
  ],
  "errors": null
}

失败示例：

HTTP 500，无统一 Resource 体（异常未捕获，由 Spring 默认异常处理）

---

11. 获取节点历史审批人

按文档 id 与节点 id 查询该节点的历史审批人列表（去重，过滤掉 Admin）。返回审批人 id 与姓名。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/applicationid/{applicationid}/workflow/intervention/approvers（完整：{manager-context}/api/authtime/domain/applicationid/{applicationid}/workflow/intervention/approvers）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationid	path	string	是	软件 id
id	query	string	是	文档 id（直接用作 DocumentProcess.doView 主键，不再截取）
nodeid	query	string	是	节点 id

请求示例

GET /api/authtime/domain/applicationid/__APP01/workflow/intervention/approvers?id=__DOC001&nodeid=2 HTTP/1.1

响应

结构：统一 Resource。 data：JSONArray，元素字段：

字段	类型	说明
id	string	审批人用户 id
username	string	审批人姓名

注：源码 @Operation(summary) 文案为「获取节点历史审批人」，但 @Parameter 把 id 误注为「文档id」（实际正确）；本端点方法签名 throws Exception，未捕获异常时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "id": "__U001", "username": "张三" } ],
  "errors": null
}

失败示例：

HTTP 500，无统一 Resource 体（异常未捕获，由 Spring 默认异常处理）

---

12. 获取流程指定审批人用户选择框列表

按软件、文档、流程、节点查询可被指定为审批人的候选用户列表（StateMachineHelper.getPrincipalList），按 type 区分查询范围（3：查询；2：角色；1：部门），支持分页。结果转换为 UserNode 精简结构后内存分页。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/applications/{applicationId}/documents/{docId}/workflows/{flowId}/selectApprovers（完整：{manager-context}/api/authtime/domain/applications/{applicationId}/documents/{docId}/workflows/{flowId}/selectApprovers）
• 鉴权：是
• Tag：流程监控模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件 id
docId	path	string	是	文档 id
flowId	path	string	是	流程定义 id
nodeId	query	string	是	节点 id
type	query	string	是	类型（3：查询；2：角色；1：部门）
selectId	query	string	否	点击角色或部门时选中的 id
pageSize	query	string	否	每页条数，默认 10
pageNum	query	string	否	当前页码，默认 1

请求示例

GET /api/authtime/domain/applications/__APP01/documents/__DOC001/workflows/__FLOW001/selectApprovers?nodeId=2&type=1&selectId=__DEPT01&pageSize=10&pageNum=1 HTTP/1.1

响应

结构：统一 Resource。 data：Map，字段：

字段	类型	说明
datas	array\<UserNode>	当前页用户节点列表（由 MyProfileHelper.buildProfileUser 构造的精简结构）
pageCount	int	总页数
linesPerPage	int	每页条数
rowCount	int	候选用户总数（分页前）
pageNum	int	当前页码

注：本端点方法签名 throws Exception，未捕获异常时由 Spring 默认异常处理（HTTP 500，无统一 Resource 体）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "datas": [ { "id": "__U001", "name": "张三", "loginno": "zhangsan" } ],
    "pageCount": 1,
    "linesPerPage": 10,
    "rowCount": 1,
    "pageNum": 1
  },
  "errors": null
}

失败示例：

HTTP 500，无统一 Resource 体（异常未捕获，由 Spring 默认异常处理）

---