推送信息管理

推送信息管理模块用于创建和管理向设备推送的各类apk。本模块集成了审批工作流，确保任务变更的安全性和规范性。

快速访问 (推送信息管理)

在推送信息管理模块中，您可以快速访问在线系统。

点击访问：推送信息管理

审批流程说明 (推送信息管理)

在推送信息管理模块中，审批流程是保障数据安全的关键机制。

重要

本模块结合了工作流模块，非管理员的修改操作都会触发审批流程。管理员修改则立即生效，无需审批。审批进度请前往审批中心查看。

审批状态说明 (推送信息管理)

在推送信息管理模块中，各类状态的含义如下：

业务审批状态：未开始(草稿)、审批中、审批通过、审批不通过、已取消。
流程实例状态：审批中、审批通过、审批不通过、已取消。
流程实例结果：待审批、审批中、审批通过、审批不通过、已取消、已退回、委派中、审批通过中。

变更状态说明 (推送信息管理)

在推送信息管理模块中，业务数据的变更状态如下：

未生效：数据已修改但未通过审批。
已生效：数据已通过审批并生效。
已生效且做修改标记：原有数据生效中，新的修改正在审批。
已生效且做移除标记：请求删除该数据，正在审批中。
已生效且修改状态为启用/禁用：请求改变启用状态，正在审批中。

1. 任务列表 (推送信息管理)

在推送信息管理模块中，任务列表展示了所有的推送任务信息，支持查询和管理。

列表查询

查询条件 (推送任务)

任务名称：输入任务名称进行模糊查询。
备注：输入备注信息进行查询。
筛选方式：选择筛选方式（1品牌/机型、2渠道、3MAC导入）。
启用状态：选择任务的启用状态。
变更状态：选择数据的变更状态（如已生效、未生效等）。
流程状态：选择审批流程的状态（如草稿、审批中等）。

列表字段说明 (推送任务)

在推送信息管理模块的任务列表中，各字段含义如下：

ID：任务唯一标识。
任务名称：推送任务的名称。
启用状态：任务是否开启。
配置方式：显示任务的筛选方式（如渠道、MAC导入等）。
设备总数：该任务覆盖的设备总数。
任务推送成功数：任务模块传统推送成功的设备数量。
launcher推送成功数：通过 Launcher 广告位安装并上报成功的设备数量（去重）。初始显示"未查询"，点击后触发实时统计；查询完成后点击数字可查看 MAC 列表并导出。
总推送成功数：将「任务推送成功数」与「launcher推送成功数」按 MAC 地址去重合并后的总数量，反映该任务的全渠道真实覆盖量。初始显示"未查询"，点击后触发实时统计；查询完成后点击数字可直接导出合并去重 MAC 列表。
备注：任务备注信息。
变更状态：当前数据的审批/生效状态。
流程状态：关联的审批流程状态。
更新时间：最后修改时间。
创建时间：任务创建时间。

操作按钮说明 (推送任务)

在推送信息管理模块的任务列表中，支持以下操作：

搜索/重置：查询或重置筛选条件。
新增：创建新的推送任务。
导出：导出任务列表数据。
编辑：修改现有任务信息（需审批）。
删除：删除任务（需审批）。
更多：
- 草稿：查看当前任务的草稿数据（仅当存在草稿时显示）。
- 取消数据变更（当前数据）：仅取消主表（任务基本信息）的修改申请。
- 取消数据变更（包含配置）：取消主表及所有关联子表（渠道、MAC、地区、规则等）的修改申请。
- 提交审批：将草稿或修改提交审批（仅草稿、审批不通过、已取消状态可操作）。
- 取消审批：撤回正在进行的审批（仅审批中状态可操作）。
- 查看审批：跳转到审批详情页面查看审批进度（仅存在流程实例时显示）。

操作提示

管理员操作无需审批，直接生效。
非管理员的修改、删除操作均会触发审批流程。
取消数据变更操作不可撤销，请谨慎操作。

推送结果统计

任务列表中以下三列共同反映任务的推送结果：

字段	数据来源	说明
任务推送成功数	任务推送渠道	传统推送成功的设备 MAC 数量，直接显示
launcher推送成功数	Launcher 广告位	Launcher 渠道安装成功的设备 MAC 数量，需点击触发统计
总推送成功数	以上两者合并	将「任务推送成功数」与「launcher推送成功数」按 MAC 地址去重合并后的总数

计算关系

总推送成功数 = 任务推送成功数 ∪ launcher推送成功数（MAC去重合并）

即：同一设备可能同时存在于两个渠道，合并时只计一次，反映真实覆盖量。

任务推送成功数

任务模块传统推送成功的设备数量，列表直接显示，无需点击查询。

launcher推送成功数

此字段用于查看 Launcher 渠道的安装覆盖情况。

弹窗查询 MAC 分页列表

状态流转：

显示状态	显示内容	含义
未查询	未查询（蓝色可点击）	尚未发起统计请求，点击触发查询
查询中	查询中...	系统正在实时统计 MAC 数量，请稽候
已查询	数字（蓝色可点击）	显示 Launcher 渠道安装成功的去重 MAC 数量，点击可查看详情

操作步骤：

点击 launcher推送成功数 列的 未查询，触发统计。
统计完成后显示 MAC 数量，点击数字打开 MAC 列表弹窗。
点击弹窗右上角导出可下载 ZIP 压缩包。

提示

该数据来源于设备安装完成后的回调上报，需设备网络正常且成功回调才能计入。
若广告资源尚未绑定推送任务，此数字为 0。

总推送成功数

此字段用于查看全渠道去重后的真实覆盖量。

状态流转：

显示状态	显示内容	含义
未查询	未查询（蓝色可点击）	尚未发起统计请求，点击触发查询
查询中	查询中...	系统正在跨模块统计合并去重 MAC 数量，请稽候
已查询	数字（蓝色可点击）	显示合并去重后的设备总数，点击弹出确认框后导出

操作步骤：

点击 总推送成功数 列的 未查询，触发统计。
统计完成后显示合并去重后的设备总数。
点击数字，确认后直接下载 ZIP 压缩包。

注意

总推送成功数需跨模块统计（任务模块 + Launcher 模块），耗时较长，请耐心等待。

2. 新增/编辑任务 (推送信息管理)

在推送信息管理模块中，您可以创建或修改推送任务的基本信息。

表单字段说明 (新增/编辑任务)

基本信息

任务名称：必填，任务的显示名称。
权限配置：选填，选择可管理此任务的角色（仅新增时可配置，编辑时不可修改）。
文件列表：必填，选择要推送的APK文件（需先在文件管理中上传）。
启用状态：必填，设置任务是否立即启用（启用/禁用）。
筛选方式：必填，决定了任务推送的范围。
- 品牌/机型：按设备品牌或机型筛选（值为1）。
- 渠道：按渠道进行筛选（值为2，需在"渠道配置管理"中配置）。
- MAC导入：通过导入MAC地址指定设备（值为3，需在"MAC配置管理"中配置）。
工厂名称：必填，默认为"IK"。
备注：选填，任务的描述信息。

推送规则配置（仅新增时可配置）

激活次数：控制设备激活次数限制，默认为0。
数量限制：推送比例限制，默认100%（单位：百分比）。
开机启动：是否开机自启动（是/否）。
Launcher启动：是否作为默认Launcher启动（是/否）。
开机启动路径：当开机启动为"是"时必填，格式为"包名/类名"。
APP开机启动次数：当开机启动为"是"时必填，0表示一直启动。

系统APP配置

是否系统APP：标识是否为系统级应用（是/否）。
开发者：选填，开发者信息。
文件存储路径：当"是否系统APP"为"是"时必填，APK文件在设备上的存储路径。
系统安装路径：当"是否系统APP"为"是"时必填，系统应用的安装路径。

提示

编辑任务时，筛选方式和推送规则配置不可修改。
当数据处于"已生效且做修改标记"状态时，编辑会弹出选择框，可选择编辑"草稿数据"或"原有数据"。

关联配置管理概述 (推送信息管理)

在推送信息管理模块中，根据业务需求，您可以选择使用 规则引擎模式（推荐） 或 传统配置模式 来定义任务的推送范围。

模式说明

规则引擎模式：支持更复杂的逻辑（如"指定渠道且系统版本>10"），是新版系统的核心能力。
传统配置模式：仅支持单一维度的筛选（如仅按渠道或仅按MAC），主要用于兼容旧版数据。
逻辑共存：当任务同时配置了规则和传统条件时，系统通常会取并集或根据业务逻辑并行处理，建议新任务统一使用规则引擎。

1. 规则配置管理 (新版推荐)

这是新版任务推送的核心配置入口，集成了系统强大的规则引擎能力。

规则详情

功能说明

绑定规则：直接引用规则中心已定义好的规则（如"高端机型通用规则"）。
新建规则：为当前任务创建一个专用规则。
灵活条件：支持渠道、MAC、地区、版本号、设备型号等多种条件的组合与逻辑运算。

列表字段说明

编号：规则配置的唯一标识。
是否限制推送区域：是否启用地区限制功能（是/否）。
激活次数：设备激活次数限制。
Launcher启动：是否作为默认Launcher启动。
数量限制：推送比例限制（百分比）。
是否开机启动：是否开机自启动。
开机启动路径：启动类路径（包名/类名）。
APP开机启动次数：启动次数，0表示一直启动。
变更状态：当前配置的审批/生效状态。

操作说明

编辑：修改规则配置信息。
取消数据变更：撤销当前正在审批中的修改（仅"已生效且做修改标记"状态显示）。

2. 传统配置模式 (Legacy)

以下配置方式属于旧版逻辑，主要用于兼容历史数据。

2.1 渠道配置管理

当筛选方式选择为"渠道"时，在此处管理关联的渠道。

渠道列表

新增：添加关联的渠道。
删除：移除关联的渠道。

2.2 MAC配置管理

当筛选方式选择为"MAC导入"时，在此处管理目标设备的MAC地址。

MAC列表

新增单条：手动输入单个MAC地址。
批量导入：通过Excel文件批量导入MAC地址。
异步导出：导出当前的MAC地址列表。导出任务请在导出任务管理中查看。
删除：移除MAC地址。

2.3 地区配置管理

配置任务生效的地区限制。

地区限制

新增：添加限制的地区（国家/省份/城市）。
删除：移除地区限制。

3. 设备推送详情管理 (推送信息管理)

在推送信息管理模块中，您可以查看任务推送到具体设备的执行结果。

推送结果

查询条件 (设备推送详情)

任务ID：所属推送任务的唯一标识（通常自动填充）。
MAC：输入设备 MAC 地址进行查询。
是否推送成功：按推送结果状态筛选（如：是、否）。
设备时间：仅在推送成功后显示。记录设备完成 APK 安装时的本地系统时间。
创建时间：按数据生成的初始时间进行筛选。

列表字段说明 (设备推送详情)

在推送结果列表中，各字段含义如下：

MAC：设备的唯一物理地址标识。当存在APP运行记录时，MAC显示为蓝色可点击链接，点击可查看详细的运行记录。
是否推送成功：显示任务是否已成功推送到该设备。
变更状态：当前设备关联数据的审批/生效状态（如：已生效、审批中等）。
设备时间：仅在推送成功后显示。记录设备完成 APK 安装时的本地系统时间。
更新时间：该记录在服务端最后一次变更的时间（任何字段的变化均会触发更新）。
创建时间：
- 该条数据在系统中最初生成的时间。
- 未引入规则引擎的传统模式 (按 MAC 导入)：在后台手动添加或批量导入 MAC 时即生成。若设备本地时间准确，设备时间应晚于创建时间。
- 未引入规则引擎的传统模式 (按渠道推送)：在设备成功安装并上报后才生成。若设备本地时间准确，设备时间通常早于或接近创建时间（服务端接收时间）。
APP运行记录首次上报时间(设备时间)：设备首次上报APP运行记录时的设备本地时间。
APP运行记录首次上报时间：服务端首次接收到APP运行记录的时间。

提示

MAC字段显示为蓝色链接时，表示该设备有APP运行记录，点击可查看详细信息。
设备时间由设备本地时钟记录，可能与服务端时间存在偏差。

3. 请求处理流程 (APK任务推送)

3.1 机顶盒请求说明

机顶盒通过 UOTA-APP 定时向服务器请求任务推送信息。请求接口为 /task/checkTaskPush。

请求参数

参数	类型	必填	说明
mac	String	是	设备MAC地址
cpu	String	否	设备CPU标识（当Token中无设备信息时需要）

请求头

Header	说明
Authorization	设备Token（包含设备ID、渠道ID、地区ID等信息）
api-version	API版本号

响应数据结构

[
  {
    "taskId": 123,
    "taskVersionCode": 1704067200000,
    "taskType": 1,
    "taskData": {
      "fileUrl": "https://xxx/file.apk",
      "fileSize": 4747480,
      "fileName": "app.apk",
      "packageName": "com.example.app",
      "versionCode": 100,
      "versionName": "1.0.0",
      "isSystemApp": 0,
      "installPath": null,
      "isRedirect": false
    },
    "isAutoStart": 1,
    "countActivate": 0,
    "isDefaultLauncher": 0,
    "classPath": "com.example.app/.MainActivity",
    "openApptimes": 0
  }
]

响应字段说明

字段	说明
taskId	任务ID
taskVersionCode	任务版本号（时间戳），设备端用于判断是否需要更新配置
taskType	任务类型，固定为1（APK推送）
taskData.fileUrl	APK下载地址
taskData.fileSize	文件大小（字节）
taskData.packageName	应用包名
taskData.versionCode	应用版本号
taskData.isSystemApp	是否系统应用（1是/0否）
taskData.installPath	系统应用安装路径
isAutoStart	是否开机自启动（1是/0否）
countActivate	激活次数限制（0表示无限制）
isDefaultLauncher	是否默认Launcher（1是/0否）
classPath	启动类路径
openApptimes	APP启动次数（0表示一直启动）

3.2 服务端处理流程

服务端根据配置决定使用 规则引擎模式 或 传统配置模式 进行任务匹配。

模式切换

通过配置项 task.rule.enable 控制是否启用规则引擎模式。默认为 false（使用传统模式）。

3.2.1 规则引擎模式（推荐）

规则引擎模式是新版系统的核心能力，支持复杂的条件组合和灵活的匹配逻辑。

Mermaid Diagram Code:

sequenceDiagram
    participant STB as "机顶盒/设备"
    participant Controller as "AppTaskController"
    participant Service as "AppTaskService"
    participant RuleRun as "RuleRunUtil"
    participant Redis as "Redis缓存"
    participant LiteFlow as "LiteFlow引擎"

    STB->>Controller: "1. POST /task/checkTaskPush"
    Controller->>Controller: "2. 获取设备信息 (Token/缓存)"
    
    alt 规则引擎已启用
        Controller->>Service: "3. pushV2(设备信息)"
        Service->>RuleRun: "4. matchBusinessIds(业务类型, 设备信息)"
        
        Note right of RuleRun: "5. 初筛候选规则"
        RuleRun->>Redis: "获取 MAC专属规则"
        RuleRun->>Redis: "获取 渠道关联规则"
        RuleRun->>Redis: "获取 无限制规则"
        RuleRun->>Redis: "获取 业务类型规则"
        
        RuleRun->>RuleRun: "6. 集合运算 (并集∩交集)"
        Note right of RuleRun: "候选集 = (MAC规则 ∪ 无限制 ∪ 渠道规则) ∩ 业务类型规则"
        
        loop "7. 遍历候选规则"
            RuleRun->>Redis: "获取规则详情"
            RuleRun->>RuleRun: "检查规则启用状态"
            RuleRun->>RuleRun: "检查地区限制"
            alt 地区匹配通过
                RuleRun->>LiteFlow: "执行EL表达式匹配"
                LiteFlow-->>RuleRun: "返回匹配结果"
            else 地区不匹配
                RuleRun->>RuleRun: "跳过该规则"
            end
        end
        
        RuleRun-->>Service: "8. 返回匹配成功的任务ID集合"
        Service->>Service: "9. 查询任务详情"
        Service->>Service: "10. 过滤禁用任务"
        Service->>Service: "11. 构建返回数据"
        Service-->>Controller: "返回任务列表"
    end
    
    Controller-->>STB: "12. 返回APK配置信息"

规则匹配核心逻辑：

初筛候选规则：从多个维度获取候选规则集合，进行集合运算
- MAC专属规则：该设备MAC绑定的规则
- 渠道关联规则：该设备所属渠道绑定的规则
- 无限制规则：未绑定任何设备/渠道的全局规则
- 业务类型规则：任务推送类型的规则
- 集合运算：(MAC规则 ∪ 无限制规则 ∪ 渠道规则) ∩ 业务类型规则
规则详情校验：
- 检查规则是否启用
- 检查规则是否生效（valid状态）
- 检查地区限制（设备地区是否在规则配置的地区范围内）
EL表达式匹配：
- 使用 LiteFlow 引擎执行规则的 EL 表达式
- 支持设备属性判断（CPU型号、内存大小、Android版本等）
- 支持逻辑组合（AND、OR、NOT）
数量限制检查：
- 检查任务配置的推送数量限制
- 当前推送数量 < 限制数量时才返回该任务

3.2.2 传统配置模式（Legacy）

未来弃用

传统配置模式仅用于兼容历史数据，新任务建议统一使用规则引擎模式。该模式计划在未来版本中弃用。

传统配置模式根据任务的 筛选方式 进行匹配：

Mermaid Diagram Code:

sequenceDiagram
    participant STB as "机顶盒/设备"
    participant Controller as "AppTaskController"
    participant Service as "TaskService"
    participant Channel as "TaskChannelService"
    participant Device as "TaskDeviceService"
    participant Region as "TaskRegionService"

    STB->>Controller: "1. POST /task/checkTaskPush"
    Controller->>Controller: "2. 获取设备信息 (Token/缓存)"
    
    alt 传统模式
        Controller->>Service: "3. listTaskDevice(设备信息)"
        
        par "渠道筛选 (filterType=2)"
            Service->>Channel: "根据渠道ID获取任务列表"
            Channel-->>Service: "返回任务ID集合"
        and "MAC导入筛选 (filterType=3)"
            Service->>Device: "根据MAC获取已配置的任务"
            Device-->>Service: "返回任务列表"
        end
        
        Service->>Service: "4. 合并任务列表 (去重)"
        Service->>Service: "5. 过滤禁用任务"
        
        loop "遍历任务"
            Service->>Region: "检查地区限制"
            alt 地区匹配
                Service->>Service: "保留该任务"
            else 地区不匹配
                Service->>Service: "跳过该任务"
            end
        end
        
        Service->>Service: "6. 构建返回数据"
        Service-->>Controller: "返回任务列表"
    end
    
    Controller-->>STB: "7. 返回APK配置信息"

筛选方式说明：

筛选方式	filterType	匹配逻辑
品牌/机型	1	按设备品牌或机型匹配（已弃用）
渠道	2	设备所属渠道与任务配置的渠道匹配
MAC导入	3	设备MAC在任务配置的MAC列表中

传统模式局限性：

仅支持单一维度筛选，无法组合条件
配置分散在多个子表（渠道表、MAC表、地区表）
不支持复杂的逻辑判断（如"渠道A且版本>10"）
维护成本高，扩展性差

3.3 设备端处理逻辑

设备收到服务端返回的任务列表后，按以下逻辑处理：

Mermaid Diagram Code:

flowchart TB
    A[收到任务列表] --> B{列表是否为空?}
    B -->|是| C[结束]
    B -->|否| D[遍历任务]
    D --> E{检测是否安装同包名应用?}
    E -->|未安装| F[下载APK]
    E -->|已安装| G{本地版本 < 服务端版本?}
    G -->|是| F
    G -->|否| H[跳过该任务]
    F --> I[安装APK]
    I --> J{是否开机启动?}
    J -->|是| K[配置开机启动]
    J -->|否| L[结束]
    K --> L
    H --> D
    L --> D

处理步骤：

版本检测：
- 检查设备是否已安装同包名应用
- 若已安装，比较版本号（本地版本 < 服务端版本则升级）
下载安装：
- 从 fileUrl 下载APK文件
- 支持断点续传
- 校验文件大小
系统应用处理：
- 若 isSystemApp=1，安装到 installPath 指定路径
- 需要系统权限
启动配置：
- 若 isAutoStart=1，配置开机自启动
- 若 isDefaultLauncher=1，设置为默认Launcher
- 使用 classPath 作为启动类

3.4 推送结果回调

设备安装完成后，通过 /task/taskPush/callBack 接口上报执行结果。

回调请求参数

[
  {
    "taskId": 123,
    "mac": "AA:BB:CC:DD:EE:FF",
    "cpuid": "xxx",
    "pushTaskTime": "2025-01-01 12:00:00"
  }
]

回调处理流程

Mermaid Diagram Code:

sequenceDiagram
    participant Device as "设备"
    participant Controller as "AppTaskController"
    participant Kafka as "Kafka"
    participant Consumer as "消费者"
    participant DB as "数据库"

    Device->>Controller: "POST /task/taskPush/callBack"
    Controller->>Controller: "遍历回调数据"
    
    loop 每条回调记录
        Controller->>Controller: "查询任务信息"
        Controller->>Controller: "查询文件信息"
        Controller->>Kafka: "发送消息到 apk_push_callback Topic"
    end
    
    Controller-->>Device: "返回成功数量"
    
    par "异步处理"
        Consumer->>Kafka: "消费消息"
        Consumer->>DB: "更新推送记录"
        Consumer->>DB: "写入推送历史"
    end

回调处理说明：

同步处理：接收回调后立即发送Kafka消息，快速响应设备
异步处理：Kafka消费者异步更新数据库记录
数据记录：
- 更新 task_device 表的推送状态
- 写入 apk_push_history 推送历史记录

快速访问 (推送信息管理)​

审批流程说明 (推送信息管理)​

审批状态说明 (推送信息管理)​

变更状态说明 (推送信息管理)​

1. 任务列表 (推送信息管理)​

查询条件 (推送任务)​

列表字段说明 (推送任务)​

操作按钮说明 (推送任务)​

推送结果统计​

任务推送成功数​

launcher推送成功数​

总推送成功数​

2. 新增/编辑任务 (推送信息管理)​

表单字段说明 (新增/编辑任务)​

基本信息​

推送规则配置（仅新增时可配置）​

系统APP配置​

关联配置管理概述 (推送信息管理)​

1. 规则配置管理 (新版推荐)​

功能说明​

列表字段说明​

操作说明​

2. 传统配置模式 (Legacy)​

2.1 渠道配置管理​

2.2 MAC配置管理​

2.3 地区配置管理​

3. 设备推送详情管理 (推送信息管理)​

查询条件 (设备推送详情)​

列表字段说明 (设备推送详情)​

3. 请求处理流程 (APK任务推送)​

3.1 机顶盒请求说明​

请求参数​

请求头​

响应数据结构​

响应字段说明​

3.2 服务端处理流程​

3.2.1 规则引擎模式（推荐）​

3.2.2 传统配置模式（Legacy）​

3.3 设备端处理逻辑​

3.4 推送结果回调​

回调请求参数​

回调处理流程​

快速访问 (推送信息管理)

审批流程说明 (推送信息管理)

审批状态说明 (推送信息管理)

变更状态说明 (推送信息管理)

1. 任务列表 (推送信息管理)

查询条件 (推送任务)

列表字段说明 (推送任务)

操作按钮说明 (推送任务)

推送结果统计

任务推送成功数

launcher推送成功数

总推送成功数

2. 新增/编辑任务 (推送信息管理)

表单字段说明 (新增/编辑任务)

基本信息

推送规则配置（仅新增时可配置）

系统APP配置

关联配置管理概述 (推送信息管理)

1. 规则配置管理 (新版推荐)

功能说明

列表字段说明

操作说明

2. 传统配置模式 (Legacy)

2.1 渠道配置管理

2.2 MAC配置管理

2.3 地区配置管理

3. 设备推送详情管理 (推送信息管理)

查询条件 (设备推送详情)

列表字段说明 (设备推送详情)

3. 请求处理流程 (APK任务推送)

3.1 机顶盒请求说明

请求参数

请求头

响应数据结构

响应字段说明

3.2 服务端处理流程

3.2.1 规则引擎模式（推荐）

3.2.2 传统配置模式（Legacy）

3.3 设备端处理逻辑

3.4 推送结果回调

回调请求参数

回调处理流程