FEAT: 按渠道处理应用更新与订阅诊断

Author: echo-loop

TASKS.md

@@ -1,8 +1,64 @@
 # Echo Loop 任务清单
 
-> 最后更新：2026-07-06（修复 Release iOS RevenueCat Apple key 变量来源）
+> 最后更新：2026-07-06（订阅页自动续费说明弱化）
 > 当前焦点：Android 结束录音闪退（离线 ASR / Silero VAD）——**仍未解决**
 
+## 已完成：订阅页自动续费说明弱化
+
+用户反馈订阅页「到期前 24 小时」提醒语气偏重且信息冗余，后续又反馈说明文字视觉仍太黑。保留自动续费与账户管理/取消的核心披露，去掉 24 小时细节，并降低辅助说明文字对比度，让它退到 CTA 下方的次要信息层级。
+
+- [x] **中文文案收敛**：`premiumAutoRenewNotice` 改为「自动续费，可在 App Store 账户中管理或取消。」。
+- [x] **英文文案同步**：英文改为 `Auto-renews. Manage or cancel in your App Store account.`。
+- [x] **视觉层级弱化**：自动续费说明使用更低透明度的 `onSurfaceVariant`，浅色模式更淡，深色模式保留可读性。
+- [x] **本地化同步**：更新 ARB 与生成的 `app_localizations*.dart` 文件，避免运行时文案分叉。
+- [x] **验证**：`flutter analyze lib/features/subscription/screens/paywall_screen.dart lib/l10n/app_localizations.dart lib/l10n/app_localizations_en.dart lib/l10n/app_localizations_zh.dart test/features/subscription/paywall_screen_test.dart` 0 问题；`flutter test test/features/subscription/paywall_screen_test.dart` 全过。
+
+  **完成时间**: 2026-07-06
+
+## 已完成：订阅页条款链接改为随内容滚动
+
+用户反馈会员页底部「服务条款 / 隐私政策」固定在安全区底部，视觉上挤压甚至遮挡订阅按钮。订阅页应按购买信息阅读顺序，把法律链接放在 CTA 与自动续费说明之后，并随页面一起滚动。
+
+- [x] **布局收敛**：`PaywallScreen` 去掉固定底部 footer，改为单一 `ListView` 承载权益、套餐、CTA、自动续费说明与法律链接。
+- [x] **法律链接位置**：`_LegalFooter` 移到购买区域末尾，仅购买态展示；会员管理态继续不展示。
+- [x] **回归测试**：补充 paywall widget 断言，锁定 `Terms of Service` 属于 `ListView` 滚动内容，并确认会员态不显示条款/隐私链接。
+- [x] **验证**：`flutter analyze lib/features/subscription/screens/paywall_screen.dart test/features/subscription/paywall_screen_test.dart` 0 问题；`flutter test test/features/subscription/paywall_screen_test.dart` 全过。
+
+  **完成时间**: 2026-07-06
+
+## 已完成：订阅价格链路诊断日志
+
+用户反馈会员页 UI 显示人民币价格，但 Apple 付款弹窗显示美区账号价格。先补齐 RevenueCat / StoreKit 价格来源日志，用于确认 `getOfferings()` 的 package price、当前 storefront、direct `getProducts()` 价格与购买前价格是否一致。
+
+- [x] **storefront 记录**：`RevenueCatPurchaseService.fetchPlans()` 与购买前分别记录 `Purchases.storefront.countryCode`。
+- [x] **Offering 价格记录**：套餐列表拉取时记录 current offering 的 package id、package type、product id 与 `storeProduct.priceString`。
+- [x] **Direct product 价格记录**：套餐列表拉取与购买前额外调用 `Purchases.getProducts(productIds)`，记录 direct product 的 `priceString`、`currencyCode` 与 raw price；查询失败只写日志，不影响现有流程。
+- [x] **验证**：`dart format lib/features/subscription/services/revenuecat_purchase_service.dart`；`flutter analyze lib/features/subscription/services/revenuecat_purchase_service.dart` 0 问题。
+
+  **完成时间**: 2026-07-06
+
+## 已完成：更新模块渠道化改造
+
+用户反馈现有更新模块存在三类风险：iOS 无法强制更新；Google Play 用户依赖后端 `version.json` 可能出现“提示更新但 Play 未上架”；Android 无法区分 Google Play 与官网/GitHub APK 安装，导致中国用户被错误导向 Google Play，甚至诱导卸载重装丢数据。
+
+- [x] **远端配置向前兼容升级**：`../fluency-frontend/apps/app/public/version.json` 保留旧顶层字段，新增 `schemaVersion=2` 与 `platforms.ios / platforms.android.googlePlay / platforms.android.apk` 渠道配置；旧客户端继续读顶层字段，新客户端优先读渠道字段。
+- [x] **iOS 强制更新补齐**：iOS 仍用 App Store Lookup 获取真实可下载 `latestVersion` 和商店链接，同时从 `version.json` 读取 iOS `minimumVersion`；若最低版本高于 App Store 当前版本则不强制，避免审核中版本锁死用户。
+- [x] **Android 渠道分流**：新增 `top.echo-loop/app_update` MethodChannel，Android 原生层只读取安装来源；Google Play 安装包主按钮打开 `market://details?id=app.echoloop`，失败回退 HTTPS 商店页；非 Play/未知来源走 APK 直链。
+- [x] **更新弹窗兜底**：APK 渠道主按钮直接下载 APK；删除 Play Core / In-App Update 逻辑，避免柔性更新完成链路、恢复状态等特殊分支。
+- [x] **验证**：`flutter analyze` 更新模块相关文件 0 问题；`flutter test test/models/app_update_info_test.dart test/services/app_update_checker_test.dart test/services/app_update_launcher_test.dart test/widgets/app_update_dialog_test.dart test/providers/app_update_provider_test.dart` 全过；`./gradlew :app:compileProdDebugKotlin -x compileFlutterBuildProdDebug` 构建成功。
+
+  **完成时间**: 2026-07-06
+
+### 收尾审查 + 加固（2026-07-06）
+
+对上述改造做可靠性审查，收敛 3 处问题：
+
+- [x] **`minimumVersion` 全平台只认 `platforms.*`**：iOS/Android GP/Android APK 三处去掉 `?? manifest.minimumVersion` 兜底，缺省回落 `'0.0.0'`。顶层 `minimumVersion` 仅供不识别 `platforms` schema 的**旧版本 App**兼容，新版本一律忽略——避免为旧版而设的顶层 min 误触发（尤其 iOS 的不可关闭强更）。`latestVersion` 不变（GP 无 per-channel latest，soft update 无阻断风险）。
+- [x] **Google Play 隐藏「直接下载 APK」逃生按钮**：贴合「统一走商店更新」并规避 Play 政策风险。移除 `secondaryDownloadUrl` 后该机制无路径再填充，一并清理死代码（model 字段、dialog 按钮/方法、传参、l10n `downloadApkDirectly`、对应测试）。
+- [x] **Launcher 回退链补齐**：GP 商店链接打不开时回退改为 `platforms.android.googlePlay.fallbackUrl ?? downloadUrl['fallback']`，使 `_googlePlayDownloadUrl` 写入的默认 Play 网页链接生效。
+- [x] **验证**：`flutter analyze` 改动文件 0 问题；更新相关 4 个测试文件（含新增「顶层 min 不波及各平台」「GP 无渠道 fallback 回退顶层」用例）全过；`flutter test` 全量 3864 通过。
+- ⚠️ **发布前需确认**：生产 `version.json` 已按各平台补齐 `platforms.*.minimumVersion`（否则该平台永不强更），顶层字段保留给旧版。
+
 ## 已完成：修复 Release iOS RevenueCat Apple key 变量来源
 
 最新 GitHub Actions `Release` run `28766561568` 中 Android release job 已成功完成 APK/AAB 构建与上传；iOS release job 失败在 `Build iOS app (no codesign)`，日志显示 `REVENUECAT_API_KEY_APPLE` 为空并触发硬校验退出。根因是 Release workflow 的 iOS 步骤读取 `${{ secrets.REVENUECAT_API_KEY_APPLE }}`，而 RevenueCat public SDK API key 按项目约定配置在 GitHub repository variables，Android 步骤也已使用 `${{ vars.REVENUECAT_API_KEY_GOOGLE }}`。

android/app/src/main/kotlin/app/echoloop/MainActivity.kt

@@ -1,5 +1,6 @@
 package app.echoloop
 
+import android.os.Build
 import com.google.android.gms.common.ConnectionResult
 import com.google.android.gms.common.GoogleApiAvailability
 import android.util.Log
@@ -9,6 +10,7 @@ import io.flutter.plugin.common.MethodChannel
 
 class MainActivity : AudioServiceActivity() {
     private var googleServicesChannel: MethodChannel? = null
+    private var appUpdateChannel: MethodChannel? = null
     private var speechPracticeHandler: AndroidSpeechPracticeHandler? = null
     private var audioDecodeHandler: AndroidAudioDecodeHandler? = null
 
@@ -26,6 +28,17 @@ class MainActivity : AudioServiceActivity() {
                 }
             }
         }
+        appUpdateChannel = MethodChannel(
+            flutterEngine.dartExecutor.binaryMessenger,
+            "top.echo-loop/app_update",
+        ).also { channel ->
+            channel.setMethodCallHandler { call, result ->
+                when (call.method) {
+                    "getInstallerPackageName" -> result.success(installerPackageName())
+                    else -> result.notImplemented()
+                }
+            }
+        }
         speechPracticeHandler = AndroidSpeechPracticeHandler(
             this, flutterEngine.dartExecutor.binaryMessenger,
         )
@@ -37,6 +50,8 @@ class MainActivity : AudioServiceActivity() {
     override fun cleanUpFlutterEngine(flutterEngine: FlutterEngine) {
         googleServicesChannel?.setMethodCallHandler(null)
         googleServicesChannel = null
+        appUpdateChannel?.setMethodCallHandler(null)
+        appUpdateChannel = null
         speechPracticeHandler?.dispose()
         speechPracticeHandler = null
         audioDecodeHandler?.dispose()
@@ -68,4 +83,20 @@ class MainActivity : AudioServiceActivity() {
             else -> "UNKNOWN"
         }
     }
+
+    private fun installerPackageName(): String? {
+        return try {
+            val installer = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                packageManager.getInstallSourceInfo(packageName).installingPackageName
+            } else {
+                @Suppress("DEPRECATION")
+                packageManager.getInstallerPackageName(packageName)
+            }
+            Log.i("AppUpdate", "installerPackageName=${installer ?: "(null)"}")
+            installer
+        } catch (e: Exception) {
+            Log.w("AppUpdate", "installer source failed", e)
+            null
+        }
+    }
 }

ios/Podfile.lock

@@ -186,6 +186,9 @@ PODS:
   - GTMSessionFetcher/Core (3.5.0)
   - GTMSessionFetcher/Full (3.5.0):
     - GTMSessionFetcher/Core
+  - in_app_purchase_storekit (0.0.1):
+    - Flutter
+    - FlutterMacOS
   - integration_test (0.0.1):
     - Flutter
   - just_audio (0.0.1):
@@ -289,6 +292,7 @@ DEPENDENCIES:
   - flutter_timezone (from `.symlinks/plugins/flutter_timezone/ios`)
   - flutter_tts (from `.symlinks/plugins/flutter_tts/ios`)
   - google_sign_in_ios (from `.symlinks/plugins/google_sign_in_ios/darwin`)
+  - in_app_purchase_storekit (from `.symlinks/plugins/in_app_purchase_storekit/darwin`)
   - integration_test (from `.symlinks/plugins/integration_test/ios`)
   - just_audio (from `.symlinks/plugins/just_audio/darwin`)
   - just_waveform (from `.symlinks/plugins/just_waveform/darwin`)
@@ -366,6 +370,8 @@ EXTERNAL SOURCES:
     :path: ".symlinks/plugins/flutter_tts/ios"
   google_sign_in_ios:
     :path: ".symlinks/plugins/google_sign_in_ios/darwin"
+  in_app_purchase_storekit:
+    :path: ".symlinks/plugins/in_app_purchase_storekit/darwin"
   integration_test:
     :path: ".symlinks/plugins/integration_test/ios"
   just_audio:
@@ -433,6 +439,7 @@ SPEC CHECKSUMS:
   GoogleUtilities: 00c88b9a86066ef77f0da2fab05f65d7768ed8e1
   GTMAppAuth: 217a876b249c3c585a54fd6f73e6b58c4f5c4238
   GTMSessionFetcher: 5aea5ba6bd522a239e236100971f10cb71b96ab6
+  in_app_purchase_storekit: 22cca7d08eebca9babdf4d07d0baccb73325d3c8
   integration_test: 4a889634ef21a45d28d50d622cf412dc6d9f586e
   just_audio: 4e391f57b79cad2b0674030a00453ca5ce817eed
   just_waveform: be2cb6dec86096cb972bf8b73c893fe16bf1cff4

ios/Runner.xcodeproj/project.pbxproj

@@ -355,14 +355,10 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-frameworks-${CONFIGURATION}-input-files.xcfilelist",
 			);
-			inputPaths = (
-			);
 			name = "[CP] Embed Pods Frameworks";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-frameworks-${CONFIGURATION}-output-files.xcfilelist",
 			);
-			outputPaths = (
-			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-frameworks.sh\"\n";
@@ -413,14 +409,10 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-resources-${CONFIGURATION}-input-files.xcfilelist",
 			);
-			inputPaths = (
-			);
 			name = "[CP] Copy Pods Resources";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-resources-${CONFIGURATION}-output-files.xcfilelist",
 			);
-			outputPaths = (
-			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-Runner/Pods-Runner-resources.sh\"\n";

lib/features/subscription/screens/paywall_screen.dart

@@ -81,30 +81,17 @@ class _PaywallScreenState extends ConsumerState<PaywallScreen> {
       body: SafeArea(
         child: Stack(
           children: [
-            Column(
-              children: [
-                Expanded(
-                  child: ListView(
-                    padding: const EdgeInsets.fromLTRB(20, 8, 20, 24),
-                    children: isPremium
-                        ? _buildMemberBody(l10n)
-                        : [
-                            _Header(l10n: l10n),
-                            const SizedBox(height: 24),
-                            _BenefitCard(l10n: l10n),
-                            const SizedBox(height: 24),
-                            _buildPurchaseArea(l10n),
-                          ],
-                  ),
-                ),
-                // 条款/隐私固定在页面底部（类登录页）；仅在展示购买选项时显示，
-                // 会员管理态无购买行为，不显示。
-                if (!isPremium)
-                  Padding(
-                    padding: const EdgeInsets.fromLTRB(20, 4, 20, 8),
-                    child: _LegalFooter(l10n: l10n),
-                  ),
-              ],
+            ListView(
+              padding: const EdgeInsets.fromLTRB(20, 8, 20, 24),
+              children: isPremium
+                  ? _buildMemberBody(l10n)
+                  : [
+                      _Header(l10n: l10n),
+                      const SizedBox(height: 24),
+                      _BenefitCard(l10n: l10n),
+                      const SizedBox(height: 24),
+                      _buildPurchaseArea(l10n),
+                    ],
             ),
             if (_busy)
               const ColoredBox(
@@ -206,10 +193,18 @@ class _PaywallScreenState extends ConsumerState<PaywallScreen> {
             Text(
               l10n.premiumAutoRenewNotice,
               style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                color: Theme.of(context).colorScheme.onSurfaceVariant,
+                color: Theme.of(context).colorScheme.onSurfaceVariant
+                    .withValues(
+                      alpha: Theme.of(context).brightness == Brightness.dark
+                          ? 0.72
+                          : 0.58,
+                    ),
               ),
               textAlign: TextAlign.center,
             ),
+            const SizedBox(height: 8),
+            // 购买相关法律链接跟随订阅按钮一起滚动，避免小屏底部固定区挤压 CTA。
+            _LegalFooter(l10n: l10n),
           ],
         );
       },

lib/features/subscription/services/revenuecat_purchase_service.dart

@@ -34,6 +34,7 @@ class RevenueCatPurchaseService implements PurchaseService {
   @override
   Future<List<SubscriptionPlan>> fetchPlans() async {
     try {
+      await _logStorefront('fetchPlans:beforeOfferings');
       final offerings = await Purchases.getOfferings();
       final current = offerings.current;
       AppLogger.log(
@@ -59,10 +60,17 @@ class RevenueCatPurchaseService implements PurchaseService {
       for (final p in current.availablePackages) {
         AppLogger.log(
           'Subscription',
-          'package=${p.identifier} type=${p.packageType} '
+          'offering package=${p.identifier} type=${p.packageType} '
               'product=${p.storeProduct.identifier} price=${p.storeProduct.priceString}',
         );
       }
+      await _logDirectProductsForDiagnostics(
+        current.availablePackages
+            .map((p) => p.storeProduct.identifier)
+            .toSet()
+            .toList(),
+        stage: 'fetchPlans:directProducts',
+      );
       return current.availablePackages.map(_packageToPlan).toList();
     } catch (e) {
       AppLogger.log('Subscription', 'getOfferings 异常: $e');
@@ -104,6 +112,10 @@ class RevenueCatPurchaseService implements PurchaseService {
           'product=${package.storeProduct.identifier} '
           'price=${package.storeProduct.priceString}',
     );
+    await _logStorefront('purchase:beforeSheet');
+    await _logDirectProductsForDiagnostics([
+      package.storeProduct.identifier,
+    ], stage: 'purchase:directProductBeforeSheet');
     try {
       final result = await Purchases.purchase(PurchaseParams.package(package));
       AppLogger.log('Subscription', 'RC purchase 完成: 交易成功，开始映射权益');
@@ -210,6 +222,56 @@ class RevenueCatPurchaseService implements PurchaseService {
     };
   }
 
+  /// 记录当前 Apple/Google 商店账号所在 storefront。
+  ///
+  /// 该值决定平台本地化价格。诊断时用它对齐 Offering 商品价、direct product
+  /// 查询价与系统付款弹窗价格，判断是否存在 SDK/商店商品详情缓存不一致。
+  Future<void> _logStorefront(String stage) async {
+    try {
+      final storefront = await Purchases.storefront;
+      AppLogger.log(
+        'Subscription',
+        'storefront[$stage]=${storefront?.countryCode ?? "null"}',
+      );
+    } catch (e) {
+      AppLogger.log('Subscription', 'storefront[$stage] 获取失败: $e');
+    }
+  }
+
+  /// 直接向 RevenueCat/商店查询商品详情并记录价格。
+  ///
+  /// Offering 的 package 内也带 [StoreProduct]，但本问题需要确认它是否与
+  /// 当前 storefront 下的 direct product 查询结果一致。这里只做诊断日志，
+  /// 不参与业务决策，避免改变现有购买路径。
+  Future<void> _logDirectProductsForDiagnostics(
+    List<String> productIds, {
+    required String stage,
+  }) async {
+    if (productIds.isEmpty) return;
+    try {
+      final products = await Purchases.getProducts(productIds);
+      final foundIds = <String>{};
+      for (final product in products) {
+        foundIds.add(product.identifier);
+        AppLogger.log(
+          'Subscription',
+          'direct product[$stage] product=${product.identifier} '
+              'price=${product.priceString} currency=${product.currencyCode} '
+              'rawPrice=${product.price}',
+        );
+      }
+      final missingIds = productIds.where((id) => !foundIds.contains(id));
+      if (missingIds.isNotEmpty) {
+        AppLogger.log(
+          'Subscription',
+          'direct product[$stage] 未返回商品: ${missingIds.toList()}',
+        );
+      }
+    } catch (e) {
+      AppLogger.log('Subscription', 'direct product[$stage] 查询失败: $e');
+    }
+  }
+
   Entitlement _entitlementFrom(CustomerInfo info) {
     final active = info.entitlements.active;
     // 诊断：打印 RevenueCat 实际返回的 active 权益键 + 全部权益键 + 我们要找的标识。

lib/l10n/app_en.arb

@@ -45,7 +45,7 @@
     }
   },
   "premiumLifetimeAccessNote": "Lifetime access, no renewal needed",
-  "premiumAutoRenewNotice": "Subscriptions auto-renew unless canceled at least 24 hours before the end of the current period. You can manage or cancel anytime in your store account.",
+  "premiumAutoRenewNotice": "Auto-renews. Manage or cancel in your App Store account.",
   "premiumNoPlans": "No plans available right now. Please try again later.",
   "premiumLoginRequired": "Please sign in before subscribing.",
   "premiumPurchaseFailed": "Purchase failed. Please try again.",