广告配置
核心广告模块负责统一维护广告平台 ID、广告形式、展示平台和可使用该广告的业务插件。新闻等业务插件只维护自身的展示位置，不重复保存广告平台开发信息。
所有接口均使用管理端鉴权，请求头需要携带 Authorization: Bearer <token>，并且当前角色必须具有对应的 METHOD:/admin/advertisement/... 接口权限。统一响应格式为 {code, msg, data}。
枚举说明
广告形式
| 值 | 名称 | 说明 |
|---|---|---|
1 | 信息流广告 | 嵌入列表或详情内容流 |
2 | 激励视频 | 用户主动触发的视频广告 |
3 | 弹窗广告 | 页面弹层或插屏广告 |
启用状态
| 值 | 名称 |
|---|---|
1 | 启用 |
2 | 停用 |
展示平台
展示平台复用用户注册来源枚举：
| 值 | 平台 | 值 | 平台 |
|---|---|---|---|
1 | 微信小程序 | 6 | 支付宝小程序 |
2 | 微信公众号 | 7 | 百度小程序 |
3 | iOS | 8 | 抖音小程序 |
4 | Android | 9 | QQ 小程序 |
5 | H5 | 10 | 快手小程序 |
查询广告列表
接口地址
text
GET /admin/advertisement/list权限标识
text
GET:/admin/advertisement/list接口说明
返回全部符合条件的广告配置，按数据库主键倒序排列。当前接口不分页，支持按名称、广告形式和状态筛选；关联插件通过批量查询补全，不会产生逐行查询。
请求参数
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | 广告名称，模糊匹配，最长 128 字符 |
format | integer | 否 | 广告形式：1 信息流、2 激励视频、3 弹窗 |
status | integer | 否 | 状态：1 启用、2 停用 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 12,
"name": "微信新闻信息流",
"ad_id": "adunit-xxxxxxxxxxxxxxxx",
"format": 1,
"status": 1,
"plugin_ids": [1],
"plugin_names": ["新闻资讯"],
"platforms": [1],
"description": "新闻列表与详情页信息流广告",
"created_at": "2026-09-30T09:30:00+08:00",
"updated_at": "2026-09-30T10:00:00+08:00"
}
]
}响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
data[].id | integer | 核心广告配置 ID |
data[].name | string | 广告名称 |
data[].ad_id | string | 第三方广告平台分配的广告 ID |
data[].format | integer | 广告形式枚举 |
data[].status | integer | 核心广告启用状态 |
data[].plugin_ids | array<integer> | 允许使用该广告的插件数据库 ID |
data[].plugin_names | array<string> | 允许使用该广告的插件名称 |
data[].platforms | array<integer> | 允许展示的平台来源枚举 |
data[].description | string | 广告说明 |
data[].created_at | string | 创建时间 |
data[].updated_at | string | 更新时间 |
查询业务插件选项
接口地址
text
GET /admin/advertisement/plugin/options权限标识
text
GET:/admin/advertisement/plugin/options接口说明
返回已安装插件，用于广告表单选择允许使用该广告的业务插件。停用插件仍会返回，并通过 status 供管理端标记状态。
请求参数
无。
响应示例
json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 1,
"plugin_id": "news",
"name": "新闻资讯",
"status": 1
}
]
}| 字段 | 类型 | 说明 |
|---|---|---|
data[].id | integer | sys_plugin 数据库主键，保存广告时传入 plugin_ids |
data[].plugin_id | string | 插件业务标识 |
data[].name | string | 插件名称 |
data[].status | integer | 插件状态：1 启用、2 停用 |
新增或修改广告
接口地址
text
POST /admin/advertisement/save权限标识
text
POST:/admin/advertisement/save请求参数
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 否 | 新增传 0 或不传，修改时传已有广告 ID |
name | string | 是 | 广告名称，最长 128 字符 |
ad_id | string | 是 | 第三方平台广告 ID，最长 255 字符 |
format | integer | 是 | 广告形式：1 信息流、2 激励视频、3 弹窗 |
status | integer | 是 | 状态：1 启用、2 停用 |
plugin_ids | array<integer> | 是 | 至少选择一个真实存在的业务插件，重复值会自动去重 |
platforms | array<integer> | 是 | 至少选择一个展示平台，可选值 1～10 |
description | string | 否 | 广告说明，最长 1000 字符 |
请求示例：
json
{
"id": 0,
"name": "微信新闻信息流",
"ad_id": "adunit-xxxxxxxxxxxxxxxx",
"format": 1,
"status": 1,
"plugin_ids": [1],
"platforms": [1],
"description": "新闻列表与详情页信息流广告"
}响应示例
json
{ "code": 0, "msg": "success" }广告主体和插件绑定关系在同一数据库事务内保存。修改时会锁定目标记录，替换原有插件绑定；所选插件不存在时整个操作回滚。
删除广告
接口地址
text
POST /admin/advertisement/delete权限标识
text
POST:/admin/advertisement/delete请求参数
| Body 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 核心广告配置 ID，必须大于 0 |
响应示例
json
{ "code": 0, "msg": "success" }删除操作会在同一事务内物理删除广告与插件绑定关系。业务插件自身的投放配置不会被此接口直接清理，但由于核心广告已不存在，不会再向用户端返回。删除前应先确认所有插件中的引用关系。
新闻插件投放
核心广告保存完成且绑定 news 插件后，还需要在新闻插件的广告配置页面选择列表或详情展示位置。参见新闻资讯插件接口中的“广告配置接口”。