广告播放数据分析

本模块旨在对广告位的播放数据进行多维度统计与深入分析，协助管理员全面掌握广告的投放与展示效能。

数据源于终端设备 Launcher 上报。其中，广告播放汇总数据为非实时数据，由系统定时任务或人工触发任务基于设备明细数据聚合生成，记录特定广告位在特定时间粒度（年/月/日）下的执行情况。

设备明细统计数据包含实时与非实时两部分：部分数据由定时/人工任务基于详细记录汇总生成，部分为设备端次日上报数据。该层级记录了单台设备在特定时间（年/月/日）针对特定广告位的执行详情。

详细播放记录为实时流水数据。当终端设备 Launcher 在对应广告位执行特定操作后，会立即触发数据上报，确保数据的及时性。

广告位定义扩展说明：该定义源于数据字典 launcher_ad_index（Launcher 广告位索引）。初期仅指代物理存在的实际广告位，随着业务发展，为满足多样化的统计需求，其概念已泛化，涵盖了多种业务场景与状态。当前涵盖的类型包括：1-14号广告位、Banner 广告位、开屏广告，以及三方广告相关状态（三方请求素材失败、三方播放完成、三方播放错误、三方播放跳过、三方播放跳转、三方 APP 打开、三方获取素材成功、三方 APP 打开(艾科统计)）。

功能说明

1. 广告播放汇总（一级页面）

在广告播放数据分析的一级页面中，本页面展示了经过聚合处理的广告播放数据，支持用户按多种维度进行灵活查询。

一级页面多维度汇总列表查询

操作说明：

支持组合以下条件进行精确检索：
- 包名：Launcher 应用程序包名。
- 版本号：Launcher 应用程序版本号。
- 统计维度：选择数据聚合的时间粒度（年、月、日）。
- 记录时间：指定查询的具体日期范围，需结合统计维度解读。
- 广告位：筛选特定的广告位类型，源于数据字典 launcher_ad_play_type（Launcher 广告播放类型）。
- 广告播放分类：筛选广告的业务分类，源于数据字典 launcher_ad_index（Launcher 广告位索引）。

字段说明：

ID：记录唯一标识符。
包名：Launcher 应用程序包名。
版本号：Launcher 应用程序版本号。
广告位：广告位的具体名称。
广告播放分类：广告的业务分类描述。
统计维度：数据聚合的时间范围类型（年、月、日）。
播放次数：在该统计维度下的累计播放总次数。
播放时长：在该统计维度下的累计播放总时长（已格式化显示）。
记录时间：数据所对应的具体业务时间，需结合统计维度解读。
创建时间：数据被采集并录入系统的时间。

数据导出：

同步导出：点击导出后，系统立即处理并返回导出结果。

2. 设备明细统计（二级页面）

在广告播放数据分析的二级页面中，点击汇总列表中的任意一条记录，界面下方将展开该记录关联的 设备明细统计 列表。此列表展示了在选定统计维度下，各独立终端设备的具体播放数据。

二级页面按设备列表查询

列表字段说明：

设备 MAC：执行广告播放的设备 MAC 地址。
播放次数：该设备累计的播放次数。
播放时长：该设备累计的播放时长。
记录时间：数据对应的具体业务日期。

数据导出：

同步导出：点击导出按钮后，系统实时处理并直接下载导出文件。
异步导出：针对大数据量场景，系统采用异步导出模式。您可以在导出任务管理模块中追踪进度并下载文件。

3. 详细播放记录（三级页面）

在广告播放数据分析的三级页面中，点击设备明细列表中的任意一条记录，界面下方将展开该设备对应的 详细播放记录 列表。此列表展示了该设备在指定时间范围内每一次广告播放的流水详情。

详细播放记录为实时流水数据。当终端设备 Launcher 在对应广告位执行特定操作后，会立即触发数据上报，确保数据的及时性。

三级页面详细播放列表查询

列表字段说明：

设备 MAC：设备的 MAC 地址。
开始时间：广告开始播放的时间点（以设备本地时间为准）。
结束时间：广告结束播放的时间点（以设备本地时间为准）。
播放时长：单次播放的持续时长。
创建时间：数据上报至服务器的时间（以服务器时间为准）。

技术实现与数据流

本章节详细阐述了广告播放数据的采集、传输、处理与存储逻辑，便于开发与运维人员理解系统底层运作机制。

1. 数据采集 (Data Collection)

终端设备通过 HTTP 接口上报广告播放数据，主要由 ForeignLauncherController 进行处理：

上报接口：
- V1 接口：/third/launcher/ad/play/callback。接收设备批量上报的播放记录列表 (List<DeviceBaseReq>)，对数据进行基础校验（如 MAC 格式化、设备合法性检查），并按“包名+广告位+版本号+日期”进行初步聚合。
- V2 接口：/launcher/ad/play/callback/v2。接收结构化的 LauncherAdPlayKafkaDTO 对象，支持更灵活的创建时间处理（如上报时间与服务器时间偏差在 1 小时内则采信上报时间，否则使用服务器时间）。
数据投递：
- 所有合法请求的数据最终被封装为 LauncherAdPlayKafkaDTO 消息。
- 消息通过 KafkaTemplate 异步发送至 Kafka Topic：launcher-ad-play-detail（配置项 ${kafka.topic.launcher-ad-play-detail}）。

2. 消息处理 (Message Processing)

LauncherAdPlayConsumer 负责消费 Kafka 中的广告播放数据，执行实时存储与初步聚合：

消费者监听：监听 launcher-ad-play-detail Topic。
实时明细存储 (TDengine)：
- 触发条件：针对特定类型（如德国三方定制广告 THIRD_GERMANY_COM_MEDIA_SYSTEMADSOLUTION_CUSTOM）或在配置名单 (launcherSaveAdRealTimePNames) 中的包名。
- 处理逻辑：调用 saveAdPlayDetailOnRealTime 方法，将单次播放明细写入 TDengine 的 LauncherAdPlayDetail 表。
- 时区处理：支持跨时区数据修正（如将北京时间转换为德国时间）。
设备级日统计 (TDengine)：
- 处理逻辑：遍历消息中的播放索引信息，生成 LauncherAdPlayDeviceCountDO 对象。
- 数据落库：调用 adPlayCountService 将数据按“设备+天”维度存入设备统计表。这确保了二级页面（设备明细统计）能快速获取到最新的日维度数据。

3. 定时调度 (Scheduled Tasks)

系统利用 XXL-JOB 执行 LauncherAdJob 中的定时任务，完成数据的多级汇总与同步：

数据同步 (TDengine → MySQL)：
- 任务：countLauncherAdPlayTdToMysql
- 逻辑：从 TDengine 获取设备级的日统计数据，汇总生成系统级的日统计数据，并写入 MySQL 的 LauncherAdPlayCount 表。同时触发 MySQL 层面的“日→月”和“月→年”的自动汇总。
多级聚合 (TDengine 内部)：
- 日转月：countLauncherAdPlayDayToMonth 任务读取 TDengine 中的日统计数据 (LauncherAdPlayDeviceCountDay)，聚合生成月统计数据 (LauncherAdPlayDeviceCountMonth)。
- 月转年：countAdPlayMonthToYear 任务读取月统计数据，聚合生成年统计数据 (LauncherAdPlayDeviceCountYear)。
数据回溯与修复：
- 任务：adPlayDetailToDeviceCount
- 功能：支持从原始明细数据 (LauncherAdPlayDetail) 重新计算并覆盖设备级统计数据，用于数据修复或补录场景。

4. 架构图解

数据流向图

下图展示了从设备上报到最终数据落库的完整流程：

Mermaid Diagram Code:

graph TD
    Device["终端设备"] -- "HTTP POST (Controller)" --> API["ForeignLauncherController"]
    API -- "Produce" --> Kafka{{"Kafka Topic<br/>launcher-ad-play-detail"}}
    
    Kafka -- "Consume" --> Consumer["LauncherAdPlayConsumer"]
    
    subgraph RealTime_Processing ["实时处理 (Consumer)"]
        Consumer -- "Insert (条件触发)" --> DetailDB[("TDengine<br/>LauncherAdPlayDetail<br/>(实时明细)")]
        Consumer -- "Insert/Update" --> DeviceDayDB[("TDengine<br/>LauncherAdPlayDeviceCount<br/>(设备日统计)")]
    end
    
    subgraph Batch_Processing ["定时任务 (XXL-JOB)"]
        JobSync["countLauncherAdPlayTdToMysql"]
        JobDayMonth["countLauncherAdPlayDayToMonth"]
        JobMonthYear["countAdPlayMonthToYear"]
        
        DeviceDayDB -- "Read" --> JobSync
        JobSync -- "Write (汇总)" --> MysqlDB[("MySQL<br/>LauncherAdPlayCount<br/>(系统汇总)")]
        
        DeviceDayDB -- "Read" --> JobDayMonth
        JobDayMonth -- "Write" --> DeviceMonthDB[("TDengine<br/>(设备月统计)")]
        
        DeviceMonthDB -- "Read" --> JobMonthYear
        JobMonthYear -- "Write" --> DeviceYearDB[("TDengine<br/>(设备年统计)")]
    end

    style Kafka fill:#f9f,stroke:#333,stroke-width:2px
    style MysqlDB fill:#6db,stroke:#333,stroke-width:2px
    style DetailDB fill:#fb7,stroke:#333,stroke-width:2px

数据模型关系图

下图展示了明细数据、设备统计数据与系统汇总数据之间的逻辑关系：

Mermaid Diagram Code:

erDiagram
    LauncherAdPlayDetail {
        timestamp ts "记录时间"
        string mac "设备MAC"
        string package_name "包名"
        int ad_index_id "广告位ID"
        int play_duration "播放时长"
    }
    
    LauncherAdPlayDeviceCount {
        timestamp ts "统计时间(日/月/年)"
        string mac "设备MAC"
        string package_name "包名"
        int play_count "播放次数"
        int play_duration "总时长"
        string time_dimension "维度"
    }

    LauncherAdPlayCount {
        date record_time "记录日期"
        string package_name "包名"
        int play_count "播放次数"
        int play_duration "总时长"
        string dimension "维度(日/月/年)"
    }

    LauncherAdPlayDetail ||--o{ LauncherAdPlayDeviceCount : "聚合 (实时/离线)"
    LauncherAdPlayDeviceCount ||--o{ LauncherAdPlayCount : "汇总 (同步至MySQL)"

功能说明​

1. 广告播放汇总（一级页面）​

2. 设备明细统计（二级页面）​

3. 详细播放记录（三级页面）​

技术实现与数据流​

1. 数据采集 (Data Collection)​

2. 消息处理 (Message Processing)​

3. 定时调度 (Scheduled Tasks)​

4. 架构图解​

数据流向图​

数据模型关系图​