广告引擎 — Facebook 广告部署

从数据库组件组装广告，并部署至 Facebook。读取 Supabase 的 ad_components 和 messages 表，拼装完整广告文案，上传图片，并在 Facebook Ads Manager 中创建 Campaign → Ad Set → Ad。

首次设置

1. Facebook 前置条件（一次性，需手动完成）：

• Facebook Business Manager 账户
• 已创建广告账户（Ad Account）
• 已关联 Facebook 页面（Page）
• 已在 Facebook Developer 平台注册应用（App），并授予 ads_management 权限
• 已获取长期有效访问令牌（Long-lived access token，可在 developers.facebook.com 生成）

2. 存储凭证：

python3 scripts/fb_deploy.py --setup

将提示输入访问令牌（access token）、广告账户 ID（ad account ID）和页面 ID（page ID）。脚本会调用 Facebook API 进行验证，并将配置保存至 ~/.config/ad-engine/fb_config.json。

使用方法

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

# 预览单条广告
python3 scripts/fb_deploy.py --preview --message-id 8555

# 预览某 Campaign 下所有草稿状态广告
python3 scripts/fb_deploy.py --preview --campaign-id 43

# 以 JSON 格式输出预览结果
python3 scripts/fb_deploy.py --preview --campaign-id 43 --json

部署单条广告：

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

批量部署某 Campaign 下所有草稿广告：

python3 scripts/fb_deploy.py --deploy 
  --campaign-id 43 
  --image-dir /path/to/ad-images/ 
  --landing-url "https://calendly.com/your-link" 
  --objective messages

试运行（预览实际将创建的内容，不执行任何写入操作）：

python3 scripts/fb_deploy.py --deploy 
  --campaign-id 43 
  --image-dir /path/to/images/ 
  --landing-url "https://calendly.com/link" 
  --dry-run

检查已部署广告的状态及实时数据指标：

python3 scripts/fb_deploy.py --status --campaign-id 43

参数说明

图片命名规范

使用 --image-dir 批量部署时，请按广告角度（angle）命名图片文件：

security-audit-ad.png      → 匹配 angle "security_audit"
setup-is-hell-ad.png       → 匹配 angle "setup_is_hell"
dm-trigger-checklist.png   → 匹配 angle "dm_trigger"
anti-wrapper-graveyard.png → 匹配 angle "anti_wrapper"

工作原理

1. 从 Supabase messages 表中读取消息（要求 content_type = 'fb_ad'）
2. 解析该消息的 extra_data.components 字段，获取所引用的组件键列表
3. 根据组件键，从 ad_components 表中查出对应的实际文案内容
4. 将各组件内容填入框架模板中的 {{merge_tags}} 占位符位置
5. 将广告图片上传至 Facebook，获取返回的 image_hash
6. 依次创建 Campaign（如为新 Campaign）、Ad Set（如为新 Ad Set）、Ad Creative 和 Ad
7. 更新 messages 表中对应记录的状态为 'deployed'，并将 Facebook 分配的各层级 ID 存入 extra_data

数据库结构

完整数据库 Schema 文档请参见 AD_ENGINE_SPEC.md。

依赖项

• psycopg2-binary — 用于连接 Supabase PostgreSQL 数据库
• facebook-business — Facebook Marketing API 官方 SDK
• requests — HTTP 客户端库
• 所有依赖将在首次运行时自动安装。