9、Activiti-任务（Task）的相关操作

1. 引言

Activiti是一个轻量级、开源的工作流和业务流程管理(BPM)平台，基于Java开发。它实现了BPMN 2.0规范，提供了强大的流程定义、执行和监控能力。在Activiti中，任务(Task)是流程执行的核心概念之一，代表需要人工参与完成的工作项。

任务操作API是Activiti提供的RESTful和Java API集合，用于对流程中的任务进行各种操作。Activiti的任务操作功能非常丰富，涵盖了任务生命周期管理、变量处理、身份链接、评论与附件等多个方面。

2. 任务操作概述

2.1. 任务操作功能体系

Activiti的任务操作功能可以划分为以下几个主要类别：

• 基础任务操作：包括获取、查询、更新和删除任务等基本CRUD操作
• 任务变量管理：处理与任务相关的各种变量，包括创建、更新、删除等
• 身份链接管理：处理任务与用户/组之间的关联关系
• 评论与附件：为任务添加评论和附件，丰富任务内容
• 历史任务查询：查询已完成任务的历史记录

2.2. 任务模型

在Activiti中，任务(Task)是org.activiti.api.task.model.Task接口的实例，主要包含以下属性：

|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| 方法名称 | 说明 |
| enum TaskStatus { CREATED, ASSIGNED, SUSPENDED, COMPLETED, CANCELLED, DELETED } | 定义任务的当前生命周期状态： * CREATED：任务已创建但未分配（未认领）。 * ASSIGNED：任务已分配给某人（已认领）。 * SUSPENDED：任务被挂起（暂时不可操作）。 * COMPLETED：任务已完成。 * CANCELLED：任务被取消。 * DELETED：任务被删除。 |
| String getId() | 任务的唯一标识符（UUID 或数据库主键） |
| String getOwner() | 任务的原属用户（任务创建者或初始责任人） |
| String getAssignee() | 任务的当前处理人（认领任务的人） |
| String getName() | 任务名称（如"审批申请"、"处理投诉"） |
| String getDescription() | 任务的详细描述 |
| Date getCreatedDate() | 任务的创建时间 |
| Date getClaimedDate() | 任务被认领的时间（从 CREATED 变为 ASSIGNED 的时间点 |
| Date getDueDate() | 任务的截止时间（超时未完成可能触发警告或自动操作） |
| int getPriority() | 任务优先级（数值越高优先级越高，如 0=低，100=高） |
| String getProcessDefinitionId() | 关联的流程定义ID（标识任务所属的流程定义） |
| String getProcessInstanceId() | 关联的流程实例ID（标识任务所属的具体流程实例） |
| String getParentTaskId() | 父任务ID（用于子任务场景，如会签任务中的子任务） |
| TaskStatus getStatus() | 任务的当前状态（参考 TaskStatus 枚举） |
| String getFormKey() | 关联的表单KEY（用于动态渲染任务处理表单） |
| Date getCompletedDate() | 任务完成时间（状态为 COMPLETED 时有效） |
| Long getDuration() | 任务从创建到完成的耗时（毫秒，仅完成的任务有值） |
| Integer getProcessDefinitionVersion() | 流程定义的版本号（用于区分同一流程定义的不同版本） |
| String getBusinessKey() | 业务主键（通常关联业务系统的ID，如订单号、合同号等） |
| boolean isStandalone() | 是否为独立任务（true 表示非流程关联的任务，如手动创建的任务） |

3. 基础任务操作

3.1. 根据taskId获取单个任务

3.1.1. 特点

通过任务ID精确获取特定任务对象，是其他任务操作的基础。

3.1.2. 使用场景

当已知任务ID需要获取任务详细信息时使用

3.1.3. 查询示例

3.1.3.1. 方式一：TaskService taskService

public AjaxResult getATask(String taskId) {
    Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
    return AjaxResult.success(new TaskDomain(task).toString());
}

3.1.3.2. 方式二：TaskRuntime taskRuntime

    public AjaxResult getATask(String taskId) {
        Task task = taskRuntime.task(taskId);
        return AjaxResult.success(new TaskDTO(task).toString());
    }

3.2. 查询任务列表

3.2.1. 特点

支持多种条件组合查询，可分页返回结果。

3.2.2. 使用场景

需要列出满足特定条件的任务集合，如待办任务列表。

3.2.3. 查询示例

3.2.3.1. 方式一：TaskService taskService

    public AjaxResult listOfTasks() {
        List<Task> tasks = taskService.createTaskQuery().list();
        //  如果需要分页处理 将 list()替换为 .listPage(0,10)
        return AjaxResult.success(tasks.stream().map(t -> new TaskDomain(t)).collect(Collectors.toList()));
    }

3.2.3.2. 方式二：TaskRuntime taskRuntime

    @Resource
    private APITaskConverter taskConverter;
    public AjaxResult listOfTasks() {
        // 1、获取任务查询对象
        TaskQuery taskQuery = taskService.createTaskQuery();
        //2、将org.activiti.engine.task.Task 接口转换为 org.activiti.api.task.model.Task
        List<Task> tasks = taskConverter.from(taskQuery.list());
        // 3、获取任务数据查询条目数量
        Page<Task> taskPage = new PageImpl<>(tasks, Math.toIntExact(taskQuery.count()));
        int totalItems = taskPage.getTotalItems();
        return AjaxResult.success("数据详情：" + tasks.stream().map(t -> new TaskDTO(t)).collect(Collectors.toList()) + "; 数量：" + totalItems);
    }

3.2.3.3. 查询条件

|-------------|-------------------------------------------------------------|-----------------------------------|
| 分类 | 方法 | 说明 |
| 按照任务名称查询 | taskName(String name) | 按任务名称精确匹配 |
| 按照任务名称查询 | taskNameIn(List<String>) | 按任务名称列表查询（区分大小写） |
| 按照任务名称查询 | taskNameInIgnoreCase(List<String>) | 按任务名称列表查询（不区分大小写） |
| 按照任务名称查询 | taskNameLike(String) | 按任务名称模糊匹配（SQL语法，如 %activiti%） |
| 按照任务名称查询 | taskNameLikeIgnoreCase(String) | 按任务名称模糊匹配（不区分大小写） |
| 按照任务描述查询 | taskDescription(String) | 按任务描述精确匹配 |
| 按照任务描述查询 | taskDescriptionLike(String) | 按任务描述模糊匹配 |
| 按照任务描述查询 | taskDescriptionLikeIgnoreCase(String) | 按任务描述模糊匹配（不区分大小写） |
| 按照优先级查询 | taskPriority(Integer) | 按优先级精确匹配 |
| 按照优先级查询 | taskMinPriority(Integer) | 查询优先级≥指定值的任务 |
| 按照优先级查询 | taskMaxPriority(Integer) | 查询优先级≤指定值的任务 |
| 按照处理人查询 | taskAssignee(String) | 按当前处理人（Assignee）精确匹配 |
| 按照处理人查询 | taskAssigneeLike(String) | 按处理人模糊匹配（如 %admin%） |
| 按照处理人查询 | taskAssigneeLikeIgnoreCase(String) | 按处理人模糊匹配（不区分大小写） |
| 按照处理人查询 | taskAssigneeIds(List<String>) | 按处理人ID列表查询 |
| 按照任务所有者查询 | taskOwner(String) | 按任务所有者（Owner）精确匹配 |
| 按照任务所有者查询 | taskOwnerLike(String) | 按所有者模糊匹配 |
| 按照任务所有者查询 | taskOwnerLikeIgnoreCase(String) | 按所有者模糊匹配（不区分大小写） |
| 按照任务候选人/组查询 | taskCandidateUser(String) | 查询用户为候选人的任务（含用户所在组的任务） |
| 按照任务候选人/组查询 | taskCandidateUser(String, List<String>) | 查询用户为候选人的任务（指定用户组） |
| 按照任务候选人/组查询 | taskCandidateGroup(String) | 查询组为候选人的任务 |
| 按照任务候选人/组查询 | taskCandidateGroupIn(List<String>) | 按候选组列表查询 |
| 按照任务参与人/组查询 | taskInvolvedUser(String) | 查询用户参与的任务（含处理人、所有者、候选人） |
| 按照任务参与人/组查询 | taskInvolvedGroupsIn(List<String>) | 查询指定组参与的任务 |
| 按照租户查询 | taskTenantId(String tenantId) | 查询具有给定租户id的任务 |
| 按照租户查询 | taskTenantIdLike(String tenantIdLike) | 租户id模糊匹配 |
| 按照租户查询 | taskWithoutTenantId() | 查询没有租户id的任务 |
| 按流程实例关联查询 | processInstanceId(String) | 按流程实例ID查询 |
| 按流程实例关联查询 | processInstanceIdIn(List<String>) | 按流程实例ID列表查询 |
| 按流程实例关联查询 | processInstanceBusinessKey(String) | 按业务键（BusinessKey）精确匹配 |
| 按流程实例关联查询 | processInstanceBusinessKeyLike(String) | 按业务键模糊匹配 |
| 按流程实例关联查询 | processInstanceBusinessKeyLikeIgnoreCase(String) | 按业务键模糊匹配（不区分大小写） |
| 按流程实例关联查询 | executionId(String) | 按执行ID查询 |
| 按时间范围查询 | taskCreatedOn(Date) | 查询指定创建时间的任务 |
| 按时间范围查询 | taskCreatedBefore(Date) | 查询创建时间≤指定日期的任务 |
| 按时间范围查询 | taskCreatedAfter(Date) | 查询创建时间≥指定日期的任务 |
| 按时间范围查询 | taskDueDate(Date) | 查询指定截止时间的任务 |
| 按时间范围查询 | taskDueBefore(Date) | 查询截止时间≤指定日期的任务 |
| 按时间范围查询 | taskDueAfter(Date) | 查询截止时间≥指定日期的任务 |
| 按时间范围查询 | withoutTaskDueDate() | 查询无截止时间的任务 |
| 按照任务类别查询 | taskCategory(String category) | 查询给定类别的任务 |
| 按流程定义关联查询 | processDefinitionKey(String) | 按流程定义Key精确匹配 |
| 按流程定义关联查询 | processDefinitionKeyLike(String) | 按流程定义Key模糊匹配 |
| 按流程定义关联查询 | processDefinitionKeyLikeIgnoreCase(String) | 按流程定义Key模糊匹配（不区分大小写） |
| 按流程定义关联查询 | processDefinitionKeyIn(List<String>) | 按流程定义Key列表查询 |
| 按流程定义关联查询 | processDefinitionId(String) | 按流程定义ID查询 |
| 按流程定义关联查询 | processDefinitionName(String) | 按流程定义名称精确匹配 |
| 按流程定义关联查询 | processDefinitionNameLike(String) | 按流程定义名称模糊匹配 |
| 按流程定义关联查询 | processCategoryIn(List<String>) | 查询流程分类在指定列表中的任务 |
| 按流程定义关联查询 | processCategoryNotIn(List<String>) | 查询流程分类不在指定列表中的任务 |
| 按流程定义关联查询 | deploymentId(String) | 按部署ID查询 |
| 按流程定义关联查询 | deploymentIdIn(List<String>) | 按部署ID列表查询 |
| 按照变量查询 | taskVariableValueEquals(String, Object) | 按本地任务变量名和值精确匹配 |
| 按照变量查询 | taskVariableValueEquals(Object) | 查询存在指定值的本地任务变量 |
| 按照变量查询 | taskVariableValueEqualsIgnoreCase(String, String) | 按字符串变量值匹配（不区分大小写） |
| 按照变量查询 | taskVariableValueNotEquals(String, Object) | 按本地变量名和值不匹配查询 |
| 按照变量查询 | taskVariableValueNotEqualsIgnoreCase(String, String) | 按字符串变量值不匹配（不区分大小写） |
| 按照变量查询 | taskVariableValueGreaterThan(String, Object) | 查询变量值>指定值的任务 |
| 按照变量查询 | taskVariableValueGreaterThanOrEqual(String, Object) | 查询变量值≥指定值的任务 |
| 按照变量查询 | taskVariableValueLessThan(String, Object) | 查询变量值<指定值的任务 |
| 按照变量查询 | taskVariableValueLessThanOrEqual(String, Object) | 查询变量值≤指定值的任务 |
| 按照变量查询 | taskVariableValueLike(String, String) | 按字符串变量模糊匹配（如 %activiti%） |
| 按照变量查询 | taskVariableValueLikeIgnoreCase(String, String) | 按字符串变量模糊匹配（不区分大小写） |
| 按照变量查询 | processVariableValueEquals(String, Object) | 按流程变量名和值精确匹配 |
| 按照变量查询 | processVariableValueEquals(Object) | 查询存在指定值的流程变量 |
| 按照变量查询 | processVariableValueEqualsIgnoreCase(String, String) | 按流程字符串变量匹配（不区分大小写） |
| 按照变量查询 | processVariableValueNotEquals(String, Object) | 按流程变量名和值不匹配查询 |
| 按照变量查询 | processVariableValueNotEqualsIgnoreCase(String, String) | 按流程字符串变量不匹配（不区分大小写） |
| 按照变量查询 | processVariableValueGreaterThan(String, Object) | 查询流程变量值>指定值的任务 |
| 按照变量查询 | processVariableValueLessThan(String, Object) | 查询流程变量值<指定值的任务 |
| 按结果控制与本地化查询 | includeTaskLocalVariables() | 在结果中包含本地任务变量 |
| 按结果控制与本地化查询 | includeProcessVariables() | 在结果中包含流程变量 |
| 按结果控制与本地化查询 | limitTaskVariables(Integer) | 限制返回的变量数量 |
| 按结果控制与本地化查询 | locale(String) | 指定任务名称和描述的本地化语言 |
| 按结果控制与本地化查询 | withLocalizationFallback() | 启用本地化回退（找不到指定语言时使用默认语言） |
| 逻辑组合查询 | or() | 开始一个OR条件组合，后续条件用OR连接 |
| 逻辑组合查询 | endOr() | 结束OR条件组合，回归默认的AND连接 |
| 排序 | orderByTaskId() | 按任务ID排序（需搭配 asc()/desc()） |
| 排序 | orderByTaskName() | 按任务名称排序 |
| 排序 | orderByTaskDescription() | 按任务描述排序 |
| 排序 | orderByTaskPriority() | 按优先级排序 |
| 排序 | orderByTaskAssignee() | 按处理人排序 |
| 排序 | orderByTaskCreateTime() | 按创建时间排序 |
| 排序 | orderByProcessInstanceId() | 按流程实例ID排序 |
| 排序 | orderByExecutionId() | 按执行ID排序 |
| 排序 | orderByProcessDefinitionId() | 按流程定义ID排序 |
| 排序 | orderByTaskDueDate() | 按截止时间排序 |
| 排序 | orderByTaskOwner() | 按所有者排序 |
| 排序 | orderByTaskDefinitionKey() | 按任务定义Key排序 |
| 排序 | orderByTenantId() | 按租户ID排序 |
| 排序 | orderByDueDateNullsFirst() | 截止时间NULL值排在最前 |
| 排序 | orderByDueDateNullsLast() | 截止时间NULL值排在最后 |

3.3. 更新任务

3.3.1. 特点

可更新任务的各种属性，如名称、描述、优先级等。

3.3.2. 使用场景

需要修改任务属性时使用。

3.3.3. 更新示例

3.3.3.1. 修改任务所有者

taskService.setOwner(taskId,"admin");

3.3.3.2. 修改任务处理人

taskService.setAssignee(taskId,"zhaoyun");

3.3.3.3. 修改任务优先级

taskService.setPriority(taskId,72);

3.3.3.4. 修改任务到期时间

taskService.setDueDate(taskId,new Date() );

3.3.3.5. 通过taskRuntime更新任务

taskRuntime.update(new UpdateTaskPayload(taskId,"审批","system/user",new Date() ,80,"admin","",""));

|------------------|-------------|--------------|
| 字段名 | 类型 | 说明 |
| taskId | String | 要更新的任务ID（必填） |
| name | String | 新任务名称（可选） |
| description | String | 新任务描述（可选） |
| dueDate | Date | 新截止时间（可选） |
| priority | Integer | 新优先级（可选） |
| assignee | String | 新处理人（可选） |
| parentTaskId | String | 新父任务ID（可选） |

3.4. 任务操作

3.4.1. 特点

包括认领、完成、委派等核心操作。

3.4.2. 使用场景

处理任务流转的关键操作。

3.4.3. 示例

3.4.3.1. 领取任务

3.4.3.1.1. 使用TaskService

taskService.claim(taskId,"admin")

3.4.3.1.2. 使用TaskRuntime

taskRuntime.claim(new ClaimTaskPayload(taskId,""))

3.4.3.2. 释放任务

3.4.3.2.1. 使用TaskService

taskService.unclaim(taskId);

3.4.3.2.2. 使用TaskRuntime

taskRuntime.release(new ReleaseTaskPayload(taskId));

3.4.3.3. 委派任务

taskService.delegateTask(taskId,"admin");

3.4.3.4. 解决任务

taskService.resolveTask(taskId);

3.4.3.4.1. resolveTask重载方法说明

|--------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-----------------------------------------|------------------------------|
| 方法签名 | 参数说明 | 关键特性 | 适用场景 |
| void resolveTask(String taskId) | taskId : 要解决的任务ID（必填） | 将委托任务标记为已解决（RESOLVED ），不传递任何变量。 | 任务处理人完成委托后，无需向流程传递额外数据时使用。 |
| void resolveTask(String taskId,
Map<String, Object> variables) | variables : 持久化变量（存入数据库，可选） | 解决任务时提交持久化变量，供后续流程节点使用。 | 需要记录审批结果、表单数据等需长期保存的信息时使用。 |
| void resolveTask(String taskId,
Map<String, Object> variables,
Map<String, Object> transientVariables) | transientVariables : 临时变量（仅当前操作有效，不存储到数据库，可选） | 解决任务时同时提交持久化和临时变量。 | 需传递临时数据（如通知消息）且避免污染流程变量表时使用。 |

3.4.3.5. 完成任务

3.4.3.5.1. 使用TaskService

taskService.complete(taskId);

3.4.3.5.2. complete重载方法说明

|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|-----------------------|-------------------------|
| 方法签名 | 参数说明 | 关键特性 | 适用场景 |
| void complete(String taskId) | taskId : 要完成的任务ID | 仅完成任务，不传递任何变量 | 任务无需携带额外数据时使用 |
| void complete(String taskId,
Map<String, Object> variables) | variables : 流程级变量（全局可见，存入数据库） | 提交持久化变量，后续流程节点可读取 | 需要传递审批结果等持久化数据时 |
| void complete(String taskId,
Map<String, Object> variables,
Map<String, Object> transientVariables) | transientVariables : 临时变量（仅当前生命周期有效，不存储） | 同时传递持久化和临时变量 | 需临时传递消息（如通知内容）且避免污染流程变量 |
| void complete(String taskId,
Map<String, Object> variables,
boolean localScope) | localScope : 变量作用域（true=任务级，false=流程级，默认false） | 控制变量作用范围，任务级变量仅当前任务可见 | 需要限制变量作用域（如临时表单数据） |

3.4.3.5.3. 使用TaskRuntime

taskRuntime.complete(new CompleteTaskPayload());

3.5. 删除任务

3.5.1. 特点

删除任务及其相关数据，需谨慎使用。

3.5.2. 使用场景

需要取消或删除无效任务时使用。

3.5.3. 示例

3.5.3.1. 使用TaskService

taskService.deleteTask(taskId);
taskService.deleteTasks(Collections.singleton(taskId));

3.5.3.1.1. deleteTask及deleteTasks重载方法说明

|---------------------------------------------------------------------------------------|------------------------------------|--------------------------|------------------------|
| 法签名 | 参数说明 | 功能特点 | 适用场景 |
| void deleteTask(String taskId) | taskId : 要删除的任务ID | 删除任务但保留历史记录 | 常规任务删除，需审计留痕时使用 |
| void deleteTask(String taskId, boolean cascade) | cascade : 是否级联删除历史记录（true=删除） | 控制是否同步清理历史数据 | 需要彻底清理任务所有痕迹时使用 |
| void deleteTask(String taskId, String deleteReason) | deleteReason : 删除原因（记录到历史） | 删除任务并记录原因（历史模块启用时可见） | 需要追踪删除操作的业务场景（如"用户撤销"） |
| void deleteTask(String taskId, String deleteReason, boolean cancel) | cancel : 是否标记为"已取消"（影响业务状态） | 删除任务时附加状态标记和原因 | 需要区分正常完成与取消的场景（如工单作废） |
| void deleteTasks(Collection<String> taskIds) | taskIds: 要删除的任务ID集合 | 批量删除任务但保留历史记录 | 清理多个任务同时需保留审计轨迹 |
| void deleteTasks(Collection<String> taskIds, boolean cascade) | cascade: 是否级联删除历史记录（true=同步清理） | 批量删除任务并可选清理历史数据 | 需要彻底移除任务及其历史痕迹（如数据迁移后） |
| void deleteTasks(Collection<String> taskIds, String deleteReason) | deleteReason: 统一删除原因（记录到历史） | 批量删除任务并记录统一原因 | 需要记录批量操作原因（如"系统批量清理"） |
| void deleteTasks(Collection<String> taskIds, String deleteReason, boolean cancel) | cancel: 是否标记为"已取消" | 批量删除任务时附加状态标记和原因 | 需要批量作废任务（如订单批量取消） |

3.5.3.2. 使用TaskRuntime

taskRuntime.delete(new DeleteTaskPayload(taskId,"无用信息"));

4. 任务变量操作

4.1. 获取任务的所有（多个）变量

4.1.1. 特点

返回任务的所有变量Map，变量值已反序列化。

4.1.2. 示例

4.1.2.1. 使用TaskService

taskService.getVariables(taskId);
// 或
taskService.getVariablesLocal(taskId);

4.1.2.1.1. getVariables重载方法说明

|---------------------------------------------------------------------------------------|-------------------------------------------|---------------|---------------|
| 方法签名 | 参数说明 | 作用域 | 典型使用场景 |
| Map<String, Object> getVariables(String taskId) | taskId：任务ID | 任务作用域 + 执行作用域 | 需要获取任务所有关联变量时 |
| Map<String, Object> getVariables(String taskId, Collection<String> variableNames) | taskId：任务ID variableNames：指定变量名集合 | 仅任务作用域 | 只需要获取特定变量时 |

4.1.2.1.2. getVariablesLocal重载方法说明

|--------------------------------------------------------------------------------------------|---------------------------------------------|------------------------------|-----------------------------|
| 方法签名 | 参数说明 | 作用域 | 典型使用场景 |
| Map<String, Object> getVariablesLocal(String taskId) | taskId ：任务ID | 仅搜索当前任务作用域（Task Local Scope） | 1. 需要获取任务所有本地变量 2. 需要完整变量快照 |
| Map<String, Object> getVariablesLocal(String taskId, Collection<String> variableNames) | taskId ：任务ID variableNames ：指定变量名集合 | 仅搜索当前任务作用域（Task Local Scope） | 1. 只需要获取特定变量集合 2. 需要优化查询性能 |

4.1.2.2. 使用TaskRuntime

//返回一个List<VariableInstance>，包含匹配查询条件的所有变量实例
taskRuntime.variables(new GetTaskVariablesPayload(taskId));

4.2. 从任务中获取指定变量

4.2.1. 特点

按变量名获取特定变量，支持指定是否从父作用域获取。

4.2.2. 示例

taskService.getVariable(taskId,"name");
// 或
taskService.getVariableLocal(taskId,"name");

4.2.2.1. getVariable重载方法：

|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|-----------------------------------------------------|-------------------------------------------------------|
| 方法签名 | 参数说明 | 作用域 | 典型使用场景 |
| Object getVariable(String taskId, String variableName) | taskId：要查询的任务ID variableName：变量名称 | 先搜索任务作用域（Task Scope） 若未找到，再搜索执行作用域（Execution Scope） | 获取变量但不确定其类型 需要动态处理变量值（如JSON解析） 兼容旧代码或弱类型场景 |
| <T> T getVariable(String taskId, String variableName, Class<T> variableClass) | taskId：要查询的任务ID variableName：变量名称 variableClass：目标类型（如 String.class、Integer.class） | 先搜索任务作用域（Task Scope） 若未找到，再搜索执行作用域（Execution Scope） | 需要类型安全的变量访问 直接获取特定类型的变量（如 Integer、Boolean） 减少手动类型转换代码 |

4.2.2.2. getVariableLocal重载方法

|----------------------------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------|-----------------------------------------------|
| 方法签名 | 参数说明 | 作用域 | 典型使用场景 |
| Object getVariableLocal(String taskId, String variableName) | taskId ：任务ID variableName ：变量名 | 仅搜索当前任务作用域（Task Local Scope） | 1. 仅需检查任务本地变量 2. 不确定变量类型时 3. 动态类型处理场景 |
| <T> T getVariableLocal(String taskId, String variableName, Class<T> variableClass) | taskId ：任务ID variableName ：变量名 variableClass ：目标类型类对象 | 仅搜索当前任务作用域（Task Local Scope） | 1. 需要类型安全的变量访问 2. 直接获取特定类型的任务本地变量 3. 避免手动类型转换 |

4.3. 添加/更新任务变量

4.3.1. 特点：

支持多种Java类型，自动序列化存储。

4.3.2. 示例

4.3.2.1. 使用TaskService

taskService.setVariable(taskId, "newVar", "value");
// 或
taskService.setVariableLocal(taskId, "localVar", 100);
// 或
 taskService.setVariables(taskId, new HashMap<String, Object>() {{
            put("key1", "value");
            put("key2", 123);
        }});
// 或
taskService.setVariablesLocal(taskId, new HashMap<String, Object>() {{
            put("key1", "value");
            put("key2", 123);
        }});

|------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------|-------------|--------------------------|
| 方法签名 | 参数说明 | 作用域规则 | 变量存在性处理 | 典型使用场景 |
| void setVariable(String taskId, String variableName, Object value) | taskId : 任务ID variableName : 变量名 value : 变量值 | 优先在现有作用域设置 不存在时在最外层作用域(如流程实例)创建 | 更新现有变量或新建变量 | 1. 需要自动处理变量作用域 2. 单个变量设置 |
| void setVariables(String taskId, Map<String, ? extends Object> variables) | taskId : 任务ID variables : 变量键值对集合 | 同setVariable规则，批量处理 | 批量更新/创建变量 | 1. 需要设置多个变量 2. 批量操作场景 |
| void setVariableLocal(String taskId, String variableName, Object value) | taskId : 任务ID variableName : 变量名 value : 变量值 | 严格在任务本地作用域操作 | 只操作任务本地变量 | 1. 明确需要任务局部变量 2. 隔离变量作用域 |
| void setVariablesLocal(String taskId, Map<String, ? extends Object> variables) | taskId : 任务ID variables : 变量键值对集合 | 严格在任务本地作用域批量操作 | 批量操作任务本地变量 | 1. 批量设置任务局部变量 2. 需要作用域隔离 |

4.3.2.2. 使用TaskRuntime

// 新增任务变量
taskRuntime.createVariable(new CreateTaskVariablePayload(taskId, "newVar", "value"));
// 更新任务变量
taskRuntime.updateVariable(new UpdateTaskVariablePayload(taskId, "newVar", "value"));

4.4. 删除任务变量

4.4.1. 特点：

删除所有（指定）变量，支持局部变量删除。

4.4.2. 示例

taskService.removeVariable(taskId, "existVar");
// 或
taskService.removeVariables(taskId,Arrays.asList("comment;linkTest".split(";")));
// 或
taskService.removeVariableLocal(taskId,"existVar");
// 或
taskService.removeVariablesLocal(taskId,Arrays.asList("comment;linkTest".split(";")));

5. 身份链接（IdentityLink）管理

5.1. 获取任务的所有身份链接

5.1.1. 特点

返回任务的所有用户/组关联关系。

5.1.2. 示例

5.1.2.1. 使用TaskService

taskService.getIdentityLinksForTask(taskId);

5.1.2.2. 使用TaskRuntime

taskRuntime.userCandidates(taskId);
taskRuntime.groupCandidates(taskId);

|-------------------------------------------------|------------------|---------------------------------------------------|-------------------------------------------|
| 方法签名 | 参数说明 | 返回值说明 | 典型使用场景 |
| List<String> userCandidates(String taskId) | taskId ：任务ID | 返回该任务的所有候选用户ID列表 （格式如：["user1", "user2"] ） | 1. 查询可处理任务的用户列表 2. 任务分配前的权限检查 3. 生成用户选择界面 |
| List<String> groupCandidates(String taskId) | taskId ：任务ID | 返回该任务的所有候选用户组ID列表 （格式如：["group1", "group2"] ） | 1. 查询可处理任务的用户组 2. 基于组的任务分配 3. 批量权限管理 |

5.2. 在任务上创建身份链接

5.2.1. 特点

建立任务与用户/组的关联

5.2.2. 示例

5.2.2.1. 使用TaskService

taskService.addCandidateUser(taskId,"userId");
// 或
taskService.addCandidateGroup(taskId,"userGroup");
// 或
taskService.addUserIdentityLink(taskId,"userId", IdentityLinkType.ASSIGNEE);
// 或
taskService.addGroupIdentityLink(taskId,"userGroup",IdentityLinkType.PARTICIPANT);

5.2.2.1.1. 身份链接方法说明

|---------------------------------------------------------------------------------------|-----------------------------------------------------------------|--------------|---------------|
| 方法签名 | 参数说明 | 作用 | 典型用例 |
| void addCandidateUser(String taskId, String userId) | taskId : 任务ID userId : 用户ID | 添加用户作为任务候选人 | 将用户加入可领取任务列表 |
| void addCandidateGroup(String taskId, String groupId) | taskId : 任务ID groupId : 组ID | 添加用户组作为任务候选组 | 让整个组的成员都能处理任务 |
| void addUserIdentityLink(String taskId, String userId, String identityLinkType) | taskId : 任务ID userId : 用户ID identityLinkType : 链接类型 | 自定义用户任务关系 | 设置任务负责人/参与者 |
| void addGroupIdentityLink(String taskId, String groupId, String identityLinkType) | taskId : 任务ID groupId : 组ID identityLinkType : 链接类型 | 自定义组任务关系 | 设置部门/业务单元关联 |

5.2.2.1.2. 身份链接类型说明

|-----------------|--------|-----------------|--------------------------------------------------------|
| 常量 | 类型 | 用途说明 | 适用方法示例 |
| ASSIGNEE | 用户 | 标记任务受托人（直接责任人） | addUserIdentityLink(taskId, "user1", ASSIGNEE) |
| CANDIDATE | 用户/组 | 标记候选用户或组（可领取任务） | addCandidateUser(taskId, "user2") |
| OWNER | 用户 | 标记任务所有者（管理权限） | addUserIdentityLink(taskId, "user3", OWNER) |
| PARTICIPANT | 用户/组 | 标记任务参与者（协作权限） | addGroupIdentityLink(taskId, "dept1", PARTICIPANT) |
| STARTER | 用户 | 系统自动标记流程发起人 | 通常由引擎自动设置 |

5.2.2.2. 使用TaskRuntime

taskRuntime.addCandidateGroups(new CandidateGroupsPayload(taskId, Collections.singletonList("userGroup")));
taskRuntime.addCandidateUsers(new CandidateUsersPayload(taskId, Collections.singletonList("userId")));

5.3. 删除任务上的身份链接

5.3.1. 特点

移除特定的身份关联

5.3.2. 示例

5.3.2.1. 使用TaskService

taskService.deleteCandidateUser(taskId,"userId");
taskService.deleteCandidateGroup(taskId,"userGroup");
taskService.deleteUserIdentityLink(taskId,"userId", IdentityLinkType.ASSIGNEE);
taskService.deleteGroupIdentityLink(taskId,"userGroup",IdentityLinkType.PARTICIPANT);

5.3.2.2. 使用TaskRuntime

taskRuntime.deleteCandidateGroups(new CandidateGroupsPayload(taskId, Collections.singletonList("userGroup")));
taskRuntime.deleteCandidateUsers(new CandidateUsersPayload(taskId, Collections.singletonList("userId")));

6. 评论（Comment）管理

6.1. 为任务创建新评论

6.1.1. 特点

为任务添加文字评论，记录处理意见。

6.1.2. 示例

taskService.addComment(taskId,processInstanceId,"审批通过");
taskService.addComment(taskId,processInstanceId,"APPROVAL","审批通过");

|------------------------------------------------------------------|-------------------------------------------------------------------------|--------------------------------------------------------|----------------------------|-------------------------------|-----------------------|
| 方法签名 | 参数说明 | 必填参数 | 默认值/自动处理 | 返回对象 | 典型使用场景 |
| Comment addComment(taskId, processInstanceId, message) | taskId : 关联任务ID processInstanceId : 关联流程实例ID message : 评论内容 | message 必填 taskId 和processInstanceId 至少填一个 | type 默认为 "comment" | Comment 对象（包含ID、时间、作者等信息） | 添加普通文本评论 |
| Comment addComment(taskId, processInstanceId, type, message) | type : 评论类型（自定义分类） 其他参数同上 | 所有参数必填 | 无自动处理 | Comment 对象 | 添加带分类的评论（如审批意见、系统日志等） |

6.2. 查询任务评论

6.2.1. 特点

根据相关参数获取全部（特定）评论。

6.2.2. 示例

// 获取单个评论详情
Comment comment = taskService.getComment("comment001");
if (comment != null) {
    System.out.println(comment.getMessage());
}

// 获取任务全部评论
List<Comment> taskComments = taskService.getTaskComments("task123");
taskComments.forEach(c -> System.out.println(c.getUserId() + ": " + c.getMessage()));

// 获取任务的审批意见（自定义类型）
List<Comment> approvals = taskService.getTaskComments("task456", "APPROVAL");

// 获取全系统错误日志
List<Comment> errorLogs = taskService.getCommentsByType("SYSTEM_ERROR");

// 统计流程的人工评论数量
long humanComments = taskService.getProcessInstanceComments("proc789")
    .stream()
    .filter(c -> !c.getType().startsWith("SYSTEM_"))
    .count();

// 提取流程的系统自动评论
List<String> systemMessages = taskService.getProcessInstanceComments("proc101", "SYSTEM")
    .stream()
    .map(Comment::getMessage)
    .collect(Collectors.toList());

|-----------------------------------------------------------------------|----------------------------------------------|------------------|-------------|----------------------------|
| 方法签名 | 参数说明 | 返回值 | 查询范围 | 典型应用场景 |
| Comment getComment(commentId) | commentId ：评论唯一ID | 单个Comment 对象 | 全局查询 | 1. 精确获取特定评论 2. 评论详情展示 |
| List<Comment> getTaskComments(taskId) | taskId ：任务ID | 该任务所有评论列表 | 任务关联评论 | 1. 查看任务全部讨论记录 2. 任务历史追溯 |
| List<Comment> getTaskComments(taskId, type) | taskId ：任务ID type ：评论类型 | 该任务指定类型的评论列表 | 任务关联评论+类型过滤 | 1. 筛选任务审批意见 2. 分离系统日志与人工评论 |
| List<Comment> getCommentsByType(type) | type ：评论类型 | 全系统该类型评论列表 | 全局类型过滤 | 1. 统计所有审批记录 2. 系统日志审计 |
| List<Comment> getProcessInstanceComments(processInstanceId) | processInstanceId ：流程实例ID | 该流程所有评论列表 | 流程关联评论 | 1. 流程全局讨论记录 2. 流程运行监控 |
| List<Comment> getProcessInstanceComments(processInstanceId, type) | processInstanceId ：流程实例ID type ：评论类型 | 该流程指定类型的评论列表 | 流程关联评论+类型过滤 | 1. 提取流程审批意见 2. 过滤流程系统消息 |

6.3. 删除任务的评论

6.3.1. 特点

删除已添加的相关评论

6.3.2. 示例

// 删除单条评论
taskService.deleteComment(commentId);

// 删除特定任务的所有评论
taskService.deleteComments(taskId, null);

// 删除特定流程实例的所有评论
taskService.deleteComments(null, processInstanceId);

// 删除同时关联任务和流程实例的评论
taskService.deleteComments(taskId, processInstanceId);

|----------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------|--------------------------|
| 方法签名 | 参数说明 | 删除范围 | 异常处理 | 典型应用场景 |
| void deleteComments(taskId, processInstanceId) | taskId ：关联任务ID processInstanceId ：关联流程实例ID | 批量删除： - 仅任务评论（processInstanceId=null） - 仅流程评论（taskId=null） - 两者交集评论（均非null） | 参数全null时抛ActivitiIllegalArgumentException | 1. 任务/流程数据清理 2. 敏感信息批量移除 |
| void deleteComment(commentId) | commentId ：评论唯一ID | 精确删除单条评论 | 评论不存在时抛ActivitiObjectNotFoundException | 1. 特定评论撤回 2. 违规内容删除 |

7. 附件（Attachment）管理

7.1. 在任务上创建新附件(文件)

7.1.1. 特点：

上传文件作为任务附件

7.1.2. 示例

// 通过输入流上传文件
try (InputStream fileStream = new FileInputStream("report.pdf")) {
    Attachment attachment = taskService.createAttachment(
        "DOCUMENT",
        "taskId",
        null,
        "季度报告.pdf",
        "2023年Q4销售数据",
        fileStream
    );
}

// 通过URL添加附件
Attachment urlAttachment = taskService.createAttachment(
    "LINK",
    null,
    "processInstanceId",
    "产品官网",
    "官方网站参考链接",
    "https://product.com"
);

7.2. 获取任务的附件

7.2.1. 特点

返回任务的所有（部分）附件列表

7.2.2. 示例

// 获取任务附件列表
List<Attachment> taskFiles = taskService.getTaskAttachments("taskId");
taskFiles.forEach(att -> {
    System.out.println(att.getName());
    
    // 下载内容
    try (InputStream is = taskService.getAttachmentContent(att.getId())) {
        Files.copy(is, Paths.get("/downloads/" + att.getName()));
    }
});

7.3. 更新附件信息

7.3.1. 特点：

更新执行附件文件信息

7.3.2. 示例

// 更新附件描述
Attachment att = taskService.getAttachment("att456");
att.setDescription("更新版合同");
taskService.saveAttachment(att);

7.4. 删除附件信息

7.4.1. 特点

删除指定附件。

7.4.2. 示例

// 删除附件
taskService.deleteAttachment("att789");

7.5. 附件相关方法说明

|----------|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|---------------------------------|------------|
| 方法类别 | 方法签名 | 参数说明 | 返回值/行为 | 典型应用场景 |
| 创建附件 | createAttachment(type, taskId, processInstanceId, name, description, content) | type ：附件类型 taskId /processInstanceId ：至少一个非null name ：文件名 description ：描述 content ：输入流 | 返回新创建的Attachment 对象 | 上传本地文件作为附件 |
| 创建附件 | createAttachment(type, taskId, processInstanceId, name, description, url) | url ：外部资源地址 | 返回新创建的Attachment 对象 | 链接外部资源作为附件 |
| 更新附件 | saveAttachment(attachment) | attachment ：需更新的附件对象（需设置id） | 无返回值 | 修改附件名称或描述 |
| 查询附件 | getAttachment(attachmentId) | attachmentId ：附件唯一ID | 返回Attachment 对象（不存在时返回null） | 获取附件元数据 |
| 查询附件 | getAttachmentContent(attachmentId) | attachmentId ：附件唯一ID | 返回InputStream （需手动关闭） | 下载附件内容 |
| 查询附件 | getTaskAttachments(taskId) | taskId ：任务ID | 返回附件列表（可能为空） | 查看任务所有附件 |
| 查询附件 | getProcessInstanceAttachments(processInstanceId) | processInstanceId ：流程实例ID | 返回附件列表（可能为空） | 查看流程所有附件 |
| 删除附件 | deleteAttachment(attachmentId) | attachmentId ：附件唯一ID | 无返回值 | 移除无效附件 |