Ad Engine — Facebook 广告部署

从数据库组件组装广告并部署到 Facebook。读取 Supabase 的 ad_components 和 messages 表，组装完整的广告文案，上传图片，并在 Facebook 广告管理器中创建广告系列 → 广告组 → 广告。

首次设置

1. Facebook 前置条件（一次性手动操作）：

• - Facebook 商务管理平台账户
• 已创建的广告账户
• 已关联的 Facebook 主页
• 拥有 ads_management 权限的 Facebook 开发者应用
• 长期有效的访问令牌（在 developers.facebook.com 生成）

2. 存储凭证：
bash
python3 scripts/fb_deploy.py --setup

提示输入访问令牌、广告账户 ID 和主页 ID。通过 Facebook API 验证后保存至 ~/.config/ad-engine/fb_config.json。

使用方法

预览已组装的广告（不部署）：
bash

预览单个广告

预览某个广告系列的所有草稿广告

以 JSON 格式预览

部署单个广告：
bash
python3 scripts/fb_deploy.py --deploy \
--message-id 8556 \
--image /path/to/security-audit-ad.png \
--landing-url https://calendly.com/your-link \
--objective messages

部署某个广告系列的所有草稿广告：
bash
python3 scripts/fb_deploy.py --deploy \
--campaign-id 43 \
--image-dir /path/to/ad-images/ \
--landing-url https://calendly.com/your-link \
--objective messages

试运行（预览将要创建的内容）：
bash
python3 scripts/fb_deploy.py --deploy \
--campaign-id 43 \
--image-dir /path/to/images/ \
--landing-url https://calendly.com/link \
--dry-run

检查已部署广告的状态和实时指标：
bash
python3 scripts/fb_deploy.py --status --campaign-id 43

参数

图片命名规范

使用 --image-dir 进行批量部署时，按角度命名图片：

security-audit-ad.png → 匹配角度 security_audit
setup-is-hell-ad.png → 匹配角度 setupishell
dm-trigger-checklist.png → 匹配角度 dm_trigger
anti-wrapper-graveyard.png → 匹配角度 anti_wrapper

工作原理

1. 1. 从 Supabase 的 messages 表读取消息（contenttype = fbad）
2. 从消息的 extradata.components 读取组件引用
3. 解析组件键 → 从 adcomponents 表获取实际文本
4. 使用 {{mergetags}} 将组件填入框架模板
5. 上传图片到 Facebook → 获取 imagehash
6. 创建广告系列（如为新）→ 广告组（如为新）→ 广告创意 → 广告
7. 将消息状态更新为 deployed，并将 Facebook ID 存储在 extra_data 中

数据库架构

完整架构文档请参见 ADENGINESPEC.md。

依赖项

• - psycopg2-binary — Supabase Postgres 连接
• facebook-business — Facebook 营销 API SDK
• requests — HTTP 客户端
• 首次运行时自动安装所有依赖。