FEAT: direct 渠道接入 Paddle 支付

Author: echo-loop

.github/workflows/release.yml

@@ -153,9 +153,6 @@ jobs:
           SUPABASE_URL: ${{ vars.SUPABASE_URL }}
           SUPABASE_PUBLISHABLE_KEY: ${{ vars.SUPABASE_PUBLISHABLE_KEY }}
           GOOGLE_WEB_CLIENT_ID: ${{ vars.GOOGLE_WEB_CLIENT_ID }}
-          REVENUECAT_API_KEY_GOOGLE: ${{ vars.REVENUECAT_API_KEY_GOOGLE }}
-          # 侧载 APK 走网页支付所需的 RevenueCat Web Purchase Link 模板。
-          WEB_PURCHASE_LINK_TEMPLATE: ${{ vars.WEB_PURCHASE_LINK_TEMPLATE }}
         run: |
           flutter clean
           DART_DEFINES=(
@@ -168,19 +165,8 @@ jobs:
           if [[ -n "$POSTHOG_API_KEY" ]]; then
             DART_DEFINES+=("--dart-define=POSTHOG_API_KEY=${POSTHOG_API_KEY}")
           fi
-          if [[ -z "$REVENUECAT_API_KEY_GOOGLE" ]]; then
-            echo "ERROR: REVENUECAT_API_KEY_GOOGLE repository variable is required for Android release builds." >&2
-            exit 1
-          fi
-          DART_DEFINES+=("--dart-define=REVENUECAT_API_KEY_GOOGLE=${REVENUECAT_API_KEY_GOOGLE}")
-          # 侧载 APK（GitHub / 官网直装）：声明 direct 渠道 → 走网页支付而非 Play Billing。
-          # 缺 WEB_PURCHASE_LINK_TEMPLATE 时优雅退回原行为（不启用网页支付）。
+          # 侧载 APK（GitHub / 官网直装）：声明 direct 渠道 → 走后端 Paddle Checkout。
           DART_DEFINES+=("--dart-define=DISTRIBUTION_CHANNEL=direct")
-          if [[ -n "$WEB_PURCHASE_LINK_TEMPLATE" ]]; then
-            DART_DEFINES+=("--dart-define=WEB_PURCHASE_LINK_TEMPLATE=${WEB_PURCHASE_LINK_TEMPLATE}")
-          else
-            echo "WARN: WEB_PURCHASE_LINK_TEMPLATE 未配置，侧载 APK 将无法使用网页支付。" >&2
-          fi
           flutter build apk --release --flavor=prod \
             --target-platform android-arm64 \
             --build-name="$BUILD_NAME" \

PLAN.md

@@ -21,7 +21,7 @@ Echo Loop 是一个围绕“音频输入 + 句子级学习 + 间隔复习 + AI 
 - 词典体系：本地词典、AI 词典、网页词典、多源切换、非 modal 面板。
 - AI 能力：翻译、句子解析、单词深度解析、转录。
 - PDF 导出：学习材料导出为可打印 PDF。
-- 订阅体系：平台/渠道识别、RevenueCat 接入、Web/Paddle 托管结账、AI 配额后端裁决。
+- 订阅体系：平台/渠道识别、native RevenueCat、direct Paddle 后端结账、AI 配额后端裁决。
 
 当前主要风险：
 
@@ -59,7 +59,7 @@ Echo Loop 是一个围绕“音频输入 + 句子级学习 + 间隔复习 + AI 
 
 当前状态：
 
-- 已完成：客户端 RevenueCat 接入、订阅页、平台/渠道识别、Web checkout、AI 配额后端裁决、release 渠道注入。
+- 已完成：客户端 RevenueCat 接入、订阅页、平台/渠道识别、direct Paddle Checkout 与 Customer Portal、AI 配额后端裁决、release 渠道注入。
 - 待继续：真实生产环境验证、退款/撤销回退、多设备/换机验证、更多渠道回归。
 
 参考文档：

TASKS.md

@@ -1,6 +1,6 @@
 # Echo Loop 任务清单
 
-> 最后更新：2026-07-14（版本号升级到 1.0.26）
+> 最后更新：2026-07-15（direct 渠道切换为 Paddle 自建支付）
 > 当前焦点：Android 结束录音闪退（离线 ASR / Silero VAD）——仍未解决
 
 ## 当前优先级
@@ -60,6 +60,14 @@
 
 ## 最近完成（保留近两周）
 
+- [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 购买与恢复路径保持隔离。
+- [x] 2026-07-15 12:11：订阅页英文标题由“Echo Loop Membership”改为“Echo Loop Premium”，并补充 paywall 标题回归断言。
+- [x] 2026-07-15 10:31：统一 direct/Web 渠道订阅页右上角文案为“恢复购买”，底层仍走后端权益同步，避免“刷新”造成用户困惑。
+- [x] 2026-07-15 10:20：调整 direct 渠道订阅页中文 CTA 文案，由“前往安全结账”改为“查看订阅方案”，匹配 RevenueCat 托管页仍会展示套餐选择的实际流程。
+- [x] 2026-07-15 09:40：优化 direct 渠道 Web checkout 入口，网页支付 CTA 改为安全结账文案，使用系统内置浏览器容器打开 RevenueCat/Paddle 托管结账页，并补充未登录拦截、打开成功等待权益确认、打开失败提示的 widget 回归测试。
+- [x] 2026-07-15 09:07：补充 RevenueCat CustomerInfo 关键诊断日志，覆盖 current/purchase/restore/update 路径，输出 expiresAt、willRenew、productId、active entitlements、RC 用户与订阅明细，并补充摘要/快照回归测试。
 - [x] 2026-07-14 22:38：版本号升级到 `1.0.26`。
 - [x] 2026-07-14 22:24：修复订阅权益前台长驻跨过 expiresAt 后仍保持 Premium；`SubscriptionController` 根据有效权益到期时间安排一次性 refresh，新权益到来时重排 timer，并补到期刷新/重排/永久权益回归测试。
 - [x] 2026-07-14 22:11：收口 Web/direct 渠道恢复购买语义，`SubscriptionController.restore()` 在 Web 渠道转为后端权益刷新，避免误穿透到 `WebPurchaseService.restore()` 抛异常，并补充回归测试。

docs/subscription-setup.md

@@ -77,31 +77,29 @@ flutter run --dart-define-from-file=auth.env
 **订阅实现由 `platform + DISTRIBUTION_CHANNEL` 本地决定**：
 
 - `ios|macos + app_store` → Apple IAP / StoreKit；`android + play` → Google Play / RevenueCat Google。
-- `android|macos|windows + direct` → RevenueCat Web Purchase Link / Paddle。
+- `android|macos|windows + direct` → App 套餐页 + 后端 Paddle Checkout。
 - 未注入 key 的平台：RC 不初始化、**订阅入口整体隐藏**（设置页 tile 不渲染、`openPaywall` 拦截并提示、Paywall 路由显示占位页），app 照常匿名运行。
 - 未注入或非法 distribution 保守隐藏支付入口；旧值 `apk` / `desktop` 仅在客户端解析层兼容为 `direct`，不再作为正式 header 值。
 - 停用/启用支付需要发版；**限额侧按平台+渠道组合由后端 env 控制**（见第 7 节 `AI_QUOTA_ENFORCED_CLIENTS`）。
 
 相关代码：`lib/config/revenuecat_config.dart`（读 key + `isSubscriptionSupported`）、`lib/features/subscription/providers/subscription_availability.dart`（UI 门控 provider）、`lib/main.dart`（`Purchases.configure`）。
 
-### 非商店渠道：RevenueCat Web Paywall + Paddle
+### 非商店渠道：Paddle Checkout
 
-Android 侧载 APK / 桌面等非商店渠道不初始化 RevenueCat 原生 SDK，购买入口打开
-RevenueCat 托管 Web Paywall（底层 Paddle 计费），权益仍经 RevenueCat webhook
-落库后由 `/api/entitlements` 读回。
+Android 侧载 APK / 桌面等非商店渠道不初始化 RevenueCat 原生 SDK。App 从
+`GET /api/paddle/plans` 拉取月付/年付套餐，登录后通过 `POST /api/paddle/checkout`
+创建 Paddle transaction，并在系统浏览器容器中打开服务端返回的 checkout URL。
+权益只由 Paddle webhook 更新，App 通过 `/api/entitlements` 读回。
 
 构建时注入：
 
 ```
 DISTRIBUTION_CHANNEL=direct
-WEB_PURCHASE_LINK_TEMPLATE=https://pay.rev.cat/<token>/{app_user_id}/paywall
 ```
 
-`{app_user_id}` 会被客户端替换为 URL-encoded 的 Supabase user.id。模板未配置或缺
-`{app_user_id}` 时，网页支付入口不可用。
-
-Web/Paddle 的价格、五折优惠码、节日促销文案在 RevenueCat 托管 Paywall /
-Paddle Checkout 中维护；客户端不读取 Paddle discount，也不硬编码 Web 价格。
+客户端不接收 price ID、discount ID 或 redirect URL。价格与首年优惠由后端 Paddle
+catalog 返回；checkout completion 只进入等待态，必须等 `/api/entitlements` 确认。
+订阅管理通过 `POST /api/paddle/portal` 创建短期 Customer Portal session。
 
 ---
 

ios/Runner/AppDelegate.swift

@@ -3,6 +3,7 @@ import Flutter
 import NaturalLanguage
 import PostHog
 import Speech
+import StoreKit
 import UIKit
 import UserNotifications
 
@@ -1194,6 +1195,18 @@ private final class IOSAudioDecodeHandler: NSObject {
       }
     }
 
+    let subscriptionManagementChannel = FlutterMethodChannel(
+      name: "top.echo-loop/subscription_management",
+      binaryMessenger: controller.binaryMessenger
+    )
+    subscriptionManagementChannel.setMethodCallHandler { [weak self] (call, result) in
+      if call.method == "openManageSubscriptions" {
+        self?.openManageSubscriptions(result: result)
+      } else {
+        result(FlutterMethodNotImplemented)
+      }
+    }
+
     speechPracticeHandler = IOSSpeechPracticeHandler(binaryMessenger: controller.binaryMessenger)
     textEmbeddingHandler = IOSTextEmbeddingHandler(binaryMessenger: controller.binaryMessenger)
     audioDecodeHandler = IOSAudioDecodeHandler(binaryMessenger: controller.binaryMessenger)
@@ -1202,6 +1215,47 @@ private final class IOSAudioDecodeHandler: NSObject {
     return super.application(application, didFinishLaunchingWithOptions: launchOptions)
   }
 
+  /// 打开 iOS 系统订阅管理页。
+  ///
+  /// 使用 StoreKit 原生入口而不是浏览器 URL；Dart 侧会在本方法不可用或失败时回退
+  /// App Store 订阅管理链接，兼容旧系统与异常场景。
+  private func openManageSubscriptions(result: @escaping FlutterResult) {
+    guard #available(iOS 15.0, *) else {
+      result(FlutterError(
+        code: "unsupported",
+        message: "StoreKit subscription management requires iOS 15 or later",
+        details: nil
+      ))
+      return
+    }
+
+    let foregroundScene = UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .first { $0.activationState == .foregroundActive }
+
+    guard let scene = foregroundScene else {
+      result(FlutterError(
+        code: "no_scene",
+        message: "No foreground UIWindowScene for subscription management",
+        details: nil
+      ))
+      return
+    }
+
+    Task { @MainActor in
+      do {
+        try await AppStore.showManageSubscriptions(in: scene)
+        result(true)
+      } catch {
+        result(FlutterError(
+          code: "open_failed",
+          message: error.localizedDescription,
+          details: nil
+        ))
+      }
+    }
+  }
+
   /// 从 Info.plist 读取 API Key/Host，构造完整 PostHog 配置（含 Session Replay）并启动 SDK。
   ///
   /// 与 posthog_flutter 插件 initPlugin 的差异：插件版本不支持 sessionReplay 配置项，

lib/config/paddle_config.dart

@@ -0,0 +1,20 @@
+/// Direct 渠道 Paddle 配置。
+library;
+
+import 'package:flutter/foundation.dart' show visibleForTesting;
+
+import 'client_distribution.dart';
+import 'api_config.dart';
+
+@visibleForTesting
+bool? debugIsPaddleCheckoutChannelOverride;
+
+/// direct 构建使用后端 Paddle API；Play/App Store 构建不会进入该分支。
+bool get isPaddleCheckoutConfigured =>
+    isPaddleCheckoutChannel && apiBaseUrl.trim().isNotEmpty;
+
+bool get isPaddleCheckoutChannel {
+  final override = debugIsPaddleCheckoutChannelOverride;
+  if (override != null) return override;
+  return clientPaymentChannel == ClientPaymentChannel.web;
+}

lib/config/revenuecat_config.dart

@@ -113,7 +113,6 @@ String? get manageSubscriptionsUrl {
 }
 
 /// 按本地支付实现选择订阅管理入口。
-@visibleForTesting
 String? manageSubscriptionsUrlForChannel(
   ClientPaymentChannel channel, {
   required String webManageUrl,

lib/config/web_purchase_config.dart

@@ -5,15 +5,15 @@
 ///
 /// 真相源是 channel-aware 的 [subscriptionAvailableFor]：先由 `platform +
 /// DISTRIBUTION_CHANNEL` 决定 [clientPaymentChannel]（见 `client_distribution.dart`），
-/// 再看该渠道对应实现是否配置就绪（原生 RC key / 网页 Purchase Link）。
+/// 再看该渠道对应实现是否配置就绪（原生 RC key / Paddle 后端 API）。
 library;
 
 import 'package:flutter_riverpod/flutter_riverpod.dart' show Ref;
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 
-import '../../../config/revenuecat_config.dart';
-import '../../../config/web_purchase_config.dart';
 import '../../../config/client_distribution.dart';
+import '../../../config/paddle_config.dart';
+import '../../../config/revenuecat_config.dart';
 
 part 'subscription_availability.g.dart';
 
@@ -28,7 +28,7 @@ bool subscriptionAvailability(Ref ref) => subscriptionAvailableFor(
       isRevenueCatConfigured ||
       (useLocalStoreKit &&
           clientPaymentChannel == ClientPaymentChannel.appleStore),
-  webConfigured: isWebCheckoutConfigured,
+  webConfigured: isPaddleCheckoutConfigured,
 );
 
 /// 根据本地渠道与对应实现的配置状态决定是否展示订阅能力。
@@ -45,14 +45,14 @@ bool subscriptionAvailableFor({
   };
 }
 
-/// 当前是否走「网页支付」渠道（侧载 APK / 桌面）。
+/// 当前是否走 Paddle 网页支付渠道（侧载 APK / 桌面）。
 ///
-/// Paywall 据此切换购买交互：true 时不展示商店套餐卡、改为「浏览器结账 + 回流对账」。
-/// 测试可 override 模拟网页渠道。
+/// Paywall 据此切换购买动作：套餐仍由统一 UI 展示，点击后改为
+/// 「服务端创建 Paddle checkout + 浏览器结账 + 回流对账」。
 @riverpod
 bool webCheckoutMode(Ref ref) => webCheckoutModeFor(
   channel: clientPaymentChannel,
-  webConfigured: isWebCheckoutConfigured,
+  webConfigured: isPaddleCheckoutConfigured,
 );
 
 /// 仅 direct 且网页结账配置完整时进入 Web checkout 模式。