4.1 Apple IAP 生态体系 - 数据结构与落地全解

在上一章《4. 应用内购买（IAP）- 整体 IAP 生态理解》里，我们把“能买、能验证、能恢复、能审计”这四个环节过了一遍，更多是在搭建概念上的地基。到了苹果这一章，我想把视角拉得更近一些：真实落地 Apple IAP 时，你会遇到哪些角色、跑哪些流程、踩哪些坑、如何把那堆看似重复的 id 绑成一张清晰的网。

我强烈推荐大家观看这个视频，你能很大程度的了解整体生态和各种ID。([Apple Developer][1])

Apple IAP 的数据怎么跑

如果没有把整个生态的角色看清楚，光记一堆 id 没意义。我会先把 Apple IAP 拆成三个环：

1. 客户端 & StoreKit：负责展示商品、触发交易、把票据上传；
2. Apple 服务：App Store 负责付款、生成票据；而App Store Server API + Notifications 就是用来通知和查交易状态的；([Apple Developer][2])
3. 我们自家服务端：验证票据、发放/回收权益、审计与对账。

入口推荐：StoreKit 2 官方页，含概览与资源集合。([Apple Developer][3])

数据在这三环里的流转顺序几乎不会变：客户端发起购买 -> App Store 生成 transaction 并写入服务器 -> StoreKit 用票据把交易回传给我们 -> 我们调用 Server API 或等待 Notifications 获取状态 -> 数据落库、发权益。理解这个顺序之后，再去看 transactionId、webOrderLineItemId 这些 id，会知道它们分别属于哪一环。([Apple Developer][4])

商品的提前准备和定义

其实Apple IAP 的实现不是从写代码开始的，而是从“能否创建商品、能否正确结算、能否在测试环境登录”这些基础准备起步。

角色与权限

Apple Developer Program 和 App Store Connect 各有一套角色体系。IAP 涉及到的几个关键角色：Account Holder（只有他能签协议、创建高级功能）、App Manager（配置 App）、Developer（上传构建）、Marketing（查看销售数据）。如果你的团队里没有 Account Holder 的配合，订阅相关的“自动续订协议”根本没法签。

商品设计文档

苹果的商品创建在 App Store Connect 里完成。表面看就是填表格，实则有一堆约束：

• Reference Name 可以随便写，但会在报表里出现；
• Product ID 创建后永远不能修改或删除，只能下架，因此命名一定要留扩展空间；
• Cleared for Sale 默认会勾选，若不小心去掉，客户端就看不到商品；
• 订阅类商品需要配置周期、价格、试用期、促销优惠、订阅组。

我其实是把商品设计和架构设计一样对待，写了一个专门的 SKU Sheet（因为我产品内的订阅和商品实在有点多），里面包含 productId、显示名称、货币、价格层级、是否家庭共享、属于哪个订阅组、是否允许优惠码。一旦上线后有人想改，就必须先改 SKU Sheet，再去 Connect 操作，保证信息同步。 （图文参考：App Store Connect “In-App Purchase 信息/管理订阅/Win-back offers”等帮助页。） ([Apple Developer][5])

订阅组与跨订阅组的拆法

订阅组可以理解为苹果替你维护的一条“权益线”，组内的所有订阅互斥、共享试用/优惠状态，是实现自动续订策略的基础单元。

订阅组（Subscription Group）

Apple 要求每一个自动续订订阅都必须隶属某个订阅组，且用户在同一组内任一时间只能持有一个订阅。组的职责是：

• 定义互斥：比如「月度」「年度」是同一条权益线，只能取其一；
• 约束升级/降级规则：StoreKit 依赖订阅组来判断补差价、按比例退款等场景；
• 提供唯一的 subscriptionGroupIdentifier，帮助服务端建模、对账以及识别退款/续费回调来自哪个权益线；
• 关联 Intro Offer / Promo Offer / Win-back Offer 的生效条件——因为这些优惠默认只在组内判断“是否为新用户/回流用户”。 ([Apple Developer][24])

升级、降级和平级切换策略

在同一个订阅组里，Apple 预设了三类跳转路径，我们需要结合自身权益系统补完策略：

• 升级（Upgrade）：用户从低价档切到更贵档位，StoreKit 会立即生效新权益并按比例返还剩余时间。服务端要监听 transactionReason = UPGRADE 或 ASSN 的 UPGRADE subtype，立刻把用户权限提升，并记录原订阅的剩余时长（方便审计）。
• 降级（Downgrade）：用户从高价档切到低价档位，苹果会在当前周期结束后才生效。我们需要在订单状态机里标记“待降级”，等看到新的 originalTransactionId / webOrderLineItemId 变体或 ASSN DID_CHANGE_RENEWAL_PREF 后再真正回收权益。
• 平级（Crossgrade / Lateral move）：同价档之间的互换（例如 Monthly A 与 Monthly B 只是内容不同）。系统默认视为降级策略，即新订阅在下一计费期生效。为了减少等待，你可以在应用内做“软切换”：立即调整内容分发，但在服务端保留原订阅到期日，直到苹果发出新的续订交易。

我的做法是把这三种跳转映射到统一的 plan_migration 表：记录 fromProductId、toProductId、migrationType、effectiveDate。每次收到新的交易或通知，就查这张表决定是立即升级、延迟降级还是平级切换，避免状态错乱。

什么时候需要多个订阅组

典型拆分依据：产品线完全不同（如 Chat vs Storage）、法律或税务要求（必须拆不同 bundle）、历史包袱导致旧产品无法迁移。我的经验是：当互斥关系无法用单个状态机描述，或者你需要允许用户同时持有两种权益，就该拆组。

更具体的评估步骤可以照着这三个问题走：

1. 权益矩阵是否存在“同时为真”的格子？ 如果用户可能同时拥有「AI Plus」和「Cloud Plus」，但两者的权益不冲突，就应该拆成两个组；
2. 是否需要不同的试用/定价梯度？ 订阅组的 Intro Offer 只能在组内判断新/老用户，如果你要对同一个人投放两个完全独立的试用策略，就必须拆组；
3. 合规或结算要求是否强制拆分？ 某些地区对教育版/企业版有不同税率或合同，放在同组会导致报表无法区分。

最好在产品上线前画一张“订阅组 vs 商品”的矩阵图，并且在 PRD 里明确“该组允许的迁移路径”。一旦上线后再拆组，老用户无法迁移，需要用 offer code 或后台补偿，非常痛苦。

跨订阅组（Cross-group Entitlement）

苹果不会替你管理组与组之间的关系，用户可以同时付费多个组。因此我们通常还会在自家系统里做一层「跨订阅组」映射，用来描述：

• 哪些组在业务上互斥，需要主动阻断/提示（例如「教育版」与「企业版」）；
• 哪些组共享权益，需要在权益服务里把多个 subscriptionGroupIdentifier 映射到同一套餐；
• 如何给跨组迁移的用户补差价或延后权益（例如旧版 A 订阅迁移到新版 B 订阅，需要自家逻辑计算新的到期时间）。

实践上我会在 SKU Sheet 里新增一个 logicalPlanId 字段，并在数据库里维护 subscription_group_relations 表。收到票据或通知时，先按苹果给的 subscriptionGroupIdentifier 找到对应的逻辑权益，再决定是并行生效、互斥抢占还是触发升级流程。这样一来，跨订阅组的策略完全掌握在我们手里，而不是被 Connect 的结构限制死。

同时别忘了在监控侧做三件事：统计“跨组并发数”用于发现 double charge，给客服后台暴露“该用户持有的所有组”避免重复退费，以及在账务对账时按组拆分收入（尤其是多币种下）。这些内容虽然不是苹果强制，但会直接决定你能否长期稳定运营多组订阅。

沙箱账号与环境

当创建商品后，我们需要测试，苹果会有一个专门的沙河环境是进行测试的。几个要点：