业务系统交互接口

1. 交互概览

以下是业务系统与规则引擎交互的流程概览。

1.1 规则绑定与审批流程 (交互流程)

Mermaid Diagram Code:

sequenceDiagram
    participant User as 运营人员
    participant Biz as 业务系统
    participant Rule as 规则引擎
    participant DB as 数据库
    participant BPM as 审批中心
    participant MQ as Kafka消息

    Note over User, MQ: 阶段一：业务绑定与提交审批
    User->>Biz: 在业务后台配置规则并提交
    Biz->>Rule: RPC调用 bindOrUnbindRule()
    Rule->>DB: 记录绑定关系 (valid=未生效/待审批)
    Rule-->>Biz: 返回成功
    
    Biz->>Rule: RPC调用 getApprovalChangeInfo()
    Rule-->>Biz: 返回变更摘要(新增/删除多少MAC等)
    
    Biz->>BPM: 发起审批流程 (携带规则业务信息变量)
    
    Note over User, MQ: 阶段二：审批通过与生效
    BPM->>BPM: 审批流转...
    BPM->>MQ: 发送流程状态变更事件 (status=APPROVE)
    MQ->>Rule: 消费 BpmProcessInstanceStatusEvent
    Rule->>DB: 更新规则/绑定状态 (valid=已生效)
    Rule->>Rule: 刷新 Redis 缓存
    Note right of Rule: 此时规则正式对机顶盒生效

1.2 规则变更反向通知流程 (交互流程)

Mermaid Diagram Code:

sequenceDiagram
    participant Admin as 管理员
    participant Rule as 规则引擎
    participant MQ as Kafka消息
    participant Biz as 业务系统

    Admin->>Rule: 在规则平台修改/删除规则
    Rule->>Rule: 检测到规则被引用
    Rule->>MQ: 发送 rule-bpm-no-start-event
    MQ->>Biz: 消费通知 (RuleBpmNoStartEventListener)
    Biz->>Biz: 将对应业务单据置为"草稿"或"待处理"
    Note right of Biz: 提示用户规则已变动，需重新确认或审批

2. 前端集成指南 (Vue3)

为了方便业务系统快速集成规则引擎，我们在 yudao-ui-admin-vue3 中封装了通用的规则配置组件 RuleBusinessTabs。

2.1 组件介绍

RuleBusinessTabs 是一个集成了规则绑定、解绑、查看以及规则详情配置（MAC、渠道、地区）的综合组件。业务系统只需将其引入到页面下方，即可赋予该业务对象（如一条广告、一个黑名单配置）强大的规则调度能力。

2.2 使用方式

1. 引入组件

import RuleBusinessTabs from '@/components/RuleBusiness/RuleBusinessTabs.vue'
import { BusinessTypeEnum } from '@/utils/enums/BusinessTypeEnum'

2. 在模板中使用

通常放置在业务列表页面的底部，配合表格的 current-change 事件使用，当用户选中某一行业务数据时，展示对应的规则配置。

<template>
  <!-- 业务列表 -->
  <el-table 
    highlight-current-row 
    @current-change="handleCurrentChange"
    ...
  >
    <!-- ... -->
  </el-table>

  <!-- 规则配置组件 -->
  <ContentWrap>
    <RuleBusinessTabs
      :business-type="BusinessTypeEnum.BLACKLIST" 
      :business-id="currentRow?.id"
      :type="false" 
      @refresh-list="getList"
    />
  </ContentWrap>
</template>

3. 参数说明 (Props)

参数名	类型	必填	说明
business-type	`Number`	是	业务类型枚举值（参考 `BusinessTypeEnum`）
business-id	`Number`	是	当前选中的业务记录ID
type	`Boolean`	否	布局模式（true: 详情页模式, false: 列表页Tab模式）。默认为 false

2.3 界面效果

集成后，业务人员可以在该组件中：

绑定规则：选择已有的通用规则绑定到当前业务。
新建规则：直接创建一个新规则并自动绑定。
管理关联：在不跳转页面的情况下，直接为绑定的规则追加 MAC、渠道或地区限制。

3. 后端集成 - RPC 接口 (业务发起)

3.1 基础说明

3.1.1 接口概述

业务系统通过 FeignClient 调用规则引擎提供的 RuleBusinessApi 接口，实现规则的绑定/解绑、查询等功能。

FeignClient 名称: rule-server
接口前缀: /rpc-api/rule/rule-business。
如果是前端直接对接规则引擎，不通过业务rpc调用，请把/rpc-api/rule/rule-business改为/admin-api/rule/rule-business

3.1.2 接口对接步骤

添加依赖: 在业务系统的 pom.xml 中添加规则引擎 API 依赖

<dependency>
    <groupId>cn.iocoder.cloud</groupId>
    <artifactId>yudao-module-rule-api</artifactId>
    <version>${revision}</version>
</dependency>

注入 FeignClient: 在业务代码中注入 RuleBusinessApi

@Resource
private RuleBusinessApi ruleBusinessApi;

调用接口: 按照上述示例调用相应的接口方法

3.1.3 注意事项

分区查询: MAC列表查询时，系统会自动根据规则ID和MAC资源ID计算分区索引，避免全表扫描，提高查询性能。
去重规则:
- 渠道列表和地区列表会自动去重，同一ID只返回一条记录
- MAC列表不去重，会返回所有匹配的记录
数据来源: MAC列表包含两种数据来源：
- sourceType=1: 规则直接关联的MAC
- sourceType=2: 规则通过MAC资源间接关联的MAC
错误处理: 所有接口调用失败时会抛出 ServiceException，业务系统需要做好异常处理。

3.2 非审批场景接口

3.2.1 绑定或解绑规则

接口说明: 业务系统绑定或解绑规则，最终调用 RuleLiteflowChainService.createBusiness 和 deleteBusiness 方法。

接口地址: POST /rpc-api/rule/rule-business/bind-or-unbind

请求参数 (RuleBindReqDTO):

参数名	类型	必填	说明
businessType	Integer	是	业务类型(0-任务推送，1-launcher广告配置，2-黑名单，3-uota升级，4-域名分发)
businessId	Long	是	业务ID
liteflowChainId	Long	是	规则ID
operateType	Integer	是	操作类型(1-绑定，2-解绑)

返回结果:

{
  "code": 0,
  "data": true,
  "msg": "success"
}

调用示例 (Java):

@Resource
private RuleBusinessApi ruleBusinessApi;

public void bindRule(Long businessId, Long ruleId) {
    RuleBindReqDTO reqDTO = new RuleBindReqDTO();
    reqDTO.setBusinessType(1); // launcher广告配置
    reqDTO.setBusinessId(businessId);
    reqDTO.setLiteflowChainId(ruleId);
    reqDTO.setOperateType(1); // 绑定
    CommonResult<Boolean> result = ruleBusinessApi.bindOrUnbindRule(reqDTO);
}

3.2.2 查询规则列表

接口说明: 业务系统查询规则列表(不分页)。规则引擎根据业务类型和业务ID先查询出所有绑定的规则ID集合，然后再查询规则详情。

接口地址: GET /rpc-api/rule/rule-business/list-rules

请求参数:

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID

返回结果 (RuleListRespDTO[]):

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "测试规则",
      "chainName": "test_rule",
      "scope": 1,
      "elData": "THEN(node1, node2)",
      "jsonData": "{}",
      "businessType": 1,
      "remark": "备注",
      "route": null,
      "enable": 1,
      "hasMac": 1,
      "ruleValid": 1, 
      "bindValid": 1 
    }
  ],
  "msg": "success"
}

字段说明:

id: 规则ID
name: 规则名称(别名)
chainName: 规则名称(只能是英文)
scope: 使用范围：0-通用规则 1-特定业务类型多条业务 2-不限业务类型的单条业务 3-特定业务类型的单条业务
elData: EL表达式的字段(只存EL)
jsonData: el对应json数据
businessType: 业务类型
remark: 备注
route: 决策路由
enable: 是否生效(1为生效，0为不生效)
hasMac: 是否挂有mac(0-无mac，1-有mac)
ruleValid: 规则生效状态(0-未生效，1-已生效，2-已生效且做修改标记，3-已生效且做移除标记)
bindValid: 绑定关系生效状态(0-未生效，1-已生效，2-已生效且做修改标记，3-已生效且做移除标记)

调用示例 (Java):

public List<RuleListRespDTO> getRules(Long businessId) {
    CommonResult<List<RuleListRespDTO>> result =
            ruleBusinessApi.listRules(1, businessId);
    return result.getData();
}

3.2.3 查询MAC列表

接口说明: 业务系统查询MAC列表(分页、不排序、不去重)。规则引擎根据业务类型和业务ID先查询出所有绑定的规则ID集合，再根据规则ID集合查询所有规则关联的MAC资源，最后用联合查询同时查询 rule_mac_resource_item 和 rule_mac_item 合并结果，使用 partition_index 避免全表扫描。

接口地址: POST /rpc-api/rule/rule-business/list-macs

请求参数 (MacListReqDTO):

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID
mac	String	否	MAC地址(支持最左匹配模糊查询)
valid	int	否	数据有效性
pageNo	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认10

返回结果 (PageResult<MacListRespDTO>):

{
  "code": 0,
  "data": {
    "list": [
      {
        "mac": "00:11:22:33:44:55",
        "liteflowChainId": 1,
        "name": "测试规则",
        "chainName": "test_rule",
        "enable": 1,
        "valid": 1,
        "sourceType": 1,
        "ruleMacItemId": 100,
        "macResourceItemId": null,
        "macResourceId": null,
        "macResourceName": null
      },
      {
        "mac": "AA:BB:CC:DD:EE:FF",
        "liteflowChainId": 1,
        "name": "测试规则",
        "chainName": "test_rule",
        "enable": 1,
        "valid": 1,
        "sourceType": 2,
        "ruleMacItemId": null,
        "macResourceItemId": 50,
        "macResourceId": 100,
        "macResourceName": "测试MAC资源"
      }
    ],
    "total": 2
  },
  "msg": "success"
}

字段说明:

liteflowChainId: 规则ID
name: 规则名称(别名)
chainName: 规则名称(只能是英文)
enable: 是否生效(1为生效，0为不生效)
valid: 是否有效
channelId: 渠道ID
sourceType: 数据来源，1-规则直接关联MAC，2-规则关联MAC资源
ruleMacItemId: 规则关联MAC项ID(仅sourceType=1时有值)
macResourceItemId: MAC资源关联项ID(仅sourceType=2时有值)
macResourceId: MAC资源ID(仅sourceType=2时有值)
macResourceName: MAC资源名称(仅sourceType=2时有值)

调用示例 (Java):

public PageResult<MacListRespDTO> getMacs(Long businessId, String mac, Integer pageNo) {
    MacListReqDTO reqDTO = new MacListReqDTO();
    reqDTO.setBusinessType(1);
    reqDTO.setBusinessId(businessId);
    reqDTO.setMac(mac);
    reqDTO.setPageNo(pageNo);
    reqDTO.setPageSize(20);
    CommonResult<PageResult<MacListRespDTO>> result = 
        ruleBusinessApi.listMacs(reqDTO);
    return result.getData();
}

3.2.4 查询所有渠道列表

接口说明: 业务系统查询所有渠道列表(不分页、去重)。规则引擎根据业务类型和业务ID先查询出所有绑定的规则ID集合，再根据规则ID集合查询 rule_channel_item。

接口地址: GET /rpc-api/rule/rule-business/list-channels

请求参数:

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID
valid	int	否	数据有效性

返回结果 (ChannelListRespDTO[]):

{
  "code": 0,
  "data": [
    {
      "ruleChannelItemId": 10,
      "liteflowChainId": 1,
      "name": "测试规则",
      "chainName": "test_rule",
      "enable": 1,
      "channelId": 1,
      "valid": 1
    },
    {
      "ruleChannelItemId": 11,
      "liteflowChainId": 1,
      "name": "测试规则",
      "chainName": "test_rule",
      "enable": 1,
      "channelId": 2,
      "valid": 1
    }
  ],
  "msg": "success"
}

字段说明:

ruleChannelItemId: 规则关联渠道项ID
liteflowChainId: 规则ID
name: 规则名称(别名)
chainName: 规则名称(只能是英文)
enable: 是否生效(1为生效，0为不生效)
channelId: 渠道ID
valid: 是否有效

调用示例 (Java):

public List<ChannelListRespDTO> getChannels(Long businessId) {
    CommonResult<List<ChannelListRespDTO>> result = 
        ruleBusinessApi.listChannels(1, businessId);
    return result.getData();
}

3.2.5 查询所有地区列表

接口说明: 业务系统查询所有地区列表(不分页、去重)。规则引擎根据业务类型和业务ID先查询出所有绑定的规则ID集合，再根据规则ID集合查询 rule_region_item。

接口地址: GET /rpc-api/rule/rule-business/list-regions

请求参数:

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID
valid	int	否	数据有效性

返回结果 (RegionListRespDTO[]):

{
  "code": 0,
  "data": [
    {
      "ruleRegionItemId": 20,
      "liteflowChainId": 1,
      "name": "测试规则",
      "chainName": "test_rule",
      "enable": 1,
      "regionId": 1,
      "valid": 1
    },
    {
      "ruleRegionItemId": 21,
      "liteflowChainId": 1,
      "name": "测试规则",
      "chainName": "test_rule",
      "enable": 1,
      "regionId": 2,
      "valid": 1
    }
  ],
  "msg": "success"
}

字段说明:

ruleRegionItemId: 规则关联地区项ID
liteflowChainId: 规则ID
name: 规则名称(别名)
chainName: 规则名称(只能是英文)
enable: 是否生效(1为生效，0为不生效)
regionId: 地区ID
valid: 是否有效

调用示例 (Java):

public List<RegionListRespDTO> getRegions(Long businessId) {
    CommonResult<List<RegionListRespDTO>> result = 
        ruleBusinessApi.listRegions(1, businessId);
    return result.getData();
}

3.2.6 更新业务数量限制(后端执行)

接口说明: 业务系统通过调用规则引擎提供的工具类 RuleUtil 推送业务数量限制变更。该操作用于同步业务侧的限制配置（如任务推送上限、黑名单卸载上限等）到规则引擎。底层通过 Kafka 异步消息通知规则引擎。

调用方式: Java工具类调用 RuleUtil.updateBusinessLimit(RuleBusinessLimitDTO)

请求参数 (RuleBusinessLimitDTO):

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID
limitCount	Integer	否	业务数量限制 -1: 无限制 null: 不更新此字段
currentCount	Integer	否	当前已操作数量 null: 不更新有值: 直接覆盖
addCount	Integer	否	本次增加数量当 currentCount 和 addCount 都有值时，以 currentCount 为准

返回结果: 无 (void)

调用示例 (Java):

import cn.iocoder.yudao.module.rule.dto.RuleBusinessLimitDTO;
import cn.iocoder.yudao.module.rule.util.RuleUtil;

// 构建请求对象
RuleBusinessLimitDTO reqDTO = RuleBusinessLimitDTO.builder()
        .businessType(1)        // 业务类型
        .businessId(10086L)     // 业务ID
        .limitCount(100)        // 设置总限制数量
        .currentCount(10)       // 设置当前数量(覆盖)
        // .addCount(1)         // 或者设置增加数量(增量)
        .build();

// 调用工具类推送
RuleUtil.updateBusinessLimit(reqDTO);

3.2.7 删除业务时解绑全部规则（unbindAllRulesNoBpm）

接口说明：业务主表删除后，解除该业务下所有规则绑定关系，释放规则资源。

接口地址：POST /rpc-api/rule/rule-business/unbind-all-rules-no-bpm

后台调用 ：当业务主表被物理删除且不经过审批流程时（例如无需审批的删除），业务系统需要显式调用 RuleBusinessApi.unbindAllRulesNoBpm 释放规则绑定资源。

请求参数：

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID（对应 `rule_business.business_id`）

返回结果：

{
  "code": 0,
  "data": true,
  "msg": "success"
}

3.2.8 获取业务绑定的设备数量

接口说明: 获取指定业务绑定的所有规则覆盖的设备总量。

详细接口定义与交互规范请参考独立文档：07-设备数量统计交互指南

3.3 审批场景接口

3.3.1 规则引擎数据变更模型

业务类型为“需要审批”时，规则中心对规则及其关联数据采用“先落库标记，审批通过后生效”的模式：

有效性标记：使用 valid 字段（对应 BpmBusinessValid）区分“未生效/已生效/修改中/待删除”等状态
审批状态标记：使用 bpm_status 字段（对应 BpmProcessInstanceStatusEnum）记录流程状态（未发起、审批中、通过、驳回、取消等）
生效边界：只有审批通过后，valid 才会被统一推进为已生效（或执行删除），并同步更新 Redis 缓存；审批中/驳回/取消只更新 bpm_status，不继续推进生效逻辑

valid 状态约定（常用）：

状态值	枚举	说明
0	NO	未生效（新增待审批）
1	YES	已生效
2	UPDATE	已生效且有修改标记（待审批）
3	DELETE	已生效且有删除标记（待审批）

3.3.2 业务提交审批（业务系统主动 RPC）

业务系统在“需要审批”的业务类型下，通常会在提交审批前完成两件事：

绑定/解绑规则关系：调用 RuleBusinessApi.bindOrUnbindRule 落库绑定关系（需要审批时会记录为待生效/待删除）
生成审批变更摘要：调用 RuleBusinessApi.getApprovalChangeInfo 获取本次变更概览，用于页面展示/写入审批表单/审批标题等

另外，当业务主表被物理删除且不经过审批流程时（例如无需审批的删除），业务系统需要显式调用 RuleBusinessApi.unbindAllRulesNoBpm 释放规则绑定资源。

3.3.3 获取审批变更信息（getApprovalChangeInfo）

接口说明：业务提交审批前，向规则中心获取“本次变更”的汇总信息（新绑定/解绑/修改及其 MAC/渠道/地区/MAC资源的增删数量）。

接口地址：POST /rpc-api/rule/rule-business/get-approval-change-info

请求参数（RuleApprovalChangeReqDTO）：

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID（对应 `rule_business.business_id`）

返回结果（RuleApprovalChangeRespDTO）：

字段	类型	说明
newBindRules	RuleChangeDetailDTO[]	新绑定的规则列表（绑定关系 `valid=NO`）
unbindRules	RuleUnbindDetailDTO[]	解绑的规则列表（绑定关系 `valid=DELETE`）
noChangeRules	RuleChangeDetailDTO[]	无绑定/解绑操作但规则内部有变更的列表
changeDescription	String	变更描述（服务端根据上述列表生成的摘要文本）

RuleChangeDetailDTO 字段摘要：

字段	类型	说明
ruleId	Long	规则ID
ruleName	String	规则名称
ruleChainName	String	规则别名（chainName）
ruleSelfChange	RuleSelfChangeDTO	规则主表自身是否有变更（新增/修改/删除）
addMacCount / deleteMacCount	Integer	MAC 变更数量（包含规则直接关联 + 通过 MAC资源间接关联）
addChannelCount / deleteChannelCount	Integer	渠道变更数量
addRegionCount / deleteRegionCount	Integer	地区变更数量
addMacResourceCount / deleteMacResourceCount	Integer	MAC资源变更数量

返回示例（节选）：

{
  "code": 0,
  "data": {
    "newBindRules": [],
    "unbindRules": [],
    "noChangeRules": [
      {
        "ruleId": 1,
        "ruleName": "测试规则",
        "ruleChainName": "test_rule",
        "ruleSelfChange": { "hasChange": true, "changeType": "修改" },
        "addMacCount": 10,
        "deleteMacCount": 2,
        "addChannelCount": 1,
        "deleteChannelCount": 0,
        "addRegionCount": 0,
        "deleteRegionCount": 0,
        "addMacResourceCount": 0,
        "deleteMacResourceCount": 0
      }
    ],
    "changeDescription": "【修改规则】1条\n  1. 规则名称：测试规则（规则本身:修改）\n     - MAC变更：新增10个、删除2个\n     - 渠道变更：新增1个"
  },
  "msg": "success"
}

3.3.4 取消业务关联规则的所有待审批变更（cancelPendingChanges）

接口说明：取消该业务下所有规则的“待审批”变更状态（包括新绑定/解绑/修改），将数据回滚到最近一次已生效的状态（或物理删除未生效的新增数据）。

接口地址：PUT /rpc-api/rule/rule-business/cancel-pending-changes

请求参数：

参数名	类型	必填	说明
businessType	Integer	是	业务类型
businessId	Long	是	业务ID（对应 `rule_business.business_id`）

返回结果：

{
  "code": 0,
  "data": true,
  "msg": "success"
}

3.3.5 发起审批时需要设置的流程变量（BPM）

规则中心不会由业务系统“回调”触发审批结果处理，而是通过审批中心的事件消息驱动。为了让审批事件能准确定位到业务与规则关系，业务系统在发起流程时需要设置以下流程变量：

变量名	值类型	说明
PROCESS_INSTANCE_RULE_BUSINESS_INFO	List<BpmProcessInstanceStatusEvent.RuleBusinessInfo>	规则引擎业务信息列表（包含 businessType、businessId、businessUpdateType）
PROCESS_BUSINESS_UPDATE_TYPE	Integer	主表更新原因（兼容主子表删除场景，参考 `BpmBusinessUpdateTypeEnum`）

其中变量名常量取值为：

常量	实际值
PROCESS_INSTANCE_RULE_BUSINESS_INFO	PROCESS_INSTANCE_RULE_BUSINESS_INFO
PROCESS_INSTANCE_VARIABLE_BUSINESS_UPDATE_TYPE	PROCESS_BUSINESS_UPDATE_TYPE

3.4 规则匹配接口

业务系统需要根据设备信息进行规则匹配，获取匹配成功的业务ID集合。规则引擎已封装好工具方法，业务系统直接调用即可。

3.4.1 调用方法

在RuleRunUtil.java中提供了规则匹配工具方法：

 /**
     * 业务系统进行规则匹配
     * 根据业务类型、设备CPU、设备MAC进行规则匹配，返回匹配成功的业务ID集合
     *
     * @param businessType 业务类型
     * @param deviceRespDTO 设备详情
     * @return 匹配成功的业务ID集合
     */
    public static Set<Long> matchBusinessIds(Integer businessType, DeviceRespRuleDTO deviceRespDTO)

3.4.2 使用示例

场景1：任务推送系统

// 获取设备匹配的任务推送ID集合
Set<Long> taskIds = RuleRunUtil.matchBusinessIds(
    0,              // 业务类型：0 = TASK_PUSH
    deviceRespDTO   //设备详情
);

// 根据taskIds获取对应的任务配置
if (!taskIds.isEmpty()) {
    List<TaskConfig> configs = taskService.getTaskConfigByIds(taskIds);
    // 推送任务到设备
}

场景2：Launcher广告配置

// 获取设备匹配的广告位ID集合
Set<Long> adIds = RuleRunUtil.matchBusinessIds(
    1,              // 业务类型：1 = LAUNCHER_PUSH
    deviceRespDTO   //设备详情
);

// 根据adIds获取广告配置
if (!adIds.isEmpty()) {
    List<AdConfig> configs = adService.getAdConfigByIds(adIds);
    // 下发广告配置到设备
}

场景3：黑名单系统

// 获取设备匹配的黑名单配置ID集合
Set<Long> blacklistIds = RuleRunUtil.matchBusinessIds(
    2,              // 业务类型：2 = BLACK_LIST
    deviceRespDTO   //设备详情
);

// 根据blacklistIds获取黑名单配置
if (!blacklistIds.isEmpty()) {
    List<BlacklistConfig> configs = blacklistService.getConfigByIds(blacklistIds);
    // 下发黑名单配置到设备
}

3.4.3 注意事项

参数说明
- businessType：必填，业务类型枚举值
- deviceRespDTO：必填，设备先去
返回值
- 返回匹配成功的业务ID集合
- 未匹配到或异常时返回空集合
- 业务系统根据返回的ID集合查询具体配置
性能说明
- 已实现三级缓存机制（本地缓存 -> Redis -> 数据库）
- 支持高并发调用
- 异常情况不影响业务流程

4. 后端集成 - MQ 消息通知 (事件驱动)

4.1 审批完成（规则中心监听 Kafka 消息）

审批中心会向 Kafka Topic bpm-inst-status（BpmProcessInstanceStatusEvent.TOPIC）发送流程实例状态变更事件。规则中心通过 BpmRuleStatusListener 监听该消息，并按以下规则处理：

事件核心字段（BpmProcessInstanceStatusEvent）：

字段	类型	说明
id	String	流程实例编号
processDefinitionKey	String	流程定义 Key
status	Integer	流程状态（对应 `BpmProcessInstanceStatusEnum`）
businessKey	String	业务标识（不同业务模块定义不同；规则中心以 `ruleBusinessInfos` 为准）
ruleBusinessInfos	RuleBusinessInfo[]	规则引擎业务信息列表（业务类型、业务ID、更新原因）
businessUpdateType	Integer	主表更新原因（兼容主子表删除场景）

其中 ruleBusinessInfos[].businessId 对应 rule_business.business_id，不是规则表主键。

从事件中读取 ruleBusinessInfos，逐条处理其中的 businessType + businessId
若业务更新原因为删除（businessUpdateType=DELETE），则直接在规则中心执行“解绑全部规则”（等价于调用 unbindAllRules），用于释放规则资源
否则，根据事件 status 更新规则的 bpm_status；仅当 status=APPROVE（审批通过）时，才继续推进数据生效/删除逻辑，并更新 Redis 缓存

Redis 缓存更新范围（规则审批通过后）包含但不限于以下 Key：

r:m:r:{mac}（MAC -> 规则）
r:c:r:{channel_id}（渠道 -> 规则）
r:no:limit:r（无设备限制规则集合）
r:btype:r:{business_type}（业务类型 -> 规则）
r:r:btype:b:{rule_id}（规则 -> 业务类型/业务集合）

4.2 规则数据修改MQ通知业务

当规则中心的数据发生变更（新增、修改或删除）且该规则已绑定业务时，规则中心会向 Kafka 发送通知消息。业务系统可监听此消息，以便及时感知规则变更状态（例如将业务状态更新为“待审批”）。

通知场景:

规则被修改，且进入“未发起审批”状态
规则被删除（逻辑删除），且进入“未发起审批”状态

Topic: rule-bpm-no-start-event

交互方式: 业务系统需继承 RuleBpmNoStartEventListener 抽象类并注册为 Spring Bean。

消息体定义 (RuleBpmNoStartEvent):

字段	类型	说明
ruleId	Long	规则ID
businessType	Integer	业务类型
businessId	Long	业务ID

对接示例 (Java):

import cn.iocoder.yudao.module.rule.event.RuleBpmNoStartEventListener;
import cn.iocoder.yudao.module.rule.dto.RuleBpmNoStartEvent;
import org.springframework.stereotype.Component;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Component
public class MyBusinessRuleChangeListener extends RuleBpmNoStartEventListener {

    /**
     * 指定监听的业务类型
     * @return 业务类型枚举值
     */
    @Override
    protected Integer getBusinessType() {
        return  BusinessTypeEnum.BLACK_LIST.getType(); // 例如：黑名单
    }
      /**
     * 返回监听的业务类型集合
     * 只要有一个业务类型匹配，就会触发调用onEvent
     *
     * @return 业务类型编码
     */
    protected List<Integer> getBusinessTypes() {
        return null;
    }

    /**
     * 处理变更事件
     * @param event 变更事件数据
     */
    @Override
    protected void onEvent(RuleBpmNoStartEvent event) {
        log.info("收到规则变更通知: ruleId={}, businessId={}", event.getRuleId(), event.getBusinessId());
        
        // 业务逻辑处理，例如：
        // 1.一般是把业务对应的数据更新为“草稿”状态。
        // 2. 业务侧也可根据自己业务特性做其他处理
    }
}

注意事项:

监听器基类默认使用 ${spring.application.name}-group 作为 Kafka Consumer GroupId。
确保业务系统已配置 Kafka 连接信息。

4.3 规则编辑/新增前置检查

为了防止在业务审批过程中规则被意外修改导致数据不一致，规则引擎在编辑或新增规则（涉及到特定业务绑定）时，会向业务系统发起“可编辑性检查”。

交互流程:

发起检查: 规则引擎发送 Kafka 消息到 rule-can-edit-to-business。
业务处理: 业务系统收到消息，检查对应业务数据的状态（例如是否正在审批中）。
返回结果: 业务系统将检查结果（允许/拒绝及原因）发送回 rule-can-edit-to-rule。
引擎决策: 规则引擎根据结果决定是否继续执行编辑/新增操作。

流程图:

Mermaid Diagram Code:

sequenceDiagram
    participant Rule as 规则引擎
    participant MQ as Kafka消息
    participant Biz as 业务系统

    Rule->>MQ: 发送检查请求 (rule-can-edit-to-business)
    MQ->>Biz: 消费请求 (RuleCanEditEventListener)
    Biz->>Biz: 检查业务状态 (如是否审批中)
    Biz->>MQ: 发送检查结果 (rule-can-edit-to-rule)
    MQ->>Rule: 消费结果 (RuleCanEditCallbackConsumer)
    Rule->>Rule: 根据结果决定是否允许编辑

接入步骤:

继承监听器基类: 继承 RuleCanEditEventListener 类。
重写配置方法:
- getConsumerGroupId(): 必须重写，返回唯一的消费者组ID（建议格式 ${spring.application.name}-{businessType}-can-edit-group），避免多业务冲突。
- getBusinessType(): 返回监听的业务类型。
实现业务逻辑: 重写 onEvent 方法，根据 businessId 检查业务状态，并设置 event.setCanEdit(boolean) 和 event.setReason(String)。

代码示例 (参考黑名单业务):

@Slf4j
@Component
public class RuleBlacklistCanEditListener extends RuleCanEditEventListener {

    @Resource
    private AppBlacklistedMapper appBlacklistedMapper;

    @Override
    public String getConsumerGroupId() {
        // 必须保证唯一，避免与其他业务的监听器冲突
        return "${spring.application.name}-blacklist-can-edit-group";
    }

    @Override
    protected Integer getBusinessType() {
        return BusinessTypeEnum.BLACK_LIST.getType();
    }

    @Override
    protected void onEvent(RuleCanEditEvent event) {
        Long businessId = event.getBusinessId();

        // 查询业务数据
        AppBlacklistedDO appBlacklisted = appBlacklistedMapper.selectById(businessId);

        // 1. 数据不存在，默认允许
        if (appBlacklisted == null) {
            event.setCanEdit(true);
            return;
        }

        // 2. 检查状态：如果正在审批中，禁止编辑
        if (appBlacklisted.getBpmStatus() != null
                && appBlacklisted.getBpmStatus().equals(BpmProcessInstanceStatusEnum.RUNNING.getStatus())) {
            event.setCanEdit(false);
            event.setReason("该黑名单配置正在审批中，暂不允许编辑规则");
            log.warn("[onEvent] 黑名单正在审批中，不允许编辑规则, businessId={}", businessId);
            return;
        }

        // 3. 其他情况允许编辑
        event.setCanEdit(true);
    }
}

RuleCanEditEvent 核心字段:

字段	类型	说明
ruleId	Long	规则ID
businessType	Integer	业务类型
businessId	Long	业务ID
canEdit	boolean	是否允许编辑 (回传)
reason	String	不允许编辑的原因 (回传)

5. 附录

5.1 业务类型枚举说明

类型值	枚举名	说明	是否需要审批
0	TASK_PUSH	任务推送	是
1	LAUNCHER_PUSH	launcher广告配置	是
2	BLACK_LIST	黑名单	是
3	UOTA_UPDATE	uota升级	否
4	DOMAIN_DISPATCH	域名分发	否

1. 交互概览​

1.1 规则绑定与审批流程 (交互流程)​

1.2 规则变更反向通知流程 (交互流程)​

2. 前端集成指南 (Vue3)​

2.1 组件介绍​

2.2 使用方式​

2.3 界面效果​

3. 后端集成 - RPC 接口 (业务发起)​

3.1 基础说明​

3.1.1 接口概述​

3.1.2 接口对接步骤​

3.1.3 注意事项​

3.2 非审批场景接口​

3.2.1 绑定或解绑规则​

3.2.2 查询规则列表​

3.2.3 查询MAC列表​

3.2.4 查询所有渠道列表​

3.2.5 查询所有地区列表​

3.2.6 更新业务数量限制(后端执行)​

3.2.7 删除业务时解绑全部规则（unbindAllRulesNoBpm）​

3.2.8 获取业务绑定的设备数量​

3.3 审批场景接口​

3.3.1 规则引擎数据变更模型​

3.3.2 业务提交审批（业务系统主动 RPC）​

3.3.3 获取审批变更信息（getApprovalChangeInfo）​

3.3.4 取消业务关联规则的所有待审批变更（cancelPendingChanges）​

3.3.5 发起审批时需要设置的流程变量（BPM）​

3.4 规则匹配接口​

3.4.1 调用方法​

3.4.2 使用示例​

3.4.3 注意事项​

4. 后端集成 - MQ 消息通知 (事件驱动)​

4.1 审批完成（规则中心监听 Kafka 消息）​

4.2 规则数据修改MQ通知业务​

4.3 规则编辑/新增前置检查​

5. 附录​

5.1 业务类型枚举说明​

5.2 设备数量统计交互规范​

1. 交互概览

1.1 规则绑定与审批流程 (交互流程)

1.2 规则变更反向通知流程 (交互流程)

2. 前端集成指南 (Vue3)

2.1 组件介绍

2.2 使用方式

2.3 界面效果

3. 后端集成 - RPC 接口 (业务发起)

3.1 基础说明

3.1.1 接口概述

3.1.2 接口对接步骤

3.1.3 注意事项

3.2 非审批场景接口

3.2.1 绑定或解绑规则

3.2.2 查询规则列表

3.2.3 查询MAC列表

3.2.4 查询所有渠道列表

3.2.5 查询所有地区列表

3.2.6 更新业务数量限制(后端执行)

3.2.7 删除业务时解绑全部规则（unbindAllRulesNoBpm）

3.2.8 获取业务绑定的设备数量

3.3 审批场景接口

3.3.1 规则引擎数据变更模型

3.3.2 业务提交审批（业务系统主动 RPC）

3.3.3 获取审批变更信息（getApprovalChangeInfo）

3.3.4 取消业务关联规则的所有待审批变更（cancelPendingChanges）

3.3.5 发起审批时需要设置的流程变量（BPM）

3.4 规则匹配接口

3.4.1 调用方法

3.4.2 使用示例

3.4.3 注意事项

4. 后端集成 - MQ 消息通知 (事件驱动)

4.1 审批完成（规则中心监听 Kafka 消息）

4.2 规则数据修改MQ通知业务

4.3 规则编辑/新增前置检查

5. 附录

5.1 业务类型枚举说明

5.2 设备数量统计交互规范