FIX: 调整设置页关于入口顺序

Author: echo-loop

TASKS.md

@@ -12,16 +12,13 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
-import '../config/api_config.dart';
-import '../services/backend_dio.dart';
 import 'analytics_channel.dart';
 import 'analytics_service.dart';
 import 'channels/firebase_channel.dart';
 import 'channels/log_only_channel.dart';
 import 'channels/posthog_channel.dart';
 import 'channels/umeng_channel.dart';
 import 'consent_manager.dart';
-import 'geo_interceptor.dart';
 
 /// 分析服务单例（在 main() 中通过 [initAnalyticsService] 初始化）
 late AnalyticsService _analyticsService;
@@ -66,35 +63,6 @@ Future<AnalyticsService> initAnalyticsService(
   return AnalyticsService(channel: channel, consent: consent);
 }
 
-/// 获取地区：缓存优先 → geo API → locale fallback
-///
-/// 当前仅供 GeoInterceptor 更新缓存使用，不再用于通道选择。
-/// API 成功的结果会持久化；locale fallback 不持久化。
-Future<bool> resolveIsMainlandChina(SharedPreferences prefs) async {
-  // 1. 有缓存直接用
-  final cached = prefs.getString(geoCountryKey);
-  if (cached != null) return cached == 'CN';
-
-  // 2. 无缓存：调 geo API
-  try {
-    final response = await createBackendDio(
-      connectTimeout: const Duration(seconds: 2),
-      receiveTimeout: const Duration(seconds: 2),
-    ).get('$apiBaseUrl/api/v1/user/geo');
-    final data = response.data;
-    final country = data is Map ? data['country'] as String? : null;
-    if (country != null && country.isNotEmpty) {
-      await prefs.setString(geoCountryKey, country);
-      return country == 'CN';
-    }
-  } catch (_) {
-    // API 不可用，继续 fallback
-  }
-
-  // 3. API 失败：locale fallback（不持久化）
-  return Platform.localeName.contains('CN');
-}
-
 /// 根据配置选择分析通道
 ///
 /// 当前策略：PostHog 全平台统一上报。

assets/icon/help.svg

@@ -9,6 +9,7 @@ import '../../models/audio_item.dart';
 import '../../providers/audio_library_provider.dart';
 import '../../providers/collection_provider.dart';
 import '../../services/app_logger.dart';
+import '../../services/reliable_http_downloader.dart';
 import '../../utils/app_data_dir.dart';
 import '../../utils/audio_duration.dart';
 import 'audio_finalization_service.dart';
@@ -44,9 +45,15 @@ class AudioImportService {
          transcodeService: transcodeService ?? AudioTranscodeService(),
          computeSha256: computeSha256,
          uuid: uuid,
-       );
+       ) {
+    _downloader = DioReliableHttpDownloader(dio: _dio);
+  }
 
   final Dio _dio;
+
+  /// `ReliableHttpDownloader` 接口本身不提供释放能力，本类也不做 `dispose`
+  /// （复用调用方注入的 [_dio] 或全局默认 Dio，生命周期不归本类管）。
+  late final ReliableHttpDownloader _downloader;
   final Uuid _uuid;
   final Future<Directory> Function() _resolveDataDir;
   final Future<int> Function(String relativePath) _readDurationSeconds;
@@ -278,30 +285,37 @@ class AudioImportService {
     final tmpDir = Directory(p.join(dataDir.path, 'tmp', 'audio_import'));
     await tmpDir.create(recursive: true);
 
-    final tmpFile = File(p.join(tmpDir.path, '$audioId.part'));
     final downloadedFile = File(
       p.join(tmpDir.path, '$audioId.${resolved.extension}'),
     );
     try {
-      await _dio.download(
-        resolved.uri.toString(),
-        tmpFile.path,
+      // allowResume: false——导入取消/失败不需要跨调用续传，失败即清理
+      // `.part`，与迁移前手写 finally 删临时文件的既有语义一致。
+      await _downloader.download(
+        uri: resolved.uri,
+        savePath: downloadedFile.path,
+        allowResume: false,
         cancelToken: cancelToken,
-        options: Options(followRedirects: true),
-        onReceiveProgress: (received, total) {
-          onProgress?.call(received, total <= 0 ? null : total);
-        },
+        onProgress: (received, total) => onProgress?.call(received, total),
       );
-      await tmpFile.rename(downloadedFile.path);
       return p.join('tmp', 'audio_import', p.basename(downloadedFile.path));
-    } on DioException catch (e) {
-      if (CancelToken.isCancel(e)) {
+    } on ReliableDownloadException catch (e) {
+      if (e.kind == ReliableDownloadFailure.cancelled) {
         throw const AudioImportException(
           AudioImportFailureCode.canceled,
           'Audio import canceled',
         );
       }
       _logDownloadFailure(resolved.uri, e);
+      // 磁盘写入失败已被下载器内部归类为 storage（如空间不足），单独区分，
+      // 不与「网络请求失败」混为一谈。
+      if (e.kind == ReliableDownloadFailure.storage) {
+        throw AudioImportException(
+          AudioImportFailureCode.storage,
+          'Failed to save audio',
+          e,
+        );
+      }
       throw AudioImportException(
         AudioImportFailureCode.network,
         'Failed to download audio',
@@ -313,12 +327,6 @@ class AudioImportService {
         'Failed to save audio',
         e,
       );
-    } finally {
-      if (await tmpFile.exists()) {
-        try {
-          await tmpFile.delete();
-        } catch (_) {}
-      }
     }
   }
 
@@ -365,14 +373,14 @@ class AudioImportService {
     return uri.replace(scheme: 'https', pathSegments: nextSegments);
   }
 
-  void _logDownloadFailure(Uri uri, DioException error) {
+  void _logDownloadFailure(Uri uri, ReliableDownloadException error) {
     AppLogger.log(
       _logTag,
       'download failed url=$uri '
-      'type=${error.type} '
-      'status=${error.response?.statusCode ?? "(null)"} '
-      'message=${error.message ?? "(null)"} '
-      'cause=${error.error ?? "(null)"}',
+      'kind=${error.kind} '
+      'status=${error.statusCode ?? "(null)"} '
+      'message=${error.message} '
+      'cause=${error.cause ?? "(null)"}',
     );
   }
 

lib/analytics/analytics_providers.dart

@@ -182,13 +182,9 @@ class DefaultBaiduNetdiskApi implements BaiduNetdiskApi {
     } on DioException catch (error) {
       throw _mapDioException(error, fallbackMessage: 'Baidu download failed.');
     } on ReliableDownloadException catch (error) {
-      throw BaiduNetdiskFileException(
-        kind: BaiduNetdiskFileErrorKind.network,
-        message: _displayMessageForReliableDownloadException(
-          error,
-          fallbackMessage: 'Baidu download failed.',
-        ),
-        cause: error,
+      throw _mapReliableDownloadException(
+        error,
+        fallbackMessage: 'Baidu download failed.',
       );
     }
   }
@@ -259,6 +255,40 @@ class DefaultBaiduNetdiskApi implements BaiduNetdiskApi {
     );
   }
 
+  /// 把 [ReliableHttpDownloader] 的结构化异常映射回既有错误分类。
+  ///
+  /// httpStatus 按 statusCode 复用与 [_mapDioException] 相同的
+  /// unauthorized/notFound/rateLimited 判定；cancelled 映射为 canceled；
+  /// 其余 kind（network/timeout/redirect/storage/integrity/conflict/unknown）
+  /// 统一归为 network，与迁移前「非 DioException 一律 network」的行为一致。
+  BaiduNetdiskFileException _mapReliableDownloadException(
+    ReliableDownloadException error, {
+    required String fallbackMessage,
+  }) {
+    if (error.kind == ReliableDownloadFailure.cancelled) {
+      return const BaiduNetdiskFileException(
+        kind: BaiduNetdiskFileErrorKind.canceled,
+        message: 'Baidu request canceled.',
+      );
+    }
+    final kind = switch (error.kind == ReliableDownloadFailure.httpStatus
+        ? error.statusCode
+        : null) {
+      401 || 403 => BaiduNetdiskFileErrorKind.unauthorized,
+      404 => BaiduNetdiskFileErrorKind.notFound,
+      429 => BaiduNetdiskFileErrorKind.rateLimited,
+      _ => BaiduNetdiskFileErrorKind.network,
+    };
+    return BaiduNetdiskFileException(
+      kind: kind,
+      message: _displayMessageForReliableDownloadException(
+        error,
+        fallbackMessage: fallbackMessage,
+      ),
+      cause: error,
+    );
+  }
+
   /// 保留 Dio 底层异常原因，供批量导入结果页展示可排查的失败信息。
   String _displayMessageForDioException(
     DioException error, {

lib/features/audio_import/audio_import_service.dart

@@ -15,6 +15,7 @@ import '../../../providers/audio_library_provider.dart';
 import '../../../providers/learning_progress_provider.dart';
 import '../../../providers/listening_practice/listening_practice_provider.dart';
 import '../../../services/app_logger.dart';
+import '../../../services/reliable_http_downloader.dart';
 import '../../../utils/app_data_dir.dart';
 import '../../../utils/transcript_stats.dart';
 import '../data/official_collection_api.dart';
@@ -237,33 +238,36 @@ class OfficialDownload extends _$OfficialDownload {
     String remoteAudioId,
   ) async {
     final api = ref.read(officialCollectionApiProvider);
-    final dio = Dio();
+    final downloader = DioReliableHttpDownloader(dio: Dio());
     final docDir = await getAppDataDirectory();
     final tmpDir = Directory(p.join(docDir.path, 'tmp', 'official_audio'));
     await tmpDir.create(recursive: true);
-    final tmpAudioFile = File(p.join(tmpDir.path, '${audioItem.id}.m4a.part'));
+    final tmpAudioFile = File(p.join(tmpDir.path, '${audioItem.id}.m4a'));
 
     try {
       // 1) 拉 /content（SRT + wordTimestamps + audioUrl）
       final content = await api.getAudioContent(remoteAudioId);
       if (sid != _sessionId) return false; // 过期
 
-      // 2) 下载音频到 tmp
-      await dio.download(
-        content.audioUrl,
-        tmpAudioFile.path,
+      // 2) 下载音频到 tmp（allowResume: false——失败/取消不留 `.part` 残留，
+      // 与下方 finally 清理 tmp 文件的既有语义一致；取消判定不依赖异常类型，
+      // 由 [cancel] 提前递增 sessionId、下面的 `sid != _sessionId` 检查负责丢弃）。
+      await downloader.download(
+        uri: Uri.parse(content.audioUrl),
+        savePath: tmpAudioFile.path,
+        allowResume: false,
         cancelToken: _cancelToken,
-        onReceiveProgress: (received, total) {
+        onProgress: (received, total) {
           if (sid != _sessionId) return;
           if (state is! DownloadInProgress) return;
           final prev = state as DownloadInProgress;
-          final ratio = total > 0 ? received / total : -1.0;
+          final ratio = (total != null && total > 0) ? received / total : -1.0;
           state = DownloadInProgress(
             audioItemId: prev.audioItemId,
             displayName: prev.displayName,
             progress: ratio,
             receivedBytes: received,
-            totalBytes: total <= 0 ? null : total,
+            totalBytes: total,
           );
         },
       );

lib/features/baidu_netdisk/data/baidu_netdisk_api.dart

@@ -0,0 +1,106 @@
+/// 当前用户的地区判定状态。
+///
+/// 此状态只缓存于当前 App 进程：冷启动和回到前台时会重新确认，避免把商店区、
+/// 系统地区或服务端推断出的旧结果长期写入本地偏好。
+library;
+
+/// 参与中国用户判定的证据来源。
+enum UserRegionEvidence { storefront, deviceRegion, clientConfig }
+
+/// 单个地区策略的执行状态。
+enum UserRegionSourceStatus { pending, available, skipped, failed }
+
+/// 单个地区策略的最新结果。
+class UserRegionSourceResult {
+  const UserRegionSourceResult({required this.status, this.countryCode});
+
+  const UserRegionSourceResult.pending()
+    : status = UserRegionSourceStatus.pending,
+      countryCode = null;
+
+  const UserRegionSourceResult.skipped()
+    : status = UserRegionSourceStatus.skipped,
+      countryCode = null;
+
+  const UserRegionSourceResult.failed()
+    : status = UserRegionSourceStatus.failed,
+      countryCode = null;
+
+  final UserRegionSourceStatus status;
+  final String? countryCode;
+
+  /// 此来源是否明确表明用户属于中国。
+  bool get isChina => _isChinaCountryCode(countryCode);
+
+  @override
+  String toString() => '${status.name}:${countryCode ?? "unknown"}';
+}
+
+/// 地区判定的进程内单一真相源。
+class UserRegionState {
+  const UserRegionState({
+    required this.isChinaUser,
+    required this.storefront,
+    required this.deviceRegion,
+    required this.clientConfig,
+    required this.matchedSources,
+    required this.isRefreshing,
+    this.lastRefreshedAt,
+  });
+
+  /// 以所有已知证据生成一致的最终结论。
+  factory UserRegionState.resolve({
+    required UserRegionSourceResult storefront,
+    required UserRegionSourceResult deviceRegion,
+    required UserRegionSourceResult clientConfig,
+    required bool isRefreshing,
+    DateTime? lastRefreshedAt,
+  }) {
+    final sources = <UserRegionEvidence>[
+      if (storefront.isChina) UserRegionEvidence.storefront,
+      if (deviceRegion.isChina) UserRegionEvidence.deviceRegion,
+      if (clientConfig.isChina) UserRegionEvidence.clientConfig,
+    ];
+    return UserRegionState(
+      isChinaUser: sources.isNotEmpty,
+      storefront: storefront,
+      deviceRegion: deviceRegion,
+      clientConfig: clientConfig,
+      matchedSources: List.unmodifiable(sources),
+      isRefreshing: isRefreshing,
+      lastRefreshedAt: lastRefreshedAt,
+    );
+  }
+
+  final bool isChinaUser;
+  final UserRegionSourceResult storefront;
+  final UserRegionSourceResult deviceRegion;
+  final UserRegionSourceResult clientConfig;
+  final List<UserRegionEvidence> matchedSources;
+  final bool isRefreshing;
+  final DateTime? lastRefreshedAt;
+
+  UserRegionState copyWith({
+    UserRegionSourceResult? storefront,
+    UserRegionSourceResult? deviceRegion,
+    UserRegionSourceResult? clientConfig,
+    bool? isRefreshing,
+    DateTime? lastRefreshedAt,
+  }) {
+    return UserRegionState.resolve(
+      storefront: storefront ?? this.storefront,
+      deviceRegion: deviceRegion ?? this.deviceRegion,
+      clientConfig: clientConfig ?? this.clientConfig,
+      isRefreshing: isRefreshing ?? this.isRefreshing,
+      lastRefreshedAt: lastRefreshedAt ?? this.lastRefreshedAt,
+    );
+  }
+}
+
+/// 由应用生命周期传入的刷新原因，供诊断日志区分启动和回前台。
+enum UserRegionRefreshTrigger { startup, resume }
+
+bool _isChinaCountryCode(String? countryCode) {
+  final normalized = countryCode?.trim().toUpperCase();
+  return normalized == 'CN' || normalized == 'CHN';
+}