广告投放系统

引用文件

本文引用的文件

简介

本系统为面向机顶盒（Launcher）的广告投放平台，围绕“三级配置架构”实现从基础信息、广告位到资源与策略的完整投放闭环。系统支持图片、视频、网页、应用等多种素材形式，具备规则引擎驱动的智能定向、频控与互斥策略、播放数据的实时采集与统计分析，并提供完善的管理后台 API 与设备端接口。

项目结构

模块划分
- Launcher 广告模块：负责广告位、广告内容与策略的配置与下发
- 设备模块：设备画像、渠道、地区等基础数据支撑
- 基础设施模块：文件上传、存储、分片上传、缓存等
- 规则引擎模块：设备画像匹配与业务规则计算
- 数据库与时序数据库：MySQL（配置与元数据）、TDengine（播放明细与时序统计）

Mermaid Diagram Code:

graph TB
subgraph "管理后台"
AdminUI["管理界面"]
AdminAPI["管理后台API"]
end
subgraph "Launcher模块"
Biz["业务服务层"]
Mapper["数据访问层"]
Redis["Redis缓存"]
Kafka["Kafka消息队列"]
TD["TDengine时序库"]
end
subgraph "基础设施"
File["文件服务"]
DB["MySQL"]
end
subgraph "设备端"
STB["机顶盒(设备)"]
end
AdminUI --> AdminAPI
AdminAPI --> Biz
Biz --> Mapper
Biz --> Redis
Biz --> Kafka
Kafka --> TD
Biz --> File
File --> DB
STB --> |请求广告| Biz
STB --> |上报播放| Kafka

图表来源

章节来源

核心组件

广告位与广告关联控制器与服务
- 控制器：提供广告位与广告关联的创建、更新、删除、查询、启用/停用、导出等接口
- 服务：实现 BPM 审批流程与无 BPM 直通模式，支持资源文件与 APP 文件校验、互斥启用、版本号更新与缓存清理
设备端广告获取接口
- 提供设备启动时获取广告配置的能力，包含 MAC 格式化、设备信息缓存、广告位策略匹配与频控检查
播放数据采集与统计
- 实时消费 Kafka 播放事件，落库 TDengine 明细表；定时 Job 聚合生成设备播放次数统计
文件与存储
- 支持分片上传、文件存储与删除；DBFileClient 将文件内容落库并生成 URL

章节来源

架构总览

系统采用“三级配置 + 规则引擎 + 频控互斥 + 实时统计”的架构，实现从素材管理到定向策略再到效果统计的全链路闭环。

Mermaid Diagram Code:

sequenceDiagram
participant Operator as "运营人员"
participant Admin as "管理后台API"
participant Biz as "业务服务"
participant DB as "MySQL"
participant Cache as "Redis"
participant Device as "设备端"
participant Kafka as "Kafka"
participant TD as "TDengine"
Operator->>Admin : "创建/更新广告位与广告关联"
Admin->>Biz : "调用服务层"
Biz->>DB : "持久化配置"
Biz->>Cache : "清理缓存/更新版本"
Note over Biz,Cache : "触发设备端下次拉取生效"
Device->>Admin : "POST /launcher/getLauncher/ads"
Admin->>Biz : "解析包名/版本号"
Biz->>Cache : "获取设备信息"
Biz->>Biz : "遍历广告位并匹配策略"
Biz-->>Device : "返回广告配置(JSON)"
Device->>Kafka : "上报播放/点击事件"
Kafka->>TD : "写入播放明细"
Biz->>TD : "定时聚合生成播放次数统计"

图表来源

详细组件分析

广告素材管理机制

多格式素材支持
- 图片、视频、网页、应用等素材通过文件服务统一管理，素材信息（URL、大小、包名、版本等）自动回填到广告位关联记录
存储与分片上传
- 支持分片初始化、上传与合并；DBFileClient 将二进制内容落库并生成 URL
版本管理与互斥
- 通过 BPM 审批与“已生效/修改标记/移除标记”状态机管理变更；同一广告位下仅允许一个资源处于启用状态，系统自动互斥其余资源
配置校验
- 创建/更新时校验资源文件与 APP 文件是否存在，避免无效素材上线

Mermaid Diagram Code:

classDiagram
class LauncherIndexAdvertController {
+createIndexAdvert()
+updateIndexAdvert()
+deleteIndexAdvert()
+getIndexAdvert()
+getIndexAdvertPage()
+exportIndexAdvertExcel()
+enable()/disable()
+cancelUpdate()
}
class LauncherIndexAdvertService {
<<interface>>
+createIndexAdvert()
+updateIndexAdvert()
+updateEnable()
+deleteIndexAdvert()
+getIndexAdvert()
+getIndexAdvertPage()
+cancelUpdate()
}
class LauncherIndexAdvertServiceImpl {
+createIndexAdvert()
+updateIndexAdvert()
+updateEnable()
+deleteIndexAdvert()
+getIndexAdvert()
+getIndexAdvertPage()
+cancelUpdate()
}
class LauncherIndexAdvertNoBpmServiceImpl {
+createIndexAdvert()
+updateIndexAdvert()
+updateEnable()
+deleteIndexAdvert()
+getIndexAdvert()
+getIndexAdvertPage()
+cancelUpdate()
}
class LauncherIndexAdvertDO {
+Long id
+Long indexId
+Integer type
+String url
+Long size
+String appUrl
+Long appSize
+String appPackageName
+Long appVersionCode
+Long appVersionName
+Integer enable
+Long appId
+Long resourceId
+String info
+Integer valid
+BpmDraft draft
}
LauncherIndexAdvertController --> LauncherIndexAdvertService
LauncherIndexAdvertService <|.. LauncherIndexAdvertServiceImpl
LauncherIndexAdvertService <|.. LauncherIndexAdvertNoBpmServiceImpl
LauncherIndexAdvertServiceImpl --> LauncherIndexAdvertDO
LauncherIndexAdvertNoBpmServiceImpl --> LauncherIndexAdvertDO

图表来源

章节来源

投放策略配置

两级配置模式
- 规则引擎模式：基于设备画像（CPU、内存、地区、渠道等）的复杂规则匹配，优先级最高
- 传统限制模式：基于渠道、MAC、地区的简单集合过滤
生效逻辑
- 若未配置任何限制，默认对所有设备生效；同一广告位下多策略命中时按优先级或更新时间取其一（单资源互斥）
频控检查
- 若广告设置了“限制推送设备数据”，系统查询 Redis 计数器，超限则不返回该广告

Mermaid Diagram Code:

flowchart TD
Start(["请求广告"]) --> GetVersion["识别Launcher版本"]
GetVersion --> IterateSlots["遍历广告位"]
IterateSlots --> MatchRules["规则引擎匹配"]
MatchRules --> HasMatch{"是否命中规则？"}
HasMatch --> |是| UseRule["使用规则策略"]
HasMatch --> |否| Fallback["尝试默认/无限制策略"]
UseRule --> CheckFreq["频控检查(Redis计数器)"]
Fallback --> CheckFreq
CheckFreq --> OverLimit{"超限？"}
OverLimit --> |是| Skip["跳过该广告位"]
OverLimit --> |否| Add["加入返回列表"]
Skip --> NextSlot["下一个广告位"]
Add --> NextSlot
NextSlot --> Done(["返回JSON配置"])

图表来源

launcher-info.md

章节来源

目标受众定向算法

规则引擎匹配步骤
- 输入：设备 MAC/CPU、业务类型
- 信息补全：根据 MAC 查询设备画像（渠道、地区、硬件配置等）
- 初筛候选规则：MAC专属、业务类型、渠道、无设备限制四类集合交并运算
- 规则计算：加载规则详情，先判断地区限制，再注入上下文执行 EL 表达式
- 数量限制：根据匹配规则获取业务 ID 集合，查询剩余数量限制，不足则剔除
- 输出：返回业务 ID 集合

Mermaid Diagram Code:

sequenceDiagram
participant STB as "设备"
participant Rule as "规则引擎"
participant Redis as "Redis"
participant Cache as "规则缓存"
STB->>Rule : "matchBusinessIds(mac/cpu, businessType)"
Rule->>Redis : "查询MAC专属规则ID集合"
Rule->>Redis : "查询业务类型规则ID集合"
Rule->>Redis : "查询渠道规则ID集合"
Rule->>Redis : "查询无设备限制规则ID集合"
Rule->>Cache : "加载规则详情"
Rule-->>STB : "返回命中的业务ID集合"

图表来源

launcher-info.md

章节来源

launcher-info.md

广告投放效果统计

实时数据采集
- 设备端上报播放事件写入 Kafka；消费者实时落库 TDengine 明细表
统计聚合
- 定时 Job 按日/月/年维度聚合生成设备播放次数统计，支持按包名、版本、广告位索引、时间标签等维度查询
指标体系
- 播放次数、播放时长、按分类（默认/三方）区分的统计

Mermaid Diagram Code:

sequenceDiagram
participant Device as "设备"
participant Kafka as "Kafka"
participant Consumer as "播放事件消费者"
participant TD as "TDengine明细表"
participant Biz as "统计服务"
participant TDCount as "TDengine统计表"
Device->>Kafka : "上报播放事件"
Kafka->>Consumer : "投递消息"
Consumer->>TD : "写入播放明细"
Biz->>TD : "按日聚合"
Biz->>TDCount : "写入设备播放次数统计"

图表来源

章节来源

广告API接口文档

管理后台接口
- 创建广告位与广告关联：POST /launcher/index-advert/create
- 更新广告位与广告关联：PUT /launcher/index-advert/update
- 删除广告位与广告关联：DELETE /launcher/index-advert/delete
- 获取广告位与广告关联：GET /launcher/index-advert/get
- 分页查询：GET /launcher/index-advert/page
- 导出Excel：GET /launcher/index-advert/export-excel
- 启用/停用：PUT /launcher/index-advert/enable, PUT /launcher/index-advert/disable
- 取消变更：PUT /launcher/index-advert/cancel
设备端接口
- 获取广告配置：POST /launcher/getLauncher/ads（无需登录）
三方广告播放上报
- 接口地址：http://third.ad.akrdinfo.cn:30133/app-api/launcher/ad/play/callback/v2
- 请求参数：mac、cpu、createTime、indexPlayInfos（包含播放时长、包名、版本号、开始时间、广告位索引）

章节来源

实际业务场景配置示例

场景一：规则引擎模式
- 在三级配置的“规则配置”标签页中，引用规则中心的复杂规则（如“CPU>4核且内存>2GB 且地区=巴西”），实现精准定向
场景二：传统限制模式
- 在“渠道配置管理”标签页中，仅在指定渠道生效；或在“MAC关联/地区关联”中限定特定设备或区域
场景三：资源互斥
- 在同一广告位下配置多个资源备选，仅启用一个；启用新资源时系统自动互斥其余资源

章节来源

依赖关系分析

组件耦合
- 控制器依赖服务接口；服务实现依赖 Mapper、文件 API、Redis、Kafka、TDengine
- 文件服务与存储客户端解耦，支持多种存储后端
外部依赖
- 规则引擎：基于 Redis 的规则集合与缓存
- Kafka：播放事件的异步处理
- TDengine：高吞吐时序数据存储
- MySQL：配置与元数据持久化

Mermaid Diagram Code:

graph LR
Controller["广告关联控制器"] --> Service["广告关联服务"]
Service --> Mapper["数据访问层"]
Service --> FileAPI["文件API"]
Service --> Redis["Redis"]
Service --> Kafka["Kafka"]
Kafka --> TD["TDengine"]
FileAPI --> DB["MySQL"]

图表来源

章节来源

性能考量

缓存与版本控制
- 广告配置变更后更新版本号并清理缓存，确保设备端尽快拉取最新配置
高并发与异步处理
- 播放事件通过 Kafka 异步落库，避免阻塞设备端上报
存储优化
- TDengine 时序表适合高频写入与按时间标签聚合查询
文件上传
- 分片上传降低大文件传输失败风险，DBFileClient 适配小文件存储场景

故障排查指南

广告未生效
- 检查审批状态与“已生效/修改标记/移除标记”状态；确认缓存是否清理
设备端无法获取广告
- 核对包名/版本号是否正确；检查 Redis 设备信息缓存；确认频控计数器是否超限
播放数据缺失
- 检查 Kafka 消费者是否正常；确认 TDengine 明细表写入；核对定时 Job 聚合逻辑
文件上传失败
- 检查分片上传初始化与合并流程；确认文件存储客户端配置与权限

章节来源

结论

本系统通过清晰的三级配置、灵活的规则引擎定向、严格的资源互斥与频控策略，以及完善的播放数据采集与统计，实现了从素材管理到效果评估的全链路广告投放能力。结合分片上传、异步消息与时序数据库，系统在高并发与大数据量场景下具备良好的稳定性与可扩展性。

附录

数据库与时序库建表脚本
- MySQL：广告关联表等配置表结构
- TDengine：播放明细与设备播放次数统计的稳定表与标签设计

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

广告素材管理机制​

投放策略配置​

目标受众定向算法​

广告投放效果统计​

广告API接口文档​

实际业务场景配置示例​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

广告素材管理机制

投放策略配置

目标受众定向算法

广告投放效果统计

广告API接口文档

实际业务场景配置示例

依赖关系分析

性能考量

故障排查指南

结论

附录