PROJECT_STRUCTURE.md 42 KB
auto_put_ad_mini — 项目结构文档
定位: 微信小程序投流 — 面向 ROI 的广告粒度自动调控 + 自动创建投放系统 最后更新: 2026-08-06
一、项目概述
auto_put_ad_mini 是腾讯广告自动化投放系统的核心生产单元，专注微信小程序投流场景（MARKETING_CARRIER_TYPE_MINI_PROGRAM_WECHAT）。
项目包含四条独立但协同的生产线：
| 业务线 | 入口 | 频率 | 职责 |
|---|---|---|---|
| Flow A: 决策调控 | execute_once.py |
每日 1 次 | Agent 驱动：LLM 动态编排工具调用 → ROI 分析 → 出价调整/暂停广告 |
| Flow B: 创建投放 | execute_creation_once.py |
每日 1 次 | 硬编码 Pipeline：创建广告 → 准备创意 → 飞书审批 → 提交腾讯 |
| Flow C: 审核扫描 | scan_creative_reviews.py |
每 2 小时 | 硬编码循环：扫描创意审核结果 → 记录拒审事实 |
| Flow D: ROI 精算 | roi_control/ + run_daily_roi.py |
每日 1 次 | 版本化日级 ROI 计算：动态ROI → T15成熟系数 → 策略规则 → 飞书行级审批 → 执行 |
两种执行模式：
- Flow A：Agent 驱动 —
execute_once.py通过 Agent 框架启动 LLM，由 LLM 动态决定调用哪些工具、以何种顺序执行。system prompt 中嵌入了推荐的执行流程，但实际编排权在模型。 - Flow B / C / D：确定性 Pipeline —
execute_creation_once.py、scan_creative_reviews.py和roi_control/是硬编码的多阶段脚本，不经过 LLM 编排。
二、目录结构
examples/auto_put_ad_mini/
│
├── 🔵 核心入口
│ ├── run.py # 交互式 Agent REPL（开发调试）
│ ├── execute_once.py # Flow A 主入口：Agent 驱动决策调控
│ ├── execute_once_test.py # Flow A 无审批模式（发审批但不阻塞等待，跳过执行）
│ ├── 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 # 独立数据合并脚本
│ └── logging_setup.py # ★统一日志基础设施（SLS + 本地文件）
│
├── 🟢 生产服务
│ ├── run_daily_service.py # ★ 生产日级服务入口（APScheduler，Flow B + C + D）
│ ├── run_daily_roi.py # ★ Flow D 入口：版本化日级 ROI 计算 + 飞书审批
│ ├── server.py # 旧版生产服务器（FastAPI + APScheduler，仅 Flow A，历史保留）
│ ├── schedule.sh # Shell Cron 包装脚本
│ ├── test_scheduler.sh # 调度器测试脚本
│ ├── .env.example # 环境变量声明模板
│ └── requirements.txt # 项目专属 Python 依赖
│
├── 🟡 配置与技能
│ ├── config.py # 核心业务配置
│ ├── presets.json # Agent 预设参数
│ ├── strategy_params.json # 策略参数
│ ├── whitelist.json # 账户白名单（可被 DB 覆盖）
│ ├── configs/
│ │ └── material_creative_patterns_seed.json # 素材创意范式种子数据
│ ├── prompts/
│ │ ├── system.prompt # Flow A Agent 系统提示词（嵌入推荐执行流程）
│ │ ├── ai_cover_copy.md # AI 封面文案生成 Prompt
│ │ ├── ai_generated_material.md # AI 素材生成 Prompt
│ │ ├── ai_pattern_selector.md # AI 创意范式选择 Prompt
│ │ ├── ai_sanitize_video_description.md # 视频描述清洗 Prompt
│ │ └── external_material_cleanup.md # 外部素材清洗 Prompt
│ └── skills/ # 领域知识（注入 Agent system prompt）
│ ├── ad_domain.md # 裂变模型 / R 值 / 动态 ROI 公式
│ ├── decision_strategy.md # 决策框架 / 候选标记 / 7 种 action / 权衡原则
│ ├── platform_rules.md # 腾讯平台硬约束（oCPM 学习期 / API 限制）
│ └── posterior_wisdom.md # 后验经验积累
│
├── 🟣 数据库层
│ └── db/
│ ├── __init__.py # 公开 API
│ ├── connection.py # MySQL 连接（pymysql + 连接池）
│ ├── config.py # 系统配置 + 白名单 CRUD（5 分钟缓存）
│ └── schema.sql # 12 张表 + 默认种子数据
│
├── 🟤 Flow D: ROI 精算子系统（2026-07 新增）
│ └── roi_control/
│ ├── __init__.py # 包初始化
│ ├── config.py # 日级 ROI 计算配置 + 代理商 Webhook 配置
│ ├── service.py # 编排入口：单次幂等 ROI 计算 + 审批批次
│ ├── data_source.py # 数据源抽象（ODPS + DB）
│ ├── metrics.py # 日级 ROI 指标计算（动态ROI、P25/P50/P75）
│ ├── policy.py # 策略规则（关停 / 降价决策）
│ ├── rules.py # 基础规则引擎
│ ├── reporting.py # 报表生成（P20/P80 离线调控报表等）
│ ├── fission_multiplier.py # T15 成熟系数（企微系数）计算与应用
│ ├── fission_multiplier_refresh.py # T15 系数刷新逻辑
│ ├── execution.py # 审批通过后的执行引擎
│ ├── repository.py # 数据持久化（DB 读写）
│ ├── odps_client.py # ODPS 客户端封装
│ ├── feishu.py # 飞书消息发布
│ ├── sheet_approval.py # 飞书电子表格行级审批
│ ├── agency_delivery.py # 代理商 Webhook 报表分发
│ ├── data/
│ │ └── fission_multiplier/
│ │ └── 20260712_A0-A15_v1/ # T15 系数 CSV（公众号 + 小程序 + 回退系数）
│ └── sql/
│ └── fission_multiplier/
│ └── 20260712_A0-A15_v1/ # T15 系数计算 SQL（公众号 + 小程序）
│
├── 🟠 工具层（36 个文件，含 `__init__.py`）
│ └── tools/
│ ├── __init__.py # 包初始化
│ ├── _names.py # 字段名常量 + 禁止词黑名单
│ │
│ ├── ── 腾讯 API + 数据层 ──
│ ├── ad_api.py # 腾讯广告 API v3.0 封装（读写统一入口）
│ ├── odps_module.py # ODPS 数据源模块
│ ├── data_query.py # ODPS + Reporting API 数据拉取与合并
│ │
│ ├── ── Flow A：决策调控 ──
│ ├── roi_calculator.py # 动态 ROI（7日均值）计算器
│ ├── creative_roi_calculator.py # 创意级动态 ROI（pause 候选二次细化依据）
│ ├── portfolio_metrics.py # 人群包级汇总（P25/P50/P75）
│ ├── ad_decision.py # 决策引擎（候选标记 + 三级分类 + LLM 评估）
│ ├── guardrails.py # 护栏验证（频率 / 边界 / 方向 / 兜底）
│ ├── execution_engine.py # 执行引擎（API 调用 + 审计日志）
│ ├── im_approval.py # 飞书审批（Flow A：发送 + 阻塞轮询回复）
│ ├── 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 # 素材使用追踪（7 日去重）
│ ├── creative_metrics.py # 创意级指标
│ ├── creative_review.py # 创意审核结果扫描（Flow C 核心逻辑）
│ ├── material_recall.py # 素材召回（batchByText，sim ≥ 0.8）
│ ├── external_recalled_material.py # 外部素材召回工作流
│ ├── video_recall.py # 视频内容列表获取
│ ├── video_risk.py # 视频风险标签检查
│ ├── video_feature_query.py # 视频元素特征查询（ODPS 贡献度分析）
│ ├── landing_plan.py # 落地页方案创建（xcx/save）
│ ├── scene_spec.py # 场景规格 / 微信版位
│ ├── audience_grant.py # 人群包授权验证
│ ├── im_approval_ad_creation.py # 广告创建审批（飞书 Sheet + 轮询）
│ ├── im_approval_creation.py # 创意创建审批
│ └── sls_setup.py # SLS 日志上报
│ │
│ ├── ── Flow B：AI 素材 ──
│ ├── account_material_strategy.py # 账户级素材来源策略（历史 / AI 生成）
│ ├── ai_generated_material.py # AI 生成创意图片素材（LiblibAI 等）
│ ├── ai_material_review.py # AI 生成素材审核（Gemini Flash）
│ └── material_strategy_learning.py # 素材策略学习持久化（高消耗快照 + 标注）
│ │
│ └── ── 投放配置 ──
│ └── delivery_config.py # 投放配置解析（出价模式 / 版位 / 地域）
│
├── 🔴 辅助脚本与工具
│ ├── refresh_roi_fission_multiplier.py # T15 成熟系数刷新入口
│ ├── metrics.py # Prometheus 指标导出（可选，需 prometheus-client）
│ ├── sync_ad_status.py # 同步已删除广告状态
│ ├── sync_feishu_account_config.py # 同步飞书账户配置到 DB
│ ├── scan_creative_reviews.py # Flow C 入口（独立的 2h 循环脚本）
│ ├── configure_creation_accounts.py # 批量写入账户三元组配置
│ ├── seed_material_creative_patterns.py # 素材创意范式种子数据导入
│ ├── import_material_strategy_learning.py # 素材策略学习数据导入
│ ├── quick_analysis.py # 快速分析（使用已有数据）
│ ├── regenerate_metrics.py # 从已有 CSV 重新生成指标
│ ├── analyze_snapshot.py # 决策质量分析（9 维度评估）
│ ├── analyze_dimensions.py # 维度使用率分析
│ ├── verify_decision.py # 决策验证
│ ├── run_decision_test.py # 决策引擎单元测试（绕过 Agent，直接测 ad_decision）
│ └── get_chat_id.py # 获取飞书群聊 ID
│
├── 🐛 调试脚本
│ ├── debug_generate_ai_material.py # AI 素材生成调试
│ └── debug_select_creative_patterns.py # 创意范式选择调试
│
├── 🧪 测试文件（27 个）
│ ├── test_e2e_full_flow.py # 端到端全流程测试
│ ├── test_approval_flow_e2e.py # 审批流程端到端测试
│ ├── test_real_approval_flow.py # 真实审批流程测试
│ ├── test_single_ad.py # 单广告测试
│ ├── test_tencent_api.py # API 连通性测试
│ ├── test_creative_review_scan.py # 创意审核扫描测试
│ ├── test_ai_generated_materials.py # AI 素材生成测试
│ ├── test_hot_video_feature_enrichment.py # 热门视频特征增强测试
│ ├── test_landing_video_dedupe.py # 落地视频去重测试
│ ├── test_video_recall_pagination.py # 视频召回分页测试
│ ├── test_compute_signal_scores.py # 信号分数计算测试
│ ├── test_ad_creation_status.py # 广告创建状态测试
│ ├── test_production_creation_entry.py # 生产创建入口集成测试
│ ├── test_feishu_approval.py # 飞书审批测试
│ ├── test_feishu_import.py # 飞书数据导入测试
│ ├── test_im_approval_creation.py # IM 审批创建测试
│ ├── test_approval_replay.py # 审批回放测试
│ ├── test_chat_send.py # 飞书消息发送测试
│ ├── test_send_with_sheet.py # 飞书 Sheet 发送测试
│ ├── test_send_with_sheet_simple.py # 飞书 Sheet 简化测试
│ ├── test_strategy_upgrade.py # 策略升级测试
│ ├── test_api_simple.py # API 简单连通性测试
│ ├── test_analysis_0415.py # 0415 分析验证
│ ├── test_roi_agency_delivery.py # ROI 代理商报表分发测试
│ ├── test_roi_control_metrics.py # ROI 精算指标测试
│ ├── test_roi_control_policy.py # ROI 精算策略测试
│ └── test_roi_fission_multiplier.py # T15 成熟系数测试
│
├── 📁 K8s 部署清单
│ └── k8s/
│ ├── deployment.yaml # Deployment 模式（APScheduler）
│ ├── cronjob_creation.yaml # Flow B CronJob
│ ├── cronjob_creative_review.yaml # Flow C CronJob
│ ├── configmap.yaml
│ ├── secret.yaml
│ ├── pvc.yaml
│ ├── namespace.yaml
│ └── network-policy.yaml
│
├── 📁 数据与 SQL
│ ├── data/tencent_constants/
│ │ ├── regions_sop_current.json # SOP 地域参考数据
│ │ └── regions_all.json # 全量地域数据
│ ├── sql/
│ │ └── high_consumption_materials_30d.sql # 30 日高消耗素材查询
│ ├── shared/reports/ # 共享分析报告
│ └── utils/log_capture.py # 日志捕获
│
└── 📚 文档
├── PROJECT_STRUCTURE.md # ★ 本文档
├── CLAUDE.md # 项目级 Claude 开发指南 + 工程纪律
├── ONBOARDING.md # 新人上手文档
├── DEPLOYMENT.md # 部署指南
├── PRODUCTION_AUTOMATION.md # 生产自动化说明
├── SCHEDULER_GUIDE.md # 调度器使用指南
├── APPROVAL_FLOW_UPDATE.md # 审批流程更新说明
├── CREATIVE_CREATION_TODO.md # 创意创建待办
├── TEST_RESULT.md # 测试结果
├── DOCKER_TEST.md # Docker 测试指南
├── test_db_summary.md # DB 测试汇总
├── doc/
│ └── skill_refactor_plan_20260422.md # Skill 重构方案
└── docs/
├── ad_automation_platform_architecture_plan_2026-07-25.md # 统一平台架构方案
├── unified_services_deployment.md # 统一服务部署方案
├── ai_material_strategy_plan_2026-07-07.md # AI 素材策略方案
├── material_strategy_learning_db_design_2026-07-08.md # 素材策略学习 DB 设计
├── strategy_review_2026-04-16.md # 专家级策略 Review
├── 不走LLM的规则盘点.md # 绕过 LLM 的规则清单
└── roi/
├── T15成熟系数计算说明.md # T15 成熟系数的计算口径与数据说明
└── T15成熟系数迁移指南.md # T15 系数迁移到其他工程的步骤
三、Flow A: 决策调控（execute_once.py）
3.1 执行模型：Agent 驱动，非硬编码 Pipeline
关键认知：
execute_once.py不是一个步骤固定的脚本。它启动一个 Agent（AgentRunner），将控制权交给 LLM。LLM 读取 system prompt 中嵌入的推荐流程，动态决定调用哪些工具、以何种顺序调用。
实际运行时，LLM 通常会按以下顺序调用工具（顺序由 system prompt 中的推荐流程引导，但 LLM 可以跳过、重排或插入中间步骤）：
用户消息："分析广告，执行完整的ROI计算和决策流程"
│
▼
┌─ Agent Loop（LLM 动态编排）────────────────────────────────────────┐
│ │
│ ① fetch_creative_data ODPS 拉创意数据 + 广告状态快照 │
│ → outputs/raw/creative_{date}.csv │
│ → outputs/ad_status/ad_status_{date}.csv│
│ │
│ ② merge_creative_data 合并（LLM 可能自动调用，也可能跳过） │
│ │
│ ③ calculate_roi_metrics 计算动态 ROI（7日均值） │
│ → outputs/metrics/metrics_{date}.csv │
│ │
│ ④ calculate_creative_roi 创意级动态 ROI（pause 二次细化依据） │
│ │
│ ⑤ calculate_portfolio_summary 人群包级汇总（P25/P50/P75） │
│ │
│ ⑥ get_ads_for_review 三级分类 + 候选标记 │
│ ├── 零消耗待关停（规则直达） │
│ ├── 待优化评估（进入 LLM 推理） │
│ └── 正常运行（跳过） │
│ │
│ ⑦ [LLM 推理] Agent 自身对候选广告做综合判断 │
│ 注入 skills/*.md 领域知识 │
│ 输出: action + reason │
│ │
│ ⑧ apply_decisions 保存决策 + 合并 metrics 字段 │
│ → outputs/reports/llm_decisions_{date}.csv│
│ │
│ ⑨ validate_decisions 护栏验证（频率/边界/方向/兜底） │
│ │
│ ⑩ generate_report 生成 Excel + CSV 报告 │
│ │
│ ⑪ send_approval_request 飞书 IM 审批（发送 + 阻塞等待回复） │
│ 含 Excel 附件 + 统计摘要 │
│ │
│ ⑫ check_approval_status 轮询审批状态（超时 120 分钟） │
│ │
│ ⑬ execute_decisions 执行审批通过的决策 │
│ → execution_engine → ad_api │
│ → audit JSONL 日志 │
│ │
│ ⑭ check_execution_feedback 执行效果检查 │
│ │
└─────────────────────────────────────────────────────────────────────┘
execute_once_test.py是该流程的无审批模式变体：发送审批请求但不阻塞等待，跳过执行步骤，仅生成报告收尾。用于无运营人员值班的场景。
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 推理 (Agent 自身，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 计算公式
项目使用动态 ROI（7日均值）作为核心决策指标，而非简单 ROI。
对每一天（日消耗 ≥ 100 元才参与计算）：
T0裂变系数 = T0裂变数（fission0_count）/ 首层打开数（open_count）
arpu = 总收入 / 总回流人数
当日裂变收益率 = T0裂变数 × arpu / cost
当日回流倍数 = 总回流人数 / 首层打开数
7 日滚动均值（min_periods=3，至少 3 天合格数据即可计算）：
T0裂变系数_7日均值 = mean(T0裂变系数) over 7 天
回流倍数_7日均值 = mean(当日回流倍数) over 7 天
裂变效率稳定因子 = 回流倍数_7日均值 / T0裂变系数_7日均值
动态 ROI（7日均值）= 当日裂变收益率 × 裂变效率稳定因子
决策使用规则：
- 广告级决策：使用单广告的动态 ROI（7日均值）
- 人群包评估：使用人群包整体的动态 ROI（7日均值）均值
- 关停阈值：动态 ROI < 渠道 P50 ×
ROI_LOW_FACTOR（默认 0.75）→ 触发roi_low标记
四、Flow B: 创建投放（execute_creation_once.py）
4.1 执行模型：硬编码多阶段 Pipeline
与 Flow A 不同，
execute_creation_once.py是确定性 Python 脚本，不经过 Agent 框架。所有步骤按固定顺序执行，不依赖 LLM 编排。
Phase -1: sync_feishu_account_config ← 飞书配置 → DB（account + template）
│
Phase 0 (Module A): 创建广告
│ ① enumerate_new_ad_candidates 按账户枚举候选
│ ├── 指纹去重：audience × 素材 组合
│ ├── 按 tier ROI 排序
│ └── 目标：每账户 ADS_PER_ACCOUNT=2 个在投广告
│ ② 飞书审批广告创建方案（im_approval_ad_creation.py）
│ ③ 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=8 个合格创意
│ ② 对每个广告：
│ ├── account_material_strategy 判断素材来源（历史 / AI 生成 / 外部召回）
│ ├── video_recall 拉取视频内容列表
│ ├── video_risk 风险标签检查（≥6 拦截）
│ ├── video_feature_query 查询 ODPS 视频特征（解构选题/实质）
│ ├── material_recall batchByText 召回（sim ≥ 0.8）
│ ├── external_recalled_material 外部素材召回工作流
│ ├── material 排序 按消耗降序
│ ├── 7 日去重 同素材同人群包不重复
│ └── landing_plan xcx/save 落地页方案
│ ③ 输出: creation_pending_{date}.json
│
Phase 2: 飞书审批
│ 发送创意候选列表 → 等待运营审批（im_approval_creation.py）
│ config: CREATION_APPROVAL_REQUIRED=True
│
Phase 3: 提交创意 (execute_creation_apply.py)
① 读取已审批的 pending records
② POST /dynamic_creatives/add
③ 写入 creative_creation_task 表
④ 飞书通知执行结果
4.2 AI 素材链路（2026-07 新增）
部分账户支持 AI 生成素材替代历史素材召回：
account_material_strategy.py 判断素材来源
│
├── source=history（默认）→ 走传统素材召回链路（Phase 1②）
│
└── source=ai_generated → 走 AI 生成链路：
① ai_generated_material.py 调用 LiblibAI / 其他生成引擎
② ai_material_review.py Gemini Flash 审核生成结果
③ ai_pattern_selector.md 范式选择 Prompt
④ ai_cover_copy.md 封面文案生成 Prompt
⑤ 审核通过 → 进入 landing_plan + 审批流程
素材策略学习（material_strategy_learning.py）：
- 独立于创建管线，不产生腾讯侧副作用
- 存储高消耗素材快照 + 视觉标注
- 为后续素材范式优化提供数据基础
4.3 关键配置
| 参数 | 默认值 | 说明 |
|---|---|---|
ADS_PER_ACCOUNT |
2 | 每账户目标在投广告数 |
TARGET_CREATIVES_PER_AD |
8 | 每广告目标合格创意数 |
CREATION_APPROVAL_REQUIRED |
True | 创意是否需要审批 |
RECALL_SIM_THRESHOLD |
0.8 | 素材召回相似度阈值 |
RECALL_DAYS |
180 | 素材召回时间窗口 |
MAX_LANDING_ATTEMPTS_PER_AD |
100 | 每广告落地页创建最大尝试次数 |
VIDEO_RISK_MAX_ALLOWED_LEVEL |
5 | 视频风险等级上限（6-10 拦截） |
五、Flow C: 审核扫描（scan_creative_reviews.py）
确定性脚本，不经过 Agent 框架：
每 2 小时执行一次：
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（拒审事实，供后续召回排除）
DENIED 创意不计入有效创意，触发自动补量。
六、Flow D: ROI 精算子系统（roi_control/，2026-07 新增）
6.1 定位
Flow D 是独立于 Flow A 的版本化日级 ROI 精确计算与执行管线。与 Flow A（LLM 驱动、依赖 skills 注入的领域知识）不同，Flow D 是完全确定性的 Python Pipeline，所有阈值、规则、系数均固定在代码和配置中。
为什么需要 Flow D？
- Flow A 依赖 LLM 做综合判断，灵活但有幻觉风险
- Flow D 用于需要精确可审计的场景：T15 成熟系数计算、代理商报表分发、行级飞书审批
- 两条线互补：Flow A 处理"灰色地带"的广告微调，Flow D 处理"白纸黑字"的关停/降价
6.2 执行流程
run_daily_roi.py（入口 CLI）
│
▼
roi_control/service.py ← 单次幂等编排
│
├── ① 拉取数据（data_source.py → ODPS + DB）
│ ├── 日级广告消耗、转化、裂变数据
│ └── 账户/人群包元数据
│
├── ② 计算指标（metrics.py）
│ ├── 动态 ROI（7日均值）
│ ├── P25 / P50 / P75 人群包级别
│ ├── 三日关停优先级排序
│ └── 加权日级 P25（两日加权）
│
├── ③ 应用 T15 成熟系数（fission_multiplier.py）
│ ├── 加载 T15 系数 CSV（小程序 + 公众号）
│ ├── 按人群包 × 投放载体匹配系数
│ └── 企微回退系数应用
│
├── ④ 策略判断（policy.py + rules.py）
│ ├── 关停线：动态 ROI < P50 × roi_low_factor
│ ├── 降价线：动态 ROI < P50 × bid_down_factor
│ ├── 创意关停上限（按消耗预算封顶）
│ └── 三日关停优先
│
├── ⑤ 生成报表（reporting.py）
│ ├── 标准日级 ROI 报表
│ ├── P20/P80 离线调控报表
│ └── 三日关停报表
│
├── ⑥ 飞书审批（sheet_approval.py）
│ ├── 行级审批：每条决策独立审批卡
│ ├── 审批通过 → 进入执行队列
│ └── 审批拒绝 → 记录原因，不执行
│
├── ⑦ 执行（execution.py）
│ └── 审批通过的决策 → ad_api 调用
│
└── ⑧ 分发报表（agency_delivery.py）
└── 按代理商 → 飞书 Webhook 分发
6.3 T15 成熟系数（企微系数）
Flow D 的核心差异化能力之一：
- 定义：基于 2026-07-12 首层投放用户 cohort，观察至 2026-07-27（T15），计算不同人群包（A0-A15）的裂变成熟系数
- 用途：在计算动态 ROI 时乘以成熟系数，消除"新包天然低 ROI"的偏差
- 数据源：ODPS 裂变埋点数据 → SQL 聚合 → CSV 系数表
- 刷新：
refresh_roi_fission_multiplier.py或roi_control/fission_multiplier_refresh.py - 文档：
docs/roi/T15成熟系数计算说明.md、docs/roi/T15成熟系数迁移指南.md
七、入口点全景
| 入口 | 执行模型 | 用途 | 谁来调用 |
|---|---|---|---|
run.py |
Agent REPL | 交互式调试、人工分析 | 开发者手动 |
execute_once.py |
Agent 驱动 | Flow A 决策调控（LLM 编排工具） | K8s CronJob / server.py |
execute_once_test.py |
Agent 驱动 | Flow A 无审批模式（不阻塞等待审批） | 无运营时的无人值守测试 |
execute_creation_once.py |
硬编码 Pipeline | Flow B 创建投放 | run_daily_service.py / K8s CronJob |
execute_creation_apply.py |
硬编码脚本 | Flow B Phase 3 独立提交 | 手动或 import |
run_daily_service.py |
常驻调度 | ★ 生产日级服务（Flow B + C + D，APScheduler） | Docker Compose / K8s Deployment |
run_daily_roi.py |
硬编码脚本 | Flow D 入口：版本化日级 ROI + 飞书行级审批 | run_daily_service.py / 手动 |
run_full_analysis.py |
调试工具 | 仅数据准备（无 LLM） | 开发者手动 |
fetch_data.py |
独立工具 | 仅拉取 ODPS 数据 | 开发者手动 |
merge_data.py |
独立工具 | 仅合并数据 | 开发者手动 |
server.py |
常驻服务 | 旧版 Flow A 调度（FastAPI + APScheduler） | 历史保留，非当前生产入口 |
scan_creative_reviews.py |
硬编码脚本 | Flow C 审核扫描 | run_daily_service.py / K8s CronJob |
refresh_roi_fission_multiplier.py |
硬编码脚本 | T15 成熟系数刷新 | 手动或 Cron |
sync_ad_status.py |
辅助脚本 | 同步广告状态 | execute_once.py Step 0 |
sync_feishu_account_config.py |
辅助脚本 | 同步飞书账户配置 | execute_creation_once.py Phase -1 |
configure_creation_accounts.py |
运维工具 | 批量写入账户配置 | 运维手动 |
八、部署架构
8.1 Docker Compose（当前生产方案）
同一镜像 ad-put-agent 启动两个容器：
docker-compose.yml
├── ad_control_service → tencent_realtime_control/run_control_service.py
│ 实时 CPM 调控 + 飞书 WebSocket 指令
│
└── ad_daily_service → auto_put_ad_mini/run_daily_service.py
Flow B（创建投放）+ Flow C（审核扫描）+ Flow D（ROI 精算）
注意：Flow A（Agent 驱动决策调控）当前不在生产 Compose 中运行。
server.py保留但不再是生产入口。
8.2 两种 K8s 部署模式
| 模式 | 文件 | 调度方式 | 优点 |
|---|---|---|---|
| Deployment + APScheduler | k8s/deployment.yaml + server.py 或 run_daily_service.py |
APScheduler 读取 DB cron_schedule |
HTTP 健康检查、手动触发 API |
| Kubernetes CronJob | k8s/cronjob*.yaml |
K8s CronJob | 简单、K8s 原生重试 |
8.3 生产时间线
北京时间 10:00 (UTC 02:00) → Flow A: Agent 驱动决策调控（execute_once.py）
北京时间 10:30 (UTC 02:30) → Flow B: 创建投放（execute_creation_once.py）
北京时间 15:30 (UTC 07:30) → Flow D 内部测试报表（run_daily_roi.py --internal-test）
每 2 小时 → Flow C: 创意审核扫描（scan_creative_reviews.py）
每 10 分钟 → CPM 实时调控（tencent_realtime_control）
8.4 动态配置（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 / D |
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（完整多 Agent 体系） auto_put_ad_mini（当前生产）
┌──────────────────────────┐ ┌──────────────────────────────┐
│ 受众策略 Agent │ │ │
│ 创意策略 Agent │ │ Flow A: Agent 驱动决策调控 │
│ 预算策略 Agent ───────┐ │ │ （LLM 编排 → 护栏 → 执行） │
│ 监控调控 Agent ───┐ │ │ │ │
│ 数据分析 Agent │ │ │ │ Flow B: 创建投放 │
│ 系统运维 Agent │ │ │ │ （广告 + 创意 + AI素材 │
│ 自学习 / 反馈环 │ │ │ │ + 审批 + 提交） │
└──────────────────┼───┼───┘ │ │
│ │ │ Flow C: 审核扫描 │
│ └── 出价 ──────▶│ （每 2h 确定性脚本） │
└──── 决策 ──────▶ │ │
│ Flow D: ROI 精算 │
│ （T15系数 + 行级审批 + │
│ 代理商分发） │
└──────────────────────────────┘
auto_put_ad_mini最初是auto_put_ad中「监控调控 Agent」的独立落地版- 演进中发展出完整的三层决策架构 + 独立的创建子系统（含 AI 素材链路）+ ROI 精算子系统
- 两者共享腾讯广告 API 封装思路和领域知识
tencent_realtime_control作为独立的 CPM 实时调控服务，与 mini 的 Flow A/D 互补
十一、关键设计原则
- Agent 驱动 vs 确定性 Pipeline：Flow A 由 LLM 动态编排工具调用（灵活性高、能处理边界情况），Flow B/C/D 是硬编码多阶段脚本（确定性、可审计、无 LLM 幻觉风险）。两者各司其职。
- 三层决策架构：规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
- Flow A 与 Flow D 互补：Flow A 处理"灰色地带"的广告微调（bid_up / bid_down / creative_adjust），Flow D 处理"白纸黑字"的精确关停/降价（T15 系数、行级审批、代理商分发）
- 多条业务线解耦：决策调控（Flow A）、创建投放（Flow B+C）、ROI 精算（Flow D）使用独立的入口 / CronJob / 审批流，避免互相阻塞
- DB 驱动配置：关键开关（执行启用 / 白名单 / 调度表达式）在 DB 中，无需重启即可调整
- 人工审批嵌入：执行前必须通过飞书 IM 审批（可配置关闭），Flow A 使用群聊阻塞式审批，Flow D 使用电子表格行级审批
- 7 日去重保护：素材使用记录保留 7 天，防止同一素材重复提交审核
- 年龄分层保护：≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
- 提降分离：提价 5%-10%、降价 3%-5%，降价更保守（oCPM 模式下降价效果非线性放大）
- 副作用意识：素材召回 / AI 生成 /
xcx/save/ 广告创建等均有外部副作用，端到端中断不会自动回滚 - 幂等优先：重复运行应跳过已完成的工作，只补缺口
- 版本化计算：Flow D 的 T15 系数、ROI 计算均带版本标签（如
20260712_A0-A15_v1），支持历史回溯和审计