revenuecat-entitlements-gate

revenuecat-entitlements-gate：检查 RevenueCat 权益

当用户想根据 RevenueCat 权益是否处于激活状态来决定显示或隐藏某项功能时，使用此技能。此技能涵盖单次检查和响应式监听器；不涵盖购买流程（参见 revenuecat-purchase-flow）或身份验证（参见 revenuecat-identify-user）。

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 { … } 多平台源集代码块，或依赖 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. 共用概念（所有平台）

• 检查权益标识符，而非产品 ID。 标识符（例如 "premium"）在 RevenueCat 控制面板中配置，并映射到一个或多个产品。使用权益可让你更改产品、价格和商店，而无需修改应用代码。
• customerInfo.entitlements.active 是唯一可信的数据来源。 它是一个以权益标识符为键的 Map<String, EntitlementInfo>。权益出现在 active 中，表示用户当前拥有访问权限。若未出现，则表示用户没有访问权限，不论其过去是否购买过。
• 不要依据购买历史进行门控。 已过期的订阅仍会出现在 customerInfo.entitlements.all 中，但会从 active 中移除。只使用 active。
• 先获取一次，再订阅。 首次调用 customerInfo 会快速返回缓存值，SDK 会在后台刷新。每个 SDK 都提供一个在权益发生变化时触发的监听器或流（例如购买、恢复、续订或过期后）。请订阅它，而不要轮询。
• 必须先配置 SDK。 如果尚未运行 Purchases.configure(…)，权益调用将会失败。使用此技能前，请通过 integrate-revenuecat 设置 SDK。

3. 实现

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

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

每个平台文件都会展示单次检查、响应式订阅，以及在典型应用中的放置位置。

4. 验证

在满足以下条件前，不要声称门控功能正常：

1. 拥有激活权益的用户可以看到受门控的功能，而没有该权益的用户看不到。
2. 权益状态发生变化时（使用沙盒购买或在控制面板中手动授予权益进行测试），UI 无需手动重启即可更新，这表明监听器已正确连接。
3. 代码中的权益标识符与 RevenueCat 控制面板中现有的标识符一致。这里的拼写错误会导致所有用户都被静默拒绝访问。