开发指南
工作流手册

选择审批人、发起人自选

# 1. 审批人配置

在 BPMN 流程设计器中，每个任务节点，有个 [任务（审批人）] 配置项，用于配置任务审批时，审批人的分配。如下图所示：

流程设计器的审批人配置.png

在 BPMN 的 UserTask 节点上，没有合适的内置属性存储“规则类型”、“规则参数”的属性，所以是我们拓展了 candidateStrategy 和 candidateParam 属性，用于存储审批人的规则类型和参数。如下图所示：

流程设计器的审批人配置的属性.png

拓展知识：BPMN 的 UserTask 节点，是如何拓展 `candidateStrategy` 和 `candidateParam` 属性的呢？

参见 feadd02 (opens new window)、797fddf (opens new window) 提交的代码。

# 2. 选择审批人

在上图中，我们可以看到多种审批人规则类型，它们都是 BpmTaskCandidateStrategy (opens new window) 的一种实现，如下图所示：

BpmTaskCandidateStrategy 类图

public interface BpmTaskCandidateStrategy {

    /**
     * 对应策略
     *
     * @return 策略
     */
    BpmTaskCandidateStrategyEnum getStrategy();

    /**
     * 校验参数
     *
     * @param param 参数
     */
    void validateParam(String param);

    /**
     * 基于执行任务，获得任务的候选用户们
     *
     * @param param 节点参数
     * @return 用户编号集合
     */
    default Set<Long> calculateUsers(String param) {
        throw new UnsupportedOperationException("该分配方法未实现，请检查！");
    }

    /**
     * 是否一定要输入参数
     *
     * @return 是否
     */
    default boolean isParamRequired() {
        return true;
    }

}

只依赖节点参数的策略可以实现 calculateUsers(String param)。依赖流程上下文的策略分别实现运行时和预测方法，见下文。

最终，Flowable 在创建审批任务，分配审批人时，会通过 BpmUserTaskActivityBehavior (opens new window) => BpmTaskCandidateInvoker (opens new window) => BpmTaskCandidateStrategy (opens new window)，时序图如下：

审批人分配的时序图

# 3. 自定义审批人策略

现有规则无法表达业务分配方式时，可以实现自己的 BpmTaskCandidateStrategy。如果只想按表单中的用户字段分配，先看设计器已有的「表单内用户字段」。如果规则能直接写成表达式，参考《流程表达式》。

# 3.1 注册策略

在 BpmTaskCandidateStrategyEnum (opens new window) 新增一个未使用的编号。例如 CUSTOM_USER_IDS(99, "自定义审批人列表")。编号会保存在已发布的模型中，部署后保持稳定。
实现 BpmTaskCandidateStrategy (opens new window)，用 @Component 注册在 BPM 模块可扫描的包下。启动时 BpmFlowableConfiguration 会收集策略 Bean，按策略编号分发。
在 bpm_task_candidate_strategy 字典添加相同编号和显示名。设计器的候选项和参数编辑另有前端配置，按下文接入。

# 3.2 实现示例

示例使用逗号分隔的用户编号演示参数校验和候选人计算。上线时可替换为自己的业务规则。

import cn.iocoder.yudao.module.bpm.framework.flowable.core.candidate.BpmTaskCandidateStrategy;
import cn.iocoder.yudao.module.bpm.framework.flowable.core.enums.BpmTaskCandidateStrategyEnum;
import org.springframework.stereotype.Component;
import org.springframework.util.Assert;

import java.util.LinkedHashSet;
import java.util.Set;

/** @author 芋道源码 */
@Component
public class CustomUserIdsStrategy implements BpmTaskCandidateStrategy {

    @Override
    public BpmTaskCandidateStrategyEnum getStrategy() {
        return BpmTaskCandidateStrategyEnum.CUSTOM_USER_IDS;
    }

    @Override
    public void validateParam(String param) {
        calculateUsers(param);
    }

    @Override
    public Set<Long> calculateUsers(String param) {
        Assert.hasText(param, "请配置审批人编号");
        Set<Long> userIds = new LinkedHashSet<>();
        for (String item : param.split(",", -1)) {
            long userId;
            try {
                userId = Long.parseLong(item.trim());
            } catch (NumberFormatException ex) {
                throw new IllegalArgumentException("审批人编号必须为正整数", ex);
            }
            Assert.isTrue(userId > 0, "审批人编号必须为正整数");
            userIds.add(userId);
        }
        return userIds;
    }
}

方法	调用场景
`validateParam`	发布流程时校验节点参数。无参数策略可覆写 `isParamRequired()` 返回 `false`。
`calculateUsers(String param)`	只依赖参数时实现此方法。运行时分配和未执行节点预测的默认实现都会调用它。
`calculateUsersByTask`、`calculateUsersByActivity`	依赖上下文时分别实现。运行时有真实的 `DelegateExecution`，预测时可用发起人编号、流程定义编号和已有流程变量。

候选人为空时，流程会继续按节点的「审批人为空时」配置处理。测试时请选择同一租户内启用的用户，并按节点的会签、或签或依次审批设置核对实际分配。

# 3.3 接入设计器并验证

简易设计器在 SimpleProcessDesignerV2/src/consts.ts 补充 CandidateStrategy 和 CANDIDATE_STRATEGY。在审批节点配置和 node.ts 补参数输入、校验、保存、回显和节点摘要。
BPMN 设计器在审批任务的 UserTask.vue 补参数输入和回显。保存后核对 XML 中 candidateStrategy 和 candidateParam 扩展元素。各前端应用的目录名可能不同。
保存、重新打开并发布模型。先在发起页预览候选人，再提交一笔流程核对实际待办。再用空串、非法编号和审批人为空的场景验证校验及回退。