数据层
统一拉取计划、素材、用户、订单、回传、动作日志。所有诊断都必须绑定 snapshot_id。
- 08:00 全量快照
- 动作后窗口增量
- 字段缺失降级
AI 投放决策执行系统模块详细设计
本地模块详情文档集合。每个模块包含产品目标、用户交互、流程图、数据/接口约束和技术拆解要点，用于配合 PRD 总览页弹窗阅读。
模块一：系统设计详细文档
目标是让 AI 决策不是一个孤立推荐模型，而是进入自研投放系统的可执行、可审计、可复盘闭环。
AI 决策层
先做跑不动诊断，再做 P0-P3 分池，最后生成动作候选和置信度。
- 规则优先，模型辅助
- 证据字段必须可追溯
- 风险等级独立计算
动作编排层
把 AI 建议转换成 action_card，决定确认等级、执行器、冻结窗口和复盘计划。
- auto_draft
- batch_confirm
- strong_confirm
执行复盘层
所有执行必须写日志，执行成功必须创建复盘任务，复盘结论必须回写。
- before/after 快照
- freeze_until
- review_result
1
快照
生成 snapshot_id，写入字段质量。
2
诊断
输出 bucket、reason_code、evidence。
3
动作卡
生成 action_card 和 review_plan。
4
确认
系统或钉钉触达对应负责人。
5
执行
执行器处理预算、复制、草案等动作。
6
复盘
自动产生下一步结论。
| 技术拆解 | 后端 | 算法/规则 | 前端 |
|---|---|---|---|
| 数据快照 | snapshot 表、字段质量表 | 指标口径校验 | 快照时间和字段缺失提示 |
| 动作卡 | action_card 表、状态流 | 动作推荐和风险等级 | 待办列表、详情抽屉、批量确认 |
| 复盘 | review_task 队列 | 成败判断规则 | 复盘任务页和结论回写 |
模块二：今日动作台详细设计
今日动作台不是静态看板，而是投放负责人每天处理 AI 动作卡的主工作区。它必须支持筛选、选中、查看证据、确认、驳回、转主管、查看日志和创建复盘。
待确认动作列表
P0 低耗高 ROI：复制 2 个副本批量确认
临界大 R：价值平滑强确认强确认
P2 信号不足：行为价值补点草案强确认
P1 常规赚钱：预算 +20%批量确认
1
筛选队列
按 P0、强确认、待复盘、负责人、游戏项目过滤动作。
2
选中动作
右侧抽屉加载 action_card 详情和证据快照。
3
核对证据
强确认必须核对证据、冻结窗口、复盘计划。
4
提交决定
确认、驳回、转主管或只查看日志。
5
执行编排
确认通过后创建执行任务、冻结窗口和复盘任务。
6
复盘回写
复盘结论回写动作卡和 AI 样本库。
批量确认区
只允许 batch_confirm 动作进入批量确认。系统需要在提交前再次剔除 strong_confirm、forbidden 和 freeze 冲突动作。
强确认区
价值平滑、回传策略、关停、降预算等高风险动作必须走系统强确认页，钉钉只做跳转和提醒。
复盘区
复盘任务要展示动作前后快照、消耗响应、边际 ROI、是否回滚，以及下一步推荐动作。
| 区域 | 必须字段 | 为什么需要 | 缺失降级 |
|---|---|---|---|
| 动作列表 | action_id、目标对象、动作类型、风险等级、处理时限 | 投放负责人能快速判断优先级 | 字段缺失只展示草案，不允许确认 |
| 证据区 | 消耗、ROI 达成、单用户贡献、S/A 占比、置信度 | 判断高 ROI 是真实可放量还是被大 R 扭曲 | 缺少大 R 判断时禁止扩量动作 |
| 执行参数 | 预算变更、副本数、回传范围、冻结窗口、幂等键 | 技术执行器需要可执行 payload | 参数不完整时只允许保存草案 |
| 复盘计划 | 50m、110m、5h、next_day、day7、责任人 | 保证动作执行后有闭环 | 无复盘计划则不允许执行 |
| 交互 | 用户动作 | 系统响应 | 技术要求 |
|---|---|---|---|
| 左侧导航 | 点击今日动作台 / 诊断记录 / 复盘任务 / 回传草案 / 失败参数库 / 审计日志 | 中间工作区切换到对应模块，右侧抽屉同步展示模块摘要和接口约束 | 前端状态模型：active_assistant_panel；各模块独立查询参数 |
| 场景切换 | 点击复制副本 / 强确认 / 补点 / 预算 / 复盘 | 列表选中态、抽屉内容、payload 预览同步变化 | 前端状态模型：selected_action_id |
| 筛选 | 点击 P0 / 强确认 / 待复盘 | 列表过滤，KPI 同步变化 | 前端本地状态 + 服务端查询参数 |
| 选中动作 | 点击动作卡 | 右侧抽屉展示详情 | GET /action-cards/:id |
| 批量确认 | 多选低风险动作 | 进入确认弹窗，执行后创建复盘任务 | POST /actions/batch-approve |
| 强确认 | 勾选确认清单后点击确认执行 | 二次校验影响、冻结窗口、复盘计划 | 权限校验 + idempotency_key + checklist_snapshot |
| 驳回 | 选择驳回原因 | 状态变为 rejected，原因进入训练样本 | reject_reason 必填，保留 action_version |
| 转主管 | 点击转主管 | 生成主管待办和钉钉卡片 | owner_id、supervisor_id 必填 |
| 查看日志 | 点击查看日志 | 展示 AI 证据、人工操作、执行回调和复盘结论 | action_log 按 action_id 串联 |
模块三：钉钉互动卡片详细设计
钉钉负责及时触达和轻量处理，但不能替代系统强确认页。卡片内容必须让负责人在 10 秒内判断“为什么通知我、风险多大、下一步去哪处理”。
钉钉卡片原型
强确认：P0 大 R 价值平滑
目标计划 83509 · 风险高 · 30 分钟内处理
结论单个大 R 拉高 ROI，建议生成价值平滑草案。
证据消耗 620；ROI 146%；单用户贡献 42%；置信度 0.82。
影响仅影响临界大 R 复充尖峰，非大 R 用户正常回传。
边界钉钉不直接执行，点击去确认打开系统强确认页。
查看详情去确认驳回转主管
交互规则
- 查看详情：打开系统动作详情页。
- 去确认：打开系统强确认页，不在钉钉内直接执行。
- 驳回：钉钉内可轻量回调，但必须选择原因。
- 转主管：生成主管待办，并记录转交人。
- 超时未处理：重新提醒或升级到主管。
| 通知类型 | 触发条件 | 接收人 | 卡片按钮 |
|---|---|---|---|
| 强确认 | 关停、ROI 目标修改、回传策略、价值平滑、行为价值补点 | 负责人 + 主管 | 查看详情、去确认、驳回、转主管 |
| 批量确认 | 预算 +20%-30%、复制计划、素材母题复制 | 计划负责人 | 查看详情、批量确认入口、稍后处理 |
| 风险告警 | 字段缺失、无对照组、执行失败、冻结窗口冲突 | 负责人 + 系统 Owner | 查看异常、转数据、关闭提醒 |
模块四：状态流与权限详细设计
状态流要服务于审计、恢复和协同。任何钉钉点击、系统确认、执行器回调都必须让 action_card 状态可追踪。
1
draft
AI 草案，不通知。
2
pending_confirm
待确认，已通知。
3
approved
确认通过。
4
executing
执行器处理中。
5
reviewing
复盘窗口中。
6
closed
复盘完成。
| 状态 | 允许动作 | 禁止动作 | 关键字段 |
|---|---|---|---|
| draft | 进入待确认、自动归档 | 执行 | snapshot_id、evidence |
| pending_confirm | 确认、驳回、转主管、过期升级 | 重复通知刷屏 | expire_at、receiver |
| approved | 进入执行队列 | 再次确认 | confirmed_by、idempotency_key |
| executing | 执行成功/失败回调 | 重复执行 | executor_job_id、before_snapshot |
| reviewing | 生成复盘结论 | 冲突动作 | freeze_until、review_task_id |
| closed | 进入样本库、复制经验 | 改写历史状态 | review_result、closed_reason |
模块五：接口契约详细设计
接口契约的重点不是一次定义完整数据库，而是让前端、后端、钉钉和执行器围绕 action_id 达成一致。
核心实体
- action_card：动作卡主表。
- action_evidence：证据字段表。
- confirm_log：确认/驳回/转交日志。
- executor_job：执行器任务。
- review_task：复盘任务。
幂等原则
- 所有写操作必须携带 idempotency_key。
- 所有更新必须校验 action_id + version。
- 钉钉回调不直接执行强风险动作。
- 执行器只消费 approved 状态动作。
POST /actions/{action_id}/approve
{
"version": 3,
"operator_id": "u123",
"confirm_channel": "system",
"idempotency_key": "approve_act_0001_v3_u123",
"confirm_payload": {
"ack_risk": true,
"ack_freeze_until": true,
"ack_review_plan": true
}
}| 接口 | 用途 | 关键校验 |
|---|---|---|
| GET /action-cards | 工作台列表 | owner、status、bucket、risk_level |
| GET /action-cards/:id | 详情抽屉 | 权限、version、evidence 完整性 |
| POST /actions/:id/reject | 驳回动作 | reject_reason 必填 |
| POST /dingtalk/callback | 钉钉按钮回调 | 签名、过期、幂等、动作等级 |
| POST /executor/jobs | 生成执行任务 | approved 状态、冻结窗口、执行器能力 |
模块六：复盘学习详细设计
复盘模块要让每个动作都产生下一步，而不是只产生报表。系统必须自动判断继续、维持、回退、转人工、禁止复制。
1
创建任务
执行成功后自动创建。
2
到点拉数
按 50m/110m/5h/次日/7天拉取。
3
判定成败
边际 ROI、CPA、S/A、展点消。
4
输出结论
继续、维持、回退、关停建议。
5
回写样本
沉淀成功/失败参数。
6
触发新卡
必要时生成下一动作卡。
| 复盘窗口 | 观察指标 | 成功标准 | 失败动作 |
|---|---|---|---|
| 50 分钟 | 展现、点击、消耗 | 结构性变化出现 | 继续等到 110 分钟 |
| 110 分钟 | 消耗响应、CPA、转化数 | 消耗上升且 CPA 未失控 | 停止加预算，转素材/出价诊断 |
| 5 小时 | 流量池变化、素材疲劳 | 新增消耗稳定 | 换素材变体或复制新计划 |
| 次日 | 边际 ROI、新增 CPA、S/A 占比 | 新增预算边际 ROI 达标 | 回退预算或转 P3 |
| 第 7 天 | 补点组真实付费率、对照组差异 | 显著优于对照组且不低于 15% | 暂停补点，排查模型 |