revenuecat-purchase-flow

revenuecat-purchase-flow：购买套餐并恢复购买

当用户想完成 RevenueCat 的购买流程时，使用此技能：获取 offerings、调用 purchase、处理取消和错误，并提供“恢复购买”操作。本技能不涉及渲染付费墙 UI（相关内容见 revenuecat-paywall），也不涉及功能门控（相关内容见 revenuecat-entitlements-gate）。

如果应用还没有付费墙，且用户没有要求自定义付费墙，请先确定如何构建付费墙（integrate-revenuecat，第 5c 节）。默认使用 RevenueCat Paywall，由它处理购买本身。

1. 检测平台

检查工作目录，并按以下顺序选择第一个匹配项：

1. React Native：package.json 中有 react-native-purchases 条目，或将 react-native 作为依赖项 → 阅读 platforms/react-native.md。如果 expo 也是依赖项，请标记为 Expo 项目。
2. Flutter：项目根目录下存在 pubspec.yaml → 阅读 platforms/flutter.md。
3. Kotlin Multiplatform：build.gradle.kts 包含 kotlin { … } 多平台 source sets 块，或依赖 com.revenuecat.purchases:purchases-kmp* → 阅读 platforms/kmp.md。
4. Android（原生）：build.gradle(.kts) 应用了 com.android.application（且不是 KMP）→ 阅读 platforms/android.md。
5. iOS（原生）：项目根目录下存在 Package.swift、*.xcodeproj、*.xcworkspace 或 Podfile → 阅读 platforms/ios.md。

如果有多项匹配（例如 Flutter 项目中包含 ios/ 文件夹），请选择最外层的项目，也就是拥有构建配置的项目。如果仍无法确定，请询问用户要配置哪个平台。

2. 通用概念（所有平台）

• 流程。 调用 getOfferings()，从当前 offering 中选取一个 Package，再调用 purchase(package)。成功完成后，返回的 customerInfo 已反映此次购买。读取 customerInfo.entitlements.active["<id>"] 以确认访问权限。
• 用户取消不属于应用错误。 各 SDK 的处理方式有所不同：iOS 会抛出 purchaseCancelledError 代码；Android 会抛出带有 PurchasesErrorCode.PurchaseCancelledError 的 PurchasesException；Flutter 会返回带有相同代码的 PlatformException；React Native 会设置 e.userCancelled === true。此时直接返回，不要显示警告。
• 值得向用户提示的错误。 支付被拒绝、网络错误、商店不可用、收据已被使用。其他错误都应记录下来，并让用户重试。购买实际失败时，绝不要静默地表现为成功。
• 不要在购买回调中解锁内容。 刷新客户信息，并让权益监听器（见 revenuecat-entitlements-gate）更新受门控的 UI。这样可以确保访问权限只有一个事实来源，并避免购买流程与恢复流程之间出现不一致。
• restorePurchases() 是用户操作，不是自动步骤。 它会向商店请求当前收据，并将其同步到 RevenueCat。请在付费墙和／或设置页面中提供醒目的“恢复购买”按钮。iOS 法律要求必须提供此类按钮。
• 一次只允许进行一笔购买。 购买进行期间，请禁用付费墙上的购买按钮，以防重复扣费。

3. 实现

阅读与检测结果匹配的平台文件：

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

每个平台文件都包含完整的购买函数和恢复函数。

4. 验证

满足以下条件前，不要声称流程正常：

1. 当前商品的套餐通过沙盒完成端到端购买，且用户的权益状态变为已激活。
2. 取消商店界面不会显示错误提示，也不会让 UI 一直处于加载状态。
3. 再次尝试购买同一项有效订阅时，应能妥善处理（StoreKit / Play Billing 会触发 productAlreadyPurchased / receiptAlreadyInUse 路径；流程不应崩溃）。
4. 在全新安装的应用中登录同一商店账号后，恢复按钮应能恢复权益并更新 UI。