FIX: 收口 Paddle 订阅行为与展示

Author: echo-loop

TASKS.md

@@ -1,6 +1,6 @@
 # Echo Loop 任务清单
 
-> 最后更新：2026-07-15（direct 渠道切换为 Paddle 自建支付）
+> 最后更新：2026-07-16（收口顶部优惠条展示优先级）
 > 当前焦点：Android 结束录音闪退（离线 ASR / Silero VAD）——仍未解决
 
 ## 当前优先级
@@ -60,6 +60,14 @@
 
 ## 最近完成（保留近两周）
 
+- [x] 2026-07-16 15:04：降低 direct/Paddle checkout 后权益确认轮询频次：`/api/entitlements` 轮询间隔由 3 秒改为 5 秒，保持总等待约 2 分钟，并补充轮询间隔 widget 断言。
+- [x] 2026-07-16 14:39：修复 direct/Paddle 支付等待态深色主题加载圈可见性：等待按钮禁用时保留 Premium 蓝底，spinner 使用蓝底对比色，并补充深色主题 widget 断言。
+- [x] 2026-07-16 14:26：简化 direct/Paddle 支付等待态：打开 checkout 后主订阅按钮切换为禁用加载态，移除额外等待 label 与“我已完成支付”按钮，并补充 widget 回归断言。
+- [x] 2026-07-16 11:15：收口订阅页顶部优惠高亮条：monthly/yearly 都有 paid intro offer 时只展示 yearly；yearly 不存在但 monthly 存在时展示 monthly；两者都没有可展示优惠时隐藏高亮条，并补充三类 widget 回归。
+- [x] 2026-07-16 10:55：统一 monthly/yearly paid intro offer 展示逻辑：套餐卡优惠价后缀改为只按月/年显示 `/first mo` / `/first yr`，补充中英文文案、monthly offer 显示回归与 Paddle monthly intro DTO 映射断言。
+- [x] 2026-07-16 10:45：适配后端 Paddle plans 新 DTO：App 请求不再发送 locale；direct 套餐解析移除 title / 旧 intro price 依赖，按 percentage intro offer 推导优惠展示价，并补充 repository 与价格工具回归测试。
+- [x] 2026-07-16 09:16：统一 direct/Paddle 与 native 订阅的上层行为：Paddle plans 返回 `introOffer` 时复用 native 同一套 Special offer 展示逻辑；direct 匿名权益对账直接进入 free，不再把无 token 当作 Paddle 在线源错误；补充 paywall 与 controller 回归断言。
+- [x] 2026-07-16 08:23：补强 direct/Paddle 订阅全流程关键日志，覆盖套餐加载/重试、checkout 创建与浏览器打开、权益轮询/手动检查、后端权益刷新、Customer Portal 与异常路径，便于定位未登录打开订阅页价格不显示等问题。
 - [x] 2026-07-15 23:32：修复原生订阅的“管理订阅”入口，iOS 优先调用 StoreKit 系统订阅管理页，Android 优先打开 Play Store 订阅管理页，并保留平台不可用时的外部链接兜底。
 - [x] 2026-07-15 23:04：修复原生恢复购买归属校验，RevenueCat restore 返回的订阅若已绑定其他 Echo Loop 账号则拒绝写入当前账号，并在订阅页提示登录原账号后重试。
 - [x] 2026-07-15：direct 渠道由 RevenueCat Web Purchase Link 切换为后端 Paddle 集成；App 展示 Paddle 月付/年付套餐，登录后创建 checkout、等待统一权益生效，并通过 Paddle Customer Portal 管理订阅；App Store / Google Play 的 RevenueCat 购买与恢复路径保持隔离。

lib/features/subscription/models/subscription_plan.dart

@@ -73,7 +73,7 @@ class SubscriptionPlan {
   /// 免费试用天数（[hasFreeTrial] 为 false 时为 0）。
   final int trialDays;
 
-  /// 平台配置的首期促销（免费试用 / 首期折扣），为空表示当前用户不应看到促销价。
+  /// 平台配置的 intro offer（免费试用 / 折扣），为空表示当前用户不应看到优惠价。
   final SubscriptionIntroOffer? introOffer;
 
   const SubscriptionPlan({
@@ -110,9 +110,9 @@ class SubscriptionPlan {
   );
 }
 
-/// 单个套餐的首期促销展示信息。
+/// 单个套餐的 intro offer 展示信息。
 class SubscriptionIntroOffer {
-  /// 首期促销价（本地化价格字符串）；免费试用时通常为 `$0.00`。
+  /// Intro offer 优惠价（本地化价格字符串）；免费试用时通常为 `$0.00`。
   final String priceString;
 
   /// 促销周期单位。

lib/features/subscription/providers/subscription_controller.dart

@@ -122,6 +122,11 @@ class SubscriptionController extends _$SubscriptionController {
     final identity = _identity;
     final userId = identity.userId;
     final accessToken = identity.accessToken;
+    AppLogger.log(
+      'Subscription',
+      '权益刷新开始: generation=$generation channel=${_paymentChannel.name} '
+          'userId=${userId ?? "匿名"} hasToken=${accessToken != null}',
+    );
 
     final cached = await _readValidCache(userId);
     Entitlement? remote;
@@ -132,16 +137,34 @@ class SubscriptionController extends _$SubscriptionController {
       if (_paymentChannel == ClientPaymentChannel.web &&
           userId != null &&
           accessToken != null) {
+        AppLogger.log('Subscription', 'Web/direct 权益刷新读取后端: userId=$userId');
         remote = await _repository.fetchRemote(
           userId: userId,
           accessToken: accessToken,
         );
       }
+      if (_paymentChannel == ClientPaymentChannel.web &&
+          remote == null &&
+          (userId == null || accessToken == null)) {
+        // Direct/Paddle 权益只能通过已登录账号从后端读取。匿名或 token 未就绪时
+        // 与 native 匿名无购买保持同一上层语义：明确 free，而不是把无 token 当错误态。
+        remote = Entitlement.free;
+      }
       // Native 渠道或后端不可达时，用平台购买服务的当前权益快照兜底。
-      remote ??= await _purchases.currentEntitlement();
+      if (remote == null) {
+        AppLogger.log(
+          'Subscription',
+          '权益刷新读取购买服务快照: channel=${_paymentChannel.name}',
+        );
+        remote = await _purchases.currentEntitlement();
+      }
     } catch (e) {
       // 失败不静默吞：记录错误、保留兜底，不误判为无权益。
       error = e.toString();
+      AppLogger.log(
+        'Subscription',
+        '权益刷新在线源失败: generation=$generation error=$error',
+      );
     }
 
     if (generation != _generation) return; // 已被更新的对账 / 登录切换作废。
@@ -204,32 +227,77 @@ class SubscriptionController extends _$SubscriptionController {
   /// 只有 webhook 更新后端权益并由 [refresh] 读回才算购买完成。
   Future<Uri> startPaddleCheckout(String planId) async {
     if (_paymentChannel != ClientPaymentChannel.web) {
+      AppLogger.log(
+        'Subscription',
+        'Paddle checkout 中止: channel=${_paymentChannel.name} planId=$planId',
+      );
       throw PurchaseException('当前渠道不支持 Paddle checkout');
     }
+    AppLogger.log(
+      'Subscription',
+      'Paddle checkout 创建入口: planId=$planId '
+          'userId=${_identity.userId ?? "匿名"}',
+    );
     await _ensurePurchaseIdentity();
     final token = _identity.accessToken;
     if (token == null || token.isEmpty) {
+      AppLogger.log(
+        'Subscription',
+        'Paddle checkout 中止: planId=$planId reason=tokenEmpty',
+      );
       throw PurchaseException('订阅身份未就绪，请稍后重试');
     }
-    final session = await ref
-        .read(paddleBillingRepositoryProvider)
-        .createCheckout(accessToken: token, planId: planId);
-    return session.checkoutUrl;
+    try {
+      final session = await ref
+          .read(paddleBillingRepositoryProvider)
+          .createCheckout(accessToken: token, planId: planId);
+      AppLogger.log(
+        'Subscription',
+        'Paddle checkout 创建完成: planId=$planId '
+            'attemptId=${session.attemptId} host=${session.checkoutUrl.host}',
+      );
+      return session.checkoutUrl;
+    } catch (error) {
+      AppLogger.log(
+        'Subscription',
+        'Paddle checkout 创建失败: planId=$planId error=$error',
+      );
+      rethrow;
+    }
   }
 
   /// 创建 Paddle Customer Portal session，供 direct 用户取消订阅或更新支付方式。
   Future<Uri> createPaddlePortal() async {
     if (_paymentChannel != ClientPaymentChannel.web) {
+      AppLogger.log(
+        'Subscription',
+        'Paddle Portal 中止: channel=${_paymentChannel.name}',
+      );
       throw PurchaseException('当前渠道不支持 Paddle Portal');
     }
+    AppLogger.log(
+      'Subscription',
+      'Paddle Portal 创建入口: userId=${_identity.userId ?? "匿名"}',
+    );
     await _ensurePurchaseIdentity();
     final token = _identity.accessToken;
     if (token == null || token.isEmpty) {
+      AppLogger.log('Subscription', 'Paddle Portal 中止: reason=tokenEmpty');
       throw PurchaseException('订阅身份未就绪，请稍后重试');
     }
-    return ref
-        .read(paddleBillingRepositoryProvider)
-        .createPortal(accessToken: token);
+    try {
+      final uri = await ref
+          .read(paddleBillingRepositoryProvider)
+          .createPortal(accessToken: token);
+      AppLogger.log(
+        'Subscription',
+        'Paddle Portal 创建完成: host=${uri.host} path=${uri.path}',
+      );
+      return uri;
+    } catch (error) {
+      AppLogger.log('Subscription', 'Paddle Portal 创建失败: error=$error');
+      rethrow;
+    }
   }
 
   /// 恢复购买。

lib/features/subscription/providers/subscription_plans_provider.dart

@@ -62,9 +62,19 @@ class SubscriptionPlansController
   Future<void> _refresh({required bool force}) async {
     // generation 必须在任何 await 前创建，保证后发请求始终拥有提交权。
     final generation = ++_generation;
+    AppLogger.log(
+      'Subscription',
+      '套餐刷新开始: generation=$generation force=$force',
+    );
     final service = ref.read(purchaseServiceProvider);
     final storefront = await _readStorefront(service);
-    if (!_isCurrent(generation)) return;
+    if (!_isCurrent(generation)) {
+      AppLogger.log(
+        'Subscription',
+        '套餐刷新丢弃: generation=$generation reason=storefrontOutdated',
+      );
+      return;
+    }
     final storefrontChanged =
         _lastStorefront != null &&
         storefront != null &&
@@ -75,50 +85,108 @@ class SubscriptionPlansController
         ref.read(subscriptionPlansNowProvider)().difference(lastSuccessAt) <
             subscriptionPlansRefreshInterval;
 
-    if (!force && !storefrontChanged && isFresh) return;
+    if (!force && !storefrontChanged && isFresh) {
+      AppLogger.log(
+        'Subscription',
+        '套餐刷新跳过: generation=$generation reason=freshCache '
+            'storefront=${storefront ?? "unknown"}',
+      );
+      return;
+    }
 
     final previousPlans = state.valueOrNull;
     if (storefrontChanged || previousPlans == null) {
       state = const AsyncLoading();
     }
+    AppLogger.log(
+      'Subscription',
+      '套餐刷新执行: generation=$generation storefront=${storefront ?? "unknown"} '
+          'storefrontChanged=$storefrontChanged '
+          'previousCount=${previousPlans?.length ?? 0}',
+    );
 
     try {
       // 先提交不依赖 iOS 促销资格查询的基础价格，缩短首次可见时间。
       final fastPlans = await service.fetchPlans(
         includeIntroEligibility: false,
       );
-      if (!_isCurrent(generation)) return;
+      if (!_isCurrent(generation)) {
+        AppLogger.log(
+          'Subscription',
+          '套餐基础价格丢弃: generation=$generation reason=outdated',
+        );
+        return;
+      }
       final storefrontAfterFetch = await _readStorefront(service);
-      if (!_isCurrent(generation)) return;
+      if (!_isCurrent(generation)) {
+        AppLogger.log(
+          'Subscription',
+          '套餐基础价格丢弃: generation=$generation '
+              'reason=storefrontAfterFetchOutdated',
+        );
+        return;
+      }
       if (storefront != null &&
           storefrontAfterFetch != null &&
           storefront != storefrontAfterFetch) {
         // StoreKit 在查询期间完成了跨区切换，当前返回值可能属于旧 storefront。
+        AppLogger.log(
+          'Subscription',
+          '套餐刷新检测到 storefront 切换: before=$storefront '
+              'after=$storefrontAfterFetch generation=$generation',
+        );
         state = const AsyncLoading();
         await refresh(force: true);
         return;
       }
       state = AsyncData(fastPlans);
       _lastStorefront = storefrontAfterFetch ?? storefront ?? _lastStorefront;
       _lastSuccessAt = ref.read(subscriptionPlansNowProvider)();
+      AppLogger.log(
+        'Subscription',
+        '套餐基础价格刷新成功: generation=$generation count=${fastPlans.length} '
+            'ids=${fastPlans.map((p) => p.planId).toList()}',
+      );
 
       // 再从 SDK 缓存补全促销资格；失败时继续保留已可用的基础价格。
       try {
         final completePlans = await service.fetchPlans();
-        if (!_isCurrent(generation)) return;
+        if (!_isCurrent(generation)) {
+          AppLogger.log(
+            'Subscription',
+            '套餐完整价格丢弃: generation=$generation reason=outdated',
+          );
+          return;
+        }
         state = AsyncData(completePlans);
         _lastSuccessAt = ref.read(subscriptionPlansNowProvider)();
+        AppLogger.log(
+          'Subscription',
+          '套餐完整价格刷新成功: generation=$generation '
+              'count=${completePlans.length} '
+              'ids=${completePlans.map((p) => p.planId).toList()}',
+        );
       } catch (error, stackTrace) {
         AppLogger.log('Subscription', '套餐促销资格刷新失败，保留基础价格: $error');
         AppLogger.log('Subscription', '$stackTrace');
       }
     } catch (error, stackTrace) {
-      if (!_isCurrent(generation)) return;
+      if (!_isCurrent(generation)) {
+        AppLogger.log(
+          'Subscription',
+          '套餐刷新失败但已过期: generation=$generation error=$error',
+        );
+        return;
+      }
       if (!storefrontChanged && previousPlans != null) {
         state = AsyncData(previousPlans);
         AppLogger.log('Subscription', '套餐刷新失败，保留会话缓存: $error');
       } else {
         state = AsyncError(error, stackTrace);
+        AppLogger.log(
+          'Subscription',
+          '套餐刷新失败，进入错误态: generation=$generation error=$error',
+        );
       }
     }
   }