渠道管理API

引用文件

本文档引用的文件

简介

本文件面向渠道管理API的使用者与维护者，系统性梳理渠道信息查询、渠道设备关联、渠道统计数据等核心能力。内容覆盖：

渠道数据结构与字段语义
渠道与设备的映射关系
渠道统计指标与数据来源
数据更新机制与缓存策略
渠道配置示例、设备分配策略与监控方案

项目结构

渠道管理API位于设备模块（device module）下，采用典型的分层架构：

API层：对外暴露RPC接口（Feign），供其他模块调用
控制器层：管理后台REST接口，提供CRUD与分页导出
服务层：业务逻辑封装，含缓存与默认渠道解析
数据访问层：MyBatis Mapper与Redis DAO
DTO与DO：数据传输对象与持久化对象

Mermaid Diagram Code:

graph TB
subgraph "设备模块"
API["ChannelApi<br/>RPC接口"]
API_IMPL["ChannelApiImpl<br/>实现"]
CTRL["ChannelController<br/>管理后台接口"]
SVC["ChannelService<br/>接口"]
SVC_IMPL["ChannelServiceImpl<br/>实现"]
MAPPER["ChannelMapper<br/>MyBatis"]
REDIS["ChannelRedisDAO<br/>Redis"]
DO["ChannelDO<br/>实体"]
DTO["ChannelRespDTO<br/>RPC响应DTO"]
end
CTRL --> SVC
API_IMPL --> SVC_IMPL
SVC_IMPL --> MAPPER
SVC_IMPL --> REDIS
MAPPER --> DO
API --> DTO

图表来源

章节来源

核心组件

RPC接口层（ChannelApi）
- 提供远程调用接口，包括获取渠道数据与批量更新渠道版本
控制器层（ChannelController）
- 提供管理后台REST接口，支持创建、更新、删除、查询、分页、导出
服务层（ChannelService/Impl）
- 核心业务逻辑：CRUD、分页、名称唯一性校验、默认渠道解析、版本更新、缓存读写
数据访问层（ChannelMapper/ChannelRedisDAO）
- MyBatis负责数据库持久化；Redis负责热点数据缓存
数据模型（ChannelDO/ChannelRespDTO）
- 渠道实体与RPC响应DTO

章节来源

架构总览

渠道管理API遵循“控制器-服务-数据访问”的分层设计，并通过Redis提升读性能与一致性保障。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "调用方"
participant API as "ChannelApiImpl"
participant Svc as "ChannelServiceImpl"
participant Mapper as "ChannelMapper"
participant Redis as "ChannelRedisDAO"
Client->>API : "调用 getChannelData(id)"
API->>Svc : "getChannel(id)"
Svc->>Redis : "读取缓存"
alt "命中缓存"
Redis-->>Svc : "返回ChannelDO"
else "未命中缓存"
Svc->>Mapper : "查询数据库"
Mapper-->>Svc : "返回ChannelDO"
Svc->>Redis : "写入缓存"
end
Svc-->>API : "返回ChannelDO"
API-->>Client : "返回ChannelRespDTO"

图表来源

详细组件分析

渠道信息查询接口

管理后台接口
- GET /device/channel/get?id={id}：获取单个渠道详情
- GET /device/channel/page：分页查询
- GET /device/channel/all：获取全部渠道
- POST /device/channel/create：创建渠道
- PUT /device/channel/update：更新渠道
- DELETE /device/channel/delete：删除渠道
- GET /device/channel/export-excel：导出渠道明细到Excel
RPC接口
- GET /api/device/channel/get?id={id}：获取渠道数据（供其他模块调用）
- GET /api/device/channel/update-channel_version：批量更新渠道版本

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理后台"
participant Ctrl as "ChannelController"
participant Svc as "ChannelService"
participant Mapper as "ChannelMapper"
Admin->>Ctrl : "GET /device/channel/page"
Ctrl->>Svc : "getChannelPage(pageReqVO)"
Svc->>Mapper : "selectPage(pageReqVO)"
Mapper-->>Svc : "PageResult<ChannelDO>"
Svc-->>Ctrl : "PageResult<ChannelDO>"
Ctrl-->>Admin : "分页结果"

图表来源

章节来源

渠道设备关联接口

关联模块入口与导航
- 渠道关联管理入口位于“首页导航”文档中，提供“查看关联设备”“查看应用场景”等链接
广告位与渠道关联
- 通过LauncherIndexChanelService实现广告位与渠道的绑定/解绑/分页查询
- 控制器支持批量创建、更新、删除、分页查询等操作
设备与渠道映射
- 设备表包含channelId字段，作为设备与渠道的直接映射
- 可通过设备API按渠道ID列表与激活状态查询设备MAC与设备数量

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> GetChannel["获取渠道信息"]
GetChannel --> BindIndex["广告位绑定渠道"]
BindIndex --> DeviceAssign["设备分配到渠道"]
DeviceAssign --> QueryDevice["按渠道查询设备"]
QueryDevice --> Export["导出设备清单"]
Export --> End(["结束"])

图表来源

章节来源

渠道统计数据接口

统计指标
- 设备总量：按渠道ID列表与激活状态统计设备数量
- 设备MAC集合：按渠道ID列表与激活状态获取设备MAC集合
数据来源
- 设备统计接口来源于设备API，支持按渠道ID列表与状态过滤
- 统计结果可用于报表与运营看板

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant DevAPI as "DeviceApi"
participant ES as "搜索引擎/统计存储"
Caller->>DevAPI : "GET /device/get-device-count-by-channelIds-and-status"
DevAPI->>ES : "按渠道ID列表与状态查询设备数量"
ES-->>DevAPI : "返回统计结果"
DevAPI-->>Caller : "设备数量"

图表来源

DeviceApi.java

章节来源

DeviceApi.java

渠道数据结构

渠道实体（ChannelDO）
- 字段：id、name、companyId、updateVersion、describeInfo、createUser、remarks、taskId
- 主键：id
- 表：base_channel
RPC响应DTO（ChannelRespDTO）
- 字段：id、name、updateVersion、describeInfo、remarks、taskId
BO（CountDeviceBO）
- 字段：channelId、modelId、deviceCount
- 用于设备统计聚合

Mermaid Diagram Code:

classDiagram
class ChannelDO {
+Long id
+String name
+Integer companyId
+Long updateVersion
+String describeInfo
+Long createUser
+String remarks
+Long taskId
}
class ChannelRespDTO {
+Long id
+String name
+Long updateVersion
+String describeInfo
+String remarks
+Long taskId
}
class CountDeviceBO {
+Integer channelId
+Integer modelId
+Long deviceCount
}

图表来源

章节来源

数据更新机制

渠道版本更新
- 通过RPC接口批量更新渠道版本（updateChannelVersionByIdList），用于任务下发时判断是否需要更新
- 服务层实现会逐条更新updateVersion为当前时间戳
缓存策略
- 读路径：优先从Redis缓存读取，未命中再回源数据库
- 写路径：更新/删除后清理对应Redis缓存，保证一致性
默认渠道解析
- 依据系统字典配置，按平台匹配默认渠道，若未找到则抛出异常

Mermaid Diagram Code:

flowchart TD
A["接收请求 updateChannelVersionByIdList"] --> B["遍历渠道ID"]
B --> C{"渠道存在?"}
C --> |是| D["设置updateVersion为当前时间戳"]
D --> E["更新数据库"]
E --> F["清理Redis缓存"]
C --> |否| G["跳过"]
F --> H["返回成功"]
G --> H

图表来源

章节来源

渠道配置示例

渠道基础配置
- 字段：名称、描述、备注、所属公司、任务ID
- 唯一性：名称唯一，创建/更新时进行校验
默认渠道配置
- 通过系统字典配置平台与渠道的映射关系
- 若未匹配到平台对应的渠道，默认使用配置中的默认渠道
渠道与任务关联
- 渠道可绑定任务ID，用于任务下发与版本控制

章节来源

设备分配策略

基于平台的默认分配
- 根据设备平台自动选择默认渠道，确保新设备快速进入正确渠道
手动调整
- 管理后台支持手动修改设备所属渠道，便于运营干预
批量处理
- 支持批量导入/导出渠道与设备关联信息，提升运维效率

章节来源

渠道监控方案

渠道版本监控
- 通过updateVersion字段监控渠道是否被更新，结合任务下发策略判断是否需要重新下发
渠道使用监控
- 通过设备数量统计接口监控各渠道设备规模变化
关联关系监控
- 通过渠道关联管理页面查看渠道在黑名单、广告、任务等模块的引用情况，及时发现异常

章节来源

依赖关系分析

组件耦合
- 控制器依赖服务接口；服务实现依赖Mapper与Redis DAO
- RPC接口由实现类提供，供其他模块通过Feign调用
外部依赖
- MyBatis用于数据库访问
- Redis用于缓存热点数据
- 系统字典用于默认渠道解析

Mermaid Diagram Code:

graph LR
CTRL["ChannelController"] --> SVC["ChannelService"]
API_IMPL["ChannelApiImpl"] --> SVC_IMPL["ChannelServiceImpl"]
SVC_IMPL --> MAPPER["ChannelMapper"]
SVC_IMPL --> REDIS["ChannelRedisDAO"]
MAPPER --> DO["ChannelDO"]

图表来源

章节来源

性能考虑

缓存命中率
- 读路径优先走Redis，减少数据库压力；写路径及时失效缓存
分页查询
- 使用条件构造器进行分页查询，避免全表扫描
批量更新
- 批量更新渠道版本时逐条更新并清理缓存，确保一致性

故障排查指南

渠道不存在
- 当根据ID查询渠道为空时，服务层抛出“渠道不存在”异常
名称重复
- 创建/更新时校验名称唯一性，重复则返回错误提示
默认渠道缺失
- 若字典中未配置默认渠道或未匹配到平台对应的渠道，将抛出异常
删除保护
- 删除渠道前需确认无设备关联，否则返回错误提示

章节来源

结论

渠道管理API通过清晰的分层设计与缓存策略，提供了稳定高效的渠道信息查询、设备关联与统计能力。配合默认渠道解析与版本更新机制，能够支撑任务下发与运营监控需求。建议在生产环境中重点关注缓存一致性、批量更新性能与异常处理策略。

附录

相关文档入口
- 渠道关联管理：导航文档中的“渠道关联管理”
- 设备渠道文档：设备模块渠道文档
- 广告渠道文档：启动器模块渠道文档
- 黑名单渠道关系：黑名单模块渠道关系文档

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

渠道信息查询接口​

渠道设备关联接口​

渠道统计数据接口​

渠道数据结构​

数据更新机制​

渠道配置示例​

设备分配策略​

渠道监控方案​

依赖关系分析​

性能考虑​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

渠道信息查询接口

渠道设备关联接口

渠道统计数据接口

渠道数据结构

数据更新机制

渠道配置示例

设备分配策略

渠道监控方案

依赖关系分析

性能考虑

故障排查指南

结论

附录