# 腾讯广告实时调控

独立管理实时投放指标采集、状态判断和腾讯广告调控，不依赖广告创建或历史调价分析流程。

## 数据和范围

- 从 `loghubods.advertiser_data_da_hour` 读取当天整体小时数据。
- CPM 直接使用 `真实cpm_总`。
- 固定过滤名称、广告主、公司、行业、客户和落地页类型均为 `SUM`。
- 实时管理账户取历史 `ad_creation_account_config` 与
  `account_whitelist.enabled=1` 的交集；关闭创建配置只停止新建和补创意，
  不会让既有广告退出实时管理。
- 普通出价使用 `bid_amount`，最大转化量使用 `custom_cost_cap`。
- 每条广告首次纳管时将腾讯当前实际出价持久化为基础出价。

## 调控规则

北京时间默认每天 `12:00-21:00` 每 10 分钟检查一次。广告自身投放时段
仍由 `time_series` 管理，在实时调控开始前按基础出价正常投放：

- `CPM > 250`：基础出价上调 25%。
- `190 <= CPM <= 250`：恢复基础出价并恢复策略暂停的广告。
- `CPM < 190`：恢复基础出价，将广告开始日期延后至次日；保持广告开启，次日
  进入 `time_series` 投放时段后由腾讯自动投放。
- 同一广告每天最多上调一次；恢复基础价后，当天也不会再次上调。
- 到达 `RTC_STOP_HOUR`：恢复基础出价，不主动暂停广告。广告由腾讯的
  `time_series` 在非投放时段自动停止配量，次日进入投放时段后自动投放。
- 截止时会恢复由低 CPM 策略暂停的广告，但不打开人工暂停广告。

每个真实发生调价、延后投放或状态修改的窗口会生成一张飞书在线表格
并发送到调控群。
群消息包含触发时间、数据分区、当前 CPM、决策、影响账户/广告数、动作分布和
受影响广告当日累计消耗。表格包含日期、数据分区、当前 CPM、账户、广告 ID、
广告名称、人群包、广告当日累计消耗/曝光/点击、基础出价、调整前出价、执行后
当前出价和动作。
同一窗口的所有成功动作合并在一张表中；无动作、dry-run 和已达到当日上调
上限的广告不发送通知。飞书发送失败不会回滚已经成功的腾讯操作，本地 xlsx
仍保存在 `outputs/`，错误会写入本轮 JSON 报告和进程日志。

腾讯写接口返回 `code=0` 后不会立即判定成功。流程会按广告 ID 重新读取腾讯
广告并核对本次修改的出价和状态字段，默认最多校验 3 次、间隔 1 秒。只有读回
值与目标一致才更新成功状态并进入成功通知；持续不一致按失败写入动作审计，
飞书卡片标红并在表格中展示错误。

ODPS 小时分区可能延迟。当天尚未出现 `06` 点及之后的分区时只等待，不使用
夜间低流量分区做关停判断。最新分区相对当前时间最多允许延迟 2 小时，超过后
本轮不执行基于 CPM 的调价、恢复或关停；每天 06:00 的定时恢复不依赖 CPM。

状态保存在 MySQL，使用数据库锁避免多 Pod 同时执行。相同分区和相同决策默认
不重复扫描腾讯；每 60 分钟至少刷新一次广告清单以纳管新广告。

## 初始化

```bash
.venv/bin/python examples/tencent_realtime_control/init_db.py
```

## 数据检查

读取上海时区当天分时 CPM：

```bash
.venv/bin/python examples/tencent_realtime_control/fetch_daily_hourly_cpm.py
```

指定日期：

```bash
.venv/bin/python examples/tencent_realtime_control/fetch_daily_hourly_cpm.py \
  --date 20260724
```

## 单次执行

默认 dry-run，不修改腾讯：

```bash
.venv/bin/python examples/tencent_realtime_control/run_once.py
```

验证 CPM 分支：

```bash
.venv/bin/python examples/tencent_realtime_control/run_once.py \
  --at 2026-07-24T15:00:00 \
  --cpm-override 260
```

使用真实账户、广告、出价和当日指标模拟完整通知链路，不修改腾讯广告：

```bash
.venv/bin/python examples/tencent_realtime_control/run_once.py \
  --at 2026-07-24T15:00:00 \
  --cpm-override 260 \
  --test-notification
```

模拟卡片、动作列和表格标题都会标记“模拟”。`--test-notification` 不能与
`--apply` 同时使用。

真实执行：

```bash
.venv/bin/python examples/tencent_realtime_control/run_once.py --apply
```

## 一次性延后生效日期

需要让全部自动化广告在指定日期才开始投放时，先 dry-run：

```bash
.venv/bin/python \
  examples/tencent_realtime_control/schedule_automated_ads_from_date.py \
  --begin-date 2026-07-26
```

确认账户数、广告数、待更新数和待恢复数后真实执行：

```bash
.venv/bin/python \
  examples/tencent_realtime_control/schedule_automated_ads_from_date.py \
  --begin-date 2026-07-26 \
  --apply
```

脚本只处理当前启用的自动化账户。它保留广告原有 `end_date` 和
`time_series`，逐账户更新 `begin_date` 并回读校验；日期更新成功后只恢复
由实时策略暂停的广告，不会打开人工暂停广告。默认 dry-run，必须显式传
`--apply` 才会修改腾讯广告。

## Docker 调度

统一控制服务在投放时段按 10 分钟边界执行，20 点收尾后休眠到次日 6 点：

```bash
RTC_APPLY_ENABLED=0 \
  .venv/bin/python \
  examples/tencent_realtime_control/run_control_service.py
```

默认所有执行入口均为 dry-run，必须设置 `RTC_APPLY_ENABLED=1` 或显式传
`--apply` 才会调用腾讯写接口。
`--at` 和 `--cpm-override` 只允许 dry-run。

生产使用统一完整镜像：

```bash
docker build \
  -f Dockerfile.auto_put_ad_mini \
  -t ad-put-agent:local .
```

Compose 从同一镜像启动 `ad-control-service` 和 `ad-daily-service`。完整部署和
dry-run 切换步骤见
`examples/auto_put_ad_mini/docs/unified_services_deployment.md`。
生产 Compose 文件兼容当前 ECS 的 Docker Compose `2.27.0`。

## 日级 ROI 整批审批

`ad-daily-service` 可在每天 11:00 计算版本化的三日 ROI 指标并发布只读飞书表；
`ad-control-service` 复用本服务的唯一飞书 WebSocket 处理整批命令：

```text
确认 roi_<run_id>
拒绝 roi_<run_id>
```

`DAILY_ROI_ENABLED=1` 只开启计算和通知；`ROI_APPLY_ENABLED=1` 才允许审批后
暂停低 ROI 动态创意或提高高 ROI 广告的永久基础出价。ROI 腾讯写操作与实时
CPM 调控共用 `RTC_DB_LOCK_NAME`，并在写入后回读验证。详细开关和分阶段上线
步骤见统一部署文档。

## ECS 首次迁移 ODPS 配置

仅用于旧 `auto_put_ad_mini` 容器仍在运行、但 ECS 的
`/home/server/.env` 缺少 ODPS 环境变量时。命令不会在终端打印密钥值。

先从旧容器迁移配置：

```bash
cd /home/server

sed -i \
  '/^ODPS_ACCESS_ID=/d;/^ODPS_ACCESS_SECRET=/d;/^ODPS_PROJECT=/d' \
  /home/server/.env

docker exec auto_put_ad_mini python -c 'import ast,shlex; tree=ast.parse(open("/app/examples/auto_put_ad_mini/tools/odps_module.py",encoding="utf-8").read()); values={target.attr:node.value.value for node in ast.walk(tree) if isinstance(node,ast.Assign) and isinstance(node.value,ast.Constant) for target in node.targets if isinstance(target,ast.Attribute)}; print("ODPS_ACCESS_ID="+shlex.quote(values["accessId"])); print("ODPS_ACCESS_SECRET="+shlex.quote(values["accessSecret"])); print("ODPS_PROJECT=loghubods")' >> /home/server/.env

chmod 600 /home/server/.env
```

确认变量名已经写入，不显示变量值：

```bash
grep -E '^ODPS_(ACCESS_ID|ACCESS_SECRET|PROJECT)=' /home/server/.env \
  | cut -d= -f1
```

验证 ODPS 查询：

```bash
cd /home/server
VERSION=latest docker compose --env-file /dev/null run --rm \
  ad_control_service \
  python /app/examples/tencent_realtime_control/fetch_daily_hourly_cpm.py \
  --date 20260724
```

这只是旧配置迁移手段。迁移完成后应轮换已经硬编码在旧代码和 Git 历史中的
AccessKey，并将新值只保存在受权限保护的生产环境配置中。

## 环境变量

参考 `.env.example`。部署必须提供 ODPS、MySQL、腾讯 token 服务和飞书应用
配置，不能在代码中写入凭证。通知群优先读取 `RTC_FEISHU_CHAT_ID`，为空时
复用广告调控流程的 `FEISHU_AD_PROJECT_CHAT_ID`；不会回退发送到个人或运营
审批群。`RTC_FEISHU_NOTIFY_ENABLED=0` 可临时关闭
通知。
