feat: phase1 UI prep — 设备ID系统传递 + 国家本地化展示 + 继续观看直进播放页

设备标识: Android SSAID/ iOS IDFV 原生通道 → Dart DeviceIdProvider
国家解析: 注册/登录从后端 IP → 国家/语言/时区/币种 自动落库
账号资料: 全部本地化展示 (account_display.dart)
我的页: 继续观看卡片点击直接进播放页

android/app/src/main/kotlin/com/stormg/lumadrama/MainActivity.kt

@@ -4,6 +4,7 @@ package com.stormg.lumadrama
 
 import android.content.Intent
 import android.app.PictureInPictureParams
+import android.content.Context
 import android.content.res.Configuration
 import android.graphics.Bitmap
 import android.media.MediaMetadataRetriever
@@ -12,6 +13,8 @@ import android.os.Build
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import android.provider.Settings
+import android.telephony.TelephonyManager
 import android.util.Rational
 import android.content.pm.PackageManager
 import android.view.WindowManager
@@ -21,6 +24,7 @@ import io.flutter.embedding.android.FlutterActivity
 import io.flutter.embedding.engine.FlutterEngine
 import io.flutter.plugin.common.MethodChannel
 import java.io.ByteArrayOutputStream
+import java.util.Locale
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.Executors
 import java.util.concurrent.atomic.AtomicBoolean
@@ -36,6 +40,9 @@ class MainActivity : FlutterActivity() {
     private var imeInset = 0
 
     override fun onCreate(savedInstanceState: Bundle?) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            splashScreen.setOnExitAnimationListener { screen -> screen.remove() }
+        }
         super.onCreate(savedInstanceState)
         window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
     }
@@ -62,6 +69,23 @@ class MainActivity : FlutterActivity() {
                 result.success(false)
             }
         }
+        // 设备标识：SSAID 免权限，卸载重装不变，避免客户端自己生成的 id 每次重装都变
+        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "com.stormg.lumadrama/device")
+            .setMethodCallHandler { call, result ->
+                when (call.method) {
+                    "ssaid" -> {
+                        val value = try {
+                            Settings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID)
+                        } catch (_: Exception) {
+                            null
+                        }
+                        result.success(value)
+                    }
+                    // 设备区域：注册时作为服务端 IP 解析失败后的兜底
+                    "region" -> result.success(currentRegion())
+                    else -> result.notImplemented()
+                }
+            }
         MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "com.stormg.lumadrama/share")
             .setMethodCallHandler { call, result ->
                 if (call.method != "shareText") {
@@ -153,6 +177,28 @@ class MainActivity : FlutterActivity() {
             ?.bottom
             ?: 0
 
+    /** 网络运营商国家优先，其次 SIM 卡，最后系统语言；都拿不到返回空串。 */
+    private fun currentRegion(): String {
+        return try {
+            val telephony = getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+            val localeCountry = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+                resources.configuration.locales.get(0).country
+            } else {
+                @Suppress("DEPRECATION")
+                resources.configuration.locale.country
+            }
+            val candidates = listOfNotNull(
+                telephony?.networkCountryIso,
+                telephony?.simCountryIso,
+                localeCountry
+            )
+            candidates.firstOrNull { it.isNotBlank() }?.uppercase(Locale.ROOT) ?: ""
+        } catch (_: Exception) {
+            // 个别 ROM 读运营商信息会抛 SecurityException，别让注册流程卡住
+            ""
+        }
+    }
+
     private fun emitImeInset(value: Int) {
         if (value == imeInset) return
         imeInset = value

android/app/src/main/res/drawable-night-v21/launch_background.xml

@@ -1,4 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
     <item android:drawable="@color/splash_background" />
+    <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@drawable/splash_screen" />
+    </item>
 </layer-list>

android/app/src/main/res/drawable-night/launch_background.xml

@@ -1,4 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
     <item android:drawable="@color/splash_background" />
+    <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@drawable/splash_screen" />
+    </item>
 </layer-list>

android/app/src/main/res/drawable-v21/launch_background.xml

@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@color/splash_background" />
     <item>
-        <bitmap android:gravity="fill" android:src="@drawable/background"/>
+        <bitmap
-    </item>
+            android:gravity="center"
-    <item>
+            android:src="@drawable/splash_screen" />
-        <bitmap android:gravity="center" android:src="@drawable/splash"/>
     </item>
 </layer-list>

android/app/src/main/res/drawable-v31/launch_background.xml

@@ -1,6 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Author: fruit.com.cn -->
-
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
     <item android:drawable="@color/splash_background" />
+    <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@drawable/splash_screen" />
+    </item>
 </layer-list>

android/app/src/main/res/drawable/launch_background.xml

@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@color/splash_background" />
     <item>
-        <bitmap android:gravity="fill" android:src="@drawable/background"/>
+        <bitmap
-    </item>
+            android:gravity="center"
-    <item>
+            android:src="@drawable/splash_screen" />
-        <bitmap android:gravity="center" android:src="@drawable/splash"/>
     </item>
 </layer-list>

android/app/src/main/res/values-night-v31/styles.xml

@@ -8,7 +8,8 @@
         <item name="android:windowDrawsSystemBarBackgrounds">false</item>
         <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
         <item name="android:windowSplashScreenBackground">#000000</item>
-        <item name="android:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
+        <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_brand</item>
+        <item name="android:windowSplashScreenAnimationDuration">0</item>
     </style>
     <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
         <item name="android:windowBackground">@color/splash_background</item>

android/app/src/main/res/values-v31/styles.xml

@@ -8,7 +8,8 @@
         <item name="android:windowDrawsSystemBarBackgrounds">false</item>
         <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
         <item name="android:windowSplashScreenBackground">#000000</item>
-        <item name="android:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
+        <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_brand</item>
+        <item name="android:windowSplashScreenAnimationDuration">0</item>
     </style>
     <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
         <item name="android:windowBackground">@color/splash_background</item>

docs/plans/PROGRESS.md

@@ -1318,3 +1318,4 @@ $ flutter test
 - Launcher/Android 12 启动背景统一纯黑，自适应图标背景改为品牌橙。
 - Android/iOS 图标与启动资源已重新生成；应用内开屏固定 splash_logo，宽 200 等比居中。
 - `flutter analyze`：No issues found。
+- 移除 Flutter 内 `_startupSplash` 与 `startup-splash`，只保留系统原生开屏；最新斜体字标素材已重新生成。

ios/Runner.xcodeproj/project.pbxproj

@@ -11,6 +11,7 @@
 		331C808B294A63AB00263BE5 /* RunnerTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 331C807B294A618700263BE5 /* RunnerTests.swift */; };
 		3B3967161E833CAA004F5970 /* AppFrameworkInfo.plist in Resources */ = {isa = PBXBuildFile; fileRef = 3B3967151E833CAA004F5970 /* AppFrameworkInfo.plist */; };
 		74858FAF1ED2DC5600515810 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 74858FAE1ED2DC5600515810 /* AppDelegate.swift */; };
+		8C4E1A022F9A4B1000C636F3 /* WirelessDataPrompt.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8C4E1A012F9A4B1000C636F3 /* WirelessDataPrompt.swift */; };
 		7884E8682EC3CC0700C636F2 /* SceneDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */; };
 		78A318202AECB46A00862997 /* FlutterGeneratedPluginSwiftPackage in Frameworks */ = {isa = PBXBuildFile; productRef = 78A3181F2AECB46A00862997 /* FlutterGeneratedPluginSwiftPackage */; };
 		97C146FC1CF9000F007C117D /* Main.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FA1CF9000F007C117D /* Main.storyboard */; };
@@ -49,6 +50,7 @@
 		3B3967151E833CAA004F5970 /* AppFrameworkInfo.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; name = AppFrameworkInfo.plist; path = Flutter/AppFrameworkInfo.plist; sourceTree = "<group>"; };
 		74858FAD1ED2DC5600515810 /* Runner-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "Runner-Bridging-Header.h"; sourceTree = "<group>"; };
 		74858FAE1ED2DC5600515810 /* AppDelegate.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AppDelegate.swift; sourceTree = "<group>"; };
+		8C4E1A012F9A4B1000C636F3 /* WirelessDataPrompt.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = WirelessDataPrompt.swift; sourceTree = "<group>"; };
 		7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SceneDelegate.swift; sourceTree = "<group>"; };
 		78E0A7A72DC9AD7400C4905E /* FlutterGeneratedPluginSwiftPackage */ = {isa = PBXFileReference; lastKnownFileType = wrapper; name = FlutterGeneratedPluginSwiftPackage; path = Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage; sourceTree = "<group>"; };
 		7AFA3C8E1D35360C0083082E /* Release.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = Release.xcconfig; path = Flutter/Release.xcconfig; sourceTree = "<group>"; };
@@ -122,6 +124,7 @@
 				1498D2321E8E86230040F4C2 /* GeneratedPluginRegistrant.h */,
 				1498D2331E8E89220040F4C2 /* GeneratedPluginRegistrant.m */,
 				74858FAE1ED2DC5600515810 /* AppDelegate.swift */,
+				8C4E1A012F9A4B1000C636F3 /* WirelessDataPrompt.swift */,
 				7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */,
 				74858FAD1ED2DC5600515810 /* Runner-Bridging-Header.h */,
 			);
@@ -282,6 +285,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				74858FAF1ED2DC5600515810 /* AppDelegate.swift in Sources */,
+				8C4E1A022F9A4B1000C636F3 /* WirelessDataPrompt.swift in Sources */,
 				1498D2341E8E89220040F4C2 /* GeneratedPluginRegistrant.m in Sources */,
 				7884E8682EC3CC0700C636F2 /* SceneDelegate.swift in Sources */,
 			);

ios/Runner/AppDelegate.swift

@@ -2,6 +2,8 @@ import Flutter
 import UIKit
 import AVFoundation
 
+private let thumbnailHTTPHeaderFieldsKey = "AVURLAssetHTTPHeaderFieldsKey"
+
 private final class ThumbnailResponseGate {
   private let lock = NSLock()
   private var completed = false
@@ -29,12 +31,13 @@ final class RunnerFlutterViewController: FlutterViewController {
 
   override func viewDidLoad() {
     super.viewDidLoad()
-    view.backgroundColor = UIColor(red: 16.0 / 255.0, green: 12.0 / 255.0, blue: 10.0 / 255.0, alpha: 1)
+    view.backgroundColor = .black
   }
 }
 
 @main
 @objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
+  private let wirelessDataPrompt = WirelessDataPrompt()
   private let thumbnailQueue = DispatchQueue(
     label: "com.stormg.lumadrama.thumbnail",
     qos: .userInitiated
@@ -48,8 +51,19 @@ final class RunnerFlutterViewController: FlutterViewController {
     return super.application(application, didFinishLaunchingWithOptions: launchOptions)
   }
 
+  override func applicationDidBecomeActive(_ application: UIApplication) {
+    super.applicationDidBecomeActive(application)
+    requestWirelessDataPrompt()
+  }
+
+  func requestWirelessDataPrompt() {
+    wirelessDataPrompt.requestSystemPrompt()
+  }
+
   func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
     GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
+    registerWirelessDataChannel(engineBridge)
+    registerDeviceIdChannel(engineBridge)
     let channel = FlutterMethodChannel(
       name: "com.stormg.lumadrama/share",
       binaryMessenger: engineBridge.applicationRegistrar.messenger()
@@ -104,7 +118,7 @@ final class RunnerFlutterViewController: FlutterViewController {
 
       let options: [String: Any]? = headers.isEmpty
         ? nil
-        : [AVURLAssetHTTPHeaderFieldsKey: headers]
+        : [thumbnailHTTPHeaderFieldsKey: headers]
       let asset = AVURLAsset(url: assetUrl, options: options)
       let generator = AVAssetImageGenerator(asset: asset)
       generator.appliesPreferredTrackTransform = true
@@ -130,4 +144,45 @@ final class RunnerFlutterViewController: FlutterViewController {
       }
     }
   }
+
+  /// 设备标识：IDFV 免权限，卸载本 App 不变，避免客户端自生成的 id 每次重装都变。
+  /// 同通道顺带提供设备区域（ISO-2），注册时作为服务端 IP 解析失败后的兜底。
+  private func registerDeviceIdChannel(_ engineBridge: FlutterImplicitEngineBridge) {
+    let channel = FlutterMethodChannel(
+      name: "com.stormg.lumadrama/device",
+      binaryMessenger: engineBridge.applicationRegistrar.messenger()
+    )
+    channel.setMethodCallHandler { call, result in
+      switch call.method {
+      case "idfv":
+        result(UIDevice.current.identifierForVendor?.uuidString)
+      case "region":
+        if #available(iOS 16.0, *) {
+          result(Locale.current.region?.identifier)
+        } else {
+          result(Locale.current.regionCode)
+        }
+      default:
+        result(FlutterMethodNotImplemented)
+      }
+    }
+  }
+
+  private func registerWirelessDataChannel(_ engineBridge: FlutterImplicitEngineBridge) {
+    let channel = FlutterMethodChannel(
+      name: WirelessDataPrompt.channelName,
+      binaryMessenger: engineBridge.applicationRegistrar.messenger()
+    )
+    channel.setMethodCallHandler { [weak self] call, result in
+      guard call.method == WirelessDataPrompt.awaitDecisionMethod else {
+        result(FlutterMethodNotImplemented)
+        return
+      }
+      guard let self else {
+        result(nil)
+        return
+      }
+      self.wirelessDataPrompt.awaitDecision(result)
+    }
+  }
 }

ios/Runner/Base.lproj/LaunchScreen.storyboard

@@ -16,18 +16,13 @@
                     <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
                         <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
                         <subviews>
-                            <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleToFill" image="LaunchBackground" translatesAutoresizingMaskIntoConstraints="NO" id="tWc-Dq-wcI"/>
+                            <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFit" image="LaunchImage" translatesAutoresizingMaskIntoConstraints="NO" id="YRO-k0-Ey4"/>
-                            <imageView opaque="NO" clipsSubviews="YES" multipleTouchEnabled="YES" contentMode="center" image="LaunchImage" translatesAutoresizingMaskIntoConstraints="NO" id="YRO-k0-Ey4"></imageView>
                         </subviews>
-                        <color key="backgroundColor" red="1" green="1" blue="1" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
+                        <color key="backgroundColor" red="0" green="0" blue="0" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
                         <constraints>
                             <constraint firstItem="YRO-k0-Ey4" firstAttribute="leading" secondItem="Ze5-6b-2t3" secondAttribute="leading" id="3T2-ad-Qdv"/>
-                            <constraint firstItem="tWc-Dq-wcI" firstAttribute="bottom" secondItem="Ze5-6b-2t3" secondAttribute="bottom" id="RPx-PI-7Xg"/>
-                            <constraint firstItem="tWc-Dq-wcI" firstAttribute="top" secondItem="Ze5-6b-2t3" secondAttribute="top" id="SdS-ul-q2q"/>
-                            <constraint firstAttribute="trailing" secondItem="tWc-Dq-wcI" secondAttribute="trailing" id="Swv-Gf-Rwn"/>
                             <constraint firstAttribute="trailing" secondItem="YRO-k0-Ey4" secondAttribute="trailing" id="TQA-XW-tRk"/>
                             <constraint firstItem="YRO-k0-Ey4" firstAttribute="bottom" secondItem="Ze5-6b-2t3" secondAttribute="bottom" id="duK-uY-Gun"/>
-                            <constraint firstItem="tWc-Dq-wcI" firstAttribute="leading" secondItem="Ze5-6b-2t3" secondAttribute="leading" id="kV7-tw-vXt"/>
                             <constraint firstItem="YRO-k0-Ey4" firstAttribute="top" secondItem="Ze5-6b-2t3" secondAttribute="top" id="xPn-NY-SIU"/>
                         </constraints>
                     </view>
@@ -38,7 +33,6 @@
         </scene>
     </scenes>
     <resources>
-        <image name="LaunchImage" width="1400" height="1400"/>
+        <image name="LaunchImage" width="390" height="844"/>
-        <image name="LaunchBackground" width="1" height="1"/>
     </resources>
 </document>

ios/Runner/Info.plist

@@ -48,7 +48,7 @@
 					<key>NSIncludesSubdomains</key>
 					<true/>
 				</dict>
-				<key>192.168.31.187</key>
+				<key>192.168.31.243</key>
 				<dict>
 					<key>NSExceptionAllowsInsecureHTTPLoads</key>
 					<true/>

ios/Runner/SceneDelegate.swift

@@ -1,6 +1,11 @@
+// Author: fruit.com.cn
+
 import Flutter
 import UIKit
 
 class SceneDelegate: FlutterSceneDelegate {
-
+  override func sceneDidBecomeActive(_ scene: UIScene) {
+    super.sceneDidBecomeActive(scene)
+    (UIApplication.shared.delegate as? AppDelegate)?.requestWirelessDataPrompt()
+  }
 }

ios/Runner/WirelessDataPrompt.swift

@@ -0,0 +1,68 @@
+// Author: fruit.com.cn
+
+import CoreTelephony
+import Flutter
+import Foundation
+
+/// 监听系统无线数据选择，并用 URLSession 唤起系统选择框。
+final class WirelessDataPrompt {
+  static let channelName = "com.stormg.lumadrama/wireless-data"
+  static let awaitDecisionMethod = "awaitDecision"
+
+  /// 系统选择框由 URLSession 触发，Dart 的 Socket 请求不会弹出。
+  private static let promptURL = URL(string: "https://captive.apple.com/hotspot-detect.html")
+
+  private let cellularData = CTCellularData()
+  private let lock = NSLock()
+  private var pending: [FlutterResult] = []
+  private var decided = false
+  private var didRequestPrompt = false
+
+  init() {
+    cellularData.cellularDataRestrictionDidUpdateNotifier = { [weak self] state in
+      DispatchQueue.main.async {
+        self?.completeIfDecided(state)
+      }
+    }
+  }
+
+  /// 应用进入前台后请求一次，促使系统弹出无线数据选择。
+  func requestSystemPrompt() {
+    guard !didRequestPrompt, let promptURL = Self.promptURL else {
+      return
+    }
+    didRequestPrompt = true
+    _ = cellularData.restrictedState
+    URLSession.shared.dataTask(with: promptURL) { _, _, _ in }.resume()
+  }
+
+  /// 未允许前先挂起；用户允许无线数据后再放行。
+  func awaitDecision(_ result: @escaping FlutterResult) {
+    lock.lock()
+    if decided {
+      lock.unlock()
+      DispatchQueue.main.async {
+        result(nil)
+      }
+      return
+    }
+    pending.append(result)
+    lock.unlock()
+  }
+
+  private func completeIfDecided(_ state: CTCellularDataRestrictedState) {
+    if state != .notRestricted {
+      return
+    }
+    lock.lock()
+    if decided {
+      lock.unlock()
+      return
+    }
+    decided = true
+    let waiters = pending
+    pending.removeAll()
+    lock.unlock()
+    waiters.forEach { $0(nil) }
+  }
+}

lib/app.dart

@@ -14,6 +14,7 @@ import 'core/data/remote/catalog_api.dart';
 import 'core/data/remote/category_api.dart';
 import 'core/data/remote/comment_api.dart';
 import 'core/data/remote/commerce_api.dart';
+import 'core/data/remote/device_profile.dart';
 import 'core/data/remote/download_api.dart';
 import 'core/data/remote/interaction_api.dart';
 import 'core/data/remote/library_api.dart';
@@ -30,6 +31,7 @@ import 'core/data/repositories/favorite_repository.dart';
 import 'core/data/repositories/interaction_repository.dart';
 import 'core/data/repositories/notice_repository.dart';
 import 'core/data/repositories/playback_repository.dart';
+import 'core/data/repositories/playlist_repository.dart';
 import 'core/data/repositories/search_repository.dart';
 import 'core/data/repositories/store_repository.dart';
 import 'core/data/repositories/watch_history_repository.dart';
@@ -41,6 +43,7 @@ import 'core/data/services/download_controller.dart';
 import 'core/data/services/favorite_controller.dart';
 import 'core/data/services/interaction_controller.dart';
 import 'core/data/services/locale_controller.dart';
+import 'core/data/services/playlist_controller.dart';
 import 'core/data/services/event_tracker.dart';
 import 'core/data/services/playback_position_cache.dart';
 import 'core/data/services/playback_session.dart';
@@ -83,6 +86,7 @@ class LumaDramaApp extends StatefulWidget {
     this.commerceRepository,
     this.storeRepository,
     this.searchRepository,
+    this.playlistRepository,
     this.haptics = const FlutterHaptics(),
   });
 
@@ -103,6 +107,7 @@ class LumaDramaApp extends StatefulWidget {
   final CommerceRepository? commerceRepository;
   final StoreRepository? storeRepository;
   final SearchRepository? searchRepository;
+  final PlaylistRepository? playlistRepository;
   final Haptics haptics;
 
   @override
@@ -113,12 +118,13 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
   late final AuthSessionStore _sessionStore = AuthSessionStore();
 
   /// 全 App 共用一个 ApiClient：这样目录、账号、后续的互动/进度请求
-  /// 都自动带 `Authorization` 与 `X-Device-Id`，401 的刷新重试也只有一处实现。
+  /// 都自动带 `Authorization`、`X-Device-Id` 与平台头，401 的刷新重试也只有一处实现。
   late final ApiClient _apiClient = ApiClient(
     accessTokenReader: () => _auth.accessToken,
     tokenRefresher: () => _auth.refresh(),
     onUnauthorized: () => _auth.clear(),
     deviceIdReader: _sessionStore.deviceId,
+    platformReader: clientPlatform,
   );
 
   late final AuthController _auth = AuthController(
@@ -126,8 +132,10 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
     _sessionStore,
   );
 
+  late final CatalogApi _catalogApi = CatalogApi(_apiClient);
+
   late final CatalogRepository _catalogRepository =
-      widget.catalogRepository ?? HttpCatalogRepository(CatalogApi(_apiClient));
+      widget.catalogRepository ?? HttpCatalogRepository(_catalogApi);
 
   late final CategoryRepository _categoryRepository =
       widget.categoryRepository ??
@@ -135,17 +143,11 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
 
   late final WatchHistoryRepository _watchHistory =
       widget.watchHistoryRepository ??
-      HttpWatchHistoryRepository(
+      HttpWatchHistoryRepository(WatchApi(_apiClient));
-        WatchApi(_apiClient),
-        isSignedIn: () => _auth.isSignedIn,
-      );
 
   late final FavoriteRepository _favorites =
       widget.favoriteRepository ??
-      HttpFavoriteRepository(
+      HttpFavoriteRepository(LibraryApi(_apiClient));
-        LibraryApi(_apiClient),
-        isSignedIn: () => _auth.isSignedIn,
-      );
 
   late final PlaybackRepository _playback =
       widget.playbackRepository ??
@@ -177,6 +179,13 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
   late final SearchRepository _searchRepository =
       widget.searchRepository ?? HttpSearchRepository(CatalogApi(_apiClient));
 
+  /// 测试注入了目录仓库时不打剧单接口，剧单页继续用本地分区。
+  late final PlaylistRepository? _playlistRepository =
+      widget.playlistRepository ??
+      (widget.catalogRepository == null
+          ? HttpPlaylistRepository(CatalogApi(_apiClient))
+          : null);
+
   late final StoreRepository _storeRepository =
       widget.storeRepository ?? HttpStoreRepository(CommerceApi(_apiClient));
 
@@ -206,7 +215,7 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
     unawaited(_localeController.load());
     // 登录/登出时同步收藏状态：收藏属于账号，不能跨账号串联
     _auth.addListener(_onAuthChanged);
-    if (_auth.isSignedIn) unawaited(_favoriteController.load());
+    unawaited(_favoriteController.load());
     if (_auth.isSignedIn) unawaited(_walletController.load());
     unawaited(_downloadController.restore());
   }
@@ -222,6 +231,7 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
       unawaited(_walletController.load());
     } else {
       _favoriteController.clear();
+      unawaited(_favoriteController.load());
       _downloadController.reset();
       _walletController.reset();
     }
@@ -239,14 +249,26 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
     super.dispose();
   }
 
+  CategoryController _createCategories() {
+    final controller = CategoryController(_categoryRepository);
+    if (widget.catalogRepository == null) {
+      controller.dramaPageLoader = CategoryApi(_apiClient).dramas;
+    }
+    controller.load();
+    return controller;
+  }
+
   @override
   Widget build(BuildContext context) {
+    final playlists = _playlistRepository;
     return MultiProvider(
       providers: [
         Provider(create: (_) => PlaybackCoordinator()),
         Provider<EventTracker>(create: (_) => EventTracker(_apiClient)),
         Provider<PlayerFactory>(create: (_) => widget.playerFactory),
         Provider<CatalogRepository>.value(value: _catalogRepository),
+        if (widget.catalogRepository == null)
+          Provider<CatalogApi>.value(value: _catalogApi),
         Provider<PlaybackRepository>.value(value: _playback),
         Provider<PlaybackPositionCache>.value(value: _playbackPositionCache),
         Provider<WatchHistoryRepository>.value(value: _watchHistory),
@@ -260,11 +282,15 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
         Provider<SearchRepository>.value(value: _searchRepository),
         Provider<Haptics>.value(value: widget.haptics),
         ChangeNotifierProvider(
-          create: (_) => CatalogController(_catalogRepository)..load(),
+          create: (_) {
-        ),
+            final catalog = CatalogController(_catalogRepository);
-        ChangeNotifierProvider(
+            if (widget.catalogRepository != null) catalog.load();
-          create: (_) => CategoryController(_categoryRepository)..load(),
+            return catalog;
+          },
         ),
+        ChangeNotifierProvider(create: (_) => _createCategories()),
+        if (playlists != null)
+          ChangeNotifierProvider(create: (_) => PlaylistController(playlists)),
         ChangeNotifierProvider.value(value: _favoriteController),
         ChangeNotifierProvider.value(value: _downloadController),
         ChangeNotifierProvider.value(value: _walletController),

lib/core/config/app_config.dart

@@ -14,7 +14,7 @@ class AppConfig {
   /// 开发调试默认服务地址，当前指向本机局域网 IP。
   ///
   /// 换网络时只改这一行，地址不要带结尾斜杠。
-  static const String devHostBaseUrl = 'http://192.168.31.187:8081';
+  static const String devHostBaseUrl = 'http://192.168.31.243:8081';
 
   /// 本机后端地址：通过 `adb reverse tcp:8081 tcp:8081` 映射到开发机，
   /// 探测可达时 App 直连本机服务；不可达时回落到公网地址。

lib/core/data/models/content_category.dart

@@ -1,17 +1,30 @@
 // Author: fruit.com.cn
 
+import 'locale_text.dart';
+
 /// 服务端内容分类。id 按契约保持字符串，避免雪花 ID 精度丢失。
 class ContentCategory {
-  const ContentCategory({required this.id, required this.name});
+  const ContentCategory({
+    required this.id,
+    required this.name,
+    this.locales = const {},
+  });
 
   final String id;
+
+  /// 中文名称，与 locales 里的 zh 相同。
   final String name;
+  final Map<String, String> locales;
 
   /// 解析 `GET /app/categories` 的单项。
   factory ContentCategory.fromJson(Map<String, dynamic> json) {
-    return ContentCategory(
+    final locales = localeMap(json['locales']);
-      id: (json['id'] ?? '').toString(),
+    final name = json['name'] as String? ?? locales['zh'] ?? '';
-      name: json['name'] as String? ?? '',
+    return ContentCategory(id: (json['id'] ?? '').toString(), name: name, locales: locales);
-    );
+  }
+
+  /// 按界面语言取名称。缺对应语言时回落到中文。
+  String localizedName(String languageCode) {
+    return localizedText(languageCode, name, locales);
   }
 }

lib/core/data/models/drama.dart

@@ -1,6 +1,9 @@
 // Author: fruit.com.cn
 
+import 'dart:ui';
+
 import 'json_numbers.dart';
+import 'locale_text.dart';
 
 /// 短剧与剧集，字段与后端 `/app/**` 的下发结构对应。
 ///
@@ -18,6 +21,7 @@ class Episode {
     this.likeCount,
     this.commentCount,
     this.thumbnailsUrl,
+    this.posterUrl,
   });
 
   final String id;
@@ -34,12 +38,14 @@ class Episode {
   final int? likeCount;
   final int? commentCount;
   final String? thumbnailsUrl;
+  final String? posterUrl;
 
   Episode withVideoUrl(
     String url, {
     int? likeCount,
     int? commentCount,
     String? thumbnailsUrl,
+    String? posterUrl,
   }) => Episode(
     id: id,
     number: number,
@@ -51,6 +57,21 @@ class Episode {
     likeCount: likeCount ?? this.likeCount,
     commentCount: commentCount ?? this.commentCount,
     thumbnailsUrl: thumbnailsUrl ?? this.thumbnailsUrl,
+    posterUrl: posterUrl ?? this.posterUrl,
+  );
+
+  Episode withStats({int? likeCount, int? commentCount}) => Episode(
+    id: id,
+    number: number,
+    title: title,
+    isFree: isFree,
+    videoUrl: videoUrl,
+    durationSec: durationSec,
+    locked: locked,
+    likeCount: likeCount ?? this.likeCount,
+    commentCount: commentCount ?? this.commentCount,
+    thumbnailsUrl: thumbnailsUrl,
+    posterUrl: posterUrl,
   );
 
   factory Episode.fromJson(Map<String, dynamic> json) {
@@ -65,6 +86,7 @@ class Episode {
       likeCount: _optionalInt(json['likeCount']),
       commentCount: _optionalInt(json['commentCount']),
       thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
+      posterUrl: _optionalString(json['posterUrl']),
     );
   }
 }
@@ -76,7 +98,14 @@ class Drama {
     required this.synopsis,
     required this.posterUrl,
     this.episodes = const [],
+    this.titleLocales = const {},
+    this.synopsisLocales = const {},
+    this.tag = '',
+    this.tagLocales = const {},
+    this.tagColor = '',
     this.category = '',
+    this.categoryLocales = const {},
+    this.types = const [],
     this.genre = '',
     this.totalEpisodes = 0,
     this.freeEpisodes = 0,
@@ -94,9 +123,16 @@ class Drama {
   final String id;
   final String title;
   final String synopsis;
+  final Map<String, String> titleLocales;
+  final Map<String, String> synopsisLocales;
+  final String tag;
+  final Map<String, String> tagLocales;
+  final String tagColor;
   final String posterUrl;
   final List<Episode> episodes;
   final String category;
+  final Map<String, String> categoryLocales;
+  final List<Map<String, String>> types;
   final String genre;
   final int totalEpisodes;
   final int freeEpisodes;
@@ -127,19 +163,26 @@ class Drama {
   /// 列表卡片：带一集可播预览（首页直接起播），完整剧集进详情再取。
   factory Drama.fromCardJson(Map<String, dynamic> json) {
     final preview = json['preview'];
+    final text = _DramaText.fromJson(json);
     return Drama(
       id: (json['id'] ?? '').toString(),
-      title: json['title'] as String? ?? '',
+      title: text.title,
-      synopsis: json['synopsis'] as String? ?? '',
+      synopsis: text.synopsis,
+      titleLocales: text.titleLocales,
+      synopsisLocales: text.synopsisLocales,
+      tag: text.tag,
+      tagLocales: text.tagLocales,
+      tagColor: json['tagColor'] as String? ?? '',
       posterUrl: json['cover'] as String? ?? '',
       episodes: preview is Map<String, dynamic>
           ? [Episode.fromJson(preview)]
           : const [],
-      category: json['category'] as String? ?? '',
+      category: text.category,
-      genre: json['genre'] as String? ?? '',
+      categoryLocales: text.categoryLocales,
+      types: text.types,
+      genre: text.genre,
       totalEpisodes: (json['totalEpisodes'] as num?)?.toInt() ?? 0,
       isHot: json['isHot'] == true,
-      // viewCount 后端是 Long，按字符串下发（见 json_numbers.dart）
       viewCount: jsonToInt(json['viewCount']),
       likeCount: _optionalInt(json['likeCount']),
       favoriteCount: _optionalInt(json['favoriteCount']),
@@ -152,13 +195,21 @@ class Drama {
 
   /// 详情：带剧集列表。
   factory Drama.fromDetailJson(Map<String, dynamic> json) {
+    final text = _DramaText.fromJson(json);
     return Drama(
       id: (json['id'] ?? '').toString(),
-      title: json['title'] as String? ?? '',
+      title: text.title,
-      synopsis: json['synopsis'] as String? ?? '',
+      synopsis: text.synopsis,
+      titleLocales: text.titleLocales,
+      synopsisLocales: text.synopsisLocales,
+      tag: text.tag,
+      tagLocales: text.tagLocales,
+      tagColor: json['tagColor'] as String? ?? '',
       posterUrl: json['cover'] as String? ?? '',
-      category: json['category'] as String? ?? '',
+      category: text.category,
-      genre: json['genre'] as String? ?? '',
+      categoryLocales: text.categoryLocales,
+      types: text.types,
+      genre: text.genre,
       totalEpisodes: (json['totalEpisodes'] as num?)?.toInt() ?? 0,
       freeEpisodes: (json['freeEpisodes'] as num?)?.toInt() ?? 0,
       isHot: json['isHot'] == true,
@@ -176,6 +227,37 @@ class Drama {
           .toList(),
     );
   }
+
+  String localizedTitle(String languageCode) {
+    return localizedText(languageCode, title, titleLocales);
+  }
+
+  String localizedSynopsis(String languageCode) {
+    return localizedText(languageCode, synopsis, synopsisLocales);
+  }
+
+  String localizedTag(String languageCode) {
+    return localizedText(languageCode, tag, tagLocales);
+  }
+
+  /// 标签角标背景色。接口没给合法色值时用 fallback。
+  Color tagRibbonColor(Color fallback) {
+    final parsed = _colorFromHex(tagColor);
+    return parsed ?? fallback;
+  }
+
+  /// 按当前语言取类型名称。接口没带语言表时返回空，调用方继续用中文 genre。
+  List<String> localizedTypeLabels(String languageCode) {
+    final labels = <String>[];
+    for (final item in types) {
+      final label = localizedText(languageCode, item['zh'] ?? '', item);
+      if (label.isNotEmpty && !labels.contains(label)) labels.add(label);
+    }
+    if (labels.isNotEmpty) return labels;
+    final primary = localizedText(languageCode, '', categoryLocales);
+    if (primary.isNotEmpty) return [primary];
+    return const [];
+  }
 }
 
 int? _optionalInt(dynamic value) => value == null ? null : jsonToInt(value);
@@ -184,3 +266,81 @@ String? _optionalString(dynamic value) {
   final text = value is String ? value.trim() : '';
   return text.isEmpty ? null : text;
 }
+
+Color? _colorFromHex(String raw) {
+  final text = raw.trim();
+  if (text.length != 7 || !text.startsWith('#')) return null;
+  final value = int.tryParse(text.substring(1), radix: 16);
+  if (value == null) return null;
+  return Color(0xFF000000 | value);
+}
+
+List<Map<String, String>> _typeLocales(Object? raw) {
+  if (raw is! List) return const [];
+  return raw.whereType<Map>().map(localeMap).toList(growable: false);
+}
+
+/// 从语言表还原中文展示字段。列表接口不再单独下发 title / synopsis / tag。
+class _DramaText {
+  const _DramaText({
+    required this.title,
+    required this.synopsis,
+    required this.titleLocales,
+    required this.synopsisLocales,
+    required this.tag,
+    required this.tagLocales,
+    required this.category,
+    required this.categoryLocales,
+    required this.types,
+    required this.genre,
+  });
+
+  final String title;
+  final String synopsis;
+  final Map<String, String> titleLocales;
+  final Map<String, String> synopsisLocales;
+  final String tag;
+  final Map<String, String> tagLocales;
+  final String category;
+  final Map<String, String> categoryLocales;
+  final List<Map<String, String>> types;
+  final String genre;
+
+  factory _DramaText.fromJson(Map<String, dynamic> json) {
+    final titleLocales = localeMap(json['titleLocales']);
+    final synopsisLocales = localeMap(json['synopsisLocales']);
+    final tagLocales = localeMap(json['tagLocales']);
+    final categoryLocales = localeMap(json['categoryLocales']);
+    final types = _typeLocales(json['types']);
+    final category = _firstText(categoryLocales, json['category'], types);
+    return _DramaText(
+      title: _firstText(titleLocales, json['title']),
+      synopsis: _firstText(synopsisLocales, json['synopsis'] ?? json['description']),
+      titleLocales: titleLocales,
+      synopsisLocales: synopsisLocales,
+      tag: _firstText(tagLocales, json['tag']),
+      tagLocales: tagLocales,
+      category: category,
+      categoryLocales: categoryLocales,
+      types: types,
+      genre: _genreText(types, json['genre']),
+    );
+  }
+}
+
+String _firstText(Map<String, String> locales, Object? fallback, [List<Map<String, String>>? types]) {
+  final chinese = locales['zh'] ?? '';
+  if (chinese.isNotEmpty) return chinese;
+  if (types != null && types.isNotEmpty) {
+    final label = types.first['zh'] ?? '';
+    if (label.isNotEmpty) return label;
+  }
+  return fallback is String ? fallback : '';
+}
+
+String _genreText(List<Map<String, String>> types, Object? fallback) {
+  final names = types.map((item) => item['zh'] ?? '').where((value) => value.isNotEmpty);
+  final joined = names.join(' / ');
+  if (joined.isNotEmpty) return joined;
+  return fallback is String ? fallback : '';
+}

lib/core/data/models/episode_stats.dart

@@ -0,0 +1,55 @@
+// Author: fruit.com.cn
+
+import 'json_numbers.dart';
+
+/// 播放页轻量互动计数快照，不包含播放地址或票据信息。
+class EpisodeStats {
+  const EpisodeStats({
+    required this.episodeId,
+    required this.dramaId,
+    required this.likeCount,
+    required this.commentCount,
+    required this.favoriteCount,
+    required this.liked,
+    required this.favorited,
+  });
+
+  final String episodeId;
+  final String dramaId;
+  final int likeCount;
+  final int commentCount;
+  final int favoriteCount;
+  final bool liked;
+  final bool favorited;
+
+  EpisodeStats copyWith({
+    String? dramaId,
+    int? likeCount,
+    int? commentCount,
+    int? favoriteCount,
+    bool? liked,
+    bool? favorited,
+  }) {
+    return EpisodeStats(
+      episodeId: episodeId,
+      dramaId: dramaId ?? this.dramaId,
+      likeCount: likeCount ?? this.likeCount,
+      commentCount: commentCount ?? this.commentCount,
+      favoriteCount: favoriteCount ?? this.favoriteCount,
+      liked: liked ?? this.liked,
+      favorited: favorited ?? this.favorited,
+    );
+  }
+
+  factory EpisodeStats.fromJson(Map<String, dynamic> json) {
+    return EpisodeStats(
+      episodeId: jsonToId(json['episodeId']),
+      dramaId: jsonToId(json['dramaId']),
+      likeCount: jsonToInt(json['likeCount']),
+      commentCount: jsonToInt(json['commentCount']),
+      favoriteCount: jsonToInt(json['favoriteCount']),
+      liked: json['liked'] == true,
+      favorited: json['favorited'] == true,
+    );
+  }
+}

lib/core/data/models/home_feed.dart

@@ -48,7 +48,7 @@ class FeedSection {
   factory FeedSection.fromJson(Map<String, dynamic> json) {
     return FeedSection(
       code: json['code'] as String? ?? '',
-      title: json['title'] as String? ?? '',
+      title: _sectionTitle(json),
       dramas: (json['dramas'] as List? ?? const [])
           .whereType<Map<String, dynamic>>()
           .map(Drama.fromCardJson)
@@ -84,3 +84,12 @@ class FeedBanner {
     );
   }
 }
+
+String _sectionTitle(Map<String, dynamic> json) {
+  final locales = json['titleLocales'];
+  if (locales is Map) {
+    final chinese = locales['zh']?.toString() ?? '';
+    if (chinese.isNotEmpty) return chinese;
+  }
+  return json['title'] as String? ?? '';
+}

lib/core/data/models/interaction.dart

@@ -58,14 +58,16 @@ class LikeToggleResult {
 
 /// 控制器统一返回结果；失败消息可直接展示后端 `message`。
 class OperationResult<T> {
-  const OperationResult._(this.data, this.errorMessage);
+  const OperationResult._(this.data, this.errorMessage, this.errorCode);
 
-  const OperationResult.success([T? data]) : this._(data, null);
+  const OperationResult.success([T? data]) : this._(data, null, null);
 
-  const OperationResult.failure(this.errorMessage) : data = null;
+  const OperationResult.failure(this.errorMessage, {this.errorCode})
+    : data = null;
 
   final T? data;
   final String? errorMessage;
+  final int? errorCode;
 
   bool get isSuccess => errorMessage == null;
 }

lib/core/data/models/locale_text.dart

@@ -0,0 +1,16 @@
+// Author: fruit.com.cn
+
+/// 把接口里的语言表解析成字符串映射。
+Map<String, String> localeMap(Object? raw) {
+  if (raw is! Map) return const {};
+  return raw.map((key, value) => MapEntry('$key', value?.toString() ?? ''));
+}
+
+/// 按当前语言取文案。没有对应语言时用中文，中文也没有时用 fallback。
+String localizedText(String languageCode, String fallback, Map<String, String> locales) {
+  final selected = locales[languageCode] ?? '';
+  if (selected.isNotEmpty) return selected;
+  final chinese = locales['zh'] ?? '';
+  if (chinese.isNotEmpty) return chinese;
+  return fallback;
+}

lib/core/data/models/play_ticket.dart

@@ -14,7 +14,9 @@ class PlayTicket {
     this.unlockCoin = 0,
     this.previewSeconds = 0,
     this.qualities = const [],
+    this.tracks = const [],
     this.thumbnailsUrl,
+    this.posterUrl,
     this.likeCount,
     this.commentCount,
   });
@@ -39,9 +41,13 @@ class PlayTicket {
   /// 试看秒数：仅 `COIN_REQUIRED` 时有意义（付费解锁在 B2 做）。
   final int previewSeconds;
 
-  /// 后端下发的清晰度档位（如 AUTO / 720P / 1080P），HLS 由播放器自动切换。
+  /// 后端下发的清晰度档位（如 AUTO / 720p / 1080p）。
   final List<String> qualities;
+
+  /// 各档签名地址。AUTO 是主列表，点选其它档位时换成对应地址。
+  final List<PlayQualityTrack> tracks;
   final String? thumbnailsUrl;
+  final String? posterUrl;
   final int? likeCount;
   final int? commentCount;
 
@@ -64,7 +70,9 @@ class PlayTicket {
           .whereType<String>()
           .where((quality) => quality.isNotEmpty)
           .toList(),
+      tracks: _tracks(json['tracks'], json['playUrl'] as String? ?? ''),
       thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
+      posterUrl: _optionalString(json['posterUrl']),
       likeCount: json['likeCount'] == null
           ? null
           : jsonToInt(json['likeCount']),
@@ -75,6 +83,67 @@ class PlayTicket {
   }
 }
 
+List<PlayQualityTrack> _tracks(dynamic raw, String playUrl) {
+  final tracks = <PlayQualityTrack>[];
+  if (raw is List) {
+    for (final item in raw) {
+      if (item is! Map) continue;
+      final quality = item['quality'] as String? ?? '';
+      final url = item['playUrl'] as String? ?? '';
+      if (quality.isEmpty || url.isEmpty) continue;
+      tracks.add(PlayQualityTrack(quality: quality, playUrl: url));
+    }
+  }
+  if (tracks.isEmpty && playUrl.isNotEmpty) {
+    tracks.add(PlayQualityTrack(quality: 'AUTO', playUrl: playUrl));
+  }
+  return tracks;
+}
+
+/// 按票据里的分轨地址取播放地址；没有分轨时，从主列表路径推出同目录的单档地址。
+String? qualityPlayUrl({
+  required String quality,
+  required List<PlayQualityTrack> tracks,
+  required String currentUrl,
+}) {
+  final wanted = quality.toUpperCase();
+  for (final track in tracks) {
+    if (track.quality.toUpperCase() == wanted && track.playUrl.isNotEmpty) {
+      return track.playUrl;
+    }
+  }
+  return siblingRenditionUrl(currentUrl, wanted);
+}
+
+/// `.../master.m3u8` 与 `.../720p/index.m3u8` 互相换算，查询参数原样保留。
+String? siblingRenditionUrl(String currentUrl, String quality) {
+  final uri = Uri.tryParse(currentUrl);
+  if (uri == null || uri.path.isEmpty) return null;
+  final path = uri.path;
+  const masterSuffix = '/master.m3u8';
+  String? root;
+  if (path.endsWith(masterSuffix)) {
+    root = path.substring(0, path.length - masterSuffix.length);
+  } else {
+    final match = RegExp(r'/(\d+p)/index\.m3u8$').firstMatch(path);
+    if (match == null) return null;
+    root = path.substring(0, match.start);
+  }
+  final next = quality.toUpperCase() == 'AUTO'
+      ? '$root$masterSuffix'
+      : '$root/${quality.toLowerCase()}/index.m3u8';
+  if (next == path) return currentUrl;
+  return uri.replace(path: next).toString();
+}
+
+/// 一档清晰度的签名播放地址。
+class PlayQualityTrack {
+  const PlayQualityTrack({required this.quality, required this.playUrl});
+
+  final String quality;
+  final String playUrl;
+}
+
 String? _optionalString(dynamic value) {
   final text = value is String ? value.trim() : '';
   return text.isEmpty ? null : text;

lib/core/data/models/playlist_detail.dart

@@ -0,0 +1,68 @@
+// Author: fruit.com.cn
+
+import 'drama.dart';
+import 'locale_text.dart';
+
+/// C 端剧单：`GET /app/playlists` 与 `GET /app/playlists/{id}` 的同一结构。
+class PlaylistDetail {
+  const PlaylistDetail({
+    required this.id,
+    required this.name,
+    required this.description,
+    this.locales = const {},
+    this.descriptionLocales = const {},
+    required this.dramaCount,
+    required this.dramas,
+    this.pageIndex = 1,
+    this.pageSize = 0,
+  });
+
+  final String id;
+
+  /// 中文名称，与 locales 里的 zh 相同。
+  final String name;
+  final Map<String, String> locales;
+
+  /// 中文描述，与 descriptionLocales 里的 zh 相同。
+  final String description;
+  final Map<String, String> descriptionLocales;
+  final int dramaCount;
+  final int pageIndex;
+  final int pageSize;
+  final List<Drama> dramas;
+
+  factory PlaylistDetail.fromJson(Map<String, dynamic> json) {
+    final dramas = _dramasOf(json['list']);
+    final locales = localeMap(json['locales']);
+    final descriptions = localeMap(json['descriptionLocales']);
+    return PlaylistDetail(
+      id: (json['id'] ?? '').toString(),
+      name: json['name'] as String? ?? locales['zh'] ?? '',
+      locales: locales,
+      description: json['description'] as String? ?? descriptions['zh'] ?? '',
+      descriptionLocales: descriptions,
+      dramaCount: (json['dramaCount'] as num?)?.toInt() ?? dramas.length,
+      pageIndex: (json['pageIndex'] as num?)?.toInt() ?? 1,
+      pageSize: (json['pageSize'] as num?)?.toInt() ?? dramas.length,
+      dramas: dramas,
+    );
+  }
+
+  /// 按界面语言取名称。缺对应语言时回落到中文。
+  String localizedName(String languageCode) {
+    return localizedText(languageCode, name, locales);
+  }
+
+  /// 按界面语言取描述。缺对应语言时回落到中文。
+  String localizedDescription(String languageCode) {
+    return localizedText(languageCode, description, descriptionLocales);
+  }
+}
+
+List<Drama> _dramasOf(Object? rows) {
+  if (rows is! List) return const [];
+  return rows
+      .whereType<Map>()
+      .map((item) => Drama.fromCardJson(Map<String, dynamic>.from(item)))
+      .toList(growable: false);
+}

lib/core/data/models/watch_progress.dart

@@ -1,6 +1,7 @@
 // Author: fruit.com.cn
 
 import 'json_numbers.dart';
+import 'locale_text.dart';
 
 /// 服务端续看记录：`GET /app/watch/progress?dramaId=` 与 `/app/watch/recent` 的下发结构。
 ///
@@ -13,17 +14,20 @@ class WatchProgress {
     required this.position,
     required this.duration,
     this.dramaTitle,
+    this.titleLocales = const {},
     this.dramaCover,
     this.episodeNumber,
     this.totalEpisodes,
     this.finished = false,
     this.playCount = 0,
+    this.viewCount,
     this.updatedAt,
   });
 
   final String dramaId;
   final String episodeId;
   final String? dramaTitle;
+  final Map<String, String> titleLocales;
   final String? dramaCover;
   final int? episodeNumber;
   final int? totalEpisodes;
@@ -31,6 +35,9 @@ class WatchProgress {
   final Duration duration;
   final bool finished;
   final int playCount;
+
+  /// 短剧热度。历史列表没下发时为空，不能拿用户自己的 playCount 冒充。
+  final int? viewCount;
   final DateTime? updatedAt;
 
   bool get hasPosition => position > Duration.zero;
@@ -41,11 +48,17 @@ class WatchProgress {
     return (position.inMilliseconds / duration.inMilliseconds).clamp(0.0, 1.0);
   }
 
+  /// 按当前语言取剧名。没有对应语言时回退中文，再回退 dramaTitle。
+  String localizedTitle(String languageCode) {
+    return localizedText(languageCode, dramaTitle ?? '', titleLocales);
+  }
+
   factory WatchProgress.fromJson(Map<String, dynamic> json) {
     return WatchProgress(
       dramaId: (json['dramaId'] ?? '').toString(),
       episodeId: (json['episodeId'] ?? '').toString(),
       dramaTitle: json['dramaTitle']?.toString(),
+      titleLocales: localeMap(json['titleLocales']),
       dramaCover: json['dramaCover']?.toString(),
       episodeNumber: json['episodeNumber'] == null
           ? null
@@ -57,6 +70,9 @@ class WatchProgress {
       duration: Duration(milliseconds: jsonToInt(json['durationMs'])),
       finished: json['finished'] == true,
       playCount: jsonToInt(json['playCount']),
+      viewCount: json['viewCount'] == null
+          ? null
+          : jsonToInt(json['viewCount']),
       updatedAt: DateTime.tryParse(json['updatedAt'] as String? ?? ''),
     );
   }
@@ -65,6 +81,7 @@ class WatchProgress {
     'dramaId': dramaId,
     'episodeId': episodeId,
     if (dramaTitle != null) 'dramaTitle': dramaTitle,
+    if (titleLocales.isNotEmpty) 'titleLocales': titleLocales,
     if (dramaCover != null) 'dramaCover': dramaCover,
     if (episodeNumber != null) 'episodeNumber': episodeNumber,
     if (totalEpisodes != null) 'totalEpisodes': totalEpisodes,
@@ -72,6 +89,7 @@ class WatchProgress {
     'durationMs': duration.inMilliseconds,
     'finished': finished,
     'playCount': playCount,
+    if (viewCount != null) 'viewCount': viewCount,
     if (updatedAt != null) 'updatedAt': updatedAt!.toIso8601String(),
   };
 }

lib/core/data/models/watch_record.dart

@@ -31,9 +31,13 @@ class WatchRecord {
   }
 
   /// 服务端分页标题优先，详情标题作为回退。
-  String get displayTitle {
+  String get displayTitle => localizedDisplayTitle('zh');
-    final pageTitle = progress.dramaTitle?.trim() ?? '';
+
-    return pageTitle.isNotEmpty ? pageTitle : drama?.title.trim() ?? '';
+  /// 按当前语言取标题。分页语言表优先，详情语言表作为回退。
+  String localizedDisplayTitle(String languageCode) {
+    final pageTitle = progress.localizedTitle(languageCode).trim();
+    if (pageTitle.isNotEmpty) return pageTitle;
+    return drama?.localizedTitle(languageCode).trim() ?? '';
   }
 
   /// 服务端分页封面优先，详情封面作为回退。

lib/core/data/remote/api_client.dart

@@ -24,6 +24,7 @@ class ApiClient {
     this.tokenRefresher,
     this.onUnauthorized,
     this.deviceIdReader,
+    this.platformReader,
   }) : _fixedBaseUrl = baseUrl {
     _dio = Dio(
       BaseOptions(
@@ -40,6 +41,7 @@ class ApiClient {
       AuthHeaderInterceptor(
         accessTokenReader: accessTokenReader,
         deviceIdReader: deviceIdReader,
+        platformReader: platformReader,
       ),
       const EnvelopeInterceptor(),
       NetworkLogInterceptor(),
@@ -67,6 +69,9 @@ class ApiClient {
   /// 设备号（`X-Device-Id`）：注册风控、后续下载绑定都要用
   final Future<String> Function()? deviceIdReader;
 
+  /// 客户端平台（`X-Client-Platform`）：后台区分 iOS / Android
+  final String Function()? platformReader;
+
   Future<Object?> get(String path, {Map<String, String>? query}) {
     return _request('GET', path, query: query);
   }
@@ -148,7 +153,8 @@ class ApiClient {
             skipAuthRetry: skipAuthRetry,
           );
         }
-        onUnauthorized?.call();
+        final token = accessTokenReader?.call();
+        if (token == null || token.isEmpty) onUnauthorized?.call();
         throw ApiException(401, cause.message ?? '登录已过期');
       }
       if (cause is ApiException) {

lib/core/data/remote/api_interceptors.dart

@@ -32,7 +32,11 @@ class TokenExpiredException implements Exception {
 ///
 /// 每个请求都重新取一次令牌，所以刷新成功后重发的那次会自动带上新令牌。
 class AuthHeaderInterceptor extends Interceptor {
-  AuthHeaderInterceptor({this.accessTokenReader, this.deviceIdReader});
+  AuthHeaderInterceptor({
+    this.accessTokenReader,
+    this.deviceIdReader,
+    this.platformReader,
+  });
 
   /// 当前 access token；未登录返回 null 或空串。
   final String? Function()? accessTokenReader;
@@ -40,6 +44,9 @@ class AuthHeaderInterceptor extends Interceptor {
   /// 设备号（`X-Device-Id`）：注册风控、下载绑定都用它。
   final Future<String> Function()? deviceIdReader;
 
+  /// 客户端平台（`X-Client-Platform`）：后台区分 iOS / Android，匿名请求同样要带。
+  final String Function()? platformReader;
+
   @override
   Future<void> onRequest(
     RequestOptions options,
@@ -54,6 +61,10 @@ class AuthHeaderInterceptor extends Interceptor {
     if (deviceId != null && deviceId.isNotEmpty) {
       options.headers['X-Device-Id'] = deviceId;
     }
+    final platform = platformReader?.call() ?? '';
+    if (platform.isNotEmpty) {
+      options.headers['X-Client-Platform'] = platform;
+    }
     handler.next(options);
   }
 }

lib/core/data/remote/auth_api.dart

@@ -33,6 +33,7 @@ class AuthApi {
     required String code,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -43,6 +44,7 @@ class AuthApi {
         'code': code,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -54,7 +56,9 @@ class AuthApi {
     required String target,
     required String code,
     required String deviceId,
+    String countryCode = '',
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -63,8 +67,10 @@ class AuthApi {
         'targetType': 'PHONE',
         'target': target,
         'code': code,
+        'countryCode': countryCode,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -75,7 +81,9 @@ class AuthApi {
     required String email,
     required String password,
     required String deviceId,
+    String countryCode = '',
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -84,9 +92,10 @@ class AuthApi {
         'targetType': 'EMAIL',
         'target': email,
         'password': password,
-        'countryCode': 'ID',
+        'countryCode': countryCode,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -98,6 +107,7 @@ class AuthApi {
     required String password,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -108,17 +118,25 @@ class AuthApi {
         'password': password,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
     return AuthSession.fromJson((data as Map).cast<String, dynamic>());
   }
 
-  Future<AuthSession> refresh(String refreshToken) async {
+  Future<AuthSession> refresh(
+    String refreshToken, {
+    String platform = '',
+    String osVersion = '',
+  }) async {
     final data = await _client.post(
       '/app/auth/refresh',
-      body: {'refreshToken': refreshToken},
+      body: {
-      // 刷新请求本身不带旧令牌重试，失败就是失败
+        'refreshToken': refreshToken,
+        'platform': platform,
+        'osVersion': osVersion,
+      },
       skipAuthRetry: true,
     );
     return AuthSession.fromJson((data as Map).cast<String, dynamic>());

lib/core/data/remote/catalog_api.dart

@@ -1,6 +1,9 @@
+import '../models/content_category.dart';
 import '../models/drama.dart';
 import '../models/feed_page.dart';
 import '../models/home_feed.dart';
+import '../models/page_result.dart';
+import '../models/playlist_detail.dart';
 import '../models/search_result.dart';
 import 'api_client.dart';
 
@@ -58,12 +61,95 @@ class CatalogApi {
     return SearchResult.fromJson(_asMap(data));
   }
 
+  static const int playlistPageSize = 10;
+  static const int playlistDramaPageSize = 20;
+
+  /// 已启用剧单，分页返回，每条带已上线短剧卡片。
+  Future<PageResult<PlaylistDetail>> playlists({
+    int pageIndex = 1,
+    int pageSize = playlistPageSize,
+  }) async {
+    final data = await _client.get(
+      '/app/playlists',
+      query: {
+        'pageIndex': '$pageIndex',
+        'pageSize': '$pageSize',
+      },
+    );
+    return PageResult.parse(data, PlaylistDetail.fromJson);
+  }
+
+  /// 单个剧单详情。短剧按 pageIndex、pageSize 翻页。
+  Future<PlaylistDetail> playlist(
+    String id, {
+    int pageIndex = 1,
+    int pageSize = playlistDramaPageSize,
+  }) async {
+    return PlaylistDetail.fromJson(
+      _asMap(
+        await _client.get(
+          '/app/playlists/$id',
+          query: {
+            'pageIndex': '$pageIndex',
+            'pageSize': '$pageSize',
+          },
+        ),
+      ),
+    );
+  }
+
+  /// 已启用首页分类，名称在 locales。
+  Future<List<ContentCategory>> classifications() async {
+    return _categories(await _client.get('/app/categories'));
+  }
+
+  /// 已启用类型，名称在 locales。
+  Future<List<ContentCategory>> dramaCategories() async {
+    return _categories(await _client.get('/app/drama-categories'));
+  }
+
+  /// 已启用标签，名称在 locales。
+  Future<List<ContentCategory>> tags() async {
+    return _categories(await _client.get('/app/tags'));
+  }
+
+  static const int libraryPageSize = 20;
+
+  /// 全部短剧。同一组 id 多选为或，组与组之间为且。
+  Future<PageResult<Drama>> libraryDramas({
+    List<String> categoryIds = const [],
+    List<String> classificationIds = const [],
+    List<String> tagIds = const [],
+    int pageIndex = 1,
+    int pageSize = libraryPageSize,
+  }) async {
+    final data = await _client.post(
+      '/app/dramas/page',
+      body: {
+        'pageIndex': pageIndex,
+        'pageSize': pageSize,
+        'categoryIds': categoryIds,
+        'classificationIds': classificationIds,
+        'tagIds': tagIds,
+      },
+    );
+    return PageResult.parse(data, Drama.fromCardJson);
+  }
+
   Future<Drama> dramaDetail(String dramaId) async {
     return Drama.fromDetailJson(
       _asMap(await _client.get('/app/dramas/$dramaId')),
     );
   }
 
+  List<ContentCategory> _categories(Object? data) {
+    if (data is! List) return const [];
+    return [
+      for (final item in data)
+        if (item is Map<String, dynamic>) ContentCategory.fromJson(item),
+    ];
+  }
+
   Map<String, dynamic> _asMap(Object? data) {
     if (data is Map<String, dynamic>) return data;
     throw const ApiException(-1, '返回数据格式异常');

lib/core/data/remote/category_api.dart

@@ -1,12 +1,16 @@
 // Author: fruit.com.cn
 
 import '../models/content_category.dart';
+import '../models/drama.dart';
+import '../models/page_result.dart';
 import 'api_client.dart';
 
 /// 内容分类接口，对应契约 `GET /app/categories`。
 class CategoryApi {
   const CategoryApi(this._client);
 
+  static const int dramaPageSize = 20;
+
   final ApiClient _client;
 
   /// 拉取已启用分类，id 全程按字符串解析。
@@ -18,4 +22,20 @@ class CategoryApi {
         if (item is Map<String, dynamic>) ContentCategory.fromJson(item),
     ];
   }
+
+  /// 分类下已上线短剧，pageIndex 从 1 开始。
+  Future<PageResult<Drama>> dramas(
+    String categoryId, {
+    int pageIndex = 1,
+    int pageSize = dramaPageSize,
+  }) async {
+    final data = await _client.get(
+      '/app/categories/$categoryId/dramas',
+      query: {
+        'pageIndex': '$pageIndex',
+        'pageSize': '$pageSize',
+      },
+    );
+    return PageResult.parse(data, Drama.fromCardJson);
+  }
 }

lib/core/data/remote/device_profile.dart

@@ -0,0 +1,15 @@
+// Author: fruit.com.cn
+
+import 'dart:io' show Platform;
+
+import 'package:flutter/foundation.dart';
+
+/// 客户端平台，后台只用来区分 iOS / Android。
+///
+/// 系统版本、机型一律不上报：后台列表需要的只是「这台设备是安卓还是苹果」。
+String clientPlatform() {
+  if (kIsWeb) return 'WEB';
+  if (Platform.isAndroid) return 'ANDROID';
+  if (Platform.isIOS) return 'IOS';
+  return '';
+}

lib/core/data/remote/library_api.dart

@@ -36,4 +36,9 @@ class LibraryApi {
   Future<void> removeFavorite(String dramaId) async {
     await _client.delete('/app/favorites/$dramaId');
   }
+
+  /// 一次取消多部短剧，请求体为 dramaIds 数组。
+  Future<void> removeFavorites(List<String> dramaIds) async {
+    await _client.post('/app/favorites/remove', body: {'dramaIds': dramaIds});
+  }
 }

lib/core/data/remote/playback_api.dart

@@ -1,5 +1,6 @@
 // Author: fruit.com.cn
 
+import '../models/episode_stats.dart';
 import '../models/play_ticket.dart';
 import 'api_client.dart';
 
@@ -17,4 +18,11 @@ class PlaybackApi {
     if (data is Map<String, dynamic>) return PlayTicket.fromJson(data);
     throw const ApiException(-1, '返回数据格式异常');
   }
+
+  /// 轻量刷新互动计数：不签发地址，也不占用播放票据缓存。
+  Future<EpisodeStats> episodeStats(String episodeId) async {
+    final data = await _client.get('/app/episodes/$episodeId/stats');
+    if (data is Map<String, dynamic>) return EpisodeStats.fromJson(data);
+    throw const ApiException(-1, '返回数据格式异常');
+  }
 }

lib/core/data/remote/watch_api.dart

@@ -4,7 +4,7 @@ import '../models/page_result.dart';
 import '../models/watch_progress.dart';
 import 'api_client.dart';
 
-/// 观看进度接口：`/app/watch/*`（契约 §1.5）。全部需要登录态。
+/// 观看进度接口：`/app/watch/*`（契约 §1.5）。支持账号或设备身份。
 class WatchApi {
   const WatchApi(this._client);
 

lib/core/data/repositories/favorite_repository.dart

@@ -13,29 +13,30 @@ abstract interface class FavoriteRepository {
   Future<PageResult<Drama>> page({int pageIndex = 1, int pageSize = 20});
 
   Future<void> remove(String dramaId);
+
+  /// 一次取消多部短剧。
+  Future<void> removeMany(List<String> dramaIds);
 }
 
 class HttpFavoriteRepository implements FavoriteRepository {
-  const HttpFavoriteRepository(this._api, {this.isSignedIn});
+  const HttpFavoriteRepository(this._api);
 
   final LibraryApi _api;
 
-  /// 未登录时不请求：收藏属于账号，匿名浏览时列表按空处理（点收藏按钮会先引导登录）。
-  final bool Function()? isSignedIn;
-
-  bool get _signedIn => isSignedIn?.call() ?? true;
-
   @override
   Future<bool> toggle(String dramaId) => _api.toggleFavorite(dramaId);
 
   @override
   Future<PageResult<Drama>> page({int pageIndex = 1, int pageSize = 20}) async {
-    if (!_signedIn) return const PageResult();
     return _api.favorites(pageIndex: pageIndex, pageSize: pageSize);
   }
 
   @override
   Future<void> remove(String dramaId) => _api.removeFavorite(dramaId);
+
+  @override
+  Future<void> removeMany(List<String> dramaIds) =>
+      _api.removeFavorites(dramaIds);
 }
 
 /// 内存实现：单测与 widget 测试注入用。
@@ -51,6 +52,7 @@ class InMemoryFavoriteRepository implements FavoriteRepository {
   bool failRemove = false;
   int toggleCalls = 0;
   int pageCalls = 0;
+  int removeManyCalls = 0;
 
   @override
   Future<bool> toggle(String dramaId) async {
@@ -80,4 +82,11 @@ class InMemoryFavoriteRepository implements FavoriteRepository {
     if (failRemove) throw StateError('favorite unavailable');
     _saved.remove(dramaId);
   }
+
+  @override
+  Future<void> removeMany(List<String> dramaIds) async {
+    removeManyCalls += 1;
+    if (failRemove) throw StateError('favorite unavailable');
+    _saved.removeAll(dramaIds);
+  }
 }

lib/core/data/repositories/playback_repository.dart

@@ -1,5 +1,6 @@
 // Author: fruit.com.cn
 
+import '../models/episode_stats.dart';
 import '../models/play_ticket.dart';
 import '../remote/playback_api.dart';
 
@@ -10,6 +11,9 @@ import '../remote/playback_api.dart';
 abstract interface class PlaybackRepository {
   Future<PlayTicket> ticketFor(String episodeId, {bool forceRefresh = false});
 
+  /// 读取互动计数快照；与 [ticketFor] 分离，避免为了刷新计数重新签发地址。
+  Future<EpisodeStats> episodeStats(String episodeId);
+
   /// 当前缓存的票据是否还在有效期内（用于"回前台发现过期就重新取"）。
   bool isFresh(String episodeId);
 }
@@ -42,6 +46,10 @@ class HttpPlaybackRepository implements PlaybackRepository {
     return ticket;
   }
 
+  @override
+  Future<EpisodeStats> episodeStats(String episodeId) =>
+      _api.episodeStats(episodeId);
+
   @override
   bool isFresh(String episodeId) {
     final cached = _cache[episodeId];
@@ -65,11 +73,22 @@ class _CachedTicket {
 
 /// 测试与离线场景用：按集返回固定票据，并记录被请求过几次。
 class FakePlaybackRepository implements PlaybackRepository {
-  FakePlaybackRepository({this.ticket, this.error, this.fresh = true});
+  FakePlaybackRepository({
+    this.ticket,
+    this.error,
+    this.fresh = true,
+    this.stats,
+    this.statsError,
+    Map<String, EpisodeStats>? statsByEpisode,
+  }) : statsByEpisode = statsByEpisode ?? {};
 
   PlayTicket? ticket;
   Object? error;
+  EpisodeStats? stats;
+  Object? statsError;
+  final Map<String, EpisodeStats> statsByEpisode;
   final List<String> requests = [];
+  final List<String> statsRequests = [];
   final List<bool> forced = [];
 
   /// 模拟"票据是否还有效"：置 false 可验证回前台会重新取。
@@ -95,4 +114,13 @@ class FakePlaybackRepository implements PlaybackRepository {
           qualities: const ['AUTO', '720P', '1080P'],
         );
   }
+
+  @override
+  Future<EpisodeStats> episodeStats(String episodeId) async {
+    statsRequests.add(episodeId);
+    if (statsError != null) throw statsError!;
+    final value = statsByEpisode[episodeId] ?? stats;
+    if (value != null) return value;
+    throw StateError('episode stats not configured for $episodeId');
+  }
 }

lib/core/data/repositories/playlist_repository.dart

@@ -0,0 +1,38 @@
+// Author: fruit.com.cn
+
+import '../models/page_result.dart';
+import '../models/playlist_detail.dart';
+import '../remote/catalog_api.dart';
+
+/// 剧单来源：列表分页拉取，详情用于打开单条时刷新。
+abstract interface class PlaylistRepository {
+  Future<PageResult<PlaylistDetail>> fetchPlaylists({
+    int pageIndex = 1,
+    int pageSize = CatalogApi.playlistPageSize,
+  });
+
+  Future<PlaylistDetail> fetchPlaylist(
+    String id, {
+    int pageIndex = 1,
+    int pageSize = CatalogApi.playlistDramaPageSize,
+  });
+}
+
+class HttpPlaylistRepository implements PlaylistRepository {
+  HttpPlaylistRepository(this._api);
+
+  final CatalogApi _api;
+
+  @override
+  Future<PageResult<PlaylistDetail>> fetchPlaylists({
+    int pageIndex = 1,
+    int pageSize = CatalogApi.playlistPageSize,
+  }) => _api.playlists(pageIndex: pageIndex, pageSize: pageSize);
+
+  @override
+  Future<PlaylistDetail> fetchPlaylist(
+    String id, {
+    int pageIndex = 1,
+    int pageSize = CatalogApi.playlistDramaPageSize,
+  }) => _api.playlist(id, pageIndex: pageIndex, pageSize: pageSize);
+}

lib/core/data/repositories/watch_history_repository.dart

@@ -35,18 +35,12 @@ abstract interface class WatchHistoryRepository {
 }
 
 class HttpWatchHistoryRepository implements WatchHistoryRepository {
-  const HttpWatchHistoryRepository(this._api, {this.isSignedIn});
+  const HttpWatchHistoryRepository(this._api);
 
   final WatchApi _api;
 
-  /// 未登录时这些接口必然 401：直接短路成"没有记录"，让浏览/试看保持匿名可用。
-  final bool Function()? isSignedIn;
-
-  bool get _signedIn => isSignedIn?.call() ?? true;
-
   @override
   Future<WatchProgress?> progressFor(String dramaId) async {
-    if (!_signedIn) return null;
     return _api.progressOfDrama(dramaId);
   }
 
@@ -57,7 +51,6 @@ class HttpWatchHistoryRepository implements WatchHistoryRepository {
     Duration? duration,
     bool finished = false,
   }) async {
-    if (!_signedIn) return null;
     return _api.saveProgress(
       episodeId: episodeId,
       position: position,
@@ -71,19 +64,16 @@ class HttpWatchHistoryRepository implements WatchHistoryRepository {
     int pageIndex = 1,
     int pageSize = 20,
   }) async {
-    if (!_signedIn) return const PageResult();
     return _api.recent(pageIndex: pageIndex, pageSize: pageSize);
   }
 
   @override
   Future<void> remove(String dramaId) async {
-    if (!_signedIn) return;
     await _api.removeProgress(dramaId);
   }
 
   @override
   Future<void> clear() async {
-    if (!_signedIn) return;
     await _api.clearProgress();
   }
 }

lib/core/data/services/all_dramas_controller.dart

@@ -0,0 +1,173 @@
+// Author: fruit.com.cn
+// 全部短剧筛选与分页：拉取分类、类型、标签，并按页加载短剧。
+
+import '../models/content_category.dart';
+import '../models/drama.dart';
+import '../models/page_result.dart';
+import '../remote/catalog_api.dart';
+
+/// 全部短剧筛选与分页所需的远端能力。
+abstract interface class AllDramasRemote {
+  /// 已启用分类。
+  Future<List<ContentCategory>> classifications();
+
+  /// 已启用类型。
+  Future<List<ContentCategory>> categories();
+
+  /// 已启用标签。
+  Future<List<ContentCategory>> tags();
+
+  /// 按当前筛选取一页短剧。
+  Future<PageResult<Drama>> dramas({
+    required List<String> categoryIds,
+    required List<String> classificationIds,
+    required List<String> tagIds,
+    required int pageIndex,
+  });
+}
+
+/// 用现有目录接口实现全部短剧远端能力。
+class CatalogAllDramasRemote implements AllDramasRemote {
+  /// 绑定目录接口。
+  const CatalogAllDramasRemote(this._api);
+
+  final CatalogApi _api;
+
+  @override
+  Future<List<ContentCategory>> classifications() => _api.classifications();
+
+  @override
+  Future<List<ContentCategory>> categories() => _api.dramaCategories();
+
+  @override
+  Future<List<ContentCategory>> tags() => _api.tags();
+
+  @override
+  Future<PageResult<Drama>> dramas({
+    required List<String> categoryIds,
+    required List<String> classificationIds,
+    required List<String> tagIds,
+    required int pageIndex,
+  }) {
+    return _api.libraryDramas(
+      categoryIds: categoryIds,
+      classificationIds: classificationIds,
+      tagIds: tagIds,
+      pageIndex: pageIndex,
+    );
+  }
+}
+
+/// 全部短剧：筛选项来自类型、分类、标签，列表按页加载。
+class AllDramasController {
+  AllDramasController({
+    AllDramasRemote? api,
+    this.classifications = const [],
+    this.categories = const [],
+    this.tags = const [],
+    this.dramas = const [],
+  }) : _api = api; // ignore: prefer_initializing_formals
+
+  final AllDramasRemote? _api;
+  List<ContentCategory> classifications;
+  List<ContentCategory> categories;
+  List<ContentCategory> tags;
+  final Set<String> selectedClassifications = {};
+  final Set<String> selectedCategories = {};
+  final Set<String> selectedTags = {};
+  List<Drama> dramas;
+  bool loading = false;
+  bool loadingMore = false;
+  bool hasMore = false;
+  String? error;
+  int _page = 1;
+  int _total = 0;
+
+  bool get usesRemote => _api != null;
+
+  /// 预览用：筛选项和列表都已在本地，不请求接口。
+  factory AllDramasController.preview({
+    List<ContentCategory> classifications = const [],
+    List<ContentCategory> categories = const [],
+    List<ContentCategory> tags = const [],
+    List<Drama> dramas = const [],
+  }) {
+    return AllDramasController(
+      classifications: classifications,
+      categories: categories,
+      tags: tags,
+      dramas: dramas,
+    );
+  }
+
+  /// 从第一页重新拉取筛选项和短剧。没有接口时直接返回。
+  Future<void> refresh() async {
+    if (_api == null) return;
+    loading = true;
+    error = null;
+    _page = 1;
+    try {
+      final filters = await Future.wait([
+        _api.classifications(),
+        _api.categories(),
+        _api.tags(),
+      ]);
+      classifications = filters[0];
+      categories = filters[1];
+      tags = filters[2];
+      final page = await _loadPage(1);
+      dramas = page;
+      hasMore = dramas.length < _total;
+    } catch (caught) {
+      error = '$caught';
+    } finally {
+      loading = false;
+    }
+  }
+
+  /// 追加下一页。没有更多、正在加载或没有接口时直接返回。
+  Future<void> loadMore() async {
+    if (_api == null || loading || loadingMore || !hasMore) return;
+    loadingMore = true;
+    error = null;
+    try {
+      final next = await _loadPage(_page + 1);
+      _page += 1;
+      dramas = [...dramas, ...next];
+      hasMore = dramas.length < _total;
+    } catch (caught) {
+      error = '$caught';
+    } finally {
+      loadingMore = false;
+    }
+  }
+
+  /// 切换一个分类。传入空字符串表示清空这一组。
+  void toggleClassification(String id) =>
+      _toggle(selectedClassifications, id);
+
+  /// 切换一个类型。传入空字符串表示清空这一组。
+  void toggleCategory(String id) => _toggle(selectedCategories, id);
+
+  /// 切换一个标签。传入空字符串表示清空这一组。
+  void toggleTag(String id) => _toggle(selectedTags, id);
+
+  void _toggle(Set<String> selected, String id) {
+    if (id.isEmpty) {
+      selected.clear();
+      return;
+    }
+    if (!selected.add(id)) selected.remove(id);
+  }
+
+  Future<List<Drama>> _loadPage(int pageIndex) async {
+    final page = await _api!.dramas(
+      categoryIds: selectedCategories.toList(growable: false),
+      classificationIds: selectedClassifications.toList(growable: false),
+      tagIds: selectedTags.toList(growable: false),
+      pageIndex: pageIndex,
+    );
+    _total = page.total;
+    return page.list;
+  }
+}

lib/core/data/services/auth_controller.dart

@@ -1,3 +1,5 @@
+import 'dart:io' show Platform;
+
 import 'package:flutter/foundation.dart';
 
 import '../models/auth_session.dart';
@@ -9,7 +11,7 @@ import 'auth_session_store.dart';
 ///
 /// 职责：本地会话的读写（[AuthSessionStore]）、注册/登录/登出、令牌刷新；
 /// 也是 [ApiClient] 的 `accessTokenReader` / `tokenRefresher` / `onUnauthorized` 实现方 ——
-/// 401 → 刷新 → 重试失败就清会话，UI 通过 [isSignedIn] 自动回到未登录态。
+/// 401 → 刷新 → 重试。令牌被拒绝才清会话，服务中断时保持登录。
 class AuthController extends ChangeNotifier {
   AuthController(this._api, this._store);
 
@@ -19,6 +21,10 @@ class AuthController extends ChangeNotifier {
   AuthSession? _session;
   String _deviceId = '';
   bool _loaded = false;
+  Future<bool>? _refreshing;
+
+  /// 登录已过期、账号停用才清本地会话。服务不可达不能当成退出登录。
+  static const Set<int> _rejectedSessionCodes = {401, 100001};
 
   bool get isLoaded => _loaded;
   bool get isSignedIn => _session != null;
@@ -42,7 +48,9 @@ class AuthController extends ChangeNotifier {
       email: email,
       password: password,
       deviceId: await _store.deviceId(),
+      countryCode: await _store.deviceRegion(),
       platform: _platform,
+      osVersion: _osVersion,
     );
     await _apply(session);
   }
@@ -53,14 +61,12 @@ class AuthController extends ChangeNotifier {
       password: password,
       deviceId: await _store.deviceId(),
       platform: _platform,
+      osVersion: _osVersion,
     );
     await _apply(session);
   }
 
-  Future<void> sendOtp({
+  Future<void> sendOtp({required String target, String scene = 'LOGIN'}) async {
-    required String target,
-    String scene = 'LOGIN',
-  }) async {
     await _api.sendOtp(
       target: target,
       scene: scene,
@@ -77,6 +83,7 @@ class AuthController extends ChangeNotifier {
       code: code,
       deviceId: await _store.deviceId(),
       platform: _platform,
+      osVersion: _osVersion,
     );
     await _apply(session);
   }
@@ -89,11 +96,19 @@ class AuthController extends ChangeNotifier {
       target: target,
       code: code,
       deviceId: await _store.deviceId(),
+      countryCode: await _store.deviceRegion(),
       platform: _platform,
+      osVersion: _osVersion,
     );
     await _apply(session);
   }
 
+  Future<void> clear() async {
+    _session = null;
+    await _store.clear();
+    notifyListeners();
+  }
+
   Future<void> signOut() async {
     final refreshToken = _session?.refreshToken ?? '';
     _session = null;
@@ -107,29 +122,43 @@ class AuthController extends ChangeNotifier {
     }
   }
 
-  /// 供 [ApiClient] 调用：刷新令牌并落盘。失败时清本地会话。
+  /// 供 [ApiClient] 调用：刷新令牌并落盘。
-  Future<bool> refresh() async {
+  ///
+  /// 同一时刻只刷新一次，避免重启期间并发 401 把新令牌轮换掉。
+  /// 网络失败或 5xx 保留本地会话；只有令牌被拒绝才退出登录。
+  Future<bool> refresh() {
+    final current = _refreshing;
+    if (current != null) return current;
+    final run = _refreshSingle();
+    _refreshing = run;
+    return run.whenComplete(() {
+      if (identical(_refreshing, run)) _refreshing = null;
+    });
+  }
+
+  Future<bool> _refreshSingle() async {
     final refreshToken = _session?.refreshToken ?? '';
     if (refreshToken.isEmpty) {
       await clear();
       return false;
     }
     try {
-      await _apply(await _api.refresh(refreshToken));
+      await _apply(
+        await _api.refresh(
+          refreshToken,
+          platform: _platform,
+          osVersion: _osVersion,
+        ),
+      );
       return true;
+    } on ApiException catch (error) {
+      if (_rejectedSessionCodes.contains(error.code)) await clear();
+      return false;
     } catch (_) {
-      await clear();
       return false;
     }
   }
 
-  Future<void> clear() async {
-    if (_session == null) return;
-    _session = null;
-    await _store.clear();
-    notifyListeners();
-  }
-
   /// 资料保存成功后同步登录态摘要，保留当前令牌。
   Future<void> applyProfile(AuthUser user) async {
     final current = _session;
@@ -154,4 +183,9 @@ class AuthController extends ChangeNotifier {
     if (kIsWeb) return 'WEB';
     return defaultTargetPlatform == TargetPlatform.iOS ? 'IOS' : 'ANDROID';
   }
+
+  String get _osVersion {
+    if (kIsWeb) return '';
+    return Platform.operatingSystemVersion;
+  }
 }

lib/core/data/services/auth_session_store.dart

@@ -4,6 +4,7 @@ import 'dart:math';
 import 'package:shared_preferences/shared_preferences.dart';
 
 import '../models/auth_session.dart';
+import 'device_id_provider.dart';
 
 /// 令牌与设备号的本地持久化。
 ///
@@ -11,13 +12,17 @@ import '../models/auth_session.dart';
 /// `SharedPreferences.getInstance()` 在新版本里已标注弃用，两套混用还会让
 /// widget 测试只 mock 到其中一套。
 ///
-/// 设备号是后端注册风控与后续"下载设备绑定"的依据，所以**首次生成后就固定下来**；
+/// 设备号优先取系统标识（Android SSAID / iOS IDFV），这样卸载重装后还是同一台设备；
-/// 不引 UUID 库（保持极简依赖），用「时间戳 + 随机数」拼一个够用的 id。
+/// 系统标识不可用时才回退到本地生成并持久化的 UUID，保证任何环境都能跑。
 class AuthSessionStore {
-  AuthSessionStore({SharedPreferencesAsync? preferences})
+  AuthSessionStore({
-    : _preferences = preferences ?? SharedPreferencesAsync();
+    SharedPreferencesAsync? preferences,
+    DeviceIdProvider? deviceIdProvider,
+  }) : _preferences = preferences ?? SharedPreferencesAsync(),
+       _deviceIdProvider = deviceIdProvider ?? DeviceIdProvider();
 
   final SharedPreferencesAsync _preferences;
+  final DeviceIdProvider _deviceIdProvider;
 
   static const _kAccessToken = 'auth.accessToken';
   static const _kRefreshToken = 'auth.refreshToken';
@@ -25,21 +30,46 @@ class AuthSessionStore {
   static const _kDeviceId = 'device.id';
 
   String? _cachedDeviceId;
+  String? _cachedRegion;
 
   Future<String> deviceId() async {
     if (_cachedDeviceId != null) return _cachedDeviceId!;
-    var value = await _preferences.getString(_kDeviceId) ?? '';
+    final systemId = await _deviceIdProvider.systemDeviceId();
-    if (value.isEmpty) {
+    final value = systemId ?? await _localDeviceId();
-      final random = Random();
-      value =
-          'd-${DateTime.now().millisecondsSinceEpoch.toRadixString(36)}-'
-          '${random.nextInt(1 << 32).toRadixString(36)}';
-      await _preferences.setString(_kDeviceId, value);
-    }
     _cachedDeviceId = value;
     return value;
   }
 
+  /// 设备区域（ISO-2），取不到返回空串；只在注册时作为服务端 IP 解析失败后的兜底。
+  Future<String> deviceRegion() async {
+    if (_cachedRegion != null) return _cachedRegion!;
+    final value = await _deviceIdProvider.deviceRegion() ?? '';
+    _cachedRegion = value;
+    return value;
+  }
+
+  /// 系统标识取不到时的兜底：本地 UUIDv4，生成一次后固定下来。
+  Future<String> _localDeviceId() async {
+    final stored = await _preferences.getString(_kDeviceId) ?? '';
+    if (stored.isNotEmpty) return stored;
+    final generated = 'd-${_uuidV4()}';
+    await _preferences.setString(_kDeviceId, generated);
+    return generated;
+  }
+
+  /// UUIDv4：122 位随机，碰撞概率可忽略，不引第三方依赖。
+  String _uuidV4() {
+    final random = Random.secure();
+    final bytes = List<int>.generate(16, (_) => random.nextInt(256));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    String hex(int start, int end) => bytes
+        .sublist(start, end)
+        .map((byte) => byte.toRadixString(16).padLeft(2, '0'))
+        .join();
+    return '${hex(0, 4)}-${hex(4, 6)}-${hex(6, 8)}-${hex(8, 10)}-${hex(10, 16)}';
+  }
+
   Future<AuthSession?> read() async {
     final accessToken = await _preferences.getString(_kAccessToken) ?? '';
     final refreshToken = await _preferences.getString(_kRefreshToken) ?? '';

lib/core/data/services/category_controller.dart

@@ -6,6 +6,8 @@ import '../../config/app_config.dart';
 import '../models/content_category.dart';
 import '../models/drama.dart';
 import '../models/home_feed.dart';
+import '../models/page_result.dart';
+import '../remote/category_api.dart';
 import '../repositories/category_repository.dart';
 
 /// 剧场页数据：服务端分类清单与发现 feed。
@@ -14,13 +16,80 @@ class CategoryController extends ChangeNotifier {
 
   final CategoryRepository _repository;
 
+  /// 生产环境注入。未注入时首页分类继续用本地筛选。
+  Future<PageResult<Drama>> Function(
+    String categoryId, {
+    int pageIndex,
+    int pageSize,
+  })? dramaPageLoader;
+
   List<ContentCategory> categories = const [];
+  final Map<String, CategoryDramaSlot> _slots = {};
   HomeFeed feed = const HomeFeed();
   bool loading = false;
   String? error;
   String? debugError;
   bool _disposed = false;
 
+  /// 某个分类自己的短剧分页，不和别的分类共用。
+  CategoryDramaSlot slotOf(String categoryId) {
+    return _slots.putIfAbsent(categoryId, CategoryDramaSlot.new);
+  }
+
+  /// 打开分类并加载第一页短剧。
+  Future<void> openCategory(String categoryId) async {
+    final loader = dramaPageLoader;
+    if (loader == null) return;
+    final slot = slotOf(categoryId);
+    slot.loading = true;
+    slot.loadingMore = false;
+    _notify();
+    try {
+      final page = await loader(
+        categoryId,
+        pageIndex: 1,
+        pageSize: CategoryApi.dramaPageSize,
+      );
+      slot.dramas = page.list;
+      slot.total = page.total;
+      slot.pageIndex = 1;
+    } catch (exception) {
+      if (kDebugMode) debugPrint('[category] $exception');
+    } finally {
+      slot.loading = false;
+      _notify();
+    }
+  }
+
+  /// 上拉加载这个分类的下一页。
+  Future<void> loadMore(String categoryId) async {
+    final loader = dramaPageLoader;
+    final slot = _slots[categoryId];
+    if (loader == null || slot == null) return;
+    if (slot.loading || slot.loadingMore || !slot.hasMore) return;
+    slot.loadingMore = true;
+    _notify();
+    try {
+      final page = await loader(
+        categoryId,
+        pageIndex: slot.pageIndex + 1,
+        pageSize: CategoryApi.dramaPageSize,
+      );
+      if (page.list.isEmpty) {
+        slot.total = slot.dramas.length;
+      } else {
+        slot.dramas = [...slot.dramas, ...page.list];
+        slot.total = page.total;
+        slot.pageIndex += 1;
+      }
+    } catch (exception) {
+      if (kDebugMode) debugPrint('[category] more $exception');
+    } finally {
+      slot.loadingMore = false;
+      _notify();
+    }
+  }
+
   /// 分类九宫格点击后读取该分类的剧目；缺失分区返回空列表。
   List<Drama> dramasOf(String categoryId) {
     final code = 'category-$categoryId';
@@ -30,19 +99,23 @@ class CategoryController extends ChangeNotifier {
     return const [];
   }
 
-  /// 加载分类与发现 feed；失败保留可重试错误态。
+  /// 首页只拉分类，再拉第一个分类的短剧。发现页聚合留到没有短剧分页时再取。
   Future<void> load() async {
     loading = true;
     error = null;
     debugError = null;
     _notify();
     try {
+      if (dramaPageLoader != null) {
+        categories = await _repository.fetchCategories();
+      } else {
         final results = await Future.wait<Object>([
           _repository.fetchCategories(),
           _repository.fetchDiscoverFeed(),
         ]);
         categories = results[0] as List<ContentCategory>;
         feed = results[1] as HomeFeed;
+      }
     } catch (exception) {
       error = 'categoriesError';
       debugError = exception.toString();
@@ -53,6 +126,9 @@ class CategoryController extends ChangeNotifier {
       loading = false;
       _notify();
     }
+    if (error == null && dramaPageLoader != null && categories.isNotEmpty) {
+      await openCategory(categories.first.id);
+    }
   }
 
   void _notify() {
@@ -65,3 +141,14 @@ class CategoryController extends ChangeNotifier {
     super.dispose();
   }
 }
+
+/// 单个分类的短剧分页状态。
+class CategoryDramaSlot {
+  List<Drama> dramas = const [];
+  int total = 0;
+  int pageIndex = 0;
+  bool loading = false;
+  bool loadingMore = false;
+
+  bool get hasMore => dramas.length < total;
+}

lib/core/data/services/comment_controller.dart

@@ -197,7 +197,10 @@ class CommentController extends ChangeNotifier {
       _insertPublished(comment, replyTo);
       return OperationResult.success(comment);
     } catch (failure) {
-      return OperationResult.failure(_errorMessage(failure));
+      return OperationResult.failure(
+        _errorMessage(failure),
+        errorCode: failure is ApiException ? failure.code : null,
+      );
     } finally {
       submitting = false;
       _notify();
@@ -217,7 +220,10 @@ class CommentController extends ChangeNotifier {
       return const OperationResult.success();
     } catch (failure) {
       _restoreComment(comment, location);
-      return OperationResult.failure(_errorMessage(failure));
+      return OperationResult.failure(
+        _errorMessage(failure),
+        errorCode: failure is ApiException ? failure.code : null,
+      );
     } finally {
       _deletingCommentIds.remove(comment.id);
       _notify();
@@ -253,7 +259,10 @@ class CommentController extends ChangeNotifier {
       return OperationResult.success(result);
     } catch (failure) {
       _replaceComment(current);
-      return OperationResult.failure(_errorMessage(failure));
+      return OperationResult.failure(
+        _errorMessage(failure),
+        errorCode: failure is ApiException ? failure.code : null,
+      );
     } finally {
       _likingCommentIds.remove(comment.id);
       _notify();
@@ -277,7 +286,10 @@ class CommentController extends ChangeNotifier {
       );
       return OperationResult.success(reportId);
     } catch (failure) {
-      return OperationResult.failure(_errorMessage(failure));
+      return OperationResult.failure(
+        _errorMessage(failure),
+        errorCode: failure is ApiException ? failure.code : null,
+      );
     }
   }
 

lib/core/data/services/device_id_provider.dart

@@ -0,0 +1,50 @@
+// Author: fruit.com.cn
+
+import 'dart:io' show Platform;
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+
+/// 读取系统级设备标识，两端都不需要任何权限。
+///
+/// - Android：SSAID（`Settings.Secure.ANDROID_ID`），卸载重装不变；
+/// - iOS：IDFV（`identifierForVendor`），卸载本 App 不变，同厂商应用全删才会变。
+///
+/// 两端都由原生侧提供，不引插件：项目 iOS 走 SPM，避免混入 CocoaPods。
+/// 取不到（Web、测试环境、通道异常）时返回 null，由调用方回退到本地生成的 id。
+class DeviceIdProvider {
+  static const MethodChannel _channel = MethodChannel(
+    'com.stormg.lumadrama/device',
+  );
+
+  Future<String?> systemDeviceId() async {
+    if (kIsWeb) return null;
+    try {
+      if (Platform.isAndroid) {
+        final ssaid = await _channel.invokeMethod<String>('ssaid');
+        if (ssaid != null && ssaid.isNotEmpty) return 'a-$ssaid';
+      }
+      if (Platform.isIOS) {
+        final idfv = await _channel.invokeMethod<String>('idfv');
+        if (idfv != null && idfv.isNotEmpty) return 'i-$idfv';
+      }
+    } catch (_) {
+      // 原生通道不可用（widget 测试）时走本地兜底
+    }
+    return null;
+  }
+
+  /// 设备所在区域（ISO-2），仅用于服务端 IP 解析失败时兜底注册国家。
+  /// Android 依次取网络运营商 / SIM 卡 / 系统语言的国家，iOS 取系统 region。
+  Future<String?> deviceRegion() async {
+    if (kIsWeb) return null;
+    try {
+      final region = await _channel.invokeMethod<String>('region');
+      final value = region?.trim().toUpperCase() ?? '';
+      if (value.length == 2) return value;
+    } catch (_) {
+      // 原生通道不可用（widget 测试）时返回 null，由服务端兜底
+    }
+    return null;
+  }
+}