FIX: RevenueCat 订阅绑定 Supabase user id（修复停留匿名 ID + 购买前 fail-closed 门禁）

echo-loop · echo-loop · commit 3625e98d7820 · 2026-07-08T13:25:34.000+08:00
现象：iOS 订阅成功但 RC App User ID 为 $RCAnonymousID（未绑 Supabase user id），
Supabase user_entitlements 无记录。

根因：SubscriptionController.build 的 ref.listen(subscriptionIdentityProvider)
缺 fireImmediately，只在身份"变化"时回调。启动早期路由/鉴权已把登录态落定，
controller 懒加载首次 build 时身份已是"已登录"、此后不再变化 → _onIdentityChanged
从不触发 → Purchases.logIn(supabaseUserId) 从未执行 → 购买落在匿名身份。

修复（两层）：
- fail-closed 门禁（正确性底线）：PurchaseService 新增 ensureIdentified(userId)；
  RC 实现 logIn(userId) 后核对 Purchases.appUserID==userId，异常/不匹配返回 false。
  controller.purchase/restore 开头 _ensurePurchaseIdentity() 未通过即抛
  PurchaseException，绝不在匿名身份成交。web/local 渠道不经 RC 匿名机制返回 true，
  Stub 返回 false。
- 自动尽早绑定（正常无感）：identity 监听补 fireImmediately: true；main.dart
  initState eager read subscriptionControllerProvider，启动即 logIn；也修复已受
  影响用户（下次启动重绑 / 匿名购买 Transfer 到 UUID）。

测试：新增 4 例（未绑定 purchase/restore 报错且不成交、已登录冷启动 build 即 logIn、
匿名冷启动不误 logOut）；FakePurchaseService 补 ensureIdentified/purchaseCalls seam。
diff --git a/lib/features/subscription/providers/subscription_controller.dart b/lib/features/subscription/providers/subscription_controller.dart
@@ -39,9 +39,12 @@ class SubscriptionController extends _$SubscriptionController {
   @override
   EntitlementState build() {
     // 监听身份变化：登出清权益、切换用户重对账。
+    // fireImmediately：build 时立即以当前身份触发一次，确保已登录用户即使在
+    // 「身份早已落定后」才首次创建本 controller，也会执行一次 Purchases.logIn 绑定
+    // （否则默认只在值变化时回调 → 老用户登录态无变化 → logIn 从不执行 → 匿名购买）。
     ref.listen(subscriptionIdentityProvider, (previous, next) {
       _onIdentityChanged(previous, next);
-    });
+    }, fireImmediately: true);
     // 监听平台侧权益变化（续费 / 退款 / 试用转正），运行期实时刷新。
     final sub = _purchases.entitlementStream.listen((_) => refresh());
     ref.onDispose(sub.cancel);
@@ -118,6 +121,7 @@ class SubscriptionController extends _$SubscriptionController {
       'Subscription',
       '发起购买: planId=$planId userId=${_identity.userId ?? "匿名"}',
     );
+    await _ensurePurchaseIdentity(); // fail-closed：未绑定 Supabase user_id 直接中止。
     try {
       final entitlement = await _purchases.purchase(planId);
       await _applyEntitlement(entitlement, _identity.userId);
@@ -145,6 +149,7 @@ class SubscriptionController extends _$SubscriptionController {
   /// 恢复购买。
   Future<void> restore() async {
     AppLogger.log('Subscription', '发起恢复购买: userId=${_identity.userId ?? "匿名"}');
+    await _ensurePurchaseIdentity(); // fail-closed：未绑定 Supabase user_id 直接中止。
     try {
       final entitlement = await _purchases.restore();
       await _applyEntitlement(entitlement, _identity.userId);
@@ -219,6 +224,24 @@ class SubscriptionController extends _$SubscriptionController {
     await _writeCache(entitlement, userId);
   }
 
+  /// 购买 / 恢复前的 fail-closed 身份门禁。
+  ///
+  /// 权益必须绑定到 Supabase user_id（跨设备、可恢复、能被 webhook 落库）。
+  /// 未登录，或购买服务无法确认已绑定到该用户（RC 仍是匿名 / 绑定异常）时，
+  /// 抛 [PurchaseException] 中止，**绝不允许在匿名身份上成交**。
+  Future<void> _ensurePurchaseIdentity() async {
+    final userId = _identity.userId;
+    if (userId == null) {
+      AppLogger.log('Subscription', '购买中止：未登录，无法绑定 Supabase user_id');
+      throw PurchaseException('订阅需先登录账号');
+    }
+    final bound = await _purchases.ensureIdentified(userId);
+    if (!bound) {
+      AppLogger.log('Subscription', '购买中止：身份未就绪（未绑定到 userId=$userId）');
+      throw PurchaseException('订阅身份未就绪，请稍后重试');
+    }
+  }
+
   /// 响应订阅身份变化。
   Future<void> _onIdentityChanged(
     SubscriptionIdentity? previous,
diff --git a/lib/features/subscription/services/local_storekit_purchase_service.dart b/lib/features/subscription/services/local_storekit_purchase_service.dart
@@ -174,6 +174,12 @@ class LocalStoreKitPurchaseService implements PurchaseService {
     // 本地模式无用户绑定（StoreKit 本地交易与账号无关）。
   }
 
+  @override
+  Future<bool> ensureIdentified(String userId) async {
+    // 本地 StoreKit 测试态，不经 RC 匿名机制，门禁直接通过。
+    return true;
+  }
+
   @override
   Future<void> invalidateCustomerInfoCache() async {
     // 无 RC 缓存可失效；以重建活跃集合作为「回源刷新」（删交易/取消后能正确降级）。
diff --git a/lib/features/subscription/services/purchase_service.dart b/lib/features/subscription/services/purchase_service.dart
@@ -50,6 +50,14 @@ abstract class PurchaseService {
   /// 将购买服务绑定到指定用户（如 RevenueCat `logIn`）。匿名为 null。
   Future<void> identify(String? userId);
 
+  /// 确保购买服务已绑定到 [userId]，并**核对绑定确已生效**。
+  ///
+  /// 购买 / 恢复前的 fail-closed 校验入口：权益必须挂在 Supabase user_id 上，
+  /// 绝不允许落在 RevenueCat 匿名身份（否则 webhook 无法映射用户、Supabase 无记录）。
+  /// RC 实现：`logIn(userId)` 后核对 `Purchases.appUserID == userId`；
+  /// 未就绪 / 不匹配 / 异常一律返回 false，调用方据此中止购买。
+  Future<bool> ensureIdentified(String userId);
+
   /// 使平台 SDK 的 CustomerInfo 本地缓存失效，强制下次回源服务端。
   ///
   /// 调试用：后台删除订阅后，SDK 仍会优先返回本地缓存的 CustomerInfo，
@@ -96,6 +104,9 @@ class StubPurchaseService implements PurchaseService {
   @override
   Future<void> identify(String? userId) async {}
 
+  @override
+  Future<bool> ensureIdentified(String userId) async => false;
+
   @override
   Future<void> invalidateCustomerInfoCache() async {}
 
diff --git a/lib/features/subscription/services/revenuecat_purchase_service.dart b/lib/features/subscription/services/revenuecat_purchase_service.dart
@@ -149,6 +149,25 @@ class RevenueCatPurchaseService implements PurchaseService {
     }
   }
 
+  @override
+  Future<bool> ensureIdentified(String userId) async {
+    // 购买前 fail-closed 校验：logIn（幂等）后核对 RC 当前 App User ID 确为
+    // 该 Supabase user_id，绑不上宁可返回 false 让上层报错，也不产生匿名购买。
+    try {
+      await Purchases.logIn(userId);
+      final current = await Purchases.appUserID;
+      final ok = current == userId;
+      AppLogger.log(
+        'Subscription',
+        'ensureIdentified: 期望=$userId 实际=$current → ${ok ? "已绑定" : "未匹配"}',
+      );
+      return ok;
+    } catch (e) {
+      AppLogger.log('Subscription', 'ensureIdentified 失败: $e');
+      return false;
+    }
+  }
+
   @override
   Future<void> invalidateCustomerInfoCache() async {
     await Purchases.invalidateCustomerInfoCache();
diff --git a/lib/features/subscription/services/web_purchase_service.dart b/lib/features/subscription/services/web_purchase_service.dart
@@ -54,6 +54,13 @@ class WebPurchaseService implements PurchaseService {
     // 身份通过 Web Purchase Link 里的 app_user_id 传递，无需在此绑定。
   }
 
+  @override
+  Future<bool> ensureIdentified(String userId) async {
+    // 网页渠道结账时以 supabase user_id 作 app_user_id，身份不经 RC 匿名机制，
+    // 无匿名购买风险，门禁直接通过。
+    return true;
+  }
+
   @override
   Future<void> invalidateCustomerInfoCache() async {}
 
diff --git a/lib/main.dart b/lib/main.dart
@@ -420,6 +420,11 @@ class _EchoLoopAppState extends ConsumerState<EchoLoopApp>
     // 预加载词典（触发下载或打开本地词典）
     ref.read(dictionaryProvider);
 
+    // 启动即建订阅控制器：配合其 fireImmediately 监听，在启动阶段就把 RevenueCat
+    // 身份绑定到当前登录用户（执行 logIn），不必等用户打开付费墙才触发；
+    // 也修复已受影响用户——下次启动即重绑 / 把匿名购买 Transfer 到其 Supabase UUID。
+    ref.read(subscriptionControllerProvider);
+
     _authSessionSubscription = ref.listenManual<AsyncValue<Session?>>(
       supabaseSessionProvider,
       (previous, next) {
diff --git a/test/features/subscription/subscription_controller_test.dart b/test/features/subscription/subscription_controller_test.dart
@@ -46,6 +46,15 @@ class FakePurchaseService implements PurchaseService {
   Object? purchaseError;
   final List<String?> identifyCalls = [];
 
+  /// ensureIdentified 返回值（默认已绑定，购买门禁通过）。
+  bool ensureIdentifiedResult = true;
+
+  /// ensureIdentified 调用记录。
+  final List<String> ensureIdentifiedCalls = [];
+
+  /// purchase 实际被调次数（验证门禁不通过时不成交）。
+  int purchaseCalls = 0;
+
   /// invalidateCustomerInfoCache 调用次数（验证清缓存动作）。
   int invalidateCalls = 0;
 
@@ -64,6 +73,7 @@ class FakePurchaseService implements PurchaseService {
 
   @override
   Future<Entitlement> purchase(String planId) async {
+    purchaseCalls++;
     final error = purchaseError;
     if (error != null) throw error;
     return purchaseResult;
@@ -75,6 +85,12 @@ class FakePurchaseService implements PurchaseService {
   @override
   Future<void> identify(String? userId) async => identifyCalls.add(userId);
 
+  @override
+  Future<bool> ensureIdentified(String userId) async {
+    ensureIdentifiedCalls.add(userId);
+    return ensureIdentifiedResult;
+  }
+
   @override
   Future<void> invalidateCustomerInfoCache() async => invalidateCalls++;
 
@@ -343,6 +359,88 @@ void main() {
     });
   });
 
+  test('fail-closed：身份未绑定 → purchase 报错且不成交', () async {
+    await withClock(Clock.fixed(now), () async {
+      final purchases = FakePurchaseService()
+        ..purchaseResult = proEntitlement
+        ..ensureIdentifiedResult = false; // 绑定未就绪
+      final container = makeContainer(
+        identity: signedIn,
+        repo: FakeEntitlementRepository((_) async => null),
+        cache: FakeEntitlementCache(),
+        purchases: purchases,
+      );
+      final controller = container.read(
+        subscriptionControllerProvider.notifier,
+      );
+      await pumpEventQueue();
+
+      await expectLater(
+        controller.purchase('pro_yearly'),
+        throwsA(isA<PurchaseException>()),
+      );
+      // 门禁被调用，但实际购买未发起。
+      expect(purchases.ensureIdentifiedCalls, contains('u1'));
+      expect(purchases.purchaseCalls, 0);
+    });
+  });
+
+  test('fail-closed：身份未绑定 → restore 报错且不发起恢复', () async {
+    await withClock(Clock.fixed(now), () async {
+      final purchases = FakePurchaseService()..ensureIdentifiedResult = false;
+      final container = makeContainer(
+        identity: signedIn,
+        repo: FakeEntitlementRepository((_) async => null),
+        cache: FakeEntitlementCache(),
+        purchases: purchases,
+      );
+      final controller = container.read(
+        subscriptionControllerProvider.notifier,
+      );
+      await pumpEventQueue();
+
+      await expectLater(
+        controller.restore(),
+        throwsA(isA<PurchaseException>()),
+      );
+      expect(purchases.ensureIdentifiedCalls, contains('u1'));
+    });
+  });
+
+  test('已登录冷启动 → build 即绑定 RC 身份（logIn）', () async {
+    await withClock(Clock.fixed(now), () async {
+      final purchases = FakePurchaseService();
+      final container = makeContainer(
+        identity: signedIn,
+        repo: FakeEntitlementRepository((_) async => null),
+        cache: FakeEntitlementCache(),
+        purchases: purchases,
+      );
+      container.read(subscriptionControllerProvider);
+      await pumpEventQueue();
+
+      // fireImmediately 令 build 即以当前已登录身份触发 identify(logIn)。
+      expect(purchases.identifyCalls, contains('u1'));
+    });
+  });
+
+  test('匿名冷启动 → 不误调 logOut', () async {
+    await withClock(Clock.fixed(now), () async {
+      final purchases = FakePurchaseService()..currentResult = Entitlement.free;
+      final container = makeContainer(
+        identity: SubscriptionIdentity.anonymous,
+        repo: FakeEntitlementRepository((_) async => null),
+        cache: FakeEntitlementCache(),
+        purchases: purchases,
+      );
+      container.read(subscriptionControllerProvider);
+      await pumpEventQueue();
+
+      // 匿名→匿名无变化，_onIdentityChanged 提前 return，不应调 logOut(null)。
+      expect(purchases.identifyCalls, isEmpty);
+    });
+  });
+
   test('clearLocalCacheAndRefresh：清缓存 + 失效 RC 缓存 + 回源重对账', () async {
     await withClock(Clock.fixed(now), () async {
       final cache = FakeEntitlementCache()..stored = cached(proEntitlement);
diff --git a/test/features/subscription/subscription_debug_screen_test.dart b/test/features/subscription/subscription_debug_screen_test.dart
@@ -32,6 +32,8 @@ class _FakePurchaseService implements PurchaseService {
   @override
   Future<void> identify(String? userId) async {}
   @override
+  Future<bool> ensureIdentified(String userId) async => true;
+  @override
   Future<void> invalidateCustomerInfoCache() async => invalidateCalls++;
   @override
   Future<Map<String, Object?>> debugCustomerInfoSnapshot() async => {
