广告播放数据分析

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

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

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

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

数据上报机制

终端设备 Launcher 在广告位播放完成后，通过 HTTP 接口向服务器上报播放数据。系统采用 Kafka 消息队列 实现数据采集与处理的解耦，确保高并发场景下的系统稳定性。

上报时机

上报模式	说明	适用场景
实时上报	广告播放完成后立即上报	德国三方定制广告等特殊场景
批量上报	设备本地缓存播放记录，定时批量上报	常规广告播放
次日上报	设备在次日将前一天的播放记录上报	部分老旧设备或网络受限场景

数据处理流程

Mermaid Diagram Code:

graph LR
    A[终端设备] -->|HTTP POST| B[Controller接口]
    B -->|消息投递| C[Kafka Topic]
    C -->|消息消费| D[Consumer处理]
    D -->|存储| E[TDengine时序库]
    D -->|统计| F[设备日统计]
    
    G[定时任务] -->|汇总| H[月/年统计]
    G -->|同步| I[MySQL汇总表]

功能说明

数据分为三个层级：

广告播放汇总：非实时数据，由定时任务或人工触发任务基于设备明细数据聚合生成，记录特定广告位在特定时间粒度（年/月/日）下的执行情况。
设备明细统计：包含实时与非实时两部分，记录单台设备在特定时间针对特定广告位的执行详情。
详细播放记录：实时流水数据，当终端设备在广告位执行播放操作后立即上报。

广告位定义扩展说明：该定义源于数据字典 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. 数据采集 (Controller层)

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

接口版本	路径	说明
V1	`/third/launcher/ad/play/callback`	接收批量上报，按“包名+广告位+版本号+日期”聚合
V2	`/launcher/ad/play/callback/v2`	接收结构化对象，支持灵活的时间处理

时间校准机制：

V2 接口支持设备上报时间校准
若上报时间与服务器时间偏差在 1 小时内，采信设备上报时间
否则使用服务器当前时间

Kafka 解耦：

所有合法数据封装为 LauncherAdPlayKafkaDTO 消息
通过 KafkaTemplate 异步发送至 Topic：launcher-ad-play-detail
实现数据采集与处理的解耦，提升系统吞吐量

2. 消息处理 (Consumer层)

LauncherAdPlayConsumer 消费 Kafka 消息，执行存储与聚合：

处理分支：

分支	触发条件	处理方式
实时明细存储	德国三方定制广告(type=1) 或配置名单中的包名	写入 `LauncherAdPlayDetail` 表
设备日统计	其他常规广告	写入 `LauncherAdPlayDeviceCount` 表

3. 德国时区特殊处理

针对德国三方定制广告（adPlayType=1），系统执行时区转换：

德国时区转换说明

德国客户要求广告播放数据以德国本地时间记录。由于设备上报时间通常为北京时间（UTC+8），系统在存储实时明细时会自动进行时区转换：

计算北京时间与德国时间（UTC+1/UTC+2，考虑夏令时）的时差
将播放时间减去时差，转换为德国本地时间
以转换后的时间存储到 TDengine

代码示例：

// 计算中德时差（小时）
int hoursDifference = DateUtils.calculateHoursDifference(
    indexPlayInfo.getDateTime(), 
    DateUtils.BEIJING_ZONE, 
    DateUtils.GERMAN_ZONE
);
// 调整时间
Date adjustedDateTime = new Date(originalDateTime.getTime() - hoursDifference * 60 * 60 * 1000L);

4. 定时任务汇总

系统通过 XXL-JOB 调度以下定时任务：

任务名称	功能说明
`countLauncherAdPlayTdToMysql`	从 TDengine 同步设备日统计到 MySQL 汇总表，并触发日月、月年汇总
`countLauncherAdPlayDayToMonth`	TDengine 内部日数据汇总为月数据
`countAdPlayMonthToYear`	TDengine 内部月数据汇总为年数据
`adPlayDetailToDeviceCount`	从原始明细数据重新计算设备级统计（用于数据修复）

5. 架构图解

数据流向图

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

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. 数据采集 (Controller层)​

2. 消息处理 (Consumer层)​

3. 德国时区特殊处理​

4. 定时任务汇总​

5. 架构图解​

数据流向图​

数据模型关系图​

数据上报机制

上报时机

数据处理流程

功能说明

功能说明

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

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

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

技术实现与数据流

1. 数据采集 (Controller层)

2. 消息处理 (Consumer层)

3. 德国时区特殊处理

4. 定时任务汇总

5. 架构图解

数据流向图

数据模型关系图