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

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

README.md

@@ -135,6 +135,27 @@ flutter run -d <device> \
   --dart-define=API_BASE_URL=http://127.0.0.1:8081
 ```
 
+## 生产打包（Android）
+
+生产包只包含以下两个 ABI，**打成一个 APK**，不做 split：
+
+| ABI | 适用设备 |
+| --- | --- |
+| `arm64-v8a` | 现代手机（64 位） |
+| `armeabi-v7a` | 老 32 位机 |
+
+```bash
+flutter build apk --release --target-platform android-arm64,android-arm
+# 产出单个：build/app/outputs/flutter-apk/app-release.apk（约 37MB）
+```
+
+说明：
+
+- `android/app/build.gradle.kts` 的 `release` 已配置 `abiFilters`，只保留 `arm64-v8a` 与 `armeabi-v7a`，插件也不会再带入 `x86_64` 原生库。
+- `x86_64` 只用于模拟器，不进入生产包。
+- 不要直接运行 `flutter build apk --release`：默认会编译三套原生库，包体约 57MB。
+- 只有需要进一步压缩单机下载体积时，才考虑 `--split-per-abi` 出分架构包（arm64 约 21MB、armv7 约 19MB），默认不用。
+
 ## 门禁
 
 ```bash

android/app/build.gradle.kts

@@ -29,6 +29,10 @@ android {
 
     buildTypes {
         release {
+            // 生产包只保留 arm64-v8a 与 armeabi-v7a，避免插件带入 x86_64 原生库
+            ndk {
+                abiFilters += listOf("arm64-v8a", "armeabi-v7a")
+            }
             // TODO: Add your own signing config for the release build.
             // Signing with the debug keys for now, so `flutter run --release` works.
             signingConfig = signingConfigs.getByName("debug")
@@ -42,6 +46,13 @@ kotlin {
     }
 }
 
+// 生产包不允许出现 x86_64：部分插件 AAR 会带入少量 x86_64 原生库，这里显式剔除。
+androidComponents {
+    onVariants(selector().withBuildType("release")) { variant ->
+        variant.packaging.jniLibs.excludes.add("lib/x86_64/**")
+    }
+}
+
 flutter {
     source = "../.."
 }

android/app/src/main/AndroidManifest.xml

@@ -1,7 +1,7 @@
 <!-- Author: fruit.com.cn -->
-
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <uses-permission android:name="android.permission.INTERNET"/>
+    <uses-permission
+        android:name="android.permission.INTERNET"/>
     <application
         android:label="FruitShorts"
         android:name="${applicationName}"
@@ -23,9 +23,8 @@
                  while the Flutter UI initializes. After that, this theme continues
                  to determine the Window background behind the Flutter UI. -->
             <meta-data
-              android:name="io.flutter.embedding.android.NormalTheme"
+                android:name="io.flutter.embedding.android.NormalTheme"
-              android:resource="@style/NormalTheme"
+                android:resource="@style/NormalTheme"/>
-              />
             <intent-filter>
                 <action android:name="android.intent.action.MAIN"/>
                 <category android:name="android.intent.category.LAUNCHER"/>
@@ -35,7 +34,7 @@
              This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
         <meta-data
             android:name="flutterEmbedding"
-            android:value="2" />
+            android:value="2"/>
     </application>
     <!-- Required to query activities that can process text, see:
          https://developer.android.com/training/package-visibility and
@@ -44,8 +43,10 @@
          In particular, this is used by the Flutter engine in io.flutter.plugin.text.ProcessTextPlugin. -->
     <queries>
         <intent>
-            <action android:name="android.intent.action.PROCESS_TEXT"/>
+            <action
-            <data android:mimeType="text/plain"/>
+                android:name="android.intent.action.PROCESS_TEXT"/>
+            <data
+                android:mimeType="text/plain"/>
         </intent>
     </queries>
 </manifest>

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

@@ -4,23 +4,49 @@ 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
+import android.net.Uri
 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
 import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
 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
 
 class MainActivity : FlutterActivity() {
     private val shareRequestCode = 9041
+    private val thumbnailExecutor: ExecutorService = Executors.newSingleThreadExecutor()
+    private val thumbnailHandler = Handler(Looper.getMainLooper())
     private var pendingShare: MethodChannel.Result? = null
     private var pipChannel: MethodChannel? = null
     private var keyboardChannel: MethodChannel? = null
+    private var thumbnailChannel: MethodChannel? = null
     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)
+    }
+
     override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
         super.configureFlutterEngine(flutterEngine)
         pipChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "com.stormg.lumadrama/pip")
@@ -43,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") {
@@ -79,6 +122,47 @@ class MainActivity : FlutterActivity() {
             emitImeInset(inset)
             result.success(inset)
         }
+        thumbnailChannel = MethodChannel(
+            flutterEngine.dartExecutor.binaryMessenger,
+            "com.stormg.lumadrama/thumbnail"
+        )
+        thumbnailChannel?.setMethodCallHandler { call, result ->
+            if (call.method != "frame") {
+                result.notImplemented()
+                return@setMethodCallHandler
+            }
+            val timeMs = (call.argument<Number>("timeMs"))?.toLong()
+            if (timeMs == null) {
+                result.success(null)
+                return@setMethodCallHandler
+            }
+            val localPath = call.argument<String>("localPath").orEmpty()
+            val remoteUrl = call.argument<String>("url").orEmpty()
+            val rawHeaders = call.argument<Map<*, *>>("headers")
+            val headers = rawHeaders?.entries
+                ?.associate { it.key.toString() to it.value.toString() }
+                .orEmpty()
+            val responded = AtomicBoolean(false)
+            val task = thumbnailExecutor.submit {
+                val bytes = renderThumbnail(
+                    timeMs = timeMs,
+                    localPath = localPath,
+                    remoteUrl = remoteUrl,
+                    headers = headers
+                )
+                thumbnailHandler.post {
+                    if (responded.compareAndSet(false, true)) {
+                        result.success(bytes)
+                    }
+                }
+            }
+            thumbnailHandler.postDelayed({
+                if (responded.compareAndSet(false, true)) {
+                    task.cancel(true)
+                    result.success(null)
+                }
+            }, thumbnailTimeoutMs)
+        }
         val decorView = window.decorView
         ViewCompat.setOnApplyWindowInsetsListener(decorView) { view, insets ->
             emitImeInset(insets.getInsets(WindowInsetsCompat.Type.ime()).bottom)
@@ -93,12 +177,87 @@ 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
         keyboardChannel?.invokeMethod("insetsChanged", value)
     }
 
+    private fun renderThumbnail(
+        timeMs: Long,
+        localPath: String,
+        remoteUrl: String,
+        headers: Map<String, String>
+    ): ByteArray? {
+        val retriever = MediaMetadataRetriever()
+        var frame: Bitmap? = null
+        var scaled: Bitmap? = null
+        return try {
+            when {
+                localPath.isNotEmpty() -> retriever.setDataSource(normalizeLocalPath(localPath))
+                remoteUrl.isNotEmpty() -> retriever.setDataSource(remoteUrl, headers)
+                else -> return null
+            }
+            frame = retriever.getFrameAtTime(
+                timeMs * 1000,
+                MediaMetadataRetriever.OPTION_CLOSEST_SYNC
+            )
+            val source = frame ?: return null
+            scaled = if (source.width > thumbnailMaxWidth) {
+                val targetHeight = (source.height * thumbnailMaxWidth / source.width)
+                    .coerceAtLeast(1)
+                Bitmap.createScaledBitmap(
+                    source,
+                    thumbnailMaxWidth,
+                    targetHeight,
+                    true
+                )
+            } else {
+                source
+            }
+            val outputBitmap = scaled ?: source
+            val output = ByteArrayOutputStream()
+            val compressed = outputBitmap.compress(
+                Bitmap.CompressFormat.JPEG,
+                thumbnailJpegQuality,
+                output
+            )
+            if (!compressed) return null
+            output.toByteArray()
+        } catch (_: Exception) {
+            null
+        } finally {
+            if (scaled != null && scaled !== frame) scaled.recycle()
+            frame?.recycle()
+            retriever.release()
+        }
+    }
+
+    private fun normalizeLocalPath(path: String): String =
+        if (path.startsWith("file:")) Uri.parse(path).path ?: path else path
+
     override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration) {
         super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
         pipChannel?.invokeMethod("onPipChanged", isInPictureInPictureMode)
@@ -117,6 +276,16 @@ class MainActivity : FlutterActivity() {
         ViewCompat.setOnApplyWindowInsetsListener(window.decorView, null)
         keyboardChannel?.setMethodCallHandler(null)
         keyboardChannel = null
+        thumbnailChannel?.setMethodCallHandler(null)
+        thumbnailChannel = null
+        thumbnailHandler.removeCallbacksAndMessages(null)
+        thumbnailExecutor.shutdownNow()
         super.onDestroy()
     }
+
+    companion object {
+        private const val thumbnailMaxWidth = 240
+        private const val thumbnailJpegQuality = 70
+        private const val thumbnailTimeoutMs = 1500L
+    }
 }

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/mipmap-anydpi-v26/ic_launcher.xml

@@ -1,5 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-  <background android:drawable="@mipmap/ic_launcher_background"/>
+  <background android:drawable="@color/ic_launcher_background"/>
-  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+  <foreground>
+      <inset
+          android:drawable="@drawable/ic_launcher_foreground"
+          android:inset="16%" />
+  </foreground>
 </adaptive-icon>

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

@@ -1,11 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Author: fruit.com.cn -->
-
 <resources>
     <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
         <item name="android:windowBackground">@drawable/launch_background</item>
-        <item name="android:windowSplashScreenBackground">@color/splash_background</item>
+        <item name="android:forceDarkAllowed">false</item>
-        <item name="android:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
+        <item name="android:windowFullscreen">false</item>
+        <item name="android:windowDrawsSystemBarBackgrounds">false</item>
+        <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
+        <item name="android:windowSplashScreenBackground">#000000</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

@@ -1,11 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Author: fruit.com.cn -->
-
 <resources>
     <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
         <item name="android:windowBackground">@drawable/launch_background</item>
-        <item name="android:windowSplashScreenBackground">@color/splash_background</item>
+        <item name="android:forceDarkAllowed">false</item>
-        <item name="android:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
+        <item name="android:windowFullscreen">false</item>
+        <item name="android:windowDrawsSystemBarBackgrounds">false</item>
+        <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
+        <item name="android:windowSplashScreenBackground">#000000</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>

android/app/src/main/res/values/colors.xml

@@ -2,5 +2,6 @@
 <!-- Author: fruit.com.cn -->
 
 <resources>
-    <color name="splash_background">#1F1B16</color>
+	<color name="splash_background">#000000</color>
+	<color name="ic_launcher_background">#FF6B2C</color>
 </resources>

docs/plans/2026-10-22-dark-theme-client.md

@@ -0,0 +1,28 @@
+# ReelShort 客户端深色视觉改造
+
+## 目标
+
+- 深色设为默认且唯一主题，页面、卡片、浮层、播放器和底部导航保持一致。
+- 色板收敛到 `AppColors`，主题组件配置收敛到 `AppTheme`。
+- 保持现有布局、信息结构、路由、业务逻辑和文案不变。
+
+## 结果
+
+- 背景 `#0B1020`、卡片 `#151B2E`、浮层 `#1C2436`、分割线白色 6%。
+- 主文字白色 92%、次文字 64%、禁用 38%。
+- 主色 `#FF6B2C`，辅助链接色 `#22D3EE`。
+- 卡片 12、按钮/输入框 10、标签 6，阴影关闭，组件使用分割线分层。
+- 页面级透明、遮罩、阴影、媒体底、玻璃面和渐变全部映射到 AppColors 语义 token。
+- 系统栏统一浅色图标，AppBar 与底部导航使用深色表面。
+
+## 验证
+
+- 主题 token、对比度、系统栏、圆角与关键页 smoke 测试。
+- `dart analyze lib test`
+- `flutter test --no-pub`
+- `flutter build apk --debug`
+
+## 约束
+
+- 不提交 `pubspec.lock` 漂移。
+- 不启停服务、不操作真机。

docs/plans/2026-10-22-debug-http-logging.md

@@ -0,0 +1,24 @@
+# Android Studio 调试 HTTP 日志
+
+## 目标
+
+- 仅在调试构建中输出 Dio 请求、响应与异常日志。
+- Android Studio Run 控制台通过 `debugPrint` 展示，logcat 标签保持 `flutter`。
+- Authorization 脱敏，X-Device-Id 保留，二进制响应只显示字节数。
+- 单条请求体或响应体最多 3000 字符。
+
+## 实现步骤
+
+1. 新增 `NetworkLogInterceptor`，支持注入日志回调并保留请求耗时。
+2. 在 Envelope 解包前暂存原始 bytes；日志拦截器追加到拦截链末尾后读取暂存值。
+3. 在 `ApiClient` 注册调试拦截器，`kDebugMode` 与常量开关同时满足时才输出。
+4. 以 fake adapter 补单测，覆盖行格式、脱敏、UTF-8、截断、非 JSON 与二进制。
+5. 运行 `dart analyze lib test` 和 `flutter test`，更新 PROGRESS 留痕。
+
+## 风险与约束
+
+- `ResponseType.bytes` 不能直接 `toString`，响应体统一 `utf8.decode`。
+- Dio 响应拦截器按 FIFO 执行；链尾日志通过 Envelope 暂存的原始 bytes 读取，
+  避免拿到已解包后的 `data`。
+- release/profile 通过 `kDebugMode` 短路，不输出任何 HTTP 日志。
+- 不新增依赖，不提交现有 `pubspec.lock` 改动，不启停服务、不操作真机。

docs/plans/2026-10-22-favorite-card-synopsis.md

@@ -0,0 +1,20 @@
+# 收藏卡片简介
+
+## 目标
+
+- 收藏卡片在标题/标签下方显示后端 `synopsis`，最多 2 行并省略溢出。
+- 空白简介不创建文本节点、不占高度，不显示 `null/undefined`。
+- 保持封面 80x106 和现有卡片高度，不引入布局溢出。
+
+## 实现
+
+1. `_FavoriteCard` 对 synopsis 做 trim 后条件渲染。
+2. 简介使用 `Flexible` 占据标题、标签与底部统计之间的剩余空间，
+   `maxLines: 2`、`TextOverflow.ellipsis`、次要文案色和字号。
+3. 无简介时继续使用原 Spacer，保持原布局。
+4. widget 测试覆盖有简介、空简介和卡片高度稳定性。
+
+## 约束
+
+- 不改接口、后端、收藏分页。
+- 不新增依赖，不提交现有 `pubspec.lock`，不启停服务、不操作真机。

docs/plans/2026-10-22-keep-awake-auto-resume.md

@@ -0,0 +1,31 @@
+# 屏幕常亮与前台自动续播
+
+## 目标
+
+- Android 与 iOS 前台保持屏幕常亮，不引入插件或依赖。
+- 用户主动暂停后切后台再回前台，在播放器与票据状态安全时自动续播。
+- 锁定、blocked、票据失败、错误态及浮层遮挡场景不得强制起播。
+
+## 实施步骤
+
+1. Android `MainActivity.onCreate` 添加 `FLAG_KEEP_SCREEN_ON`，保留现有渠道逻辑。
+2. iOS `AppDelegate` 设置 `UIApplication.shared.isIdleTimerDisabled = true`。
+3. 为 `PlaybackSession` 增加无浮层、路线可见且 active 播放器可用的恢复判断。
+4. 调整 `PlayerLogic.onLifecycle`，在现有 PiP 复位和过期票据刷新流程后安全设置播放意图。
+5. 补用户暂停恢复、锁定/票据失败不恢复、后台保存并暂停测试。
+6. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 真机常亮和生命周期行为由 PM 验收，本次不启停服务、不操作设备。
+- PiP 继续沿用现有可见性策略，不额外修改后台播放行为。
+
+## 执行结果
+
+- Android 主 Activity 已添加 `FLAG_KEEP_SCREEN_ON`，未改动 Flutter 渠道与 PiP 逻辑。
+- iOS AppDelegate 已设置 `UIApplication.shared.isIdleTimerDisabled = true`。
+- 用户主动暂停后回前台可安全恢复；过期票据会等待重取完成后再恢复。
+- locked、blocked、票据错误、会话错误、解锁/浮层遮挡和 PiP 场景均不会强制续播。
+- 后台仍先保存进度并暂停。
+- `dart analyze lib test` 零告警，`flutter test --no-pub` 580 项全过。
+- 未启停服务，未操作真机。

docs/plans/2026-10-22-library-paging-ui.md

@@ -0,0 +1,31 @@
+# 收藏与观看历史分页 UI
+
+## 目标
+
+- `/app/favorites` 与 `/app/watch/recent` 按 `PageResult{total,list}` 分页接入。
+- 收藏页、观看历史页支持首屏、触底加载、无更多、刷新、失败重试和总数展示。
+- 观看记录直接使用后端 `dramaTitle/dramaCover/episodeNumber`，缺失时安全兜底。
+
+## 实现步骤
+
+1. 新增通用 `PageResult<T>`，更新 LibraryApi、WatchApi、Repository 与内存替身。
+2. FavoriteController、WatchRecordsController 增加分页状态、请求代次、dramaId 去重。
+3. 页面通过滚动通知触发 `loadMore`，复用下拉刷新并增加通用分页 footer。
+4. 观看卡片优先渲染接口字段，标题为空时用本地化“第 N 集”，封面为空显示占位。
+5. 补 API、Controller 和 widget 测试，运行 analyze 与全量 flutter test。
+
+## 风险与约束
+
+- 刷新期间保持旧列表，成功后原子替换并回到第 1 页；失败保留旧数据。
+- loadMore 与 refresh 通过请求代次隔离，旧响应不得覆盖新列表。
+- 空页立即停止加载；`loaded >= total` 后不再请求。
+- 不新增依赖、不提交现有 `pubspec.lock`，不启停服务、不操作真机。
+
+## 2026-10-22 范围修订
+
+- 分页协议和 Controller 分页状态保持不改。
+- 观看历史优先使用后端 `dramaTitle/dramaCover/episodeNumber`，只有标题为空时才预取详情。
+- 标题为空且详情也未返回标题时，用本地化“第 N 集”兜底。
+- 有标题的条目点击播放时再按需加载详情，不在列表加载阶段产生 N+1。
+- 使用当前真实后端校验第 1/2 页请求参数、total 与 list；若运行实例仍忽略分页，
+  只在 PROGRESS 记录证据，不做前端全量兜底。

docs/plans/2026-10-22-login-error-center-dialog.md

@@ -0,0 +1,28 @@
+# 登录异常居中弹窗
+
+## 目标
+
+- 邮箱登录、邮箱注册及手机号 OTP 登录的提交异常改为屏幕居中弹窗。
+- 本地表单校验继续使用现有内联字段错误，不触发弹窗。
+
+## 实施步骤
+
+1. 新增 `lib/core/widgets/centered_error_dialog.dart`，统一弹窗样式、遮罩关闭和确认按钮。
+2. 补充登录失败、注册失败、确认按钮的中英文印尼语文案并重新生成 l10n。
+3. 调整邮箱认证页：接口异常展示居中弹窗，提交 busy 在展示弹窗前复位。
+4. 调整手机号弹窗：OTP 发送和验证码登录/注册异常展示居中弹窗，成功 SnackBar 保持不变。
+5. 补接口异常、注册标题、本地校验不弹窗和手机号两条异常路径测试。
+6. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 同级 FruitServer 的 `INBOX.md` 当前顶部为已处理 K100，未找到本需求条目；以用户消息中的完整需求为准。
+- 现有主工作区处于 `feature/payment-iap` 且有未提交 `pubspec.lock`，本次使用独立 worktree，不触碰该文件。
+
+## 执行结果
+
+- 已新增居中错误弹窗组件及三语言文案，邮箱登录/注册和手机号 OTP/验证码提交异常均改为弹窗。
+- 本地字段校验仍走原内联错误；异常展示前提交 busy 已复位。
+- 接口异常、注册标题、未知异常网络文案、遮罩关闭、确认关闭、本地校验不弹窗均有测试覆盖。
+- `dart analyze lib test` 零告警，`flutter test --no-pub` 570 项全过。
+- 未启停服务，未操作真机。

docs/plans/2026-10-22-login-error-center-toast.md

@@ -0,0 +1,29 @@
+# 登录异常居中吐司
+
+## 目标
+
+- 将上一版认证异常 AlertDialog 替换为无交互的屏幕居中吐司。
+- 吐司淡入展示约 2 秒后自动淡出，不遮罩、不拦截手势。
+- 同一时刻只存在一个吐司，新消息替换旧消息。
+
+## 实施步骤
+
+1. 删除 `centered_error_dialog.dart`，新增 `centered_toast.dart`。
+2. 认证页和手机号弹窗异常路径改用 `showCenteredToast`，保留 busy 复位和成功 SnackBar。
+3. 清理不再使用的认证错误标题与确认按钮 l10n 键，重新生成 AppLocalizations。
+4. 更新认证测试为吐司断言，并补单例替换、自动消失测试。
+5. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 吐司使用 root Overlay，认证路由退出时仍会按自身计时器自动清理。
+- 测试必须 pump 超过展示和淡出时长，确保不遗留 Timer 或 OverlayEntry。
+
+## 执行结果
+
+- 已删除 AlertDialog 组件，新增 OverlayEntry 居中吐司。
+- 邮箱和手机号异常改用吐司；busy 复位、成功 SnackBar 和本地内联校验保持不变。
+- 已清理三个不再使用的 l10n 键并重新生成 AppLocalizations。
+- 覆盖单例替换、点击穿透、自动消失、接口异常和本地校验不弹吐司。
+- `dart analyze lib test` 零告警，`flutter test --no-pub` 573 项全过。
+- 未启停服务，未操作真机。

docs/plans/2026-10-22-playback-entry-no-buffer.md

@@ -0,0 +1,21 @@
+# 播放入口无缓冲提示
+
+## 目标
+
+- 未初始化进度条显示静态 inactive 轨道，不出现流动加载高光。
+- 仅真实 buffering 持续超过 350ms 时显示白色高光。
+- 起播定位阶段不叠加 session 居中 loading；只有 ticket loading 居中显示。
+- 同集返回复用 controller；重建时 initialize→seek→play。
+
+## 实施步骤
+
+1. 调整 SeekProgressBar 与 _FeedProgressBar 的初始化/缓冲状态判断。
+2. 删除 PlayerView 的 session loading 居中圈，仅保留 ticket loading。
+3. preparePlayer 统一通过 VideoPlayerPort.seekTo 定位缓存位置。
+4. 更新进度条、全屏入口、详情返回和重建顺序测试。
+5. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 真实持续网络卡顿仍保留缓冲高光。
+- 锁定集继续沿用静态空轨道和禁用 seek 行为。

docs/plans/2026-10-22-playback-position-continuity.md

@@ -0,0 +1,32 @@
+# 播放位置连续性
+
+## 目标
+
+- 首页进入详情、详情返回首页、详情再进播放器时保持同一集同一秒。
+- 新增进程内最近播放位置缓存，优先于服务端旧记录。
+- 跨剧、跨集不串位；锁定/票据失败不因缓存强行起播；进程重启仍回服务端。
+
+## 实施步骤
+
+1. 新增 `PlaybackPositionCache`，按 episodeId 保存 dramaId/position/duration/updatedAt。
+2. App Provider 注入单一缓存实例，PlayerPage 与详情页共享。
+3. PlayerLogic 进度监听、saveCurrentProgress 写入缓存；loadResumePoint 优先命中缓存。
+4. preparePlayer 对每个待准备集按 dramaId 校验缓存，并继续使用现有位置钳位。
+5. 详情页续看状态优先使用该剧最新缓存，未命中再请求服务端。
+6. 补缓存、缓存命中不请求服务端、跨剧隔离、服务端回落和详情返回位置测试。
+7. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 缓存仅保存在进程内，App 重启后自动回落到服务端观看记录。
+- 片尾附近继续复用现有 `clampResumePosition` 完成保护。
+
+## 执行结果
+
+- 新增进程内按集缓存并通过 Provider 全局共享，详情页与播放器共用。
+- 进度监听、`saveCurrentProgress` 和进入详情前会写入缓存。
+- `loadResumePoint` 优先缓存，未命中或跨剧时才请求服务端。
+- 详情页继续观看与 CTA 优先进缓存集；返回首页保持原播放器与位置。
+- 已覆盖缓存读写/过期、跨剧隔离、缓存命中去网络、服务端回落和详情往返。
+- `dart analyze lib test` 零告警，`flutter test --no-pub` 589 项全过。
+- 未启停服务，未操作真机。

docs/plans/2026-10-22-playback-seek-position.md

@@ -0,0 +1,21 @@
+# Seek 后播放位置保持
+
+## 目标
+
+- 拖动进度条后，缓存与观看记录立即使用 seek 完成后的真实位置。
+- 拖动后立即进详情/离开也不会回退到旧进度。
+- 越界位置 clamp，锁定/票据失败不写无效缓存。
+
+## 实施步骤
+
+1. 增加播放位置 clamp 纯函数，缓存写入统一限制在 `0..duration`。
+2. VideoPlayerPort 暴露 seek 方法，PlayerLogic 等待 seek 完成后再读取 controller。
+3. PlayerLogic 统一当前播放快照，监听、缓存和上报共用同一份 position/duration。
+4. 增加 pending seek 屏障，saveCurrentProgress 与离开路径等待 seek 和上报完成。
+5. 补 seek 缓存、越界 clamp、seek 后进详情并返回测试。
+6. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 片尾与完成逻辑继续沿用现有 controller/播放器行为。
+- 缓存仅在进程内，不改变服务端观看记录契约。

docs/plans/2026-10-22-player-loading-polish.md

@@ -0,0 +1,30 @@
+# 播放器 loading 与锁定进度条调整
+
+## 目标
+
+- 播放器票据与 session loading 圈统一为 24×24、线宽 2。
+- 缓冲/加载进度高光改为白色。
+- 未解锁剧集显示静态 inactive 轨道，不进入 loading，不允许拖动 seek。
+
+## 实施步骤
+
+1. 更新 `LoadingProgressTrack` 默认高光颜色，并补颜色断言。
+2. 为 `SeekProgressBar`、`PlayerOverlayData`、`HomeFeedOverlay` 和 `_FeedProgressBar` 增加 locked 状态。
+3. `PlayerPage` 使用 `logic.session.isLocked || episode.locked` 传入两个浮层。
+4. 缩小 `player-ticket-loading` 与 `player-session-loading` 的尺寸和线宽。
+5. 补首页/全屏锁定态、缓冲高光和两个 loading 指示器尺寸测试。
+6. 执行 `dart analyze lib test` 与 `flutter test --no-pub`，回填 PROGRESS 后提交合并。
+
+## 风险 / 待确认
+
+- 锁定态只影响进度条 UI 与手势，不改播放、解锁或接口逻辑。
+- 首页浮层锁定线沿用当前 `Colors.white24` inactive 色，避免改变非锁定轨道样式。
+
+## 执行结果
+
+- 两个播放器 loading 圈均为 24×24、线宽 2、主色不变。
+- loading 高光默认改为白色，普通轨道与首页 white24 轨道颜色未变。
+- 首页与全屏播放器均按剧集锁定态渲染静态空轨道并禁用 seek。
+- 已覆盖锁定轨道高度、无 loading、无拖动 seek、loading 指示器尺寸和高光颜色。
+- `dart analyze lib test` 零告警，`flutter test --no-pub` 576 项全过。
+- 未启停服务，未操作真机。

docs/plans/2026-10-22-scrub-frame-preview.md

@@ -0,0 +1,62 @@
+# 播放器进度拖动画面预览
+
+## 目标
+
+首页 feed 与全屏播放器的进度条在拖动时显示当前时间点的视频画面缩略图、
+当前时间与总时长；松手立即隐藏并提交 seek。缩略图未返回或失败时显示短剧
+封面，不出现空白闪烁或错误文案。
+
+## 性能红线
+
+1. 拖动期间主线程无卡顿；图片解码和原生取帧不得阻塞 UI 线程。
+2. 原生取帧并发数不超过 1。
+3. 预览图最大宽度 240px。
+4. Dart 内存 LRU 缓存不超过 24 帧。
+5. 不新增 pub 依赖。
+6. 不改后端契约。
+
+## 实现
+
+### 缩略图服务
+
+- 新增 `PlaybackThumbnailService`，公开入口按 `episodeId + position` 取
+  `ByteData`，底层通过
+  `MethodChannel('com.stormg.lumadrama/thumbnail')` 调用原生。
+- 时间按 1 秒分桶；同一 bucket 的在途请求合流。
+- 最多 24 帧 LRU；成功和失败结果都做过期控制，避免旧拖动位置覆盖当前预览。
+- 全局单飞；拖动期间只保留最新 bucket，尚未开始的旧请求直接丢弃。
+- 拖动停顿 120ms 后最多预取相邻一个 bucket，松手取消尚未开始的请求。
+- 原生异常、缺失实现和超过 1.5 秒无结果统一返回 `null`。
+
+### 原生取帧
+
+- Android 使用 `MediaMetadataRetriever`，优先本地下载路径，其次签名 URL；
+  `OPTION_CLOSEST_SYNC` 取帧，最大宽 240px，JPEG 质量 70，单线程 Executor，
+  完成后立即 release。
+- iOS 使用 `AVAssetImageGenerator`，应用画面方向，最大尺寸约 240x426，
+  合理时间容差，后台串行队列生成 JPEG。
+- 两端均保证只回调一次；失败或 1.5 秒超时返回 `null`，不向 UI 抛异常。
+
+### UI
+
+- 新增 `ScrubPreviewCard`：宽 120dp、圆角 8、白色 1px 描边，显示
+  `当前时间 / 总时长`；沿拖动点水平跟随并做安全边距 clamp。
+- 首页 `_FeedProgressBar` 与全屏 `SeekProgressBar` 共用该卡片。
+- 封面始终铺在卡片底层；`Image.memory` 仅在帧到达后覆盖，并限制
+  `cacheWidth: 240`。
+- 开始拖动请求当前 bucket，拖动更新只保留最新位置；松手立即隐藏卡片并取消
+  未开始请求。
+- `PlayerPage` 持有页面级服务，dispose 时清空缓存，避免跨页面串集。
+
+## 测试
+
+- 单测：bucket、LRU 淘汰、同 bucket 合流、过期请求丢弃、松手取消、
+  相邻 bucket 防抖、异常/超时回落。
+- Widget：拖动显示预览卡片和时间、松手消失、无缩略图显示封面。
+- 门禁：`dart analyze lib test` 与 `flutter test --no-pub`。
+
+## 非目标
+
+- 不改服务端接口或持久化策略。
+- 不新增第三方依赖。
+- 不启停服务、不操作真机；原生取帧实际效果由 PM 真机验收。

docs/plans/2026-10-22-sprite-scrub-preview.md

@@ -0,0 +1,46 @@
+# 雪碧图 VTT 拖动预览
+
+## 目标
+
+将进度条拖动预览主链路改为服务端雪碧图 + WebVTT 局部裁剪，原生取帧只作为降级：
+
+1. `Episode` 与 `PlayTicket` 解析 `thumbnailsUrl`。
+2. VTT 只拉取/解析一次，内存缓存 10 分钟。
+3. cue 使用起止时间 + 相对 sprite 文件名 + `xywh`，按 position 二分选择。
+4. sprite 图最多缓存 2 张 `ui.Image`，拖动帧只绘制 sourceRect。
+5. 无 VTT、空轴或图片失败时回退现有 `PlaybackThumbnailService`，再回退封面。
+
+## 性能红线
+
+- 拖动帧禁止网络请求与图片解码，只允许 cue 二分查找和 `RawImage.sourceRect` 绘制。
+- VTT 每个 URL 只解析一次；sprite 解码不在 build/build paint 中执行。
+- sprite ui.Image LRU 上限 2 张，页面 dispose 清空。
+- 解码 sprite 最长边超过 2048px 时按比例缩小后常驻。
+- 签名 `thumbnailsUrl` 不写入任何持久化缓存。
+
+## 实施
+
+- 新增 `SpriteThumbnailAxisService`：
+  - Dio 拉取 VTT，403 清缓存后重试一次；
+  - 解析和选 cue 为纯函数，解析失败返回空轴；
+  - 播放器就绪时预取当前 cue 及相邻 sprite；
+  - LRU2 sprite 缓存和 10 分钟 VTT 缓存。
+- `PlayerPage` 持有页面级服务，按当前选中集预取，dispose 时清空。
+- `ScrubPreviewCard` 优先读取已缓存 sprite frame，显示 `RawImage` 裁剪；
+  VTT 未就绪时暂显封面，轴为空/不可用后启动本地取帧，全部失败保留封面。
+- 首页 feed 和全屏播放器都把 `thumbnailsUrl` 传到预览卡片。
+- 不新增 pub 依赖、不改后端契约。
+
+## 测试
+
+- VTT 解析：时间、xywh、多 sprite 文件。
+- cue 选择：命中、越界最近邻。
+- sprite LRU 最多 2 张。
+- 回退状态判定。
+- Widget：sprite 裁剪且不触发本地取帧；无 URL 回退本地；全部失败显示封面。
+- 门禁：`dart analyze lib test`、`flutter test --no-pub`。
+
+## 风险
+
+- 真实网络 VTT/sprite 可访问性和签名过期由 PM 真机验收。
+- 本次不启动服务、不操作真机、不修改 Web/FruitServer。

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

@@ -1,5 +1,26 @@
 import Flutter
 import UIKit
+import AVFoundation
+
+private let thumbnailHTTPHeaderFieldsKey = "AVURLAssetHTTPHeaderFieldsKey"
+
+private final class ThumbnailResponseGate {
+  private let lock = NSLock()
+  private var completed = false
+
+  func send(_ result: @escaping FlutterResult, data: Data?) {
+    lock.lock()
+    if completed {
+      lock.unlock()
+      return
+    }
+    completed = true
+    lock.unlock()
+    DispatchQueue.main.async {
+      result(data)
+    }
+  }
+}
 
 /// Keeps the system LaunchScreen as the only splash. Flutter would otherwise
 /// instantiate that storyboard again and the icon appears a second time.
@@ -10,21 +31,39 @@ 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
+  )
+
   override func application(
     _ application: UIApplication,
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
   ) -> Bool {
+    UIApplication.shared.isIdleTimerDisabled = true
     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()
@@ -43,5 +82,107 @@ final class RunnerFlutterViewController: FlutterViewController {
       activity.completionWithItemsHandler = { _, _, _, _ in result(nil) }
       controller.present(activity, animated: true)
     }
+
+    let thumbnailChannel = FlutterMethodChannel(
+      name: "com.stormg.lumadrama/thumbnail",
+      binaryMessenger: engineBridge.applicationRegistrar.messenger()
+    )
+    thumbnailChannel.setMethodCallHandler { [weak self] call, result in
+      guard call.method == "frame" else {
+        result(FlutterMethodNotImplemented)
+        return
+      }
+      guard let self,
+            let arguments = call.arguments as? [String: Any],
+            let timeNumber = arguments["timeMs"] as? NSNumber else {
+        result(nil)
+        return
+      }
+      let localPath = arguments["localPath"] as? String ?? ""
+      let remoteUrl = arguments["url"] as? String ?? ""
+      let headers = arguments["headers"] as? [String: String] ?? [:]
+      let assetUrl: URL?
+      if !localPath.isEmpty {
+        assetUrl = localPath.hasPrefix("file:")
+          ? URL(string: localPath)
+          : URL(fileURLWithPath: localPath)
+      } else if !remoteUrl.isEmpty {
+        assetUrl = URL(string: remoteUrl)
+      } else {
+        assetUrl = nil
+      }
+      guard let assetUrl else {
+        result(nil)
+        return
+      }
+
+      let options: [String: Any]? = headers.isEmpty
+        ? nil
+        : [thumbnailHTTPHeaderFieldsKey: headers]
+      let asset = AVURLAsset(url: assetUrl, options: options)
+      let generator = AVAssetImageGenerator(asset: asset)
+      generator.appliesPreferredTrackTransform = true
+      generator.maximumSize = CGSize(width: 240, height: 426)
+      generator.requestedTimeToleranceBefore = CMTime(seconds: 0.5, preferredTimescale: 600)
+      generator.requestedTimeToleranceAfter = CMTime(seconds: 0.5, preferredTimescale: 600)
+      let time = CMTime(value: timeNumber.int64Value, timescale: 1000)
+      let gate = ThumbnailResponseGate()
+
+      self.thumbnailQueue.async {
+        do {
+          let image = try generator.copyCGImage(at: time, actualTime: nil)
+          let data = UIImage(cgImage: image).jpegData(compressionQuality: 0.7)
+          gate.send(result, data: data)
+        } catch {
+          gate.send(result, data: nil)
+        }
+      }
+      DispatchQueue.global(qos: .userInitiated).asyncAfter(
+        deadline: .now() + 1.5
+      ) {
+        gate.send(result, data: nil)
+      }
+    }
+  }
+
+  /// 设备标识：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="1152" height="1152"/>
+        <image name="LaunchImage" width="390" height="844"/>
-        <image name="LaunchBackground" width="1" height="1"/>
     </resources>
 </document>

ios/Runner/Info.plist

@@ -1,109 +1,111 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
-<dict>
-	<key>CADisableMinimumFrameDurationOnPhone</key>
-	<true/>
-	<key>CFBundleDevelopmentRegion</key>
-	<string>$(DEVELOPMENT_LANGUAGE)</string>
-	<key>CFBundleDisplayName</key>
-	<string>FruitShorts</string>
-	<key>CFBundleExecutable</key>
-	<string>$(EXECUTABLE_NAME)</string>
-	<key>CFBundleIdentifier</key>
-	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
-	<key>CFBundleInfoDictionaryVersion</key>
-	<string>6.0</string>
-	<key>CFBundleName</key>
-	<string>FruitShorts</string>
-	<key>CFBundlePackageType</key>
-	<string>APPL</string>
-	<key>CFBundleShortVersionString</key>
-	<string>$(FLUTTER_BUILD_NAME)</string>
-	<key>CFBundleSignature</key>
-	<string>????</string>
-	<key>CFBundleVersion</key>
-	<string>$(FLUTTER_BUILD_NUMBER)</string>
-	<key>LSRequiresIPhoneOS</key>
-	<true/>
-	<key>NSAppTransportSecurity</key>
 	<dict>
-		<key>NSAllowsArbitraryLoads</key>
+		<key>CADisableMinimumFrameDurationOnPhone</key>
 		<true/>
-		<key>NSAllowsLocalNetworking</key>
+		<key>CFBundleDevelopmentRegion</key>
+		<string>$(DEVELOPMENT_LANGUAGE)</string>
+		<key>CFBundleDisplayName</key>
+		<string>FruitShorts</string>
+		<key>CFBundleExecutable</key>
+		<string>$(EXECUTABLE_NAME)</string>
+		<key>CFBundleIdentifier</key>
+		<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+		<key>CFBundleInfoDictionaryVersion</key>
+		<string>6.0</string>
+		<key>CFBundleName</key>
+		<string>FruitShorts</string>
+		<key>CFBundlePackageType</key>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>$(FLUTTER_BUILD_NAME)</string>
+		<key>CFBundleSignature</key>
+		<string>????</string>
+		<key>CFBundleVersion</key>
+		<string>$(FLUTTER_BUILD_NUMBER)</string>
+		<key>LSRequiresIPhoneOS</key>
 		<true/>
-		<key>NSExceptionDomains</key>
+		<key>NSAppTransportSecurity</key>
 		<dict>
-			<key>127.0.0.1</key>
+			<key>NSAllowsArbitraryLoads</key>
+			<true/>
+			<key>NSAllowsLocalNetworking</key>
+			<true/>
+			<key>NSExceptionDomains</key>
 			<dict>
-				<key>NSExceptionAllowsInsecureHTTPLoads</key>
+				<key>127.0.0.1</key>
-				<true/>
-				<key>NSIncludesSubdomains</key>
-				<true/>
-			</dict>
-			<key>localhost</key>
-			<dict>
-				<key>NSExceptionAllowsInsecureHTTPLoads</key>
-				<true/>
-				<key>NSIncludesSubdomains</key>
-				<true/>
-			</dict>
-			<key>192.168.31.187</key>
-			<dict>
-				<key>NSExceptionAllowsInsecureHTTPLoads</key>
-				<true/>
-				<key>NSIncludesSubdomains</key>
-				<true/>
-			</dict>
-			<key>39.162.50.99</key>
-			<dict>
-				<key>NSExceptionAllowsInsecureHTTPLoads</key>
-				<true/>
-				<key>NSIncludesSubdomains</key>
-				<true/>
-			</dict>
-		</dict>
-	</dict>
-	<key>NSLocalNetworkUsageDescription</key>
-	<string>开发阶段需要访问同一局域网内的短剧内容服务。</string>
-	<key>UIApplicationSceneManifest</key>
-	<dict>
-		<key>UIApplicationSupportsMultipleScenes</key>
-		<false/>
-		<key>UISceneConfigurations</key>
-		<dict>
-			<key>UIWindowSceneSessionRoleApplication</key>
-			<array>
 				<dict>
-					<key>UISceneClassName</key>
+					<key>NSExceptionAllowsInsecureHTTPLoads</key>
-					<string>UIWindowScene</string>
+					<true/>
-					<key>UISceneConfigurationName</key>
+					<key>NSIncludesSubdomains</key>
-					<string>flutter</string>
+					<true/>
-					<key>UISceneDelegateClassName</key>
-					<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
-					<key>UISceneStoryboardFile</key>
-					<string>Main</string>
 				</dict>
-			</array>
+				<key>localhost</key>
+				<dict>
+					<key>NSExceptionAllowsInsecureHTTPLoads</key>
+					<true/>
+					<key>NSIncludesSubdomains</key>
+					<true/>
+				</dict>
+				<key>192.168.31.243</key>
+				<dict>
+					<key>NSExceptionAllowsInsecureHTTPLoads</key>
+					<true/>
+					<key>NSIncludesSubdomains</key>
+					<true/>
+				</dict>
+				<key>39.162.50.99</key>
+				<dict>
+					<key>NSExceptionAllowsInsecureHTTPLoads</key>
+					<true/>
+					<key>NSIncludesSubdomains</key>
+					<true/>
+				</dict>
+			</dict>
 		</dict>
+		<key>NSLocalNetworkUsageDescription</key>
+		<string>开发阶段需要访问同一局域网内的短剧内容服务。</string>
+		<key>UIApplicationSceneManifest</key>
+		<dict>
+			<key>UIApplicationSupportsMultipleScenes</key>
+			<false/>
+			<key>UISceneConfigurations</key>
+			<dict>
+				<key>UIWindowSceneSessionRoleApplication</key>
+				<array>
+					<dict>
+						<key>UISceneClassName</key>
+						<string>UIWindowScene</string>
+						<key>UISceneConfigurationName</key>
+						<string>flutter</string>
+						<key>UISceneDelegateClassName</key>
+						<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
+						<key>UISceneStoryboardFile</key>
+						<string>Main</string>
+					</dict>
+				</array>
+			</dict>
+		</dict>
+		<key>UIApplicationSupportsIndirectInputEvents</key>
+		<true/>
+		<key>UILaunchStoryboardName</key>
+		<string>LaunchScreen</string>
+		<key>UIMainStoryboardFile</key>
+		<string>Main</string>
+		<key>UISupportedInterfaceOrientations</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+		<key>UISupportedInterfaceOrientations~ipad</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+		<key>UIStatusBarHidden</key>
+		<false/>
 	</dict>
-	<key>UIApplicationSupportsIndirectInputEvents</key>
-	<true/>
-	<key>UILaunchStoryboardName</key>
-	<string>LaunchScreen</string>
-	<key>UIMainStoryboardFile</key>
-	<string>Main</string>
-	<key>UISupportedInterfaceOrientations</key>
-	<array>
-		<string>UIInterfaceOrientationPortrait</string>
-		<string>UIInterfaceOrientationLandscapeLeft</string>
-		<string>UIInterfaceOrientationLandscapeRight</string>
-	</array>
-	<key>UISupportedInterfaceOrientations~ipad</key>
-	<array>
-		<string>UIInterfaceOrientationPortrait</string>
-		<string>UIInterfaceOrientationLandscapeLeft</string>
-		<string>UIInterfaceOrientationLandscapeRight</string>
-	</array>
-</dict>
 </plist>

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,7 +43,9 @@ 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';
 import 'core/data/services/video_player_port.dart';
 import 'core/data/services/wallet_controller.dart';
@@ -52,13 +56,15 @@ import 'core/theme/app_colors.dart';
 import 'l10n/app_localizations.dart';
 import 'pages/home/home_view.dart';
 
-/// 全局系统栏样式：浅暖导航栏、关闭 Android 对比遮罩。
+/// 全局系统栏样式：深色底 + 浅色图标，关闭 Android 对比遮罩。
-final SystemUiOverlayStyle appSystemOverlayStyle = SystemUiOverlayStyle.dark
+final SystemUiOverlayStyle appSystemOverlayStyle = SystemUiOverlayStyle.light
     .copyWith(
-      statusBarColor: Colors.transparent,
+      statusBarColor: AppColors.transparent,
+      statusBarIconBrightness: Brightness.light,
+      statusBarBrightness: Brightness.dark,
       systemNavigationBarColor: AppColors.ink,
-      systemNavigationBarDividerColor: Colors.transparent,
+      systemNavigationBarDividerColor: AppColors.transparent,
-      systemNavigationBarIconBrightness: Brightness.dark,
+      systemNavigationBarIconBrightness: Brightness.light,
       systemNavigationBarContrastEnforced: false,
     );
 
@@ -72,6 +78,7 @@ class LumaDramaApp extends StatefulWidget {
     this.watchHistoryRepository,
     this.favoriteRepository,
     this.playbackRepository,
+    this.playbackPositionCache,
     this.commentRepository,
     this.interactionRepository,
     this.noticeRepository,
@@ -79,6 +86,7 @@ class LumaDramaApp extends StatefulWidget {
     this.commerceRepository,
     this.storeRepository,
     this.searchRepository,
+    this.playlistRepository,
     this.haptics = const FlutterHaptics(),
   });
 
@@ -91,6 +99,7 @@ class LumaDramaApp extends StatefulWidget {
   final WatchHistoryRepository? watchHistoryRepository;
   final FavoriteRepository? favoriteRepository;
   final PlaybackRepository? playbackRepository;
+  final PlaybackPositionCache? playbackPositionCache;
   final CommentRepository? commentRepository;
   final InteractionRepository? interactionRepository;
   final NoticeRepository? noticeRepository;
@@ -98,6 +107,7 @@ class LumaDramaApp extends StatefulWidget {
   final CommerceRepository? commerceRepository;
   final StoreRepository? storeRepository;
   final SearchRepository? searchRepository;
+  final PlaylistRepository? playlistRepository;
   final Haptics haptics;
 
   @override
@@ -108,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(
@@ -121,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 ??
@@ -130,22 +143,19 @@ 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 ??
       HttpPlaybackRepository(PlaybackApi(_apiClient));
 
+  late final PlaybackPositionCache _playbackPositionCache =
+      widget.playbackPositionCache ?? PlaybackPositionCache();
+
   late final FavoriteController _favoriteController = FavoriteController(
     _favorites,
   );
@@ -169,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));
 
@@ -198,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());
   }
@@ -214,6 +231,7 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
       unawaited(_walletController.load());
     } else {
       _favoriteController.clear();
+      unawaited(_favoriteController.load());
       _downloadController.reset();
       _walletController.reset();
     }
@@ -231,15 +249,28 @@ 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),
         Provider<FavoriteRepository>.value(value: _favorites),
         Provider<CommentRepository>.value(value: _commentRepository),
@@ -251,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),
@@ -273,9 +308,9 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
           localeResolutionCallback: (deviceLocale, _) =>
               resolveAppLocale(deviceLocale),
           debugShowCheckedModeBanner: false,
-          themeMode: ThemeMode.light,
+          themeMode: ThemeMode.dark,
-          theme: AppTheme.light(),
+          theme: AppTheme.dark(),
-          darkTheme: AppTheme.light(),
+          darkTheme: AppTheme.dark(),
           builder: (context, child) => AnnotatedRegion<SystemUiOverlayStyle>(
             value: appSystemOverlayStyle,
             child: child ?? const SizedBox.shrink(),

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/**` 的下发结构对应。
 ///
@@ -17,6 +20,8 @@ class Episode {
     this.locked = false,
     this.likeCount,
     this.commentCount,
+    this.thumbnailsUrl,
+    this.posterUrl,
   });
 
   final String id;
@@ -32,19 +37,42 @@ class Episode {
   final bool locked;
   final int? likeCount;
   final int? commentCount;
+  final String? thumbnailsUrl;
+  final String? posterUrl;
 
-  Episode withVideoUrl(String url, {int? likeCount, int? commentCount}) =>
+  Episode withVideoUrl(
-      Episode(
+    String url, {
-        id: id,
+    int? likeCount,
-        number: number,
+    int? commentCount,
-        title: title,
+    String? thumbnailsUrl,
-        isFree: isFree,
+    String? posterUrl,
-        videoUrl: url,
+  }) => Episode(
-        durationSec: durationSec,
+    id: id,
-        locked: locked,
+    number: number,
-        likeCount: likeCount ?? this.likeCount,
+    title: title,
-        commentCount: commentCount ?? this.commentCount,
+    isFree: isFree,
-      );
+    videoUrl: url,
+    durationSec: durationSec,
+    locked: locked,
+    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) {
     return Episode(
@@ -57,6 +85,8 @@ class Episode {
       videoUrl: json['playUrl'] as String? ?? '',
       likeCount: _optionalInt(json['likeCount']),
       commentCount: _optionalInt(json['commentCount']),
+      thumbnailsUrl: _optionalString(json['thumbnailsUrl']),
+      posterUrl: _optionalString(json['posterUrl']),
     );
   }
 }
@@ -68,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,
@@ -78,15 +115,24 @@ class Drama {
     this.favoriteCount,
     this.commentCount,
     this.language = '',
+    this.dramaType = '',
+    this.createdAt,
     this.detailLoaded = false,
   });
 
   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;
@@ -101,6 +147,12 @@ class Drama {
   /// 卡片语种（如 zh-CN / id），用于剧场语言筛选。
   final String language;
 
+  /// 内容类型：ANIME 漫剧，LIVE 真人剧。
+  final String dramaType;
+
+  /// 上架时间；卡片接口未直接下发时可由 Snowflake id 估算。
+  final DateTime? createdAt;
+
   /// 详情接口是否已经取过完整剧集列表。
   /// 列表卡片只带一集可播预览，需要完整剧集时再进详情。
   final bool detailLoaded;
@@ -111,36 +163,53 @@ 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']),
       commentCount: _optionalInt(json['commentCount']),
       language: json['language'] as String? ?? '',
+      dramaType: json['dramaType'] as String? ?? '',
+      createdAt: DateTime.tryParse(json['createdAt']?.toString() ?? ''),
     );
   }
 
   /// 详情：带剧集列表。
   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,
@@ -149,6 +218,8 @@ class Drama {
       favoriteCount: _optionalInt(json['favoriteCount']),
       commentCount: _optionalInt(json['commentCount']),
       language: json['language'] as String? ?? '',
+      dramaType: json['dramaType'] as String? ?? '',
+      createdAt: DateTime.tryParse(json['createdAt']?.toString() ?? ''),
       detailLoaded: true,
       episodes: (json['episodes'] as List? ?? const [])
           .whereType<Map<String, dynamic>>()
@@ -156,6 +227,120 @@ 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);
+
+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? ?? '';
+}