充值、订单、礼包与内购
0. 本篇结论
本篇是 WEN-13 / B2-A 文档整理稿，状态为 draft；原 producer_review_needed / canonical_candidate 审核事实保留，未取得新增产品批准。第 5 节规则、第 6 节参考图、第 7 节数据需求及第 12 节验收均为候选资料，不能解释为已上线功能或实现授权。来源、冲突及待裁定问题集中在商业化系统。
公共货币/道具表示、库存增减、奖励展示和防重复发放只引用经济系统及道具资源，本篇仅拥有业务触发条件。价格、消耗数量、概率、限购与次数尚未确认时不补默认值。
1. 功能定位
充值礼包系统负责付费商品展示、创建订单、客户端内购、支付验证、发放付费奖励、触发礼包和首充/累计充值类奖励。
2. 范围
In Scope：礼包列表、商品 ID、创建订单、支付验证、取消订单、领取充值奖励、触发礼包、红点。
Out of Scope：平台后台商品配置、财务对账规则。
3. 玩家入口、解锁与提示
入口位于主界面、商店、礼包弹窗或触发礼包入口。开放条件可能由充值配置和活动时间控制。
4. 核心玩家流程（候选，非当前支付行为）
- 玩家打开礼包/充值界面。
- 客户端请求充值主数据。
- 玩家选择商品并创建订单。
- 客户端调用内购 SDK 完成支付。
- 客户端向后端验证支付。
- 后端发放奖励并通知客户端。
5. 核心规则
本节与订单流程仅保留原候选职责。商店钻石充值栏位的“暂不开发”不等于所有礼包被废弃，也不授权开放支付；充值、首充、月卡、累计充值与触发礼包的版本范围均待裁定（B2A-Q09～Q10）。
5.1 商品与订单状态机
RECHARGE-GIFTPACK-R-001：商品分礼包、充值卡、首充、累计充值、触发礼包等类型。RECHARGE-GIFTPACK-R-002：订单创建、支付验证、取消、完成必须有状态机。
5.2 充值奖励防重复
RECHARGE-GIFTPACK-R-003：充值奖励领取必须防重复。
5.3 操作矩阵
N/A。当前不在策划案正文中复述核心玩家流程；进入 PLAN 时，仅对状态变化、消耗/产出、奖励发放、跨系统反馈或失败反馈补齐操作矩阵。
6. UI 状态与交互
6.1 界面图与交互说明
N/A。当前未从迁移草稿中映射到界面图片；如后续涉及 UI 改动，应补充界面图、线框图或参考图。
6.2 页面结构与交互
礼包页展示商品、价格、奖励、购买按钮、领取状态、支付中、支付失败、补单提示。
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 / Ops |
| 订单状态规则 | 订单号、渠道、金额、状态、回调、验签、防重复 | 定义创建、支付验证、取消、完成和回调状态机 | 进入执行前补齐默认值、边界和可选性 | Backend / Ops |
| 奖励领取规则 | 奖励组、领取条件、领取状态、防重复、补偿策略 | 定义充值奖励和礼包奖励领取条件 | 进入执行前补齐默认值、边界和可选性 | Planning / Backend |
7.2 运行时数据与接口需求
| Contract | 设计含义 | 使用方 | 说明 |
|---|---|---|---|
| 充值主页状态 | 同步商品、礼包、首充和累计充值状态 | 服务端 / 客户端 | 展示和领取状态以状态权威为准 |
| 订单与支付验证 | 处理创建订单、支付验证、取消和服务端回调 | Backend / SDK / Ops | 需要幂等和防重复发奖 |
| 奖励领取接口 | 处理充值奖励和礼包奖励领取 | 服务端 / 客户端 | 领取必须防重复 |
7.3 跨部门 Contract 命名清单
| Contract 类型 | 逻辑对象 | 命名状态 | 阻塞阶段 | 说明 |
|---|---|---|---|---|
| 配置数据 | 商品、礼包、充值卡、触发条件、限购、奖励和渠道 | 待 PLAN 确认 | PLAN 前 | 不预设物理配置表名 |
| 协议 / API | 充值主页、创建订单、支付验证、取消订单、奖励领取、回调 | 待 PLAN 确认 | 执行前 | 由服务端 / 客户端 / 运营 brief 确认 |
| 错误码 | 商品不可购买、订单不存在、支付失败、重复领取、验签失败 | 待 PLAN 确认 | 执行前 | 需要玩家提示和后台日志 |
| 埋点事件 | 下单、支付成功、支付失败、礼包领取、首充完成 | 待 PLAN 确认 | PLAN 前 | 由 analytics 方案确认 |
8. 系统边界
| 方向 | 负责内容 | 备注 |
|---|---|---|
| Planning | 逻辑数据、数值、文本需求、资源需求 | 进入执行前由 PL 任务细化 |
| 服务端 | 协议、校验、持久化、奖励发放、幂等与安全 | 仅相关功能需要 |
| 客户端 | UI、交互、表现、本地状态、红点和跳转 | 仅相关功能需要 |
| 美术 | 图标、模型、特效、音频和导出资源 | 仅相关功能需要 |
| Ops / GM | 后台配置、运营投放、公告、补偿和数据看板 | 仅相关功能需要 |
客户端与表现
GiftPackIAPService接入内购服务。
美术与音频需求
需要礼包卡片、价格标签、奖励展示、购买反馈、支付成功反馈。
9. 数值、经济与奖励
- 充值配置数据定义 定义充值开放、礼包和充值卡配置。
- 礼包奖励的资产表示、库存增减与公共发放边界只引用经济系统及道具资源；礼包拥有商品、触发/购买/领取条件，订单拥有创建、验证、取消与完成的候选职责。
- 付费金额、商品 ID、渠道 ID、现金类型需统一 contract。
10. 异常、安全与运营边界
10.1 异常与安全
付费流程必须后端校验，订单验证幂等。生产订单、凭据、SDK 配置、补单操作必须人工审批。
10.2 埋点与运营
记录商品曝光、点击购买、订单创建、支付成功/失败、验证成功/失败、奖励领取、触发礼包展示。
11. Feature Relations 与回归范围
Feature Relations
依赖 item-resource、shop、main-entry-red-dot、平台 SDK 和运营配置。
回归范围
以 Feature Relations 影响功能、核心玩家流程、配置与系统边界为基础；进入执行前由 PLAN / QA brief 细化最小回归范围。
12. 验收标准
12.1 关键验收结论
商品展示、订单、支付验证、奖励发放、取消、补单和红点流程正确。
12.2 规则验收清单
-
RECHARGE-GIFTPACK-R-001：候选内容见第 5 节；核对批准状态、证据与商业化系统待裁定项。 -
RECHARGE-GIFTPACK-R-002：候选内容见第 5 节；核对批准状态、证据与商业化系统待裁定项。 -
RECHARGE-GIFTPACK-R-003：候选内容见第 5 节；核对批准状态、证据与商业化系统待裁定项。
12.3 执行层验收
- 如填写操作矩阵，成功路径、失败场景、玩家反馈和状态权威均已覆盖。
- 如填写 UI 页面状态表，页面 / 弹窗状态均已覆盖，或明确标记为
N/A。 - Section 7 中标记为 PLAN 前或执行前阻塞的 contract 已在
contract-registry.yaml、execution brief 或执行任务中确认。 - 相关 Feature Relations 回归通过。
13. 待澄清问题 / Open Questions
- 是否使用 Google Play 为唯一支付渠道。
- 首充、月卡、触发礼包、累计充值是否需要拆成独立 feature。
14. 变更记录
| 日期 | 版本 | 修改人 | 变更摘要 |
|---|---|---|---|
| 2026-06-16 | v0.2 | Codex | 补充规则编号、操作矩阵、UI 状态表、逻辑字段和执行层验收锚点 |
| 2026-06-16 | v0.1 | Codex | 按新版功能策划案模板重排章节；保留既有规则内容并映射参考图 |