广告自动化投放结构文档更新

examples/auto_put_ad_mini/PROJECT_STRUCTURE.md

@@ -1,7 +1,7 @@
 # auto_put_ad_mini — 项目结构文档
 
 > **定位**: 微信小程序投流 — 面向 ROI 的广告粒度自动调控 + 自动创建投放系统
-> **最后更新**: 2026-07-27
+> **最后更新**: 2026-08-05
 
 ---
 
@@ -9,17 +9,18 @@
 
 `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**：确定性 Pipeline — `execute_creation_once.py` 和 `scan_creative_reviews.py` 是硬编码的多阶段脚本，不经过 LLM 编排。
+- **Flow B / C / D**：确定性 Pipeline — `execute_creation_once.py`、`scan_creative_reviews.py` 和 `roi_control/` 是硬编码的多阶段脚本，不经过 LLM 编排。
 
 ---
 
@@ -39,10 +40,11 @@ examples/auto_put_ad_mini/
 │   └── merge_data.py                   # 独立数据合并脚本
 │
 ├── 🟢 生产服务
-│   ├── run_daily_service.py            # ★ 生产日级服务入口（APScheduler，Flow B + C）
-│   ├── run_daily_roi.py                # 独立日级 ROI 计算 + 飞书审批（可版本化运行）
-│   ├── server.py                       # 旧版生产服务器（FastAPI + APScheduler，仅 Flow A）
+│   ├── 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 依赖
 │
@@ -58,7 +60,8 @@ examples/auto_put_ad_mini/
 │   │   ├── ai_cover_copy.md            # AI 封面文案生成 Prompt
 │   │   ├── ai_generated_material.md    # AI 素材生成 Prompt
 │   │   ├── ai_pattern_selector.md      # AI 创意范式选择 Prompt
-│   │   └── ai_sanitize_video_description.md  # 视频描述清洗 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 / 权衡原则
@@ -72,7 +75,32 @@ examples/auto_put_ad_mini/
 │       ├── config.py                   # 系统配置 + 白名单 CRUD（5 分钟缓存）
 │       └── schema.sql                  # 12 张表 + 默认种子数据
 │
-├── 🟠 工具层（35 个文件，含 `__init__.py`）
+├── 🟤 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                   # 字段名常量 + 禁止词黑名单
@@ -101,6 +129,7 @@ examples/auto_put_ad_mini/
 │       ├── 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 贡献度分析）
@@ -121,6 +150,7 @@ examples/auto_put_ad_mini/
 │           └── delivery_config.py      # 投放配置解析（出价模式 / 版位 / 地域）
 │
 ├── 🔴 辅助脚本与工具
+│   ├── refresh_roi_fission_multiplier.py # T15 成熟系数刷新入口
 │   ├── metrics.py                      # Prometheus 指标导出（可选，需 prometheus-client）
 │   ├── sync_ad_status.py               # 同步已删除广告状态
 │   ├── sync_feishu_account_config.py   # 同步飞书账户配置到 DB
@@ -140,7 +170,7 @@ examples/auto_put_ad_mini/
 │   ├── debug_generate_ai_material.py   # AI 素材生成调试
 │   └── debug_select_creative_patterns.py # 创意范式选择调试
 │
-├── 🧪 测试文件（22 个）
+├── 🧪 测试文件（26 个）
 │   ├── test_e2e_full_flow.py           # 端到端全流程测试
 │   ├── test_approval_flow_e2e.py       # 审批流程端到端测试
 │   ├── test_real_approval_flow.py      # 真实审批流程测试
@@ -162,7 +192,11 @@ examples/auto_put_ad_mini/
 │   ├── test_send_with_sheet_simple.py  # 飞书 Sheet 简化测试
 │   ├── test_strategy_upgrade.py        # 策略升级测试
 │   ├── test_api_simple.py              # API 简单连通性测试
-│   └── test_analysis_0415.py           # 0415 分析验证
+│   ├── 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/
@@ -176,10 +210,12 @@ examples/auto_put_ad_mini/
 │       ├── namespace.yaml
 │       └── network-policy.yaml
 │
-├── 📁 数据与工具
+├── 📁 数据与 SQL
 │   ├── data/tencent_constants/
 │   │   └── regions_sop_current.json    # SOP 地域参考数据
-│   ├── shared/reports/                 # 共享分析报告（20260427 样本数据）
+│   ├── sql/
+│   │   └── high_consumption_materials_30d.sql  # 30 日高消耗素材查询
+│   ├── shared/reports/                 # 共享分析报告
 │   └── utils/log_capture.py            # 日志捕获
 │
 └── 📚 文档
@@ -202,7 +238,10 @@ examples/auto_put_ad_mini/
         ├── 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 的规则清单
+        ├── 不走LLM的规则盘点.md                # 绕过 LLM 的规则清单
+        └── roi/
+            ├── T15成熟系数计算说明.md          # T15 成熟系数的计算口径与数据说明
+            └── T15成熟系数迁移指南.md          # T15 系数迁移到其他工程的步骤
 ```
 
 ---
@@ -366,11 +405,12 @@ Phase 1 (Module B): 准备创意
     │  ① find_ads_needing_creatives   找缺少创意的广告
     │     目标：每广告 TARGET_CREATIVES_PER_AD=8 个合格创意
     │  ② 对每个广告：
-    │     ├── account_material_strategy  判断素材来源（历史 / AI 生成）
+    │     ├── 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 落地页方案
@@ -440,7 +480,76 @@ 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`
+
+---
+
+## 七、入口点全景
 
 | 入口 | 执行模型 | 用途 | 谁来调用 |
 |------|---------|------|---------|
@@ -449,22 +558,23 @@ DENIED 创意不计入有效创意，触发自动补量。
 | `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，APScheduler） | Docker Compose / K8s Deployment |
-| `run_daily_roi.py` | 硬编码脚本 | 独立日级 ROI 计算 + 可选飞书审批 | 手动或 Cron |
+| `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` | 运维工具 | 批量写入账户配置 | 运维手动 |
 
 ---
 
-## 七、部署架构
+## 八、部署架构
 
-### 7.1 Docker Compose（当前生产方案）
+### 8.1 Docker Compose（当前生产方案）
 
 同一镜像 `ad-put-agent` 启动两个容器：
 
@@ -474,28 +584,29 @@ docker-compose.yml
 │                           实时 CPM 调控 + 飞书 WebSocket 指令
 │
 └── ad_daily_service      → auto_put_ad_mini/run_daily_service.py
-                            Flow B（创建投放）+ Flow C（审核扫描）
+                            Flow B（创建投放）+ Flow C（审核扫描）+ Flow D（ROI 精算）
 ```
 
 > **注意**：Flow A（Agent 驱动决策调控）当前不在生产 Compose 中运行。`server.py` 保留但不再是生产入口。
 
-### 7.2 两种 K8s 部署模式
+### 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 原生重试 |
 
-### 7.3 生产时间线
+### 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）
 ```
 
-### 7.4 动态配置（DB 驱动）
+### 8.4 动态配置（DB 驱动）
 
 | 配置项 | DB 表 | 默认值 | 说明 |
 |--------|-------|--------|------|
@@ -509,7 +620,7 @@ docker-compose.yml
 
 ---
 
-## 八、数据库表（12 张）
+## 九、数据库表（12 张）
 
 | 表名 | 用途 | Flow |
 |------|------|------|
@@ -518,7 +629,7 @@ docker-compose.yml
 | `ad_creation_account_config` | 账户 × 人群包 × 出价配置 | B |
 | `brand_asset_template` | 品牌资产模板 | B |
 | `feedback_asset_template` | 反馈资产模板 | B |
-| `system_config` | 系统配置（KV） | A / B |
+| `system_config` | 系统配置（KV） | A / B / D |
 | `decision_history` | 决策历史 | A |
 | `creative_creation_task` | 创意创建任务 | B / C |
 | `creative_review_result` | 创意审核结果 | C |
@@ -528,7 +639,7 @@ docker-compose.yml
 
 ---
 
-## 九、与 auto_put_ad 的关系
+## 十、与 auto_put_ad 的关系
 
 ```
 auto_put_ad（完整多 Agent 体系）       auto_put_ad_mini（当前生产）
@@ -544,25 +655,30 @@ auto_put_ad（完整多 Agent 体系）       auto_put_ad_mini（当前生产）
                    │   │               │ Flow C: 审核扫描              │
                    │   └── 出价 ──────▶│   （每 2h 确定性脚本）         │
                    └──── 决策 ──────▶ │                              │
+                                       │ Flow D: ROI 精算              │
+                                       │   （T15系数 + 行级审批 +      │
+                                       │    代理商分发）               │
                                        └──────────────────────────────┘
 ```
 
 - `auto_put_ad_mini` 最初是 `auto_put_ad` 中「监控调控 Agent」的独立落地版
-- 演进中发展出完整的三层决策架构 + 独立的创建子系统（含 AI 素材链路）
+- 演进中发展出完整的三层决策架构 + 独立的创建子系统（含 AI 素材链路）+ ROI 精算子系统
 - 两者共享腾讯广告 API 封装思路和领域知识
-- `tencent_realtime_control` 作为独立的 CPM 实时调控服务，与 mini 的 Flow A 互补
+- `tencent_realtime_control` 作为独立的 CPM 实时调控服务，与 mini 的 Flow A/D 互补
 
 ---
 
-## 十、关键设计原则
+## 十一、关键设计原则
 
-1. **Agent 驱动 vs 确定性 Pipeline**：Flow A 由 LLM 动态编排工具调用（灵活性高、能处理边界情况），Flow B/C 是硬编码多阶段脚本（确定性、可审计、无 LLM 幻觉风险）。两者各司其职。
+1. **Agent 驱动 vs 确定性 Pipeline**：Flow A 由 LLM 动态编排工具调用（灵活性高、能处理边界情况），Flow B/C/D 是硬编码多阶段脚本（确定性、可审计、无 LLM 幻觉风险）。两者各司其职。
 2. **三层决策架构**：规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
-3. **两条业务线解耦**：决策调控（Flow A）和创建投放（Flow B + C）使用独立的入口 / CronJob / 审批流，避免互相阻塞
-4. **DB 驱动配置**：关键开关（执行启用 / 白名单 / 调度表达式）在 DB 中，无需重启即可调整
-5. **人工审批嵌入**：执行前必须通过飞书 IM 审批（可配置关闭），含 Excel 附件 + 统计摘要
-6. **7 日去重保护**：素材使用记录保留 7 天，防止同一素材重复提交审核
-7. **年龄分层保护**：≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
-8. **提降分离**：提价 5%-10%、降价 3%-5%，降价更保守（oCPM 模式下降价效果非线性放大）
-9. **副作用意识**：素材召回 / AI 生成 / `xcx/save` / 广告创建等均有外部副作用，端到端中断不会自动回滚
-10. **幂等优先**：重复运行应跳过已完成的工作，只补缺口
+3. **Flow A 与 Flow D 互补**：Flow A 处理"灰色地带"的广告微调（bid_up / bid_down / creative_adjust），Flow D 处理"白纸黑字"的精确关停/降价（T15 系数、行级审批、代理商分发）
+4. **多条业务线解耦**：决策调控（Flow A）、创建投放（Flow B+C）、ROI 精算（Flow D）使用独立的入口 / CronJob / 审批流，避免互相阻塞
+5. **DB 驱动配置**：关键开关（执行启用 / 白名单 / 调度表达式）在 DB 中，无需重启即可调整
+6. **人工审批嵌入**：执行前必须通过飞书 IM 审批（可配置关闭），Flow A 使用群聊阻塞式审批，Flow D 使用电子表格行级审批
+7. **7 日去重保护**：素材使用记录保留 7 天，防止同一素材重复提交审核
+8. **年龄分层保护**：≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
+9. **提降分离**：提价 5%-10%、降价 3%-5%，降价更保守（oCPM 模式下降价效果非线性放大）
+10. **副作用意识**：素材召回 / AI 生成 / `xcx/save` / 广告创建等均有外部副作用，端到端中断不会自动回滚
+11. **幂等优先**：重复运行应跳过已完成的工作，只补缺口
+12. **版本化计算**：Flow D 的 T15 系数、ROI 计算均带版本标签（如 `20260712_A0-A15_v1`），支持历史回溯和审计