实例级流程预测接口说明

对应实现：obpm-core 预测引擎；obpm-runtime 详情页 / 流程图 / 待办提示；obpm-manager 管理员风险清单。
功能规格见同目录 实例级流程预测功能详细描述.md。
约束：预测仅用于界面提示与消息预警，不干预真实流程流转；不向第三方系统开放预测 API。
拆分：详情页预测、流程图叠加、待办提示为 Runtime 内部 UI 接口；管理员风险清单为 Manager 流程监控接口，与运行时登录用户、DES 加密路径分离。

---

1. 通用约定

1.1 服务与基础路径

Runtime（详情页 / 流程图 / 待办）

项	值
模块	Runtime 工作流
Controller	cn.myapps.runtime.workflow.controller.WorkflowController
基础路径	/api/runtime/{applicationId}
兼容别名	/api/authtime/{applicationId}
Content-Type	application/json
鉴权	需已登录前台用户（accessToken，与现有 Runtime 接口相同）

applicationId、docId 与现网其它 Runtime 接口一致：路径上为 按当前用户 ID 加密后的密文，服务端用 DesUtil.decryptTextByUserId 解密。instanceId 为流程实例 ID（T_FLOWSTATERT.ID），明文传递。

Manager（管理员风险清单）

项	值
模块	Manager 流程监控
Controller	cn.myapps.manager.authtime.controller.flow.FlowInterventionController
基础路径	{manager-context}/api/authtime
Content-Type	application/json
鉴权	需管理员 adminToken（与现有流程监控接口相同）

domainid、applicationid 为明文企业域 id / 软件 id，**不**做 DES 加密。applicationid 仅用于选库。

1.2 统一响应包

成功时 HTTP 200，body 为 Resource：

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

字段	类型	说明
errcode	int	0 成功
errmsg	string	提示，成功为 "ok"
data	object	业务数据，见各接口

业务失败（实例不存在、无权限看见预测面板）仍返回 errcode=0，在 data.visible=false 中表达，避免前端把权限问题当成系统错误。

1.3 可见范围

角色	预测详情（Runtime 详情页）	风险清单（Manager 流程监控）
单据申请人（发起人 / 作者）	可见	不可见
当前审批处理人	可见	不可见
管理员（超管 / 域管 / 开发者）	可见	可见（管理控制台，adminToken）
其它人	visible=false	未登录管理端则无法调用

1.4 SLA 风险枚举

slaRisk	slaRiskLabel	含义
NORMAL	正常	预测完成时间 ≤ SLA 截止，或未配置 SLA
RISK	存在超时风险	预测完成略晚于 SLA（逾期不超过剩余 SLA 窗口的 20%）
HIGH	高概率超时	预测完成明显晚于 SLA，或 SLA 已过仍未结束

这是**事前预警**，与节点 deadline 事后超时提醒并存，互不替代。

1.5 时长展示

remainingDurationText 由工作分钟格式化：

• < 1h：45m
• < 1d：14h20m、8h
• ≥ 1d：1d2h

剩余分钟按**工作日历**累加得到预计完成时刻；无日历时退化为自然分钟。

---

2. 获取实例预测（详情页主接口）

流程详情页预测面板、流程图灰色虚线的主数据源。

2.1 基本信息

项	值
Method	GET
Path	/api/runtime/{applicationId}/documents/{docId}/workflows/{instanceId}/prediction
别名	/api/authtime/{applicationId}/documents/{docId}/workflows/{instanceId}/prediction
Controller 方法	WorkflowController.getFlowPrediction
服务	WorkflowRunTimeService.getFlowPrediction → FlowPredictionService.getPrediction

2.2 路径参数

参数	必填	说明
applicationId	是	软件 ID（加密）
docId	是	文档 ID（加密）
instanceId	是	流程实例 ID（FlowStateRT.id）

无 Query、无 Body。

2.3 成功 data 字段

无权限时：

{
  "visible": false
}

实例不存在时：

{
  "visible": false,
  "message": "流程实例不存在"
}

可见时：

{
  "visible": true,
  "remainingMinutes": 860,
  "remainingDurationText": "14h20m",
  "predictedFinishTime": "2026-09-09 16:30:00",
  "slaDeadline": "2026-09-09 18:00:00",
  "slaRisk": "NORMAL",
  "slaRiskLabel": "正常",
  "currentNodeId": "1001",
  "sampleSize": 42,
  "lowSample": false,
  "style": "dashed-gray",
  "predictedPath": [
    {
      "nodeId": "1001",
      "nodeName": "部门经理",
      "probability": 1.0,
      "current": true,
      "complete": false,
      "avgMinutes": 90,
      "predictedApprovers": [
        { "id": "U001", "name": "张三", "probability": 0.62 }
      ]
    },
    {
      "nodeId": "1002",
      "nodeName": "财务审核",
      "probability": 1.0,
      "current": false,
      "complete": false,
      "avgMinutes": 180,
      "predictedApprovers": []
    },
    {
      "nodeId": "1003",
      "nodeName": "归档",
      "probability": 1.0,
      "current": false,
      "complete": true,
      "avgMinutes": 0,
      "predictedApprovers": []
    }
  ],
  "predictedRelations": [
    {
      "startNodeId": "1001",
      "endNodeId": "1002",
      "probability": 1.0,
      "deterministic": true
    }
  ]
}

顶层字段

字段	类型	说明
visible	boolean	当前用户是否可看预测面板
message	string	不可用原因（可选）
remainingMinutes	int	预计剩余工作分钟
remainingDurationText	string	展示用剩余时长
predictedFinishTime	string	预计完成时刻，yyyy-MM-dd HH:mm:ss，可能为 null
slaDeadline	string	SLA 截止时刻，同上；无 SLA 为 null
slaRisk	string	NORMAL / RISK / HIGH
slaRiskLabel	string	中文标签
currentNodeId	string	当前节点 ID
sampleSize	int	同模板历史实例样本量
lowSample	boolean	样本量 < 5 时为 true，前端可提示“历史样本少，偏差可能较大”
style	string	固定 dashed-gray，前端用灰色虚线画预测边
predictedPath	array	最可能后续节点序列（含当前节点）
predictedRelations	array	预测边上的概率，用于叠加到流程图

predictedPath[]

字段	类型	说明
nodeId	string	节点 ID
nodeName	string	节点名称
probability	number	走到该节点的路径概率，0~1，保留三位小数
current	boolean	是否当前节点
complete	boolean	是否结束节点
avgMinutes	int	该节点计入剩余的工作分钟（当前节点已扣除已消耗时长）
predictedApprovers	array	预测处理人，最多 3 个；**不等于**实际待办接收人

predictedApprovers[]

字段	类型	说明
id	string	用户 ID
name	string	用户名称
probability	number	历史/配置占比，0~1

predictedRelations[]

字段	类型	说明
startNodeId	string	边起点
endNodeId	string	边终点
probability	number	该分支概率。确定性条件为 1.0；未判定网关为历史频次，如 0.87 / 0.13
deterministic	boolean	true 表示表单条件已能确定该边；false 表示概率分支

2.4 前端用法

1. 预测面板：展示 remainingDurationText、predictedFinishTime、slaRiskLabel。
2. 流程图：在已走实线之外，用灰色虚线绘制 predictedRelations，边上标注 probability * 100 + %。
3. lowSample=true 时给出精度提示。
4. 不要用本接口结果改提交、改下一节点、改审批人。

2.5 缓存与重算

结果写入 T_FLOWPREDICTION。详情页优先读快照；流程每走到新节点会在 StateMachine.updateFlowState 后自动重算。快照不存在时本接口会现场计算并落库。

---

3. 管理员风险清单

管理控制台「流程监控 → 风险清单」页签的数据源。与 Runtime 详情页预测接口分离：不走运行时登录用户，不加密软件 id。

3.1 基本信息

项	值
Method	GET
Path	/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/predictions/risks
完整路径	{manager-context}/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/predictions/risks
Controller	FlowInterventionController.queryFlowPredictionRisks
服务	new FlowPredictionServiceImpl(applicationid).queryRiskList(domainid)

未登录管理员：data.visible=false。已登录管理员返回当前域内 slaRisk 为 RISK 或 HIGH 的快照，最多 200 条，按 lastUpdated 倒序。

Runtime **不再**提供 /api/runtime/{applicationId}/workflows/predictions/risks。

3.2 路径参数

参数	必填	说明
domainid	是	企业域 ID（明文）
applicationid	是	软件 ID（明文），用于选库

无 Query、无 Body。

3.3 成功 data

无权限：

{
  "visible": false
}

有权限：

{
  "visible": true,
  "datas": [
    {
      "id": "预测快照ID",
      "flowStateId": "流程实例ID",
      "docId": "文档ID",
      "flowId": "流程模板ID",
      "currentNodeId": "当前节点ID",
      "remainingMinutes": 860,
      "predictedFinishTime": "2026-09-09T16:30:00.000+08:00",
      "slaDeadline": "2026-09-09T18:00:00.000+08:00",
      "slaRisk": "HIGH",
      "sampleSize": 12,
      "resultJson": "{...完整预测 JSON 字符串...}",
      "alertSent": true,
      "lastUpdated": "2026-09-08T19:00:00.000+08:00"
    }
  ]
}

字段	类型	说明
visible	boolean	是否已登录管理端管理员
datas	array	FlowPredictionSnapshot 列表
datas[].flowStateId	string	流程实例 ID，管理端可打开流程监控详情
datas[].docId	string	文档 ID
datas[].slaRisk	string	仅 RISK / HIGH
datas[].resultJson	string	与第 2 节 data 同结构的 JSON 文本
datas[].alertSent	boolean	是否已发过同档事前预警，避免重复骚扰

日期字段由 Jackson 按默认时区序列化，前端按 Date 解析即可。

---

4. 流程图接口扩展（叠加预测路径）

未新增路径，在现有新流程图接口的 data 上增加 prediction。

项	值
Method	GET
Path	/api/runtime/{applicationId}/documents/{docId}/workflows/{instanceId}/newflowchart
Controller 方法	WorkflowController.getNewWorkflowChart

原有 data.flow 不变。能算出预测时额外带：

{
  "flow": { },
  "prediction": {
    "visible": true,
    "remainingDurationText": "14h20m",
    "predictedRelations": [ ],
    "style": "dashed-gray"
  }
}

prediction 字段集与第 2 节可见时的 data 相同。预测失败时仅缺少 prediction，不影响原流程图。

前端可只请求本接口：用 flow 画已走路径，用 prediction.predictedRelations 画灰色虚线。

---

5. 待办卡片提示（既有待办接口扩展）

未新增待办 URL。WorkProcessBean.getPendingList 会按 docId 回填预测字段。

5.1 相关接口

Method	Path	说明
GET	/api/runtime/{applicationId}/flowcenters/pendings	流程中心待办列表

5.2 WorkVO 新增字段

字段	JSON 名	类型	说明
预计完成时间	predictedFinishTime	datetime	yyyy-MM-dd HH:mm:ss（GMT+8）
剩余时长文案	remainingDurationText	string	如 14h20m
风险码	slaRisk	string	NORMAL / RISK / HIGH
风险中文	slaRiskLabel	string	正常 / 存在超时风险 / 高概率超时

无快照时上述字段为空，待办列表仍照常返回。

流程中心 FlowCenterRunTimeServiceImpl.getPendings 目前手工组装 map。若卡片要展示预测，需在组装处增加上述 4 个 map.put。WorkVO 与 WorkProcessBean 侧数据已具备。

---

6. 非 HTTP 输出

设计要求预测结果**不能**给第三方系统调用，因此没有开放 API、没有独立 token。以下为内部副作用，不是对外接口。

6.1 节点变更自动重算

挂点：StateMachine.updateFlowState 末尾。
任务完成、跳转、网关执行等导致实例更新后都会调用。异常只记日志，**不回滚、不阻断**真实流转。

6.2 消息中心事前预警

当 slaRisk 为 RISK 或 HIGH，且同档预警尚未发送时，向申请人与当前处理人发站内消息。

项	值
主题类型	Notification.SUBJECT_TYPE_PREDICTION_SLA = 8
标题	流程超时风险预警： + slaRiskLabel
渠道	复用现有 Notification（站内信等）

同一风险档只发一次；风险降回 NORMAL 后清除已发标记，再次升高可再发。

---

7. Java 服务接口（供模块内调用）

包：cn.myapps.core.runtime.workflow.prediction.FlowPredictionService
实现：FlowPredictionServiceImpl(applicationId)，与现有 Runtime Process 一样按软件直接 new，不经加密 ProcessFactory。

方法	说明
refresh(FlowStateRT)	按内存中的实例重算并落库，可能发预警
refreshQuietly(FlowStateRT)	同上，吞掉异常
getPrediction(applicationId, docId, instanceId, user, params)	详情页 JSON（Runtime 调用）
queryRiskList(domainId)	管理员风险清单（Manager 调用，传入企业域 id）
fillPendingHints(Collection<WorkVO>)	给待办列表填预测字段

WorkflowRunTimeService（Runtime 用）仅增加：

• JSONObject getFlowPrediction(String applicationId, String docId, String instanceId, IFrontEndUser user)

管理员风险清单 **不**挂在 WorkflowRunTimeService / WorkflowController 上。Manager 由 FlowInterventionController 直接 new FlowPredictionServiceImpl(applicationid)。

---

8. 落库

表名：T_FLOWPREDICTION（应用库，随 AbstractApplicationInitDAO.initTables 自动建表/补列）。

列	说明
ID	主键
FLOWSTATERT_ID	流程实例 ID，按此更新
DOC_ID	文档 ID
FLOWID	流程模板 ID
CURRENT_NODEID	计算时当前节点
REMAINING_MINUTES	剩余工作分钟
PREDICTED_FINISH	预计完成时刻
SLA_DEADLINE	SLA 截止
SLA_RISK	NORMAL / RISK / HIGH
SAMPLE_SIZE	历史样本量
RESULT_JSON	完整预测 JSON
ALERT_SENT	1 已发事前预警
LAST_UPDATED	最近计算时间
APPLICATIONID / DOMAINID	软件 / 域

历史耗时来自本系统 T_RELATIONHIS、T_FLOWHISTORY，不接入外部数据集。

T_FLOWPREDICTION 只随 AbstractApplicationInitDAO.initTables() 补齐（保存默认数据源、管理端同步数据表单、或 .sync/*.init_default_datasource）。Runtime 启动和预测接口访问都不会自动建表。已有库可走上述 initTables 路径，或手工执行：

CREATE TABLE IF NOT EXISTS T_FLOWPREDICTION (
  ID VARCHAR(100) NOT NULL PRIMARY KEY,
  FLOWSTATERT_ID VARCHAR(100),
  DOC_ID VARCHAR(100),
  FLOWID VARCHAR(100),
  CURRENT_NODEID VARCHAR(100),
  REMAINING_MINUTES INT,
  PREDICTED_FINISH DATETIME,
  SLA_DEADLINE DATETIME,
  SLA_RISK VARCHAR(100),
  SAMPLE_SIZE INT,
  RESULT_JSON LONGTEXT,
  ALERT_SENT INT,
  LAST_UPDATED DATETIME,
  APPLICATIONID VARCHAR(100),
  DOMAINID VARCHAR(100),
  KEY IDX_FLOWPREDICTION_FS (FLOWSTATERT_ID),
  KEY IDX_FLOWPREDICTION_DOC (DOC_ID)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

---

9. 接口一览

能力	Method	Path	模块
实例预测面板	GET	/api/runtime/{applicationId}/documents/{docId}/workflows/{instanceId}/prediction	Runtime
流程图叠加预测	GET	/api/runtime/{applicationId}/documents/{docId}/workflows/{instanceId}/newflowchart	Runtime（原接口扩展）
管理员风险清单	GET	/api/authtime/domain/{domainid}/applicationid/{applicationid}/workflow/predictions/risks	Manager
待办卡片提示	GET	/api/runtime/{applicationId}/flowcenters/pendings	Runtime（原接口扩展字段）

以上均不对第三方开放。第三方如需预测，应按产品约束自行用原始流程历史二次计算，不要调用上述内部接口。