跳到主要内容

设备数量统计交互指南

核心概念：文档中心 | 设备数量统计交互指南 | 概览
核心概念：文档中心 | 设备数量统计交互指南 | 一、概述

一、概述​

本指南主要规范业务系统（如黑名单、域名分发等）与规则引擎之间关于设备数量统计的交互逻辑。

1.1 适用范围​

本规范适用于以下业务场景的列表页及详情页：

  • 域名分发：域名列表
  • 域名分发：UOTA列表
  • 黑名单：黑名单列表
  • launhcer：launhcer广告位配置
  • 任务推送：apk任务推送
  • UOTA升级：UOTA自升级配置
  • 规则管理：规则列表（包括规则引擎内部列表及业务侧嵌入的规则列表）
  • 其它： 其它需要引入规则的业务

1.2 核心逻辑​

规则引擎提供了一套通用的设备数量统计机制，支持：

  1. 按业务聚合：查询某个业务ID（如某个黑名单策略）下所有关联规则覆盖的设备去重总量。
  2. 按规则聚合：查询单个规则（LiteFlowChain）覆盖的设备数量。
  3. 按需计算：支持前端手动触发实时计算（calculate=true），重新扫描数据库并更新缓存。
  4. 统计去重： 支持多维度、多规则的综合去重统计。
    • 单条规则内去重：当单条规则同时配置了 MAC 列表和渠道列表时，系统会计算二者的交集（即既在 MAC 列表中，又属于指定渠道的设备）。
    • 多条规则间去重：当一个业务绑定了多条规则时，系统会计算这些规则覆盖设备的并集，并自动去除重复的设备 ID。
    • 全量兜底策略：
      • 如果单条规则未配置任何 MAC 或渠道，系统将视为全量设备（即设备管理中的所有设备）。
      • 如果业务绑定的多条规则中，只要有任意一条规则未配置任何 MAC 或渠道（即该条规则为全量），则该业务的设备统计结果为全量设备。
  5. 计算限制（忽略项）：设备数量统计仅基于 MAC 配置和渠道配置进行计算。
    • 忽略内容：更高级的过滤条件（如地区限制、规则 EL 表达式中的复杂逻辑）在统计时会被忽略。
    • 结果含义：统计结果代表的是“初筛”后的最大潜在影响范围，而非最终命中规则的精确设备数。
核心概念：文档中心 | 设备数量统计交互指南 | 二、交互设计规范

二、交互设计规范​

2.1 数据结构​

每条业务数据（如黑名单记录、域名配置）在查询详情或列表时，应包含 BusinessDeviceCountDTO 类型的 deviceCount 属性。

核心字段说明 (BusinessDeviceCountDTO):

  • deviceCount: 设备总量（聚合去重后的数值）。
  • updateTime: 最近一次触发计算的时间。
  • hasValue: 标识是否计算过。false 表示该条数据从未触发过计算。
  • type: 类型，0-规则，1-业务
  • businessType: 业务类型 (type=1有值)
  • businessId: 业务ID (type=1有值)
  • liteflowChainId: 规则ID (type=0有值)

2.2 计算策略​

  1. 批量获取（列表页）

    • 调用 getDeviceCountMore 接口。
    • 不支持实时计算，直接返回缓存中的统计结果。
    • 如果缓存中无数据，则返回 hasValue=false。

  2. 单条获取（详情/刷新）

    • 调用 getDeviceCount 接口。
    • 支持传入 calculate=true 参数，强制触发规则引擎进行实时计算（同步计算总量并更新缓存），然后返回最新结果。

2.3 业务侧后端集成指南​

业务系统后端在处理列表查询请求时，建议遵循以下流程：

  1. 查询业务数据：先从业务表查询出分页后的业务数据列表。
  2. 填充统计数据：
    • 提取业务ID集合。
    • RPC 调用 /rpc-api/rule/rule-business/get-device-count-more 批量获取统计信息。
    • 将返回的 BusinessDeviceCountDTO 匹配填充到每条业务数据中。
  3. 返回前端：将包含 deviceCount 属性的业务对象返回给前端。

注意：

  • 列表接口严禁循环调用单条实时计算接口，以免造成性能瓶颈。
  • 如需获取最新数据，应由前端用户主动触发。

2.4 前端交互规范​

前端页面在展示设备数量时，应遵循以下交互设计：

  1. 列表展示

    • 读取 deviceCount 字段。
    • 若 hasValue=false，显示文案 【未计算】 或 --。
    • 若 hasValue=true，显示具体的设备数量（如 1024）。

  2. 弹窗详情与交互

    • 点击设备数量（或【未计算】）区域，弹出详情浮层或对话框。
    • 展示内容：
      • 设备数量
      • 最早计算时间（可选）
      • 最近一次计算时间 (updateTime)
    • 操作按钮：提供 【重新计算】 按钮。

  3. 重新计算逻辑

    • 用户点击【重新计算】后，前端调用业务侧封装的刷新接口（或直接调用规则引擎的 /admin-api 接口）。
    • 接口底层应调用 getDeviceCount(..., calculate=true)。
    • 计算完成后，刷新当前页面或仅更新该条数据的显示数值。
核心概念：文档中心 | 设备数量统计交互指南 | 三、接口详情

三、接口详情​

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

接口说明: 获取指定业务绑定的所有规则覆盖的设备总量。注意：该接口会聚合该业务下所有规则的设备，并去重计算总量。

接口地址:

  • RPC调用: GET /rpc-api/rule/rule-business/get-device-count
  • 前端调用: GET /admin-api/rule/rule-business/get-device-count

请求参数:

参数名类型必填说明
businessTypeInteger是业务类型
businessIdLong是业务ID
calculateboolean是是否重新计算(true: 实时计算并更新缓存; false: 优先读缓存)

返回结果 (BusinessDeviceCountDTO):

{
  "code": 0,
  "data": {
    "type": 1,
    "businessType": 2,
    "businessId": 10086,
    "deviceCount": 500,
    "liteflowChainId": null,
    "hasValue": true,
    "createTime": "2023-10-01 12:00:00",
    "updateTime": "2023-10-01 12:00:00"
  },
  "msg": "success"
}

调用示例 (Java):

// 参考 AppBlacklistedController
BusinessDeviceCountDTO businessDeviceCountDTO = ruleBusinessApi.getDeviceCount(
    BusinessTypeEnum.BLACK_LIST.getType(), 
    id, 
    false
).getData();

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

接口说明: 批量获取多个业务绑定的设备总量。

接口地址:

  • RPC调用: POST /rpc-api/rule/rule-business/get-device-count-more
  • 前端调用: GET /admin-api/rule/rule-business/get-device-count-more

请求参数:

参数名类型必填说明
businessTypeInteger是业务类型
businessIdsList<Long>是业务ID集合

返回结果 (List<BusinessDeviceCountDTO>):

{
  "code": 0,
  "data": [
    {
      "type": 1,
      "businessType": 2,
      "businessId": 10086,
      "deviceCount": 500,
      "hasValue": true
    },
    {
      "type": 1,
      "businessType": 2,
      "businessId": 10087,
      "deviceCount": 200,
      "hasValue": true
    }
  ],
  "msg": "success"
}

调用示例 (Java):

// 参考 AppBlacklistedController
List<BusinessDeviceCountDTO> list = ruleBusinessApi.getDeviceCountMore(
    BusinessTypeEnum.BLACK_LIST.getType(), 
    ids
).getData();

3.3 获取规则的设备数量​

接口说明: 获取单个规则（LiteflowChain）覆盖的设备数量。此接口通常用于规则管理页面展示单个规则的影响范围。

接口地址: GET /admin-api/rule/rule-business/get/rule/device/count

请求参数:

参数名类型必填说明
liteflowChainIdLong是规则ID
calculateboolean是是否重新计算

返回结果: 同 BusinessDeviceCountDTO (其中 type=0, liteflowChainId有值)

3.4 批量获取规则的设备数量​

接口说明: 批量获取多个规则的设备数量。

接口地址: GET /admin-api/rule/rule-business/get/rule/device/count/more

请求参数:

参数名类型必填说明
liteflowChainIdsList<Long>是规则ID集合

返回结果: List<BusinessDeviceCountDTO>

AI 问答