style(player): 视频信息区文案统一为 65% 半透明白

test(config): 服务地址断言跟随环境开关
fix(i18n): 去掉印尼语内容完整性过滤，缺失时回退中文
2026-10-31 09:41:19 +08:00 · 2026-10-31 00:02:53 +08:00 · 2026-10-31 00:02:53 +08:00 · 2026-10-30 22:53:18 +08:00 · 2026-10-30 22:53:18 +08:00 · 2026-10-30 22:53:18 +08:00
374 changed files with 26257 additions and 7296 deletions
@@ -0,0 +1,25 @@
+# Author: fruit.com.cn
+# ReelShort 客户端 CI：静态分析 + 测试门禁
+name: flutter-ci
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+      - name: 依赖
+        run: flutter pub get
+      - name: 静态分析（零告警门禁）
+        run: dart analyze --fatal-infos
+      - name: 单元测试（全绿门禁）
+        run: flutter test -r expanded
@@ -65,3 +65,6 @@ app.*.map.json
 .env
 .env.*
 !.env.example
+
+# IDE 的 Flutter Widget Preview 生成目录。
+.widget_preview/
@@ -1,18 +1,22 @@
 # FruitShorts（ReelShort）客户端

-FruitShorts 是面向印尼市场的短剧 Flutter 客户端。当前版本已连接
-`FruitServer` 的 `/app/**` 接口，支持沉浸播放、找剧、账号、观看记录、收藏、
-下载授权、评论互动、站内通知和中英印尼三语界面。
+FruitShorts 是面向印尼市场的短剧 Flutter 客户端，已连接 `FruitServer` 的
+`/app/**` 接口。功能覆盖：四 tab 主页（推荐视频流 / 找剧 / 追剧 / 我的）、
+沉浸式播放与全屏剧集播放器、清晰度切换、剧单与排行榜、新剧页、搜索、观看记录、
+收藏短剧、评论与点赞、站内通知、钱包与商品、下载落盘与离线播放、中英印尼三语，
+以及 Android / iOS 双端画中画（退到后台自动进小窗）。

 ## 技术栈

- Flutter 3.47.7 / Dart 3.13.5
+- Flutter 3.47.7 / Dart 3.13.5（`environment.sdk: ^3.12.2`）
 - Provider 状态管理与依赖注入
 - dio 网络请求
 - video_player 播放
 - shared_preferences 与 `SharedPreferencesAsync` 本地配置
+- path_provider + dart:io 下载落盘（先写 `.part`，完成后原子改名）
 - flutter_localizations，支持 `en`、`zh`、`id`
- Android 系统画中画
+- 画中画：Android 用 `floating` + `permission_handler`（需悬浮窗权限）；
+  iOS 用原生 `AVPictureInPictureController` + 影子播放器（`ios/Runner/AppDelegate.swift`）

 ## 目录结构

@@ -22,7 +26,7 @@ lib/
    config/       地址、语言和运行时配置
    data/         models、remote API、repository、controller
    formatting/   文案与日期格式化
-    platform/     触觉等平台能力
+    platform/     平台能力：画中画通道、设备号、触觉
    theme/        颜色与主题
    widgets/      跨页面复用组件
  l10n/           三语 ARB 与生成代码
@@ -36,20 +40,21 @@ assets/           图标、图片和本地媒体文件

 ## 已接接口

-以下接口均在 `lib/core/data/remote/` 中有实际调用，共 26 个不同路径、
-31 个 HTTP 方法级调用。
+以下接口均在 `lib/core/data/remote/` 中有实际调用，共 47 个不同路径。

-| 分组 | 契约 | 接口 |
-| --- | --- | --- |
-| 账号 | §1.1 | `POST /app/auth/register`、`/login`、`/refresh`、`/logout` |
-| 内容 | §1.3、§1.4 | `GET /app/home/feed`、`/app/discover/feed`、`/app/categories`、`/app/dramas/{id}`、`/app/episodes/{id}/play` |
-| 观看记录 | §1.5 | `POST/GET /app/watch/progress`、`GET /app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress` |
-| 收藏 | §1.5 | `POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}` |
-| 下载授权 | §1.6 | `GET /app/downloads/policy`、`PUT /app/downloads/settings`、`POST/GET /app/downloads`、`GET /app/downloads/{episodeId}/url`、`POST /app/downloads/{episodeId}/progress`、`DELETE /app/downloads/{episodeId}`、`DELETE /app/downloads` |
-| 互动 | §1.7 | `GET/POST /app/comments`、`DELETE /app/comments/{id}`、`POST /app/likes/toggle`、`POST /app/reports` |
-| 公告 | §1.9.2 | `GET /app/notices` |
+| 分组 | 接口 |
+| --- | --- |
+| 账号 | `POST /app/auth/register`、`/login`、`/refresh`、`/logout`、`/otp`；`GET /app/me`、`/app/me/devices`、`/app/me/export`；`POST /app/me/deactivate`、`/app/me/deactivate/cancel` |
+| 内容 | `GET /app/home/feed`、`/app/feed`、`/app/discover/feed`、`/app/categories`、`/app/categories/{id}/dramas`、`/app/drama-categories`、`/app/dramas/page`、`/app/dramas/{id}`、`/app/tags`、`/app/search`、`/app/playlists`、`/app/playlists/{id}` |
+| 播放 | `GET /app/episodes/{id}/play`、`/app/episodes/{id}/stats`；`POST /app/episodes/{id}/unlock` |
+| 观看记录 | `POST/GET /app/watch/progress`、`GET /app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress` |
+| 收藏 | `POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}`、`POST /app/favorites/remove` |
+| 下载 | `GET /app/downloads/policy`、`PUT /app/downloads/settings`、`POST/GET /app/downloads`、`GET /app/downloads/{id}/url`、`POST /app/downloads/{id}/progress`、`DELETE /app/downloads/{id}`、`DELETE /app/downloads` |
+| 互动 | `GET/POST /app/comments`、`DELETE /app/comments/{id}`、`GET /app/comments/count`、`POST /app/likes/toggle`、`POST /app/reports` |
+| 商业化 | `GET /app/wallet`、`/app/products`、`/app/orders` |
+| 公告 | `GET /app/notices` |

-客户端没有调用 `/app/config` 或创作者入驻接口。
+客户端没有调用 `/app/config` 和创作者入驻接口。

 ## 运行

@@ -66,39 +71,60 @@ flutter pub get
 ```bash
 adb devices
 adb reverse tcp:8081 tcp:8081
-flutter run -d <device> \
-  --dart-define=API_BASE_URL=http://127.0.0.1:8081
+flutter run -d <device>
 ```

 `adb reverse` 将手机的 `127.0.0.1:8081` 转发到电脑；USB 断开或重新连接后需要
-重新执行。
+重新执行。此时用调试条把地址改成 `http://127.0.0.1:8081`（见下节）。

-Android 模拟器访问宿主机时使用：
-
-```bash
-flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8081
-```
+Android 模拟器访问宿主机时，同样在调试条里填 `http://10.0.2.2:8081`。

 ### iOS

-手机与 Mac 需在同一网络，首次启动允许“本地网络”权限：
+iOS 模拟器直接访问 Mac 本机服务，默认地址为 `http://127.0.0.1:8081`：

 ```bash
-flutter run -d <udid> \
-  --dart-define=API_BASE_URL=http://<Mac局域网IP>:8081
+flutter run -d <simulator-udid>
 ```

-### Debug 运行时地址
+iPhone 真机不能用 `127.0.0.1` 访问 Mac；真机联调时需让手机与 Mac 位于同一网络，
+并通过调试入口临时填写 Mac 的局域网地址。

-debug 版本可在「我的 → 设置 → 服务器地址」修改后端地址，保存后重启 App 生效。
-地址优先级：
+### 服务地址配置

-```text
-本地运行时设置 > --dart-define(API_BASE_URL) > 平台默认地址
+地址是代码里的一个开关，**不做任何网络探测**，也不用传构建参数。两套环境各占
+一个文件：
+
+| 文件 | 用途 | 默认值 |
+| --- | --- | --- |
+| `lib/core/config/dev_config.dart` | 开发 / 联调 | `http://127.0.0.1:8081` |
+| `lib/core/config/prod_config.dart` | 生产 | `http://39.162.50.99:8081` |
+
+切换环境只改 `lib/core/config/app_config.dart` 里的一个布尔值：
+
+```dart
+static const bool useDevConfig = true; // false 即用生产地址
 ```

-因此不带 `--dart-define` 构建的 debug APK 也可在安装后改成当前电脑 IP。
-release 版本不显示入口，也不会读取本地覆盖。
+真机或 Android 模拟器联调时，通过调试入口覆盖地址，不修改默认开发配置。打生产包前把
+`useDevConfig` 改成 `false`；release 构建若仍为 `true` 会在启动时直接报错，
+避免线上包连到开发机。
+
+debug 包在找剧页加载失败时会显示调试条，点「修改服务器地址」可临时改成当前
+电脑 IP，保存后立即重载、不需要重新打包，该覆盖保存在本地偏好里（仅 debug
+生效，release 不读取）。
+
+## 画中画
+
+| 平台 | 行为 |
+| --- | --- |
+| Android | 首次点播放页小窗按钮时申请悬浮窗权限；授权后退出 App 自动进入系统小窗。沉浸流与独立播放页共用一份引用计数，任一处活跃都算「在播」，避免互相顶掉 |
+| iOS | 原生影子播放器承载 `AVPictureInPictureController`，只有播放页处于活跃状态时退到后台才自动进小窗；停在剧单等页面退后台不会触发 |
+
+- 小窗内切集直接换源，不走页面翻页，可连续自动播放
+- iOS 从系统小窗还原时用原生过渡层盖住纹理黑帧，等首帧就绪后再淡出
+- 播放页「更多」面板里有「退出自动小窗」开关（仅支持自动小窗的平台显示），关掉后
+  退到后台不再进入小窗

 ## 环境注意

@@ -131,46 +157,56 @@ xcodebuild -resolvePackageDependencies \

 ```bash
 adb uninstall com.stormg.lumadrama
-flutter run -d <device> \
-  --dart-define=API_BASE_URL=http://127.0.0.1:8081
+flutter run -d <device>
 ```

 ## 生产打包（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）
-```
+| 渠道 | 产物 | 命令 | 体积 |
+| --- | --- | --- | --- |
+| Google Play | AAB（按设备下发） | `flutter build appbundle --release` | 上传 28MB，用户下载约 8MB |
+| 国内各大市场 | 通用 APK（arm64 + v7） | `flutter build apk --release` | 约 13MB |

 说明：

 - `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），默认不用。
+- `android/gradle.properties` 里固定了 `split-debug-info=build/symbols` 与 `dart-obfuscation=true`，**IDE 里点 Build APK / Build App Bundle 也会生效**：`libapp.so` 从 ~8MB/ABI 降到 ~1.1MB/ABI。
+- `useLegacyPackaging = true`：原生库以压缩形式存储，这是国内 APK 从 40MB 降到 13MB 的主要原因；代价是安装时解压。
+- **每次发版都要归档 `build/symbols`**，线上崩溃栈需要它还原。
+- release 仍在用 debug 签名（`build.gradle.kts` 的 TODO），上架前必须换成正式 keystore。
+- 不要用 `--split-per-abi`：与 `abiFilters` 冲突；Play 的 AAB 已经按设备拆好。
+
+## 生产打包（iOS）
+
+```bash
+# 正式签名（需要 iOS Distribution 证书 + App Store 描述文件）
+flutter build ipa --release
+
+# 只有 Apple Development 证书时：出开发签名 IPA，只能装已注册设备
+flutter build ipa --release --export-method development
+```
+
+产物在 `build/ios/ipa/*.ipa`。画中画依赖 `UIBackgroundModes` 里的 `audio` 与
+`AVPictureInPictureController`，改动 `ios/Runner/Info.plist` 或 `AppDelegate.swift`
+后要重新构建，热重载不会生效。

 ## 门禁

 ```bash
-dart analyze lib test
+dart analyze
 flutter test
 flutter build apk --debug
 ```

-测试文件按模块放在 `test/` 下，用例名使用
+当前基线：`dart analyze` 仅 1 条既存 info（`intl` 未在 `pubspec.yaml` 声明)；
+`flutter test` 全量 775 例通过。测试文件按模块放在 `test/` 下，用例名使用
 `should_<期望>_when_<条件>`。真实后端联调测试在服务未启动时会跳过。

 ## 当前边界

- 下载仅管理服务端授权，不落盘、不续传、不支持离线播放。
- 没有独立搜索接口，搜索能力尚未形成完整闭环。
+- 下载会落盘并支持离线播放，但不支持断点续传：中途失败会丢弃 `.part` 重下。
+- 支付与金币：客户端已有钱包、商品、下单接口与页面，商店票据校验依赖服务端配置凭据。
 - 站内通知没有已读/未读和红点状态。
- 支付、金币和会员权益尚未形成客户端闭环。
- Android 支持系统画中画；iOS 画中画尚未接入。
+- 播放清晰度切换会保留旧画面 500ms 掩盖闪屏，切换瞬间的进度以相对位置续播。
@@ -1,4 +1,5 @@
 /.gradle
+/build/
 /captures/
 /local.properties
 GeneratedPluginRegistrant.java
@@ -8,7 +8,9 @@ plugins {

 android {
    namespace = "com.stormg.lumadrama"
-    compileSdk = flutter.compileSdkVersion
+    // permission_handler_android 14 的 AAR 元数据要求依赖方 compileSdk >= 37，
+    // 固定为 37（比 Flutter 默认的 36 高一档，只影响编译期 API 可见性）。
+    compileSdk = 37
    ndkVersion = flutter.ndkVersion

    compileOptions {
@@ -33,6 +35,13 @@ android {
            ndk {
                abiFilters += listOf("arm64-v8a", "armeabi-v7a")
            }
+            // R8 裁剪未使用的 Java/Kotlin 代码与资源，减小 dex 与 res。
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
            // 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")
@@ -50,6 +59,9 @@ kotlin {
 androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        variant.packaging.jniLibs.excludes.add("lib/x86_64/**")
+        // 原生库随 APK 压缩存储：下载体积明显小于解压后的体积，代价是安装时解压。
+        // 本包 90% 体积是 so，这一项对国内商店的 APK 分发影响最大。
+        variant.packaging.jniLibs.useLegacyPackaging = true
    }
 }

@@ -0,0 +1,11 @@
+# Author: fruit.com.cn
+#
+# R8 保号规则：Flutter 引擎与插件自带的 consumer rules 已覆盖大部分场景，
+# 这里只补本项目原生层通过反射/通道访问、裁剪后容易失效的入口。
+
+# 画中画与权限通道由 MainActivity 直接注册，保留应用包名下的入口类。
+-keep class com.stormg.lumadrama.** { *; }
+
+# Flutter 引擎在 release 下通过 JNI 回调这些类，禁止改名。
+-keep class io.flutter.** { *; }
+-dontwarn io.flutter.embedding.**
@@ -2,8 +2,11 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission
        android:name="android.permission.INTERNET"/>
+    <!-- 画中画自动触发依赖的「显示在其他应用上层」权限（部分 ROM 用它管控 PiP） -->
+    <uses-permission
+        android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
    <application
-        android:label="FruitShorts"
+        android:label="ymb"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        android:usesCleartextTraffic="true">
@@ -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
@@ -65,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") {
@@ -156,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
@@ -241,6 +284,7 @@ class MainActivity : FlutterActivity() {
    }

    companion object {
+        private const val TAG = "FruitPip"
        private const val thumbnailMaxWidth = 240
        private const val thumbnailJpegQuality = 70
        private const val thumbnailTimeoutMs = 1500L
@@ -2,6 +2,18 @@
 <!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/splash_background" />
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:centerX="0"
+                android:centerY="0"
+                android:gradientRadius="350dp"
+                android:startColor="#FF6B011A"
+                android:centerColor="#616B011A"
+                android:endColor="#006B011A" />
+        </shape>
+    </item>
    <item>
        <bitmap
            android:gravity="center"
@@ -2,6 +2,18 @@
 <!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/splash_background" />
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:centerX="0"
+                android:centerY="0"
+                android:gradientRadius="350dp"
+                android:startColor="#FF6B011A"
+                android:centerColor="#616B011A"
+                android:endColor="#006B011A" />
+        </shape>
+    </item>
    <item>
        <bitmap
            android:gravity="center"
@@ -2,6 +2,18 @@
 <!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/splash_background" />
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:centerX="0"
+                android:centerY="0"
+                android:gradientRadius="350dp"
+                android:startColor="#FF6B011A"
+                android:centerColor="#616B011A"
+                android:endColor="#006B011A" />
+        </shape>
+    </item>
    <item>
        <bitmap
            android:gravity="center"
@@ -2,6 +2,18 @@
 <!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/splash_background" />
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:centerX="0"
+                android:centerY="0"
+                android:gradientRadius="350dp"
+                android:startColor="#FF6B011A"
+                android:centerColor="#616B011A"
+                android:endColor="#006B011A" />
+        </shape>
+    </item>
    <item>
        <bitmap
            android:gravity="center"
@@ -2,6 +2,18 @@
 <!-- Author: fruit.com.cn -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/splash_background" />
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:centerX="0"
+                android:centerY="0"
+                android:gradientRadius="350dp"
+                android:startColor="#FF6B011A"
+                android:centerColor="#616B011A"
+                android:endColor="#006B011A" />
+        </shape>
+    </item>
    <item>
        <bitmap
            android:gravity="center"
@@ -8,7 +8,7 @@
        <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:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
        <item name="android:windowSplashScreenAnimationDuration">0</item>
    </style>
    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
@@ -8,7 +8,7 @@
        <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:windowSplashScreenAnimatedIcon">@drawable/android12splash</item>
        <item name="android:windowSplashScreenAnimationDuration">0</item>
    </style>
    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
@@ -3,5 +3,5 @@

 <resources>
 	<color name="splash_background">#000000</color>
-	<color name="ic_launcher_background">#FF6B2C</color>
-</resources>
+	<color name="ic_launcher_background">#E9142E</color>
+</resources>
@@ -6,3 +6,8 @@ android.useAndroidX=true
 android.newDsl=false
 # This builtInKotlin flag was added by the Flutter template
 android.builtInKotlin=false
+
+# release 包默认剥离 Dart 调试符号并混淆：libapp.so 由 ~8MB 降到 ~1MB/ABI。
+# 符号表输出到 build/symbols，崩溃分析时用它还原堆栈，发布前务必归档。
+split-debug-info=build/symbols
+dart-obfuscation=true
@@ -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 */,
 			);
@@ -1,6 +1,7 @@
 import Flutter
 import UIKit
 import AVFoundation
+import AVKit

 private let thumbnailHTTPHeaderFieldsKey = "AVURLAssetHTTPHeaderFieldsKey"

@@ -35,8 +36,321 @@ final class RunnerFlutterViewController: FlutterViewController {
  }
 }

+/// iOS 影子播放器：独立 AVPlayer + AVPlayerLayer 专供画中画窗口。
+/// Flutter 的 video_player 走纹理渲染，没有 AVPlayerLayer，无法直接创建
+/// AVPictureInPictureController；小窗的画面与声音由影子接管，退出时把
+/// 影子进度回传给 Dart，由 Flutter 播放器 seek 对齐后继续。
+final class PipShadowCoordinator: NSObject, AVPictureInPictureControllerDelegate {
+  static let shared = PipShadowCoordinator()
+
+  private var player: AVPlayer?
+  private var playerLayer: AVPlayerLayer?
+  private var controller: AVPictureInPictureController?
+  private var endObserver: NSObjectProtocol?
+  private var possibleObservation: NSKeyValueObservation?
+  /// 画中画还原过渡层：原生窗口级红晕渐变，在系统还原动画开始时立即盖上，
+  /// 避免回前台瞬间 Flutter 表面未恢复显示黑帧；视频出帧后由 Dart 通知淡出。
+  private var restoreOverlay: UIView?
+  /// 系统要求 playerLayer 位于真实的 view 层级中才会判定画中画可用，
+  /// 因此用 1x1 透明宿主 view 承载，而不是直接挂在 window.layer 上。
+  private var hostView: UIView?
+  /// 影子图层就绪稍晚于创建，置位后由 KVO 自动拉起画中画。
+  private var pendingStart = false
+  private var startRetryWorkItems: [DispatchWorkItem] = []
+
+  weak var channel: FlutterMethodChannel?
+
+  /// active 变化回调；停止时把影子最终进度（毫秒）一并提供。
+  var onPipChanged: ((Bool, Int64) -> Void)?
+  /// 影子在画中画里播完当前集。
+  var onPlaybackEnded: (() -> Void)?
+
+  static var isSupported: Bool {
+    AVPictureInPictureController.isPictureInPictureSupported()
+  }
+
+  private var keyWindow: UIWindow? {
+    UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .flatMap { $0.windows }
+      .first { $0.isKeyWindow }
+  }
+
+  /// 首次创建影子：1x1 图层挂在 keyWindow 的宿主 view 里（肉眼不可见），静音待命。
+  /// [autoEnter] 为 true 时退后台由系统自动拉起画中画（需影子在播，见 armAutoEnter）。
+  func prepare(urlString: String, positionMs: Int64, autoEnter: Bool) {
+    teardown()
+    log("prepare begin supported=\(PipShadowCoordinator.isSupported) autoEnter=\(autoEnter)")
+    guard Self.isSupported else { return }
+    guard let url = URL(string: urlString) else {
+      log("prepare failed bad url \(urlString)")
+      return
+    }
+    guard let window = keyWindow else {
+      log("prepare failed no key window")
+      return
+    }
+    let item = AVPlayerItem(url: url)
+    let p = AVPlayer(playerItem: item)
+    p.isMuted = true
+    p.actionAtItemEnd = .pause
+    let layer = AVPlayerLayer()
+    layer.player = p
+    let host = UIView(frame: CGRect(x: 0, y: 0, width: 1, height: 1))
+    host.isUserInteractionEnabled = false
+    host.backgroundColor = .clear
+    window.addSubview(host)
+    layer.frame = host.bounds
+    host.layer.addSublayer(layer)
+    hostView = host
+    guard let c = AVPictureInPictureController(playerLayer: layer) else {
+      p.pause()
+      log("prepare failed no pip controller")
+      return
+    }
+    c.canStartPictureInPictureAutomaticallyFromInline = autoEnter
+    c.delegate = self
+    player = p
+    playerLayer = layer
+    controller = c
+    // 静音起播让 item 完成首帧解码，isPictureInPicturePossible 才会变 true。
+    p.play()
+    possibleObservation = c.observe(
+      \.isPictureInPicturePossible,
+      options: [.new, .initial]
+    ) { [weak self] controller, change in
+      let value = change.newValue ?? controller.isPictureInPicturePossible
+      self?.log("possible changed to \(value)")
+      guard let self, self.pendingStart, controller.isPictureInPicturePossible else { return }
+      self.pendingStart = false
+      // 刚翻 true 的同一 runloop 里调用会被系统静默拒绝，推到下一拍再进。
+      DispatchQueue.main.async {
+        guard self.controller === controller, controller.isPictureInPicturePossible else {
+          self.log("start via kvo aborted (shadow replaced)")
+          return
+        }
+        self.log("start via kvo")
+        controller.startPictureInPicture()
+      }
+    }
+    log("shadow ready, seeking to \(positionMs)ms")
+    if positionMs > 0 {
+      p.seek(
+        to: CMTime(value: positionMs, timescale: 1000),
+        toleranceBefore: .zero,
+        toleranceAfter: .zero
+      )
+    }
+    registerEndObserver(for: item)
+    activateAudioSession()
+  }
+
+  /// 退出 App 前（inactive）把影子对齐到当前进度并静音起播：
+  /// auto PiP 只在「player 正在播放 + 图层离屏」时由系统触发。
+  func armAutoEnter(positionMs: Int64) {
+    guard let player, let controller else {
+      log("arm failed, shadow missing")
+      return
+    }
+    guard controller.canStartPictureInPictureAutomaticallyFromInline else {
+      log("arm failed, autoEnter disabled on shadow")
+      return
+    }
+    log("arm auto enter at \(positionMs)ms")
+    if positionMs > 0 {
+      player.seek(
+        to: CMTime(value: positionMs, timescale: 1000),
+        toleranceBefore: CMTime(value: 800, timescale: 1000),
+        toleranceAfter: CMTime(value: 800, timescale: 1000)
+      )
+    }
+    player.play()
+  }
+
+  /// 回前台后取消待命：影子暂停回静音，等待下一次退后台。
+  func disarmAutoEnter() {
+    guard let player else { return }
+    log("disarm auto enter")
+    player.pause()
+    player.isMuted = true
+  }
+
+  /// 进入画中画：图层就绪则立即进入，否则 KVO/延时重试在就绪后自动进入。
+  /// 仅当影子从未创建成功（prepare 失败）时返回 false。
+  func start() -> Bool {
+    guard let controller else {
+      log("start failed, shadow not created")
+      return false
+    }
+    log("start requested possible=\(controller.isPictureInPicturePossible)")
+    pendingStart = true
+    if controller.isPictureInPicturePossible {
+      pendingStart = false
+      controller.startPictureInPicture()
+    }
+    scheduleStartRetries()
+    return true
+  }
+
+  /// KVO 偶发不触发或流加载较慢时兜底：就绪后再试两次。
+  private func scheduleStartRetries() {
+    startRetryWorkItems.forEach { $0.cancel() }
+    startRetryWorkItems.removeAll()
+    for delay in [1.0, 2.5] {
+      let item = DispatchWorkItem { [weak self] in
+        guard
+            let self,
+            self.pendingStart,
+            let controller = self.controller,
+            controller.isPictureInPicturePossible
+        else { return }
+        self.log("start via retry after \(delay)s")
+        self.pendingStart = false
+        controller.startPictureInPicture()
+      }
+      startRetryWorkItems.append(item)
+      DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: item)
+    }
+  }
+
+  /// 画中画内换集：只换 AVPlayerItem，不动 player/layer，窗口不中断。
+  func replaceItem(urlString: String, positionMs: Int64) {
+    guard let player, let url = URL(string: urlString) else { return }
+    let item = AVPlayerItem(url: url)
+    player.replaceCurrentItem(with: item)
+    registerEndObserver(for: item)
+    if positionMs > 0 {
+      player.seek(
+        to: CMTime(value: positionMs, timescale: 1000),
+        toleranceBefore: .zero,
+        toleranceAfter: .zero
+      )
+    }
+  }
+
+  /// 进入画中画后解除静音并起播（此时 Flutter 播放器已被暂停）。
+  func unmuteAndPlay() {
+    player?.isMuted = false
+    player?.play()
+  }
+
+  func positionMs() -> Int64 {
+    Int64(max(0, player?.currentTime().seconds ?? 0) * 1000)
+  }
+
+  func stopPip() {
+    controller?.stopPictureInPicture()
+  }
+
+  func teardown() {
+    startRetryWorkItems.forEach { $0.cancel() }
+    startRetryWorkItems.removeAll()
+    possibleObservation?.invalidate()
+    possibleObservation = nil
+    pendingStart = false
+    if let endObserver {
+      NotificationCenter.default.removeObserver(endObserver)
+    }
+    endObserver = nil
+    player?.pause()
+    player?.replaceCurrentItem(with: nil)
+    playerLayer?.removeFromSuperlayer()
+    playerLayer = nil
+    hostView?.removeFromSuperview()
+    hostView = nil
+    controller?.delegate = nil
+    controller = nil
+    player = nil
+  }
+
+  /// 诊断日志：NSLog 之外同步转发到 Dart，便于在 flutter run 控制台观察。
+  private func log(_ message: String) {
+    NSLog("pip: %@", message)
+    channel?.invokeMethod("pipDebug", arguments: message)
+  }
+
+  private func registerEndObserver(for item: AVPlayerItem) {
+    if let endObserver {
+      NotificationCenter.default.removeObserver(endObserver)
+    }
+    endObserver = NotificationCenter.default.addObserver(
+      forName: .AVPlayerItemDidPlayToEndTime,
+      object: item,
+      queue: .main
+    ) { [weak self] _ in
+      self?.log("item did play to end")
+      self?.onPlaybackEnded?()
+    }
+  }
+
+  /// 画中画的声音走影子播放器，需要 playback 类别的音频会话保活。
+  private func activateAudioSession() {
+    do {
+      try AVAudioSession.sharedInstance().setCategory(.playback, mode: .moviePlayback)
+      try AVAudioSession.sharedInstance().setActive(true)
+    } catch {
+      // 会话激活失败只影响后台出声，不阻断画中画。
+    }
+  }
+
+  func pictureInPictureControllerWillStartPictureInPicture(
+    _ pictureInPictureController: AVPictureInPictureController
+  ) {
+    log("will start")
+    pendingStart = false
+    onPipChanged?(true, 0)
+  }
+
+  func pictureInPictureControllerWillStopPictureInPicture(
+    _ pictureInPictureController: AVPictureInPictureController
+  ) {
+    log("will stop, showing restore overlay")
+    showRestoreOverlay()
+  }
+
+  func pictureInPictureControllerDidStopPictureInPicture(
+    _ pictureInPictureController: AVPictureInPictureController
+  ) {
+    log("did stop")
+    showRestoreOverlay()
+    onPipChanged?(false, positionMs())
+  }
+
+  /// 盖原生过渡层（幂等）：主题红晕渐变，不依赖 Flutter 渲染。
+  func showRestoreOverlay() {
+    guard let window = keyWindow else { return }
+    restoreOverlay?.removeFromSuperview()
+    let overlay = UIView(frame: window.bounds)
+    overlay.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+    let gradient = CAGradientLayer()
+    gradient.frame = overlay.bounds
+    gradient.colors = [
+      UIColor(red: 0.298, green: 0.086, blue: 0.102, alpha: 1).cgColor,
+      UIColor(red: 0.118, green: 0.043, blue: 0.047, alpha: 1).cgColor,
+      UIColor(red: 0.063, green: 0.063, blue: 0.071, alpha: 1).cgColor,
+    ]
+    gradient.locations = [0, 0.22, 0.62]
+    gradient.startPoint = CGPoint(x: 0.5, y: 0)
+    gradient.endPoint = CGPoint(x: 0.5, y: 1)
+    overlay.layer.addSublayer(gradient)
+    window.addSubview(overlay)
+    restoreOverlay = overlay
+  }
+
+  /// 淡出并移除过渡层（视频首帧已确认后由 Dart 调用）。
+  func hideRestoreOverlay() {
+    guard let overlay = restoreOverlay else { return }
+    restoreOverlay = nil
+    UIView.animate(
+      withDuration: 0.25,
+      animations: { overlay.alpha = 0 }
+    ) { _ in overlay.removeFromSuperview() }
+  }
+}
+
@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
+  private let wirelessDataPrompt = WirelessDataPrompt()
  private let thumbnailQueue = DispatchQueue(
    label: "com.stormg.lumadrama.thumbnail",
    qos: .userInitiated
@@ -50,8 +364,20 @@ 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)
+    registerPipChannel(engineBridge)
    let channel = FlutterMethodChannel(
      name: "com.stormg.lumadrama/share",
      binaryMessenger: engineBridge.applicationRegistrar.messenger()
@@ -132,4 +458,130 @@ final class RunnerFlutterViewController: FlutterViewController {
      }
    }
  }
+
+  /// iOS 画中画：影子播放器通道，与 Android 共用同一 channel 名。
+  private func registerPipChannel(_ engineBridge: FlutterImplicitEngineBridge) {
+    let channel = FlutterMethodChannel(
+      name: "com.stormg.lumadrama/pip",
+      binaryMessenger: engineBridge.applicationRegistrar.messenger()
+    )
+    let pip = PipShadowCoordinator.shared
+    pip.channel = channel
+    channel.setMethodCallHandler { call, result in
+      switch call.method {
+      case "isAvailable":
+        result(PipShadowCoordinator.isSupported)
+      case "enter":
+        guard let args = call.arguments as? [String: Any],
+              let url = args["url"] as? String else {
+          result(false)
+          return
+        }
+        let positionMs = (args["positionMs"] as? NSNumber)?.int64Value ?? 0
+        pip.prepare(urlString: url, positionMs: positionMs, autoEnter: false)
+        // 等一拍让 AVPlayerLayer 完成挂载再请求进入画中画。
+        DispatchQueue.main.async {
+          result(pip.start())
+        }
+      case "prepareShadow":
+        guard let args = call.arguments as? [String: Any],
+              let url = args["url"] as? String else {
+          result(nil)
+          return
+        }
+        pip.prepare(
+          urlString: url,
+          positionMs: (args["positionMs"] as? NSNumber)?.int64Value ?? 0,
+          autoEnter: (args["autoEnter"] as? NSNumber)?.boolValue ?? false
+        )
+        result(nil)
+      case "armAutoEnter":
+        pip.armAutoEnter(
+          positionMs: (call.arguments as? [String: Any])?["positionMs"] as? Int64 ?? 0
+        )
+        result(nil)
+      case "showRestoreOverlay":
+        pip.showRestoreOverlay()
+        result(nil)
+      case "hideRestoreOverlay":
+        pip.hideRestoreOverlay()
+        result(nil)
+      case "disarmAutoEnter":
+        pip.disarmAutoEnter()
+        result(nil)
+      case "unmute":
+        pip.unmuteAndPlay()
+        result(nil)
+      case "replaceItem":
+        guard let args = call.arguments as? [String: Any],
+              let url = args["url"] as? String else {
+          result(nil)
+          return
+        }
+        pip.replaceItem(
+          urlString: url,
+          positionMs: (args["positionMs"] as? NSNumber)?.int64Value ?? 0
+        )
+        result(nil)
+      case "stop":
+        pip.stopPip()
+        result(nil)
+      case "teardown":
+        pip.teardown()
+        result(nil)
+      default:
+        result(FlutterMethodNotImplemented)
+      }
+    }
+    pip.onPipChanged = { active, positionMs in
+      channel.invokeMethod(
+        "onPipChanged",
+        arguments: ["active": active, "positionMs": positionMs]
+      )
+    }
+    pip.onPlaybackEnded = {
+      channel.invokeMethod("onPipPlaybackEnded", arguments: 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)
+    }
+  }
 }
@@ -1,111 +1,115 @@
 <?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>ymb</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>ymb</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>CADisableMinimumFrameDurationOnPhone</key>
+		<key>NSAllowsArbitraryLoads</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>
+		<key>NSAllowsLocalNetworking</key>
 		<true/>
-		<key>NSAppTransportSecurity</key>
+		<key>NSExceptionDomains</key>
 		<dict>
-			<key>NSAllowsArbitraryLoads</key>
-			<true/>
-			<key>NSAllowsLocalNetworking</key>
-			<true/>
-			<key>NSExceptionDomains</key>
+			<key>127.0.0.1</key>
 			<dict>
-				<key>127.0.0.1</key>
-				<dict>
-					<key>NSExceptionAllowsInsecureHTTPLoads</key>
-					<true/>
-					<key>NSIncludesSubdomains</key>
-					<true/>
-				</dict>
-				<key>localhost</key>
-				<dict>
-					<key>NSExceptionAllowsInsecureHTTPLoads</key>
-					<true/>
-					<key>NSIncludesSubdomains</key>
-					<true/>
-				</dict>
-				<key>10.43.47.1</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>
+				<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>
+			<key>localhost</key>
+			<dict>
+				<key>NSExceptionAllowsInsecureHTTPLoads</key>
+				<true/>
+				<key>NSIncludesSubdomains</key>
+				<true/>
 			</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>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>UIBackgroundModes</key>
+	<array>
+		<string>audio</string>
+	</array>
+	<key>UILaunchStoryboardName</key>
+	<string>LaunchScreen</string>
+	<key>UIMainStoryboardFile</key>
+	<string>Main</string>
+	<key>UIStatusBarHidden</key>
+	<false/>
+	<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>
@@ -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()
+  }
 }
@@ -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) }
+  }
+}
@@ -14,6 +14,8 @@ 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/config_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,9 +32,11 @@ 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';
+import 'core/data/services/app_config_controller.dart';
 import 'core/data/services/auth_controller.dart';
 import 'core/data/services/auth_session_store.dart';
 import 'core/data/services/catalog_controller.dart';
@@ -41,9 +45,11 @@ 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/unlocked_episode_registry.dart';
 import 'core/data/services/video_player_port.dart';
 import 'core/data/services/wallet_controller.dart';
 import 'core/navigation/app_route_observer.dart';
@@ -83,6 +89,7 @@ class LumaDramaApp extends StatefulWidget {
    this.commerceRepository,
    this.storeRepository,
    this.searchRepository,
+    this.playlistRepository,
    this.haptics = const FlutterHaptics(),
  });

@@ -103,6 +110,7 @@ class LumaDramaApp extends StatefulWidget {
  final CommerceRepository? commerceRepository;
  final StoreRepository? storeRepository;
  final SearchRepository? searchRepository;
+  final PlaylistRepository? playlistRepository;
  final Haptics haptics;

  @override
@@ -113,12 +121,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 +135,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 +146,11 @@ class _LumaDramaAppState extends State<LumaDramaApp> {

  late final WatchHistoryRepository _watchHistory =
      widget.watchHistoryRepository ??
-      HttpWatchHistoryRepository(
-        WatchApi(_apiClient),
-        isSignedIn: () => _auth.isSignedIn,
-      );
+      HttpWatchHistoryRepository(WatchApi(_apiClient));

  late final FavoriteRepository _favorites =
      widget.favoriteRepository ??
-      HttpFavoriteRepository(
-        LibraryApi(_apiClient),
-        isSignedIn: () => _auth.isSignedIn,
-      );
+      HttpFavoriteRepository(LibraryApi(_apiClient));

  late final PlaybackRepository _playback =
      widget.playbackRepository ??
@@ -177,6 +182,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,15 +210,25 @@ class _LumaDramaAppState extends State<LumaDramaApp> {

  late final LocaleController _localeController = LocaleController();

+  /// 后台下发的启动配置（登录页背景等）；拉不到就用本地默认。
+  late final AppConfigController _appConfigController = AppConfigController(
+    ConfigApi(_apiClient),
+  );
+
+  /// 登录期内共享的「已解锁收费集」：播放页进出、feed 与全屏切换都要沿用。
+  late final UnlockedEpisodeRegistry _unlockedEpisodes =
+      UnlockedEpisodeRegistry();
+
  @override
  void initState() {
    super.initState();
    // 恢复本地令牌与设备号；未登录也能正常浏览，不阻塞首屏
    _auth.load();
    unawaited(_localeController.load());
+    unawaited(_appConfigController.load());
    // 登录/登出时同步收藏状态：收藏属于账号，不能跨账号串联
    _auth.addListener(_onAuthChanged);
-    if (_auth.isSignedIn) unawaited(_favoriteController.load());
+    unawaited(_favoriteController.load());
    if (_auth.isSignedIn) unawaited(_walletController.load());
    unawaited(_downloadController.restore());
  }
@@ -217,11 +239,14 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
    if (_auth.isSignedIn == _wasSignedIn) return;
    _wasSignedIn = _auth.isSignedIn;
    _interactionController.clear();
+    // 解锁结论属于账号：换人登录后不能沿用上一个人的可播判断。
+    _unlockedEpisodes.clear();
    if (_auth.isSignedIn) {
      unawaited(_favoriteController.load());
      unawaited(_walletController.load());
    } else {
      _favoriteController.clear();
+      unawaited(_favoriteController.load());
      _downloadController.reset();
      _walletController.reset();
    }
@@ -235,20 +260,34 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
    _walletController.dispose();
    _interactionController.dispose();
    _localeController.dispose();
+    _appConfigController.dispose();
    _apiClient.close();
    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<UnlockedEpisodeRegistry>.value(value: _unlockedEpisodes),
        Provider<WatchHistoryRepository>.value(value: _watchHistory),
        Provider<FavoriteRepository>.value(value: _favorites),
        Provider<CommentRepository>.value(value: _commentRepository),
@@ -260,16 +299,21 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
        Provider<SearchRepository>.value(value: _searchRepository),
        Provider<Haptics>.value(value: widget.haptics),
        ChangeNotifierProvider(
-          create: (_) => CatalogController(_catalogRepository)..load(),
-        ),
-        ChangeNotifierProvider(
-          create: (_) => CategoryController(_categoryRepository)..load(),
+          create: (_) {
+            final catalog = CatalogController(_catalogRepository);
+            if (widget.catalogRepository != null) catalog.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),
        ChangeNotifierProvider.value(value: _interactionController),
        ChangeNotifierProvider.value(value: _localeController),
+        ChangeNotifierProvider.value(value: _appConfigController),
        ChangeNotifierProvider.value(value: _auth),
      ],
      child: Consumer<LocaleController>(
@@ -1,165 +1,51 @@
 // Author: fruit.com.cn

-import 'dart:io';
+import 'dev_config.dart';
+import 'prod_config.dart';

-import 'package:flutter/foundation.dart';
-
-/// 客户端与后端约定的运行时配置。
+/// 客户端运行时配置。
 ///
-/// 接口地址优先级：运行时设置 > `--dart-define=API_BASE_URL=...` > 平台默认值。
-/// 开发机的局域网地址会随网络变化，换网络后改 [devHostBaseUrl] 即可。
-class AppConfig {
-  const AppConfig._();
-
-  /// 开发调试默认服务地址，当前指向本机局域网 IP。
+/// 两套环境各一个文件：
+/// - `dev_config.dart`：[DevConfig]（本机联调）
+/// - `prod_config.dart`：[ProdConfig]（生产）
+///
+/// 切换环境只改下面这一个布尔值，不用传任何构建参数、也不做网络探测。
+abstract final class AppConfig {
+  /// **环境开关**：true 用开发环境，false 用生产环境。
  ///
-  /// 换网络时只改这一行，地址不要带结尾斜杠。
-  static const String devHostBaseUrl = 'http://10.43.47.1:8081';
+  /// 打生产包前必须改成 false；release 构建若仍为 true 会在启动时直接报错。
+  static const bool useDevConfig = true;

-  /// 本机后端地址：通过 `adb reverse tcp:8081 tcp:8081` 映射到开发机，
-  /// 探测可达时 App 直连本机服务；不可达时回落到公网地址。
-  static const String lanBaseUrl = 'http://127.0.0.1:8081';
-
-  /// 公网地址（远程/移动网络访问时使用）。
-  static const String publicBaseUrl = 'http://39.162.50.99:8081';
-
-  static const String _overrideBaseUrl = String.fromEnvironment('API_BASE_URL');
+  /// 当前选中的环境地址。
+  static String get baseUrl =>
+      useDevConfig ? DevConfig.baseUrl : ProdConfig.baseUrl;

+  /// 调试面板手改的地址（见 `ServerEndpoint`）；为空表示用上面的环境地址。
  static String _runtimeBaseUrl = '';

+  /// 启动期异步准备（iOS 无线数据权限弹窗），目录请求前等待它。
  static Future<void>? _ready;

-  /// 启动地址探测完成信号；默认已完成，避免影响既有测试与调用方。
+  /// 启动准备完成信号；默认已完成，避免影响既有测试与调用方。
  static Future<void> get ready => _ready ?? Future<void>.value();
  static set ready(Future<void> value) => _ready = value;

-  static const Duration _probeTimeout = Duration(seconds: 2);
-  static const List<String> _probeCandidates = [
-    lanBaseUrl,
-    devHostBaseUrl,
-    if (devHostBaseUrl != publicBaseUrl) publicBaseUrl,
-  ];
+  static const Duration requestTimeout = Duration(seconds: 8);

-  /// Build-time server URL supplied through `--dart-define=API_BASE_URL`.
-  static String get compiledBaseUrl => _overrideBaseUrl;
+  /// 实际使用的服务地址：运行时手改优先，否则用环境开关选中的地址。
+  static String get apiBaseUrl =>
+      _runtimeBaseUrl.isNotEmpty ? _runtimeBaseUrl : baseUrl;

-  /// Existing platform-aware fallback used when no runtime or build override exists.
-  static String get defaultBaseUrl => _defaultBaseUrl;
-
-  /// Effective server URL, including the debug-only runtime override.
-  static String get apiBaseUrl => _runtimeBaseUrl.isNotEmpty
-      ? _runtimeBaseUrl
-      : (compiledBaseUrl.isNotEmpty ? compiledBaseUrl : defaultBaseUrl);
-
-  static final String _defaultBaseUrl = _runsOnDevMachine
-      ? lanBaseUrl
-      : devHostBaseUrl;
-
-  /// 模拟器、桌面端与开发机同机，环回地址可用；iOS 真机不满足。
-  /// Android 没有等价的探测方式，统一按真机处理（模拟器用
-  /// `--dart-define=API_BASE_URL=http://10.0.2.2:8081` 覆盖）。
-  static final bool _runsOnDevMachine =
-      kIsWeb ||
-      defaultTargetPlatform == TargetPlatform.macOS ||
-      defaultTargetPlatform == TargetPlatform.windows ||
-      defaultTargetPlatform == TargetPlatform.linux ||
-      (defaultTargetPlatform == TargetPlatform.iOS &&
-          Platform.environment.containsKey('SIMULATOR_DEVICE_NAME'));
-
-  /// Applies an already normalized runtime URL. Passing null clears it.
+  /// 应用一个已经规范化的运行时地址；传 null 表示清除。
  static void applyRuntimeBaseUrl(String? value) {
    _runtimeBaseUrl = value ?? '';
  }

-  /// Clears the in-memory runtime override, mainly for tests and restarts.
+  /// 清除运行时地址，主要给测试与重启流程用。
  static void clearRuntimeBaseUrl() {
    _runtimeBaseUrl = '';
  }

-  static const Duration requestTimeout = Duration(seconds: 8);
-
-  /// 按环回、开发机、公网顺序探测，写入首个返回 200 的地址。
-  ///
-  /// 全部不可达时使用平台默认地址，真机保留开发机地址，避免退回公网。
-  static Future<void> probeAndApplyBaseUrl({
-    Future<bool> Function(String baseUrl)? probe,
-    String? fallbackBaseUrl,
-
-    /// 编译期地址测试注入；未传时读取 `API_BASE_URL`。
-    String? compiledOverride,
-  }) async {
-    final compiled = compiledOverride ?? compiledBaseUrl;
-    if (compiled.isNotEmpty) {
-      if (_runtimeBaseUrl.isEmpty) applyRuntimeBaseUrl(compiled);
-      return;
-    }
-    final candidates = <String>[
-      if (_runtimeBaseUrl.isNotEmpty) _runtimeBaseUrl,
-      for (final candidate in _probeCandidates)
-        if (candidate != _runtimeBaseUrl) candidate,
-    ];
-    final results = await Future.wait([
-      for (final candidate in candidates)
-        probe == null
-            ? _probeBaseUrl(candidate)
-            : _runInjectedProbe(candidate, probe),
-    ]);
-    for (var index = 0; index < candidates.length; index++) {
-      final candidate = candidates[index];
-      final result = results[index];
-      if (kDebugMode) {
-        final status = result.ok
-            ? 'ok'
-            : 'fail(${result.reason ?? 'request failed'})';
-        debugPrint('[probe] $candidate -> $status');
-      }
-      if (result.ok) {
-        applyRuntimeBaseUrl(candidate);
-        return;
-      }
-    }
-    applyRuntimeBaseUrl(fallbackBaseUrl ?? defaultBaseUrl);
-  }
-
-  static Future<_ProbeResult> _runInjectedProbe(
-    String baseUrl,
-    Future<bool> Function(String baseUrl) probe,
-  ) async {
-    try {
-      return _ProbeResult(ok: await probe(baseUrl));
-    } catch (error) {
-      return _ProbeResult(ok: false, reason: error.toString());
-    }
-  }
-
-  static Future<_ProbeResult> _probeBaseUrl(String baseUrl) async {
-    final client = HttpClient()..connectionTimeout = _probeTimeout;
-    try {
-      return await _requestCategories(
-        client,
-        Uri.parse('$baseUrl/app/categories'),
-      ).timeout(_probeTimeout);
-    } catch (error) {
-      return _ProbeResult(ok: false, reason: error.toString());
-    } finally {
-      client.close(force: true);
-    }
-  }
-
-  static Future<_ProbeResult> _requestCategories(
-    HttpClient client,
-    Uri uri,
-  ) async {
-    final request = await client.getUrl(uri);
-    final response = await request.close();
-    await response.drain<void>();
-    final ok = response.statusCode == 200;
-    return _ProbeResult(
-      ok: ok,
-      reason: ok ? null : 'HTTP ${response.statusCode}',
-    );
-  }
-
  /// 后端返回的是相对路径（/files/...），这里补上服务地址。
  static String mediaUrl(String path) {
    if (path.isEmpty) return '';
@@ -167,10 +53,3 @@ class AppConfig {
    return '$apiBaseUrl$path';
  }
 }
-
-class _ProbeResult {
-  const _ProbeResult({required this.ok, this.reason});
-
-  final bool ok;
-  final String? reason;
-}
@@ -0,0 +1,10 @@
+// Author: fruit.com.cn
+
+/// 开发环境配置。
+///
+/// 本机联调用：模拟器与桌面端可直接用回环地址，但 iOS/Android 真机必须用
+/// 开发机的局域网 IP（真机上的 127.0.0.1 指向手机自己）。地址不要带结尾斜杠。
+abstract final class DevConfig {
+  /// 开发机后端地址（Mac 当前 Wi-Fi 地址，换网络后需要同步修改）。
+  static const String baseUrl = 'http://192.168.31.243:8081';
+}
@@ -0,0 +1,9 @@
+// Author: fruit.com.cn
+
+/// 生产环境配置。
+///
+/// 发版前确认这里的 [baseUrl]，地址不要带结尾斜杠。
+abstract final class ProdConfig {
+  /// 生产后端地址。
+  static const String baseUrl = 'http://39.162.50.99:8081';
+}
@@ -22,16 +22,9 @@ abstract final class ServerEndpoint {
    return value.replaceFirst(RegExp(r'/+$'), '');
  }

-  /// Resolves runtime > dart-define > default using normalized valid values.
-  static String resolve({
-    required String? stored,
-    required String compiled,
-    required String fallback,
-  }) {
-    return normalize(stored) ??
-        normalize(compiled) ??
-        normalize(fallback) ??
-        fallback;
+  /// 运行时手改优先，其次构建期默认地址；两者都必须先通过规范校验。
+  static String resolve({required String? stored, required String fallback}) {
+    return normalize(stored) ?? normalize(fallback) ?? fallback;
  }

  /// Loads the persisted override before the app creates its ApiClient.
@@ -46,11 +39,7 @@ abstract final class ServerEndpoint {
      final prefs = preferences ?? SharedPreferencesAsync();
      final stored = await prefs.getString(preferenceKey);
      AppConfig.applyRuntimeBaseUrl(
-        resolve(
-          stored: stored,
-          compiled: AppConfig.compiledBaseUrl,
-          fallback: AppConfig.defaultBaseUrl,
-        ),
+        resolve(stored: stored, fallback: AppConfig.baseUrl),
      );
    } catch (_) {
      AppConfig.clearRuntimeBaseUrl();
@@ -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(
-      id: (json['id'] ?? '').toString(),
-      name: json['name'] as String? ?? '',
-    );
+    final locales = localeMap(json['locales']);
+    final name = json['name'] as String? ?? locales['zh'] ?? '';
+    return ContentCategory(id: (json['id'] ?? '').toString(), name: name, locales: locales);
+  }
+
+  /// 按界面语言取名称。缺对应语言时回落到中文。
+  String localizedName(String languageCode) {
+    return localizedText(languageCode, name, locales);
  }
 }
@@ -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']),
    );
  }
 }
@@ -75,8 +97,17 @@ class Drama {
    required this.title,
    required this.synopsis,
    required this.posterUrl,
+    this.coverLandscape = '',
    this.episodes = const [],
+    this.titleLocales = const {},
+    this.synopsisLocales = const {},
+    this.tag = '',
+    this.tagLocales = const {},
+    this.tagCode = '',
+    this.tagColor = '',
    this.category = '',
+    this.categoryLocales = const {},
+    this.types = const [],
    this.genre = '',
    this.totalEpisodes = 0,
    this.freeEpisodes = 0,
@@ -94,9 +125,22 @@ 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;
+
+  /// 标签语义码（如 `NEW_ARRIVAL`）。文案会随语言变，语义判断只认这个码。
+  final String tagCode;
+  final String tagColor;
  final String posterUrl;
+
+  /// 横版封面，用于继续观看横幅等横向展示位；为空时回退竖版 `posterUrl`。
+  final String coverLandscape;
  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 +171,28 @@ 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? ?? '',
-      synopsis: json['synopsis'] as String? ?? '',
+      title: text.title,
+      synopsis: text.synopsis,
+      titleLocales: text.titleLocales,
+      synopsisLocales: text.synopsisLocales,
+      tag: text.tag,
+      tagLocales: text.tagLocales,
+      tagCode: (json['tagCode'] as String? ?? '').trim(),
+      tagColor: json['tagColor'] as String? ?? '',
      posterUrl: json['cover'] as String? ?? '',
+      coverLandscape: json['coverLandscape'] as String? ?? '',
      episodes: preview is Map<String, dynamic>
          ? [Episode.fromJson(preview)]
          : const [],
-      category: json['category'] as String? ?? '',
-      genre: json['genre'] as String? ?? '',
+      category: text.category,
+      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 +205,23 @@ 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? ?? '',
-      synopsis: json['synopsis'] as String? ?? '',
+      title: text.title,
+      synopsis: text.synopsis,
+      titleLocales: text.titleLocales,
+      synopsisLocales: text.synopsisLocales,
+      tag: text.tag,
+      tagLocales: text.tagLocales,
+      tagCode: (json['tagCode'] as String? ?? '').trim(),
+      tagColor: json['tagColor'] as String? ?? '',
      posterUrl: json['cover'] as String? ?? '',
-      category: json['category'] as String? ?? '',
-      genre: json['genre'] as String? ?? '',
+      coverLandscape: json['coverLandscape'] as String? ?? '',
+      category: text.category,
+      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 +239,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 +278,90 @@ 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 : '';
+}
@@ -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,
+    );
+  }
+}
@@ -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? ?? '';
+}
@@ -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;
 }
@@ -0,0 +1,20 @@
+// 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;
+}
@@ -16,6 +16,7 @@ class PlayTicket {
    this.qualities = const [],
    this.tracks = const [],
    this.thumbnailsUrl,
+    this.posterUrl,
    this.likeCount,
    this.commentCount,
  });
@@ -46,6 +47,7 @@ class PlayTicket {
  /// 各档签名地址。AUTO 是主列表，点选其它档位时换成对应地址。
  final List<PlayQualityTrack> tracks;
  final String? thumbnailsUrl;
+  final String? posterUrl;
  final int? likeCount;
  final int? commentCount;

@@ -70,6 +72,7 @@ class PlayTicket {
          .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']),
@@ -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);
+}
@@ -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,7 +14,9 @@ class WatchProgress {
    required this.position,
    required this.duration,
    this.dramaTitle,
+    this.titleLocales = const {},
    this.dramaCover,
+    this.dramaCoverLandscape,
    this.episodeNumber,
    this.totalEpisodes,
    this.finished = false,
@@ -25,7 +28,11 @@ class WatchProgress {
  final String dramaId;
  final String episodeId;
  final String? dramaTitle;
+  final Map<String, String> titleLocales;
  final String? dramaCover;
+
+  /// 横版封面，用于继续观看横幅等横向位；为空时回退 [dramaCover]。
+  final String? dramaCoverLandscape;
  final int? episodeNumber;
  final int? totalEpisodes;
  final Duration position;
@@ -45,12 +52,19 @@ 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(),
+      dramaCoverLandscape: json['dramaCoverLandscape']?.toString(),
      episodeNumber: json['episodeNumber'] == null
          ? null
          : jsonToInt(json['episodeNumber']),
@@ -72,7 +86,9 @@ class WatchProgress {
    'dramaId': dramaId,
    'episodeId': episodeId,
    if (dramaTitle != null) 'dramaTitle': dramaTitle,
+    if (titleLocales.isNotEmpty) 'titleLocales': titleLocales,
    if (dramaCover != null) 'dramaCover': dramaCover,
+    if (dramaCoverLandscape != null) 'dramaCoverLandscape': dramaCoverLandscape,
    if (episodeNumber != null) 'episodeNumber': episodeNumber,
    if (totalEpisodes != null) 'totalEpisodes': totalEpisodes,
    'positionMs': position.inMilliseconds,
@@ -31,9 +31,13 @@ class WatchRecord {
  }

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

  /// 服务端分页封面优先，详情封面作为回退。
@@ -42,6 +46,14 @@ class WatchRecord {
    return pageCover.isNotEmpty ? pageCover : drama?.posterUrl ?? '';
  }

+  /// 横向展示位（继续观看横幅）优先用横版封面，缺省回退竖版。
+  String get displayLandscapeCover {
+    final pageLandscape = progress.dramaCoverLandscape?.trim() ?? '';
+    if (pageLandscape.isNotEmpty) return pageLandscape;
+    final landscape = drama?.coverLandscape.trim() ?? '';
+    return landscape.isNotEmpty ? landscape : displayCover;
+  }
+
  /// 分页接口已带展示字段时无需等待详情加载。
  bool get hasDisplayMetadata =>
      displayTitle.isNotEmpty ||
@@ -4,6 +4,7 @@ import '../models/account_device.dart';
 import '../models/account_export.dart';
 import '../models/account_profile.dart';
 import 'api_client.dart';
+import 'response_decoders.dart';

 /// 个人中心接口：`/app/me*`。
 class AccountApi {
@@ -23,11 +24,9 @@ class AccountApi {

  Future<List<AccountDevice>> devices() async {
    final data = await _client.get('/app/me/devices');
-    if (data is! List) return const [];
-    return [
-      for (final item in data)
-        if (item is Map) AccountDevice.fromJson(item.cast<String, dynamic>()),
-    ];
+    return ResponseDecoders.asMapList(
+      data,
+    ).map(AccountDevice.fromJson).toList();
  }

  Future<AccountExport> export() async {
@@ -47,6 +46,7 @@ class AccountApi {
    await _client.post('/app/me/deactivate/cancel');
  }

+  /// 个人资料允许缺失：后端未返回对象时按空对象解析，页面用默认值兜底。
  Map<String, dynamic> _map(Object? data) =>
-      data is Map ? data.cast<String, dynamic>() : const {};
+      ResponseDecoders.tryMap(data) ?? const {};
 }
@@ -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);
  }
@@ -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);
  }
 }
@@ -56,6 +56,7 @@ class AuthApi {
    required String target,
    required String code,
    required String deviceId,
+    String countryCode = '',
    String platform = '',
    String osVersion = '',
    String appVersion = '',
@@ -66,6 +67,7 @@ class AuthApi {
        'targetType': 'PHONE',
        'target': target,
        'code': code,
+        'countryCode': countryCode,
        'deviceId': deviceId,
        'platform': platform,
        'osVersion': osVersion,
@@ -79,6 +81,7 @@ class AuthApi {
    required String email,
    required String password,
    required String deviceId,
+    String countryCode = '',
    String platform = '',
    String osVersion = '',
    String appVersion = '',
@@ -89,7 +92,7 @@ class AuthApi {
        'targetType': 'EMAIL',
        'target': email,
        'password': password,
-        'countryCode': 'ID',
+        'countryCode': countryCode,
        'deviceId': deviceId,
        'platform': platform,
        'osVersion': osVersion,
@@ -134,6 +137,7 @@ class AuthApi {
        'platform': platform,
        'osVersion': osVersion,
      },
+      skipAuthRetry: true,
    );
    return AuthSession.fromJson((data as Map).cast<String, dynamic>());
  }
@@ -1,8 +1,12 @@
+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';
+import 'response_decoders.dart';

 /// 客户端目录接口，对应后端 `/app/**`。
 class CatalogApi {
@@ -11,11 +15,15 @@ class CatalogApi {
  final ApiClient _client;

  Future<HomeFeed> homeFeed() async {
-    return HomeFeed.fromJson(_asMap(await _client.get('/app/home/feed')));
+    return HomeFeed.fromJson(
+      ResponseDecoders.asMap(await _client.get('/app/home/feed')),
+    );
  }

  Future<HomeFeed> discoverFeed() async {
-    return HomeFeed.fromJson(_asMap(await _client.get('/app/discover/feed')));
+    return HomeFeed.fromJson(
+      ResponseDecoders.asMap(await _client.get('/app/discover/feed')),
+    );
  }

  /// 推荐流；types/categoryId 为空表示不过滤，cursor 为上一页末条。
@@ -26,7 +34,7 @@ class CatalogApi {
    int size = 10,
  }) async {
    return FeedPage.fromJson(
-      _asMap(
+      ResponseDecoders.asMap(
        await _client.get(
          '/app/feed',
          query: {
@@ -55,17 +63,93 @@ class CatalogApi {
        'pageSize': '$pageSize',
      },
    );
-    return SearchResult.fromJson(_asMap(data));
+    return SearchResult.fromJson(ResponseDecoders.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(
+      ResponseDecoders.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')),
+      ResponseDecoders.asMap(await _client.get('/app/dramas/$dramaId')),
    );
  }

-  Map<String, dynamic> _asMap(Object? data) {
-    if (data is Map<String, dynamic>) return data;
-    throw const ApiException(-1, '返回数据格式异常');
+  List<ContentCategory> _categories(Object? data) {
+    return ResponseDecoders.asMapList(
+      data,
+    ).map(ContentCategory.fromJson).toList();
  }
 }
@@ -1,21 +1,40 @@
 // Author: fruit.com.cn

 import '../models/content_category.dart';
+import '../models/drama.dart';
+import '../models/page_result.dart';
 import 'api_client.dart';
+import 'response_decoders.dart';

 /// 内容分类接口，对应契约 `GET /app/categories`。
 class CategoryApi {
  const CategoryApi(this._client);

+  static const int dramaPageSize = 20;
+
  final ApiClient _client;

  /// 拉取已启用分类，id 全程按字符串解析。
  Future<List<ContentCategory>> list() async {
    final data = await _client.get('/app/categories');
-    if (data is! List) return const [];
-    return [
-      for (final item in data)
-        if (item is Map<String, dynamic>) ContentCategory.fromJson(item),
-    ];
+    return ResponseDecoders.asMapList(
+      data,
+    ).map(ContentCategory.fromJson).toList();
+  }
+
+  /// 分类下已上线短剧，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);
  }
 }