用途
revenuecat-entitlements-gate 用于判断某个 RevenueCat 用户当前是否拥有对某项付费功能的访问权限，从而决定在应用中显示还是隐藏该功能。当用户希望把某个功能置于高级（premium）门槛之后，或需要检查用户是否拥有某项权益时，可使用本技能。
本技能覆盖一次性检查（one shot check）和响应式监听（reactive listener）两种方式。它不覆盖购买流程（参见 revenuecat-purchase-flow），也不覆盖用户认证（参见 revenuecat-identify-user）。
主要能力
- 检测项目所使用的平台，并读取对应的平台实现文档。
- 提供一次性权益检查的实现方式。
- 提供响应式订阅（监听权益变化）的实现方式。
- 说明在典型应用中每段代码应放置的位置。
- 给出验证门控是否真正生效的检查清单。
使用方式
1. 检测平台
检查工作目录，从上到下选择第一个匹配项：
- React Native：package.json 中有 react-native-purchases 条目，或依赖 react-native → 读取 platforms/react-native.md。如果同时依赖 expo，则标记为 Expo 项目。
- Flutter：项目根目录存在 pubspec.yaml → 读取 platforms/flutter.md。
- Kotlin Multiplatform：build.gradle.kts 包含 kotlin { … } 多平台 source sets 块，或依赖 com.revenuecat.purchases:purchases-kmp* → 读取 platforms/kmp.md。
- Android（原生）：build.gradle(.kts) 应用了 com.android.application（且不是 KMP）→ 读取 platforms/android.md。
- 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. 验证
在满足以下条件之前，不要宣称门控可用：
- 拥有有效权益的用户能看到被门控的功能，没有权益的用户看不到。
- 当权益状态变化时（用沙盒购买或仪表盘手动授予进行测试），UI 无需手动重启即可更新，确认监听器已正确接入。
- 代码中的权益标识符与 RevenueCat 仪表盘中存在的标识符一致。此处拼写错误会静默地把所有用户挡在门外。
适用场景
- 需要根据用户是否拥有某项权益来显示或隐藏付费功能。
- 需要在购买、恢复、续订或过期后实时更新功能可见性。
- 需要在 React Native、Flutter、Kotlin Multiplatform、Android 原生或 iOS 原生项目中实现权益门控。
限制
- 不覆盖购买流程，购买相关需求请参见 revenuecat-purchase-flow。
- 不覆盖用户认证，认证相关需求请参见 revenuecat-identify-user。
- 使用前必须先完成 SDK 配置（Purchases.configure(…)），否则权益调用会失败。
- 必须使用权益标识符而非产品 ID，且标识符需与 RevenueCat 仪表盘中的配置一致。
- 必须依据 customerInfo.entitlements.active，不能依据购买历史。
- 关于具体价格、收费、平台支持范围等更多信息，资料中暂未提供。