createHistoricActivityInstanceQuery

Flowable 7.1.0 摘要：创建历史活动实例查询对象，用于查询流程执行过的所有活动节点历史。

方法签名与说明

HistoricActivityInstanceQuery createHistoricActivityInstanceQuery()

创建历史活动实例查询构建器。可以查询流程执行过的所有节点（用户任务、服务任务、网关等）的历史记录。

Returns:

• HistoricActivityInstanceQuery - 历史活动实例查询构建器

常见使用场景

1. 流程轨迹追踪

追踪流程实例经过了哪些节点，何时开始何时结束。

2. 流程耗时分析

分析各个节点的执行耗时，找出瓶颈环节。

3. 流程图高亮

在流程图上高亮显示已执行的节点和当前节点。

Kotlin + Spring Boot 调用示例

示例1：查询流程实例的执行轨迹

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service
import java.util.Date

data class ActivityRecord(
    val activityId: String,
    val activityName: String,
    val activityType: String,
    val startTime: Date,
    val endTime: Date?,
    val durationInMillis: Long?
)

@Service
class ProcessTraceService(
    private val historyService: HistoryService
) {
    
    /**
     * 查询流程执行轨迹
     * 企业场景：流程详情页展示完整执行路径
     */
    fun getProcessTrace(processInstanceId: String): List<ActivityRecord> {
        val activities = historyService.createHistoricActivityInstanceQuery()
            .processInstanceId(processInstanceId)
            .orderByHistoricActivityInstanceStartTime()
            .asc()
            .list()
        
        return activities.map { activity ->
            ActivityRecord(
                activityId = activity.activityId,
                activityName = activity.activityName,
                activityType = activity.activityType,
                startTime = activity.startTime,
                endTime = activity.endTime,
                durationInMillis = activity.durationInMillis
            )
        }
    }
}

示例2：分析节点执行耗时

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service

data class ActivityDurationStats(
    val activityName: String,
    val avgDurationMinutes: Double,
    val maxDurationMinutes: Double,
    val minDurationMinutes: Double,
    val executionCount: Int
)

@Service
class ActivityDurationAnalyzer(
    private val historyService: HistoryService
) {
    
    /**
     * 分析活动节点耗时
     * 企业场景：流程优化，找出耗时最长的环节
     */
    fun analyzeActivityDuration(
        processDefinitionKey: String
    ): List<ActivityDurationStats> {
        
        val activities = historyService.createHistoricActivityInstanceQuery()
            .processDefinitionKey(processDefinitionKey)
            .finished()
            .list()
        
        val groupedActivities = activities.groupBy { it.activityId }
        
        return groupedActivities.map { (activityId, activityList) ->
            val durations = activityList.mapNotNull { it.durationInMillis }
                .map { it.toDouble() / (1000 * 60) } // 转换为分钟
            
            ActivityDurationStats(
                activityName = activityList.first().activityName,
                avgDurationMinutes = if (durations.isNotEmpty()) durations.average() else 0.0,
                maxDurationMinutes = durations.maxOrNull() ?: 0.0,
                minDurationMinutes = durations.minOrNull() ?: 0.0,
                executionCount = activityList.size
            )
        }.sortedByDescending { it.avgDurationMinutes }
    }
}

示例3：获取流程图高亮节点

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service

@Service
class ProcessDiagramHighlightService(
    private val historyService: HistoryService
) {
    
    /**
     * 获取流程图高亮节点
     * 企业场景：流程监控页面，高亮显示已执行的节点
     */
    fun getHighlightedActivities(processInstanceId: String): Map<String, List<String>> {
        val activities = historyService.createHistoricActivityInstanceQuery()
            .processInstanceId(processInstanceId)
            .list()
        
        val finishedActivities = activities
            .filter { it.endTime != null }
            .map { it.activityId }
            .distinct()
        
        val currentActivities = activities
            .filter { it.endTime == null }
            .map { it.activityId }
            .distinct()
        
        return mapOf(
            "finished" to finishedActivities,
            "current" to currentActivities
        )
    }
}

示例4：REST API

import org.flowable.engine.HistoryService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/history/activities")
class HistoricActivityController(
    private val historyService: HistoryService
) {
    
    @GetMapping("/process-instance/{processInstanceId}")
    fun getActivities(@PathVariable processInstanceId: String): List<Map<String, Any>> {
        val activities = historyService.createHistoricActivityInstanceQuery()
            .processInstanceId(processInstanceId)
            .orderByHistoricActivityInstanceStartTime()
            .asc()
            .list()
        
        return activities.map { activity ->
            mapOf(
                "activityId" to activity.activityId,
                "activityName" to activity.activityName,
                "activityType" to activity.activityType,
                "startTime" to activity.startTime,
                "endTime" to activity.endTime,
                "duration" to activity.durationInMillis
            )
        }
    }
}

注意事项

1. 活动类型

• userTask：用户任务
• serviceTask：服务任务
• startEvent：开始事件
• endEvent：结束事件
• exclusiveGateway：排他网关

2. 性能优化

• 添加流程实例ID过滤，避免全表扫描
• 大数据量时考虑分页

3. 未完成的活动

• endTime为null表示活动正在执行中
• durationInMillis只有已完成的活动才有值

相关 API

• HistoryService.createHistoricActivityInstanceQuery() - 查询活动历史
• HistoryService.createHistoricProcessInstanceQuery() - 查询流程历史
• HistoryService.createHistoricTaskInstanceQuery() - 查询任务历史

本文档说明

• 基于 Flowable 7.1.0 版本编写
• 所有示例均可直接在 Spring Boot + Kotlin 项目中使用