PROJECT_STRUCTURE.md 22 KB
auto_put_ad_mini — 项目结构文档
定位: 微信小程序投流 — 面向 ROI 的广告粒度自动调控 + 自动创建投放系统 最后更新: 2026-07-16
一、项目概述
auto_put_ad_mini 是腾讯广告自动化投放系统的核心业务单元，专注微信小程序投流场景（MARKETING_CARRIER_TYPE_MINI_PROGRAM_WECHAT）。
项目已从最初的"数据→决策→执行"单向链路，演进出两条独立但共存的生产线：
| 业务线 | 入口 | 频率 | 职责 |
|---|---|---|---|
| Flow A: 决策调控 | execute_once.py |
每日 1 次 (UTC 02:00) | 分析 ROI + 跑量数据 → LLM 推理 → 出价调整/暂停广告 |
| Flow B: 创建投放 | execute_creation_once.py |
每日 1 次 (UTC 02:30) | 创建新广告 + 准备动态创意 → 提交腾讯审核 |
| Flow C: 审核扫描 | scan_creative_reviews.py |
每 2 小时 | 扫描创意审核结果 → 记录拒审事实 |
核心决策架构: 规则标记候选（Python）→ LLM 综合判断（Claude Sonnet 4.5）→ 护栏兜底（Python），三层递进。
二、目录结构
examples/auto_put_ad_mini/
│
├── 🔵 核心入口
│ ├── run.py # 交互式 Agent REPL
│ ├── execute_once.py # Flow A 主入口：决策调控（10 步 pipeline）
│ ├── execute_creation_once.py # Flow B 主入口：创建投放（Module A + B）
│ ├── execute_creation_apply.py # Flow B Phase 3：独立提交创意到腾讯
│ ├── run_full_analysis.py # 仅数据准备步骤（无 LLM，用于调试）
│ ├── fetch_data.py # 独立数据拉取脚本
│ └── merge_data.py # 独立数据合并脚本
│
├── 🟢 生产服务
│ ├── server.py # FastAPI + APScheduler 生产服务器
│ ├── schedule.sh # Shell Cron 包装脚本
│ ├── k8s/ # Kubernetes 部署清单
│ │ ├── deployment.yaml # Deployment 模式（APScheduler）
│ │ ├── cronjob.yaml # Flow A CronJob
│ │ ├── cronjob_creation.yaml # Flow B CronJob
│ │ ├── cronjob_creative_review.yaml # Flow C CronJob
│ │ ├── configmap.yaml / secret.yaml / pvc.yaml
│ │ └── namespace.yaml / network-policy.yaml
│ └── .env / .env.example # 环境变量
│
├── 🟡 配置与技能
│ ├── config.py # 核心业务配置（~1023 行）
│ ├── presets.json # 预设参数
│ ├── strategy_params.json # 策略参数
│ ├── whitelist.json # 账户白名单（可被 DB 覆盖）
│ ├── prompts/
│ │ └── system.prompt # Agent 系统提示词
│ └── skills/ # 领域知识（注入 LLM 上下文）
│ ├── ad_domain.md # 裂变模型 / R 值 / ROI 公式
│ ├── decision_strategy.md # 决策框架 / 候选标记 / 7 种 action
│ ├── platform_rules.md # 腾讯平台硬约束
│ └── posterior_wisdom.md # 后验经验积累
│
├── 🟣 数据库层
│ └── db/
│ ├── __init__.py # 公开 API
│ ├── connection.py # MySQL 连接（pymysql）
│ ├── config.py # 系统配置 + 白名单 CRUD（5 分钟缓存）
│ └── schema.sql # 12 张表 + 默认种子数据
│
├── 🟠 工具层（31 个文件）
│ └── tools/
│ ├── _names.py # 字段名常量 + 禁止词黑名单
│ ├── ad_api.py # 腾讯广告 API v3.0 封装
│ ├── odps_module.py # ODPS 数据源模块
│ ├── data_query.py # ODPS 数据拉取 + 合并
│ │
│ ├── ── Flow A 核心 ──
│ ├── roi_calculator.py # 动态 ROI (7日均值) 计算器
│ ├── portfolio_metrics.py # 人群包级汇总（tier P50 等）
│ ├── creative_roi_calculator.py # 创意级动态 ROI
│ ├── ad_decision.py # 决策引擎（候选标记 + 三级分类）
│ ├── guardrails.py # 护栏验证（频率/边界/方向）
│ ├── execution_engine.py # 执行引擎（API 调用 + 审计日志）
│ ├── im_approval.py # 飞书审批（发送 + 轮询回复）
│ ├── report_generator.py # 报告生成（Excel + CSV）
│ ├── posterior_collector.py # 后验数据采集
│ └── feishu_doc.py # 飞书文档操作
│ │
│ ├── ── Flow B 核心 ──
│ ├── ad_creation.py # Module A：广告创建
│ ├── creative_creation.py # Module B：创意准备
│ ├── creative_material_usage.py # 素材使用追踪
│ ├── creative_metrics.py # 创意级指标
│ ├── creative_review.py # 创意审核结果扫描
│ ├── material_recall.py # 素材召回（batchByText）
│ ├── video_recall.py # 视频内容列表获取
│ ├── video_risk.py # 视频风险标签检查
│ ├── video_feature_query.py # 视频元素特征查询
│ ├── landing_plan.py # 落地页方案创建（xcx/save）
│ ├── scene_spec.py # 场景规格 / 微信版位
│ ├── audience_grant.py # 人群包授权验证
│ ├── im_approval_ad_creation.py # 广告创建审批
│ ├── im_approval_creation.py # 创意创建审批
│ └── sls_setup.py # SLS 日志上报
│
├── 🔴 辅助脚本
│ ├── sync_ad_status.py # 同步已删除广告状态
│ ├── sync_feishu_account_config.py # 同步飞书账户配置到 DB
│ ├── scan_creative_reviews.py # Flow C 入口
│ ├── configure_creation_accounts.py # 批量写入账户三元组配置
│ ├── quick_analysis.py # 快速分析（使用已有数据）
│ ├── regenerate_metrics.py # 从已有 CSV 重新生成指标
│ ├── analyze_snapshot.py # 决策质量分析（9 维度评估）
│ ├── analyze_dimensions.py # 维度使用率分析
│ ├── verify_decision.py # 决策验证
│ └── get_chat_id.py # 获取飞书群聊 ID
│
├── 📁 数据与文档
│ ├── data/tencent_constants/ # 静态参考数据
│ ├── shared/reports/ # 共享报告产物
│ ├── utils/log_capture.py # 日志捕获
│ ├── docs/ # 分析文档
│ │ ├── strategy_review_2026-04-16.md # 专家级策略 Review
│ │ └── 不走LLM的规则盘点.md # 绕过 LLM 的规则清单
│ └── doc/ # 设计文档
│
└── 🧪 测试文件（~25 个）
├── test_e2e_full_flow.py # 端到端全流程测试
├── test_approval_flow_e2e.py # 审批流程端到端测试
├── test_real_approval_flow.py # 真实审批流程测试
├── test_single_ad.py # 单广告测试
├── test_tencent_api.py # API 连通性测试
└── ...（其余 20+ 个专项测试）
三、Flow A: 决策调控流程（execute_once.py）
3.1 10 步 Pipeline
Step 0: sync_ad_status ← 同步腾讯侧已删除的广告状态
│
Step 1: fetch_creative_data ← ODPS 拉创意原始数据 + 广告状态快照
│ 输出: outputs/raw/creative_{date}.csv
│ outputs/ad_status/ad_status_{date}.csv
Step 2: merge_creative_data ← 合并创意数据 + 广告状态
│ 输出: outputs/merged/
│
Step 3: calculate_roi_metrics ← 计算动态 ROI (7日均值)
│ 输出: outputs/metrics/metrics_{date}.csv
│
Step 3.5: calculate_creative_roi ← 创意级动态 ROI（pause 候选的二次细化依据）
│
Step 4: calculate_portfolio_summary ← 人群包级汇总 (tier P25/P50/P75)
│
Step 5: get_ads_for_review ← 三级分类 + 5 个候选标记计算
│ ├── 零消耗待关停 (规则)
│ ├── 待优化评估 (LLM)
│ └── 正常运行 (规则)
│
Step 6: [LLM 决策] ← Claude Sonnet 4.5 综合推理
│ 注入 skills/*.md 领域知识
│ 输出: 每个广告的 action + reason
│
Step 7: apply_decisions ← 保存决策 + 合并 metrics 字段
│ 输出: outputs/reports/llm_decisions_{date}.csv
│
Step 8: generate_report ← 生成 Excel + CSV 报告
│
Step 9: send_approval_request ← 飞书 IM 审批（发送 + 阻塞等待回复）
│ 含 Excel 附件 + 统计摘要
│
Step 9.5: check_approval_status ← 轮询审批状态（超时 120 分钟）
│
Step 10: execute_decisions ← 执行审批通过的决策
调用 execution_engine → ad_api
写入 audit JSONL 日志
3.2 核心决策架构（三层）
┌─────────────────────────────────────────────────────┐
│ Layer 1: 规则引擎 (ad_decision.py, Python) │
│ │
│ ① 年龄保护：冷启动 ≤3天 → 排除 │
│ 早期成长 4-7天 → 仅允许 bid_up │
│ 成熟期 >7天 → 全面调控 │
│ │
│ ② 零消耗检测：近 N 天消耗=0 → 规则关停 │
│ │
│ ③ 5 个候选标记计算： │
│ ├── roi_low 动态ROI < P50 × 0.75 │
│ ├── bid_down_candidate ROI < P50 × 0.90 │
│ ├── bid_up_candidate ROI > P50 × 1.05 (仅冷启)│
│ ├── decay_signal 裂变率持续下降 │
│ └── high_burn 消耗异常高 + 低ROI │
└─────────────────────────────────────────────────────┘
│ 标记完的广告列表 → 喂给 LLM
▼
┌─────────────────────────────────────────────────────┐
│ Layer 2: LLM 推理 (Claude Sonnet 4.5) │
│ │
│ 注入 skills/*.md 领域知识： │
│ ├── ad_domain.md 裂变模型、R值、ROI公式 │
│ ├── decision_strategy.md 7 种 action、权衡原则 │
│ ├── platform_rules.md oCPM学习期、调价上限 │
│ └── posterior_wisdom.md 历史经验教训 │
│ │
│ 输出 7 种 action： │
│ pause | bid_down | bid_up | scale_up | │
│ creative_adjust | observe | hold │
│ │
│ Reason 规则：纯中文、禁止变量名、解释业务逻辑 │
└─────────────────────────────────────────────────────┘
│ LLM 决策 → 写入 decisions CSV
▼
┌─────────────────────────────────────────────────────┐
│ Layer 3: 护栏验证 (guardrails.py, Python) │
│ │
│ ① 方向检查：bid_down 是否合理（ROI 真的低？） │
│ ② 频率检查：6h 内不能重复调同一广告 │
│ ③ 边界检查：出价必须在 [0.05, 1.00] 元区间 │
│ ④ 日累计检查：当日累计调幅 ≤ 20% │
│ ⑤ 兜底检查：触发次数应为 0（有则说明规则层有漏） │
│ ⑥ DRY_RUN 模式：True → 仅记录不执行 │
└─────────────────────────────────────────────────────┘
3.3 ROI 计算公式
对每一天（日消耗 ≥ 100 元才参与计算）：
T0裂变系数 = T0裂变数 / 首层打开数
arpu = 总收入 / 总回流人数
当日裂变收益率 = T0裂变数 × arpu / cost
当日回流倍数 = 总回流人数 / 首层打开数
7日滚动均值（min_periods=3）：
动态 ROI (7日均值) = 当日裂变收益率 × (回流倍数_7日均值 / T0裂变系数_7日均值)
决策使用规则：
- 广告级决策：使用单广告的动态 ROI (7日均值)
- 人群包评估：使用人群包整体的动态 ROI (7日均值) 均值
- 关停阈值：动态 ROI < 渠道 P50 × 0.75 → 触发 roi_low 标记
四、Flow B: 创建投放流程（execute_creation_once.py）
4.1 多阶段 Pipeline
Phase -1: sync_feishu_account_config ← 飞书配置 → DB (account + template)
│
Phase 0 (Module A): 创建广告
│ ① enumerate_new_ad_candidates 按账户枚举候选
│ ├── 指纹去重：audience × 素材 组合
│ ├── 按 tier ROI 排序
│ └── 目标：每账户 ADS_PER_ACCOUNT=2 个在投广告
│ ② 飞书审批广告创建方案
│ ③ POST /adgroups/add
│ 固定参数：marketing_goal=USER_GROWTH, bid_mode=OCPM
│ targeting: age 45-66, 特定区域, 6:00-23:00 投放
│ day_amount: 200 CNY
│
Phase 1 (Module B): 准备创意
│ ① find_ads_needing_creatives 找缺少创意的广告
│ 目标：每广告 TARGET_CREATIVES_PER_AD=4 个创意
│ ② 对每个广告：
│ ├── video_recall 拉取视频内容列表
│ ├── video_risk 风险标签检查
│ ├── material_recall batchByText 召回（sim ≥ 0.8）
│ ├── material 排序 按消耗降序
│ ├── 7 日去重 同素材同人群包不重复
│ └── landing_plan xcx/save 落地页方案
│ ③ 输出: creation_pending_{date}.json
│
Phase 2: 飞书审批
│ 发送创意候选列表 → 等待运营审批
│ config: CREATION_APPROVAL_REQUIRED=True
│
Phase 3: 提交创意 (execute_creation_apply.py)
① 读取已审批的 pending records
② POST /dynamic_creatives/add
③ 写入 creative_creation_task 表
④ 飞书通知执行结果
4.2 关键配置
| 参数 | 值 | 说明 |
|---|---|---|
ADS_PER_ACCOUNT |
2 | 每账户目标在投广告数 |
TARGET_CREATIVES_PER_AD |
4 | 每广告目标创意数 |
CREATION_APPROVAL_REQUIRED |
True | 创意是否需要审批 |
RECALL_SIM_THRESHOLD |
0.8 | 素材召回相似度阈值 |
RECALL_DAYS |
180 | 素材召回时间窗口 |
MAX_LANDING_ATTEMPTS_PER_AD |
100 | 每广告落地页创建最大尝试次数 |
VIDEO_RISK_MAX_ALLOWED_LEVEL |
5 | 视频风险等级上限 |
五、Flow C: 审核扫描（scan_creative_reviews.py）
每 2 小时执行一次 (k8s CronJob):
creative_review.scan_pending_reviews()
├── 读 DB: creative_creation_task (review_status=pending)
├── 调 API: GET /dynamic_creatives/get (查审核结果)
├── 写 DB: creative_review_result (审核结果)
└── 写 DB: creative_rejection_fact (拒审事实，供后续召回排除)
六、入口点全景
| 入口 | 类型 | 用途 | 谁来调用 |
|---|---|---|---|
run.py |
交互 REPL | 开发调试、人工分析 | 开发者手动 |
execute_once.py |
自动化脚本 | Flow A 决策调控 | K8s CronJob / server.py |
execute_creation_once.py |
自动化脚本 | Flow B 创建投放 | K8s CronJob |
execute_creation_apply.py |
可独立执行 | Flow B Phase 3 独立提交 | 手动或 import |
run_full_analysis.py |
调试工具 | 仅数据准备（无 LLM） | 开发者手动 |
fetch_data.py |
独立工具 | 仅拉取 ODPS 数据 | 开发者手动 |
merge_data.py |
独立工具 | 仅合并数据 | 开发者手动 |
server.py |
常驻服务 | 生产 APScheduler 调度 | K8s Deployment |
scan_creative_reviews.py |
自动化脚本 | Flow C 审核扫描 | K8s CronJob（每 2h） |
sync_ad_status.py |
辅助脚本 | 同步广告状态 | execute_once.py Step 0 |
sync_feishu_account_config.py |
辅助脚本 | 同步飞书账户配置 | execute_creation_once.py Phase -1 |
configure_creation_accounts.py |
运维工具 | 批量写入账户配置 | 运维手动 |
七、部署架构
7.1 两种部署模式
| 模式 | 文件 | 调度方式 | 优点 |
|---|---|---|---|
| Deployment + APScheduler | k8s/deployment.yaml + server.py |
APScheduler 读取 DB cron_schedule |
HTTP 健康检查、手动触发 API、单 Pod |
| Kubernetes CronJob | k8s/cronjob*.yaml |
K8s CronJob | 简单、K8s 原生重试 |
7.2 时间线
UTC 02:00 (北京时间 10:00) → Flow A: 决策调控
UTC 02:30 (北京时间 10:30) → Flow B: 创建投放（与 A 间隔 30 分钟避免 API 争用）
每 2 小时 → Flow C: 创意审核扫描
7.3 动态配置（DB 驱动）
| 配置项 | DB 表 | 默认值 | 说明 |
|---|---|---|---|
cron_schedule |
system_config |
0 2 * * * |
调度表达式 |
execution_enabled |
system_config |
false |
是否启用实际执行 |
run_on_startup |
system_config |
false |
启动时是否执行一次 |
whitelist_enabled |
system_config |
true |
白名单机制开关 |
roi_low_factor |
system_config |
0.75 |
关停线系数 |
优先级：DB > 环境变量 > 代码默认值
八、数据库表（12 张）
| 表名 | 用途 | Flow |
|---|---|---|
account_whitelist |
账户白名单 | A/B |
ad_delivery_template |
投放模板（出价/定向/预算） | B |
ad_creation_account_config |
账户 × 人群包 × 出价配置 | B |
brand_asset_template |
品牌资产模板 | B |
feedback_asset_template |
反馈资产模板 | B |
system_config |
系统配置（KV） | A/B |
decision_history |
决策历史 | A |
creative_creation_task |
创意创建任务 | B/C |
creative_review_result |
创意审核结果 | C |
creative_rejection_fact |
创意拒审事实 | C |
video_element_feature_cache |
视频特征缓存 | B |
creative_material_usage |
素材使用记录（7 日去重） | B |
九、与 auto_put_ad 的关系
auto_put_ad (完整体系) auto_put_ad_mini (当前生产)
┌──────────────────────┐ ┌──────────────────────────┐
│ 受众策略 Agent │ │ │
│ 创意策略 Agent │ │ Flow A: 决策调控 │
│ 预算策略 Agent ───────┼──出价──▶ │ (规则→LLM→护栏→执行) │
│ 监控调控 Agent ───────┼──决策──▶ │ │
│ 数据分析 Agent │ │ Flow B: 创建投放 │
│ 系统运维 Agent │ │ (广告+创意+审批+提交) │
│ 自学习/反馈环 │ │ │
└──────────────────────┘ │ Flow C: 审核扫描 │
└──────────────────────────┘
auto_put_ad_mini最初是auto_put_ad中「监控调控 Agent」的独立落地版- 实际演进中，mini 发展出了更完整的决策三层架构和独立的创建子系统
- 两者共享
tools/ad_api.py的腾讯广告 API 封装思路和skills/领域知识 - mini 的
ad_decision.py三层架构可作为大项目后续迭代的参考
十、关键设计原则
- 三层决策架构: 规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
- 两条业务线解耦: 决策调控和创建投放使用独立的入口/CronJob/审批流，避免互相阻塞
- DB 驱动配置: 关键开关（执行启用/白名单/调度表达式）在 DB 中，无需重启即可调整
- 人工审批嵌入: 执行前必须通过飞书 IM 审批（可配置关闭），含 Excel 附件 + 统计摘要
- 7 日去重保护: 素材使用记录保留 7 天，防止同一素材重复提交审核
- 年龄分层保护: ≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
- 提降分离: 提价 5%-10%、降价 3%-5%，降价更保守（因为 oCPM 模式下降价效果非线放大）