从原生内购迁移到 RevenueCat 或升级…

当应用已有 StoreKit/Google Play Billing 内购想接入 RevenueCat，或需跨大版本升级 RevenueCat SDK 时，按平台与迁移路径执行。

适用场景

解决思路

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. 确定迁移路径：询问用户或从代码库推断——Path A 接入：应用已有直接基于 StoreKit 或 Google Play Billing 的可用内购，正在其上叠加 RevenueCat；Path B 版本升级：应用已用 RevenueCat，要从一个大版本升到下一个（如 v4 到 v5、v7 到 v8）。两者可同时发生（如今天就在最新大版本上接入 RC），先跑 Path A，再按需跑 Path B。
3. Path A 使用 Observer 模式：让 SDK 观察现有 StoreKit/Billing 代码处理的交易，发送到 RevenueCat 后端校验并更新订阅者状态，但不发起也不完成交易；现有购买 UI、收据校验和交易完成逻辑保持不变。配置时设置：iOS 在 Configuration.Builder 上设 purchasesAreCompletedBy: .myApp 并配合 storeKitVersion: .storeKit1（或 .storeKit2），二者是独立参数而非单个关联值；Android 在 PurchasesConfiguration.Builder 上设 purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)；Flutter 向 PurchasesConfiguration 传 const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2)；React Native 在 configure 调用中传 purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }。默认是 RevenueCat 完成（REVENUECAT / .revenueCat），即 SDK 拥有完整流程。
4. 避免重复处理交易：当 purchasesAreCompletedBy 设为 myApp 时，RevenueCat 不会在 iOS 完成交易、也不会在 Android 确认交易，必须由现有代码继续完成。若移除 myApp 标志却保留旧的交易完成代码，交易会被确认两次，订阅者状态可能不一致。必须且只能由一方负责完成/确认，选定一方并移除另一方。
5. Path A 保证用户连续性：若应用已有自己的认证系统，在 RevenueCat 配置完成后调用 Purchases.logIn(existingAppUserID)，把既有购买历史在入库时关联到正确的 RevenueCat 用户；否则既有购买会记到匿名 RC 用户上，之后无法与应用真实用户记录匹配。仅当应用没有已认证用户概念时才跳过。
6. Path B 版本升级会改变必填字段：大版本升级会改变配置结构、移除废弃 API 并改变默认行为，且随版本变化。本技能不重复逐版本差异，应查阅 SDK 仓库的权威来源：相关 SDK 的 GitHub 仓库中的 CHANGELOG，从已安装版本逐条看到目标版本；在 SDK 仓库中搜索匹配 *MIGRATION*.md 的文件或 migrations/ 目录，大版本通常会附带专门迁移指南，该大版本在仓库 GitHub releases 页面的发布说明通常会链接到它；每个大版本在仓库 GitHub releases 页面的发布说明会总结破坏性变更。以 SDK 仓库文档为准，任何写在这里的版本差异都会过时；目标平台对应的 platforms/ 文件列出了应查阅的具体仓库。
7. 按顺序迁移：1) 在分支中把 SDK 升到新大版本；2) 以 CHANGELOG 中的废弃与移除项为指引修复编译错误；3) 通过首次启动时阅读 SDK 日志修复运行时行为；4) 合并前运行现有测试套件和手动沙盒场景。
8. 阅读与检测结果匹配的平台文件：platforms/ios.md、platforms/android.md、platforms/kmp.md、platforms/flutter.md、platforms/react-native.md；每个平台文件覆盖该平台的两条迁移路径。
9. 验证完成标准：1) 应用在新 SDK 版本上构建通过，且无你关心的废弃 API 警告；2) 沙盒购买成功，交易以预期的 appUserID 出现在 RevenueCat 仪表盘的 Sandbox 视图中；3) 迁移前的既有订阅者打开应用后权益状态正确——Path A 证明 observer 模式入库成功，Path B 证明版本升级未丢失状态；4) 发布前已移除 debug 日志级别覆盖。

适用边界 · 注意事项

• 应用尚无任何内购实现时，不适用接入路径（Path A），应直接按常规方式集成 RevenueCat。
• 应用没有已认证用户体系时，无需调用 Purchases.logIn(existingAppUserID)。
• 不确定目标平台或迁移路径时，不应直接改代码，应先询问用户确认。