广告 SDK、GM 与运营辅助
0. 本篇结论
本篇为 WEN-14 / B2-B 文档整理稿，状态为 draft。原文 producer_review_needed / canonical_candidate 保留，未取得该功能的产品批准凭证。规则编号、参考图与原候选内容不等于已上线行为。
来源为 project2-docs @ ec43be0e13c8624cfafd36c0fd803f3b89733fff 的 docs/planning/project2-game-feature-library-v1/features/ads-sdk-gm-ops.md；获取时间 2026-10-13（UTC），通过 Git 固定提交阅读。共用归属、来源清单、冲突证据与待裁定项统一见运营总览。本篇后续“必须”“验收”均属于待审规则/预留验收，未在本批执行游戏或平台验证。
1. 功能定位
广告 SDK、GM 和运营辅助能力为项目提供广告行为回调、GM 命令、运营后台服务、监控和测试调试能力。它们不直接构成玩家主玩法，但影响商店、充值、活动、测试和运营效率。
2. 范围
In Scope：TopOn 广告请求/通知、广告回调、GM 命令、服务器运营接口、Prometheus 监控、开发测试入口。
Out of Scope：商店商品规则、充值订单状态机、正式活动玩法。
3. 玩家入口、解锁与提示
广告入口通常由商店、礼包或道具购买触发。GM 和运营辅助不向普通玩家开放。
4. 核心玩家流程
- 玩家在支持广告的功能中点击广告操作。
- 客户端调用广告 SDK。
- 广告平台回调后，客户端或后端发起奖励确认。
- 后端校验广告来源并发放奖励或刷新次数。
5. 核心规则
5.1 广告奖励绑定规则
ADS-SDK-GM-OPS-R-001：广告奖励必须绑定来源功能和行为 ID。
5.2 GM 与运营接口权限
ADS-SDK-GM-OPS-R-002：GM 命令只允许测试或授权环境使用。ADS-SDK-GM-OPS-R-003：运营接口涉及服务器状态、白名单、版本、公告、充值回调等，必须权限隔离。
5.3 操作矩阵
N/A。当前不在策划案正文中复述核心玩家流程；进入 PLAN 时，仅对状态变化、消耗/产出、奖励发放、跨系统反馈或失败反馈补齐操作矩阵。
6. UI 状态与交互
6.1 界面图与交互说明
以下图片为待评审参考图，已按图片锚点和附近文字绑定到页面/状态；状态均为 仅参考，最终布局、尺寸、按钮位置和视觉风格以制作人/UI 评审确认为准。
图 01：广告图标 X 1
- 图状态：仅参考
- 关联页面 / 状态：广告图标 X 1
- 关联交互 / 状态说明：广告图标 X 1；用于在按钮上展示（如右图）
图 02：广告图标 X 1
- 图状态：仅参考
- 关联页面 / 状态：广告图标 X 1
- 关联交互 / 状态说明：广告图标 X 1；用于在按钮上展示（如右图）
6.2 页面结构与交互
广告按钮需要展示广告图标、可用次数、加载中、失败、取消、奖励已发放。GM 不进入正式 UI。
6.3 UI 页面状态表
N/A。当前仅保留已绑定页面/状态的参考图和页面结构说明；具体可执行状态在 UI 评审或 UI brief 中确认。
7. 配置、数据与 Contract
本节只记录策划案需要的逻辑数据与跨部门 contract，不预设物理配置表、协议文件、service 文件或 仓库落点。正式命名、字段名、接口名、协议对象名、文件名和仓库落点进入执行前由 Work Package 的 contract-registry.yaml、execution brief 和对应执行任务确认。
7.1 策划数据需求
策划数据需求只描述逻辑数据域、逻辑字段或规则语义，不等同于配置表字段名、协议字段名或数据库字段名。正式字段命名进入 contract-registry.yaml、execution brief 和对应执行任务确认。
| 数据域 | 逻辑字段 / 规则 | 设计含义 | 必填 / 边界 | 产出责任 |
|---|---|---|---|---|
| 广告行为定义 | 广告行为 ID、来源功能、奖励类型、次数限制、冷却、失败策略 | 定义广告入口与奖励来源绑定 | 进入执行前补齐默认值、边界和可选性 | Planning / Backend |
| GM 命令规则 | 命令类型、参数、权限、环境限制、审计要求 | 定义测试或授权环境的运维命令范围 | 进入执行前补齐默认值、边界和可选性 | Backend / Ops |
| 运营服务规则 | 操作类型、权限、目标范围、回滚和审计 | 定义服务器状态、公告、白名单、充值回调等运营入口 | 进入执行前补齐默认值、边界和可选性 | Backend / Ops |
7.2 运行时数据与接口需求
| Contract | 设计含义 | 使用方 | 说明 |
|---|---|---|---|
| 广告播放与通知 | 广告完成后发放奖励并同步状态 | 服务端 / 客户端 / SDK | 需要处理加载失败、取消、完成和重复通知 |
| GM 执行通道 | 授权环境下执行 GM 命令 | Backend / Ops | 正式环境默认隔离并记录审计 |
| 运营接口 | 处理服务器、公告、白名单和支付回调 | Backend / Ops | 需权限隔离和操作审计 |
7.3 跨部门 Contract 命名清单
| Contract 类型 | 逻辑对象 | 命名状态 | 阻塞阶段 | 说明 |
|---|---|---|---|---|
| 配置数据 | 广告行为、奖励来源、GM 权限、运营操作类型 | 待 PLAN 确认 | PLAN 前 | 不预设物理配置表名 |
| 协议 / API | 广告请求、广告完成通知、GM 命令、运营服务 | 待 PLAN 确认 | 执行前 | 由服务端 / 客户端 / 运营 brief 确认 |
| 错误码 | 广告不可用、奖励已发放、权限不足、环境禁止 | 待 PLAN 确认 | 执行前 | 需要可本地化提示 |
| 资源引用 | 广告按钮图标和加载状态资源 | 待 PLAN 确认 | 执行前 | 由美术 / UI brief 确认 |
| 埋点事件 | 广告展示、广告完成、广告失败、GM 操作 | 待 PLAN 确认 | PLAN 前 | 由 analytics 方案确认 |
8. 系统边界
| 方向 | 负责内容 | 备注 |
|---|---|---|
| Planning | 逻辑数据、数值、文本需求、资源需求 | 进入执行前由 PL 任务细化 |
| 服务端 | 协议、校验、持久化、奖励发放、幂等与安全 | 仅相关功能需要 |
| 客户端 | UI、交互、表现、本地状态、红点和跳转 | 仅相关功能需要 |
| 美术 | 图标、模型、特效、音频和导出资源 | 仅相关功能需要 |
| Ops / GM | 后台配置、运营投放、公告、补偿和数据看板 | 仅相关功能需要 |
客户端与表现
- 客户端广告入口散落在商店、礼包或道具购买相关功能。
- GM 前端证据位于
Features/Item/GM,Features/Master/GM,Features/Lottery/GM等测试入口。
美术与音频需求
广告按钮、广告标识、加载状态和失败反馈需要 UI 素材。当前候选至少需要 1 个广告图标，用于按钮内展示。GM 不需要玩家侧美术。
9. 数值、经济与奖励
广告奖励可能影响商店刷新、免费购买、礼包或资源发放。所有奖励必须走 item-resource 和后端校验。
10. 异常、安全与运营边界
10.1 异常与安全
广告回调、GM、服务器状态、白名单、版本和充值回调都属于高风险边界。生产环境必须有权限、审计和人工确认。
10.2 埋点与运营
本功能的候选采集行为统一见埋点与数据分析的业务事件目录。本篇只拥有业务触发和状态含义；事件名、属性类型、归因与跨端去重归埋点文档。候选目录不代表已有正式事件或已接入平台。
11. Feature Relations 与回归范围
Feature Relations
关联 shop、recharge-giftpack、item-resource、account-server-login、game-notice。
回归范围
以 Feature Relations 影响功能、核心玩家流程、配置与系统边界为基础；进入执行前由 PLAN / QA brief 细化最小回归范围。
12. 验收标准
12.1 关键验收结论
广告完成发奖、失败不发奖、次数刷新、GM 权限隔离、运营接口审计和监控正常。
补充验收：所有看广告按钮正确展示广告图标，广告可用、不可用、加载、取消和奖励完成状态均有清晰反馈。
12.2 规则验收清单
规则正文集中在本篇第 5 节，原有 *-R-* 编号保留。原第 12.2 节逐条重复正文已合并到第 5 节；未来人工验收按这些编号记录结果，本批未验证也未勾选。共用规则按运营总览的归属引用，不另立副本。
12.3 执行层验收
- 如填写操作矩阵，成功路径、失败场景、玩家反馈和状态权威均已覆盖。
- 如填写 UI 页面状态表，页面 / 弹窗状态均已覆盖，或明确标记为
N/A。 - Section 7 中标记为 PLAN 前或执行前阻塞的 contract 已在
contract-registry.yaml、execution brief 或执行任务中确认。 - 相关 Feature Relations 回归通过。
13. 待澄清问题 / Open Questions
- 当前正式广告平台、广告位 ID、奖励来源和广告防作弊规则需要确认。
- GM 是否只保留开发环境，还是有运营后台入口。
14. 变更记录
| 日期 | 版本 | 修改人 | 变更摘要 |
|---|---|---|---|
| 2026-10-13 | draft / WEN-14 | AutoDev Symphony | 保留原审核状态与固定来源；明确共用归属及待裁定问题；合并重复规则清单与空图入口，不变更玩法 |
| 2026-06-16 | v0.2 | Codex | 补充规则编号、操作矩阵、UI 状态表、逻辑字段和执行层验收锚点 |
| 2026-06-16 | v0.1 | Codex | 按新版功能策划案模板重排章节；保留既有规则内容并映射参考图 |