chore(merge): 将 develop 同步到 release/v1.0.0

# Conflicts:
#	lib/core/config/app_config.dart
#	lib/main.dart
#	test/config/server_endpoint_test.dart

android/app/src/main/AndroidManifest.xml

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

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

@@ -36,6 +36,9 @@ class MainActivity : FlutterActivity() {
     private var imeInset = 0
 
     override fun onCreate(savedInstanceState: Bundle?) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            splashScreen.setOnExitAnimationListener { screen -> screen.remove() }
+        }
         super.onCreate(savedInstanceState)
         window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
     }

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

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

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

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

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

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

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

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

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

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

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

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

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

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

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

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

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

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

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

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

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

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

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

@@ -20,3 +20,12 @@
 - loadMore 与 refresh 通过请求代次隔离，旧响应不得覆盖新列表。
 - 空页立即停止加载；`loaded >= total` 后不再请求。
 - 不新增依赖、不提交现有 `pubspec.lock`，不启停服务、不操作真机。
+
+## 2026-10-22 范围修订
+
+- 分页协议和 Controller 分页状态保持不改。
+- 观看历史优先使用后端 `dramaTitle/dramaCover/episodeNumber`，只有标题为空时才预取详情。
+- 标题为空且详情也未返回标题时，用本地化“第 N 集”兜底。
+- 有标题的条目点击播放时再按需加载详情，不在列表加载阶段产生 N+1。
+- 使用当前真实后端校验第 1/2 页请求参数、total 与 list；若运行实例仍忽略分页，
+  只在 PROGRESS 记录证据，不做前端全量兜底。

docs/plans/PROGRESS.md

@@ -628,8 +628,7 @@ UTF-8 解码、3000 字符截断、非 JSON、二进制字节数、DioException
 - 收藏页、观看历史页接入滚动触底加载、下拉刷新、通用分页 footer、总数展示。
 - 观看卡片优先展示分页接口的 `dramaTitle/dramaCover/episodeNumber`；
   标题为空时显示本地化“第 N 集”，封面缺失时显示占位图标。
-- API 兼容滚动发布窗口：后端仍返回旧 List 时包装为 `PageResult(total=list.length)`；
-  服务端新 PageResult 正常解析。
+- API 严格解析服务端 PageResult；旧 List 不做客户端全量包装，由后端部署新契约解决。
 - MineLogic 改用分页首屏 `list`，不再调用旧 limit 接口。
 
 ### 门禁
@@ -656,3 +655,667 @@ $ flutter test --no-pub
 观看标题/集号/封面展示及空标题兜底均通过；全量静态分析零告警，632 项测试全过。
 
 未新增依赖、未启停服务、未操作真机；现有 `pubspec.lock` 改动未提交。
+
+### 范围修订：观看标题优先与按需详情
+
+- 分页协议、Repository 与 Controller 分页状态保持不变。
+- `_hydrate` 只对 `dramaTitle` 为空的记录补拉详情；后端已有标题时不再请求详情。
+- 有标题的记录点击播放时才调用 `detailForOpen` 按需加载详情，避免列表阶段 N+1。
+- 标题仍为空时使用本地化“第 N 集”，封面缺失继续显示占位。
+- 移除了旧 List 自动包装为 PageResult 的前端全量兜底，避免掩盖后端契约问题。
+
+真实后端分页取证（仅测试账号写入，不启停服务）：
+
+```text
+GET /app/watch/recent?pageIndex=1&pageSize=1
+{"shape":"list","length":2,"dramaIds":["1","5"]}
+GET /app/watch/recent?pageIndex=2&pageSize=1
+{"shape":"list","length":2,"dramaIds":["1","5"]}
+GET /app/favorites?pageIndex=1&pageSize=1
+{"shape":"list","length":2,"dramaIds":["1","5"]}
+GET /app/favorites?pageIndex=2&pageSize=1
+{"shape":"list","length":2,"dramaIds":["1","5"]}
+```
+
+解读：当前 8081 运行实例仍是旧包，返回 List 且忽略 pageIndex/pageSize；第 1/2 页
+均返回相同两条数据。客户端不做全量兜底；live smoke 检测到旧 List 后明确标记 skipped，
+等待后端新包部署后再执行分页真实联调。
+
+门禁：
+
+```text
+$ flutter test --no-pub test/integration/live_watch_flow_test.dart test/library/library_api_test.dart test/watch/watch_api_test.dart test/watch/watch_records_controller_test.dart test/watch/watch_records_page_test.dart
+00:02 +22 ~1: All tests passed!
+
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test --no-pub
+00:52 +630 ~1: All tests passed!
+```
+
+解读：有 dramaTitle 时不触发详情请求、点击时才加载详情、空标题兜底、
+第 2 页追加去重和 hasMore 行为均通过；全量分析零告警，630 项通过、1 项旧服务
+能力探测跳过。`pubspec.lock` 既有改动未提交。
+
+## 2026-10-22 收藏卡片简介
+
+- 分支：`feature/favorite-card-synopsis`
+- 基线：`develop` / `origin/develop` = `9093700`
+- 计划：`docs/plans/2026-10-22-favorite-card-synopsis.md`
+
+### 实现
+
+- `_FavoriteCard` 在标题/标签下方条件渲染 `drama.synopsis.trim()`。
+- 简介最多 2 行、`TextOverflow.ellipsis`，使用 `AppColors.muted`、12 号字和
+  `1.15` 行高，由 `Flexible` 占据剩余空间，保持封面与卡片原高度。
+- 简介为空或纯空白时不创建文本节点，继续使用原 Spacer，不占高度。
+- 未改接口、后端和收藏分页逻辑。
+
+### 门禁
+
+```text
+$ flutter test --no-pub test/library/favorites_page_test.dart
+00:01 +7: All tests passed!
+
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test --no-pub
+00:51 +631 ~1: All tests passed!
+```
+
+解读：有简介时文本最多 2 行并省略，空简介不渲染且卡片高度与正常卡片一致；
+全量静态分析零告警，631 项通过、1 项运行中旧后端能力探测跳过。
+`pubspec.lock` 既有改动未提交。
+
+## 2026-10-22 ReelShort 客户端深色视觉改造
+
+- 分支：`feature/dark-theme-client`
+- 基线：开发前已有约 43 个未提交视觉文件，本次在原改动上继续收敛，未推倒重来。
+- 计划：`docs/plans/2026-10-22-dark-theme-client.md`
+
+### 颜色与主题
+
+- `AppTheme.dark()` 成为默认且唯一主题，系统状态栏/导航栏图标统一浅色。
+- 色板统一为背景 `#0B1020`、卡片 `#151B2E`、浮层 `#1C2436`、
+  divider `#0FFFFFFF`、主色 `#FF6B2C`、辅助链接色 `#22D3EE`。
+- 主/次/禁用文字分别使用白色 92% / 64% / 38%。
+- 卡片/按钮/输入框/标签圆角统一为 12/10/10/6，卡片阴影关闭。
+- 页面和组件内的 `Colors.*`、`Color(0x...)` 已全部映射到 `AppColors`
+  语义 token；剩余原始色值只在 `app_colors.dart` 中定义。
+- 导航、玻璃面板、播放器遮罩、加载轨道、渐变、边框和阴影均改为深色语义。
+- 修正全局输入装饰 padding 导致账户性别下拉溢出，保持原布局宽度。
+
+### 验证命令与原始结果
+
+```text
+$ git checkout -- pubspec.lock
+$ git status --short --branch
+## feature/dark-theme-client
+
+$ rg -n -P "Color\(0x|(?<!App)Colors\." lib | rg -v '^lib/core/theme/'
+(no output)
+
+$ rg -n "SystemUiOverlayStyle\.dark" lib
+(no output)
+```
+
+解读：pubspec.lock 漂移已还原；页面/组件层不再直接写颜色，所有状态栏均使用浅色图标。
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+```text
+$ flutter test --no-pub
+00:51 +644: All tests passed!
+```
+
+```text
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+    2,058ms
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态分析零告警，644 项测试全部通过，debug APK 构建成功；测试与构建后再次确认
+`pubspec.lock` 无改动，未启停服务、未操作真机。
+
+## 2026-10-22 客户端底部导航改为首页/推荐/追剧/我的
+
+- 分支：`feature/client-bottom-nav-4tabs`
+- 基线：`develop` / `origin/develop` = `ec3cb8f`
+- 计划：`docs/plans/2026-10-22-client-bottom-nav-4tabs.md`
+- 实现提交：`91e869d feat(nav): 底部导航改为首页推荐追剧我的`
+
+### 问题
+
+根导航仍为首页/剧场/创作/我的，底栏选中态使用品牌橙。追剧若通过新路由打开，
+会叠加第二层底栏并产生返回栈，不符合参考图和单根导航交互。
+
+### 改动
+
+- 新增 `AppRootTab` 统一四个 tab 的顺序、key、图标和 l10n 标签。
+- `AppBottomNav` 改为纯黑底、白色选中、`#8A8A8E` 未选中，图标 24、文字 11，
+  保留 SafeArea 与轻震动。
+- 首页 `IndexedStack` 第三槽直接使用 `FavoritesContent`，不再 push 收藏路由。
+  追剧保留顶部标题区、隐藏返回按钮，只有一个根底栏，不创建嵌套 Scaffold。
+- `FavoritesPage` 保留独立 Scaffold 和返回行为，继续供“我的”入口使用。
+- 推荐、追剧、我的三个根页面统一调用 `HomeLogic.select` 切换，不进入返回栈。
+- 创作页保留，`mine-creator-center` 入口保留；创作不再出现在根底栏。
+- 中文使用“追剧”，英文使用 `Home / Recommend / Following / My`，
+  印尼语使用 `Beranda / Rekomendasi / Daftar Tonton / Saya`。
+- `FavoritesContent` 内置顶部 SafeArea，避免嵌入首页后被状态栏遮挡。
+
+### 门禁命令与原始输出
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+```text
+$ flutter test --no-pub
+04:38 +644: All tests passed!
+```
+
+导航测试覆盖：四个 tab 数量与顺序、纯白/灰色状态、点击追剧进入
+`FavoritesContent`、仅一个 `AppBottomNav`、追剧内部无嵌套 Scaffold、
+`Navigator.canPop == false`、创作不再出现在底栏且我的入口保留。
+
+解读：静态分析零告警，644 项测试全部通过；追剧与首页/推荐/我的均在同一根页面
+内切换，无叠加导航或返回栈。`pubspec.lock` 未提交，未启动或停止服务，未操作真机。
+
+## 2026-10-22 根导航布局规格对齐
+
+- 分支：`feature/client-bottom-nav-layout`
+- 基线：`develop` / `origin/develop` = `667fdc5`
+- 实现提交：`81787dc style(nav): 对齐四 Tab 底栏布局规格`
+
+### 改动
+
+- 新增 `AppRootBottomNav` 作为首页、推荐、追剧、我的唯一根导航入口，
+  三个 Shell 页面不再各自拼装 item。
+- 四列使用 `Expanded` 等分，图标在上、文字在下，间距 4。
+- 内容高度 56，另由 `SafeArea` 增加底部安全区；图标 26、文字 11、
+  `letterSpacing = 0`，选中 `w600`、未选中 `w400`。
+- 背景纯黑，取消顶部边框；选中 `#FFFFFF`，未选中 `#8E8E93`。
+- 首页、推荐、书签、人像继续使用各自的选中实心/未选中描边图标。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-bottom-nav...
+No issues found! (ran in 5.2s)
+```
+
+```text
+$ flutter test
+04:43 +645: All tests passed!
+```
+
+解读：四等分、56 内容高度、安全区、26 图标、4 间距、精确色值和无分割线
+均有测试覆盖；645 项测试全部通过。`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 首页改为三列探索网格
+
+- 分支：`feature/home-grid-layout`
+- 基线：`develop` / `origin/develop` = `6dea9d4`
+- 实现提交：`dd96792 feat(home): 首页改为三列探索网格`
+
+### 布局与数据
+
+- 首页按参考图改为纯黑探索页：搜索框、皇冠、礼物入口、一级分类、
+  二级标签与三列封面网格。
+- `HomeFeedController` 继续使用 10 条游标分页；支持下拉刷新、触底加载、
+  空态与失败重试，没有全量拉取。
+- 一级固定项为精选/新剧/分类/榜单；古装/社群仅在 `/app/categories`
+  名称匹配时显示。新剧/分类/榜单复用现有页面。
+- 二级标签按分类与题材可用性显示，筛选按钮复用 `FilterPage`。
+- 卡片封面 5:6、圆角 8、间距 8；包含真实热剧/新剧/漫剧角标、
+  播放量、最多两行标题与最多两个题材标签。
+- `Drama` 增加 `dramaType` 和可选 `createdAt`；卡片未下发上架时间时
+  从 Snowflake id 解析，不使用假数据。
+- 原 `PlayerPage(homeMode: true)` 保留并迁至推荐 tab，播放器文件与测试未删除。
+- 首页顶部中性色、卡片与描边 token 已沉淀到 `AppColors/AppDimens`，
+  后续 P14 复用。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-bottom-nav...
+No issues found! (ran in 2.7s)
+```
+
+```text
+$ flutter test
+02:32 +651: All tests passed!
+```
+
+解读：三列网格、分类顺序、动态入口隐藏、角标、卡片信息、分页大小、
+下一页追加和卡片进入播放器均有测试覆盖。`home_view.dart` 为 478 行，
+其余新增组件均低于 500 行。`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 「我的」页视觉风格统一
+
+- 分支：`feature/mine-visual-style`
+- 基线：`develop` / `origin/develop` = `47bf645`
+- 实现提交：`83129ac feat(mine): 统一我的页深色视觉风格`
+
+### Token 与改动
+
+- 复用 P11 的 `appBackground/contentCard/contentSurface/contentBorder`，
+  新增 `textPrimary/mineCardRadius/mineRowHeight/minePageTitle/mineSectionTitle`。
+- 页面底色改为纯黑，移除「我的」页的旧深蓝渐变；页头白色标题 21/w700。
+- 头像、三宫格、金币卡、会员卡、菜单统一为深灰 16 圆角、1px 极淡描边，
+  无阴影、无渐变、无发光。
+- 主文字/昵称/金额使用 `#FFFFFF`，次级说明和 chevron 使用 `#8E8E93`。
+- 三宫格等宽，入口图标 24 线性；菜单行高 52、标题 15，分割线只存在行间。
+- 橙色仅保留在充值、加入 VIP 等主操作；头像与菜单图标不再使用粉色/橙色装饰。
+- 区块顺序、全部入口、跳转与交互逻辑保持不变。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-bottom-nav...
+No issues found!
+```
+
+```text
+$ flutter test
+00:56 +651: All tests passed!
+```
+
+解读：背景、卡片 token、圆角/描边、无渐变阴影、三宫格等宽、菜单 52 行高、
+入口保留和收藏页跳转均有测试覆盖。`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 推荐页沉浸流 / 剧单 / 全部短剧
+
+- 分支：`feature/recommend-section-feed`、`feature/recommend-tab-feed-correction`
+- 修正基线：`develop` / `origin/develop` = `af6b9bb`
+
+固定顶部三 tab 为推荐 / 剧单 / 全部短剧，右侧保留搜索。推荐 tab 直接内嵌
+`PlayerPage(homeMode: true, embedded: true)`，支持一屏一剧、上下滑切换、
+收藏/点赞/选集/简介/进度条等现有播放器能力；播放器内部频道标题条关闭，
+只保留视频与浮层。剧单 tab 包含本週爆款推薦、本週精選新劇、古裝神劇大賞
+三条横滑卡片，数据分别本地按播放量、上架时间和古装分类/题材排序过滤。
+全部短剧提供四行可用筛选 chips、三列首页同款卡片和 20 条触底分页；
+无后端字段的本地/地区/字幕/配音筛选项不展示。根底栏始终保留四个入口。
+
+```text
+$ flutter analyze
+Analyzing reelshort-recommend-correction...
+No issues found! (ran in 3.2s)
+
+$ flutter test
+01:03 +644: All tests passed!
+```
+
+解读：沉浸式推荐播放器、剧单三分区横滑、四行筛选、三列网格、tab 状态保留、
+搜索、卡片播放、播放器路由覆盖/恢复均有测试覆盖；所有生效文件低于 500 行。
+`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 追剧页三 tab 与双列网格
+
+- 分支：`feature/following-tabs-grid`
+- 基线：`develop` / `origin/develop` = `73380ee`
+
+### 页面与数据
+
+- 根导航追剧槽位改为内嵌 `FollowingPage`，不再 push 收藏路由，也不叠加
+  第二层底部导航。
+- 页面提供追剧 / 播放历史 / 预约三个子 tab，使用 `IndexedStack` 保留各自
+  滚动位置；切换 tab 会退出编辑态。
+- 追剧复用 `FavoriteController`，显示“第 N 集 / 共 M 集”，支持下拉刷新、
+  触底分页、加载/错误/无更多状态。
+- 播放历史复用 `WatchRecordsController`，优先使用分页接口的
+  `dramaTitle/dramaCover/episodeNumber`，仅在标题缺失时补取详情；卡片展示
+  已看集数与可用进度条，同样支持刷新和分页。
+- 双列网格使用共享卡片：3:4 封面、播放量胶囊、两行标题、副信息与编辑态
+  减号。删除前二次确认，最后一条移除后自动退出编辑态。
+- 预约没有独立分页数据源，本轮保留真实空态；未登录沿用 `AuthGatePanel`。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-bottom-nav...
+No issues found! (ran in 1.9s)
+```
+
+```text
+$ flutter test
+01:12 +643: All tests passed!
+```
+
+解读：三 tab、双列网格、后端历史元数据直出、编辑删除确认、最后一条自动
+退出编辑、未登录与空态均有测试覆盖；`following_page.dart` 低于 500 行。
+`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 「我的」页布局重排与迷你播放器
+
+- 分支：`feature/mine-layout-redesign`
+- 基线：`develop` / `origin/develop` = `5aa8170`
+- 实现提交：`cbc6d80 feat(mine): 重排我的页并新增迷你播放器`
+
+### 页面与入口
+
+- 用户区改为 56 圆形头像、20/w700 昵称与 13 灰色 UID；UID 支持复制，
+  未登录显示 Visitor 与登录按钮，已登录显示编辑按钮。
+- VIP 改为金色渐变通栏卡，品牌文案走 l10n，右侧开通按钮复用现有 VIP 页。
+- 删除收藏/历史/下载三宫格；单列菜单固定为钱包、离线缓存、播放历史、
+  观看偏好、联系客服、语言、设置，行高 56、图标 22、仅行间显示分割线。
+- 收藏由底部追剧 tab 承载；历史、下载、钱包、偏好、客服、语言、设置均
+  复用现有页面。我的作品、创作者中心与通知保留在登录后的编辑操作面板，
+  设置页中的通知入口继续可用。
+- 我的页 token 收敛到 `AppColors/AppDimens`：背景纯黑、卡片 `#16161A`、
+  16 圆角、极淡描边、金色渐变仅用于 VIP。
+- 左下角迷你播放器为 96x132，直接使用观看历史首条数据，展示封面、剧名和
+  集号；无记录或关闭后不占位，点击按记录集号进入全屏播放器。
+- 删除三宫格对应的 `localViewer/watchlist` 废弃 l10n key 与旧组件代码。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-mine-redesign...
+No issues found! (ran in 2.1s)
+```
+
+```text
+$ flutter test
+01:01 +647: All tests passed!
+```
+
+解读：用户区、UID、登录/编辑、VIP、7 项菜单顺序与跳转、旧入口可达性、
+迷你播放器显隐/关闭/开播及无数据不渲染均有测试覆盖。`mine_view.dart`
+与新增子组件均低于 500 行；`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 全局移除两侧悬浮元素
+
+- 分支：`feature/remove-floating-overlays`
+- 基线：`develop` / `origin/develop` = `5cead7c`
+
+### 改动
+
+- 保留首页顶部礼物入口的 `home-wallet-badge` 红色余额角标。
+- 删除「我的」页 `MineMiniPlayer` 文件、渲染分支及最近观看开播逻辑。
+- 删除仅为迷你播放器新增的 `mineMini*` 尺寸 token；没有新增专属 l10n key。
+- 首页、推荐、剧单、全部短剧和追剧页均不渲染两侧游戏/活动悬浮球、
+  悬浮关闭按钮或迷你播放器。
+- 卡片角标、播放量、标题、标签和顶部钱包红标保持不变。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-home-floating...
+No issues found! (ran in 2.5s)
+```
+
+```text
+$ flutter test
+01:32 +647: All tests passed!
+```
+
+解读：登录且钱包快照存在时钱包红标仍显示；首页四个 tab、推荐三个子 tab、
+追剧页和我的页均断言不存在两侧悬浮组件。`pubspec.lock` 未提交，
+未操作真机。
+
+## 2026-10-22 首页与短剧列表视觉字号对齐
+
+- 分支：`feature/visual-type-scale`
+- 基线：`develop` / `origin/develop` = `d03dcf1`
+
+### Token 与组件
+
+- 新增 `textTertiary = #9E9E9E`，以及搜索、页签、筛选 chip、分区标题、
+  卡片标题/播放量/标签/角标、封面比例和网格间距的公共 token。
+- 搜索框统一为高 40、圆角 8、placeholder 13；一级分类 16，选中
+  白字 w700，未选中 `#9E9E9E` w400；二级标签 13 并采用参考图选中/未选中
+  底色。
+- 三列首页网格与全部短剧网格统一左右边距 14、列间距 6、行间距 18；
+  封面 5:6、圆角 6。
+- 首页、剧单横滑、追剧双列卡片统一标题 15/w500/1.3、播放量 11 白字、
+  标签 11/高 18/左右 6，封面到标题 8、标题到标签 6。
+- 剧单分区标题 17/w700，副标题 11 `#8E8E93`，更多 12 `#8E8E93`；
+  分区间距保持 24。
+- 全部短剧筛选 chip 统一高 30、圆角 15、字号 13；我的页标题 17，
+  追剧顶部页签 16。
+
+### 门禁命令与原始输出
+
+```text
+$ flutter analyze
+Analyzing reelshort-visual-type...
+No issues found! (ran in 1.8s)
+```
+
+```text
+$ flutter test
+00:57 +648: All tests passed!
+```
+
+解读：首页搜索/页签/二级标签、三类卡片字体与标签、5:6 封面、网格间距、
+筛选 chip、我的标题和追剧双列 320 宽度适配均有测试覆盖。目标组件均低于
+500 行；`pubspec.lock` 未提交，未操作真机。
+
+## 2026-10-22 首页布局对齐修正
+
+- 一级分类未选 18/w400、选中 20/w700；二级 chips 间距 10、左右 8、15/w600，并以稳定 AnimatedContainer 切换。
+- 首页内容区改为横向 PageView：点击与滑动共用 PageController，各 tab 保留纵向滚动位置。
+- PageController 与各 tab ScrollController 改为字段直接初始化，修复热重载后的 LateInitializationError。
+- 四类卡片去底板/描边，封面统一 3:4、8 圆角、行距 10、封底标题间距 6；状态角标为右上角紧凑异形丝带。
+- 标题下方恢复左对齐题材文字，使用 `|` 分隔、灰色小字，与封面状态角标保持独立。
+- 首页搜索栏到一级、一级到二级、二级到网格间距为 8/8/10；非精选 tab 直接以 10 衔接网格。
+- 搜索框右侧皇冠与礼物使用 28 图片图标，缺图时回退原彩色 Icon；透明热区、间距和角标不变。
+- 皇冠/礼物 144×144 透明 PNG 已归档到 `assets/icon/`，组件路径与资源注册一致。
+- 两张图标已按统一 104/144 内容高重新归一化，28×28 渲染时视觉高度一致。
+- 第二轮素材按 100/144 内容高更新，入口改为 30×30、间距 6，礼物角标继续对齐右上角。
+- 播放量贴封面右下角（底 2、右 6），火焰图标 11 + 12/w400 纯文字，间距 4，并保留极淡底部渐变。
+- 修复二级 chip 运行时颜色误用 `const TextStyle` 的编译错误，并校正相关测试 Finder 类型。
+- 全部短剧的地区、字幕、配音筛选 UI 已占位；以下接口待补：地区、字幕/配音筛选数据。
+
+## 2026-10-22 短剧列表刷新体验优化
+
+- 公共下拉刷新统一为白指示器、40 displacement、Bouncing + AlwaysScrollable，并在下拉期间屏蔽内容点击与滚动条。
+- 首页移除父级 feed 监听，网格、剧单和全部短剧改为局部监听，刷新时保留旧数据及原滚动位置。
+- 剧单、全部短剧、追剧沿用相同刷新策略；首帧加载与刷新指示器分离。
+- 按当前流程未执行 analyze/test。
+
+## 2026-10-22 ChangeNotifier 监听生命周期排查
+
+- 全仓核对手动 add/remove；首页、推荐和追剧改为内容区单实例 ListenableBuilder，避免重复订阅。
+- 播放器进度监听改为具名回调，在切换、重建会话和 dispose 时解绑；评论输入弹窗补 controller 更换迁移。
+- `_onFeedChanged` 已无源码调用链，报错来源为热重载前注册的旧 tear-off；需完全关闭 App 后冷启动。
+- 按当前流程未执行 analyze/test。
+
+## 2026-10-22 二级标签筛选按钮右对齐
+
+- 三横线热区由 44 宽改为 26×26，消除 44 宽居中盒造成的视觉右边距偏移。
+- 标签滚动区与按钮间距改为 6，按钮右边缘固定对齐页面 14 边距。
+- 补充按钮尺寸与屏幕右边距断言；按当前流程未执行 analyze/test。
+
+## 2026-10-22 首页导航图标调整
+
+- `AppRootTab.home` 未选中改为 `theaters_outlined`，选中改为 `theaters`。
+- 其余三个根导航图标、26 尺寸及白/灰颜色规则保持不变；测试断言同步。
+- 按当前流程未执行 analyze/test。
+
+## 2026-10-22 首页圆形胶片盘图标
+
+- `AppRootTab` 新增可选 `assetPath`，首页使用 `assets/icon/film_reel.png`。
+- 共享导航通过 `ColorFiltered + Image.asset` 按选中态着色，尺寸保持 26，缺图回退胶片 Material 图标。
+- 推荐、追剧、我的图标不变；素材与测试断言同步，按当前流程未执行 analyze/test。
+
+## 2026-10-22 首页选中态实心摄影机
+
+- `AppRootTab` 新增 `selectedAssetPath`，首页选中使用 `film_reel_filled.png`，未选中使用描边版。
+- 共享导航保持 `ColorFiltered(srcIn)` 与 26×26，缺图按选中态回退实心/描边胶片图标。
+- 推荐、追剧、我的不变；测试断言同步，按当前流程未执行 analyze/test。
+
+## 2026-10-22 底部导航图标与文字加大
+
+- 公共 token 调整为图标 30、文字 13、图标文字间距 5、内容高度 62。
+- 图片首页图标同步使用 30×30；SafeArea 仍在内容区外独立追加，四等分布局不变。
+- 尺寸测试断言同步，按当前流程未执行 analyze/test。
+
+## 2026-10-22 推荐页沉浸式布局对齐
+
+- 推荐/剧单/全部短剧顶部改为视频内居中浮层，17 字号、无下划线，搜索固定右侧 14。
+- 右侧保留收藏/点赞/选集，白色 32 图标、28 间距；评论、分享入口已从该浮层移除。
+- 底部信息重构为标题、真实热度、剧名、题材/集数、可展开简介与渐变观看全集按钮。
+- 新增三语“观看全集”文案；按当前流程未执行 analyze/test。
+- 榜单行支持可选排名：有名次显示 `TOPn·热播榜`，无名次回退“热播榜”；热度值改用 `w` 格式。
+- 题材改为空格分隔，集数固定右侧单行；右侧操作栏改为距屏幕边缘 8，底部位置不变。
+
+## 2026-10-22 推荐页底部信息二次修正
+
+- 按最新反馈移除整行榜单与热度胶囊，信息顺序收敛为标题、剧名、标签、简介、观看全集。
+- 剧名 19/w600，箭头 20 白色并紧邻剧名；标签行改为 13/w600 亮灰内联布局。
+- 简介「展开/收起」沿用现有三语文案；进度条热区恢复 24 并接入拖动自动清屏与预览卡片。
+- 拖动仅控制视频浮层内容，顶部导航与根底栏保持常驻。
+- 进度条固定中心并动画到 6 高，命中高度 32，时间气泡限制在左右 12；end/cancel/pointer 兜底均恢复拖动前状态。
+- 修复 `scrubCancelRequest` 误置于 `initState` 的编译错误，并清理推荐页未使用变量；`flutter analyze` 无问题。
+- 观看全集按钮相对进度条上移 8，间距调整为 20；按钮改为屏幕宽度 70% 左对齐，`flutter analyze` 无问题。
+
+## 2026-10-22 进度条按下与拖动彻底修复
+
+- Slider 不再在 `onChangeStart` 清屏；首次真实移动后才进入 scrub，轨道 2/6、thumb 6/8。
+- 推荐流拖动使用独立 opaque 手势与 pointer 兜底，end/cancel 同时恢复浮层和轨道。
+- 推荐浮层改为 AnimatedOpacity + IgnorePointer，进度条节点始终留在树中；scrub setState 均加 mounted 守卫。
+- `flutter test test/player/seek_scrub_visibility_test.dart`：6 项测试全部通过。
+
+## 2026-10-22 推荐页播放跳转修正
+
+- 标题、剧名行和观看全集统一通过 `playDramaFromCatalog` 打开非 `homeMode` 逐集播放页。
+- 仅含集数的剧集标题不再显示在标题上方，集数只保留下方进度文案。
+- `flutter analyze`：No issues found。
+
+## 2026-10-22 推荐页横向切换
+
+- 推荐、剧单、全部短剧改为共享 PageController 的横向 PageView，点击与滑动均驱动同一选中态。
+- 三页使用 AutomaticKeepAliveClientMixin 保留视频、滚动位置和筛选状态；顶部导航固定在外层。
+- `flutter analyze`：No issues found。
+
+## 2026-10-22 全部短剧布局重排
+
+- 四行筛选统一 28 高、8 行距、24 项目间距；选中 chip 改为 `#4A1E1E`、白字 13/w600、圆角 14。
+- 最热/最新改为纯文字选中态，三横线筛选固定在右端；网格改为左右 12、列距 6、行距 12。
+- 第三行筛选完整展示，卡片继续复用首页组件；`flutter analyze`：No issues found。
+- 筛选项字号提升到 15、圆角 15；筛选区移出滚动容器并固定吸顶，下拉刷新仅作用于网格。
+- 四行首项文字统一到同一 x；行高 30、行距 6、项目距 12，第 4 行保持弹性空白后固定筛选图标。
+- 按最新截图改为 16sp、32 高、10 行距、16 项距；选中态为 `#21090E` 底配 `#FF4D6A` 粉字。
+- 第 4 行复用选中胶囊样式，右侧改为 44×44 圆形深灰按钮和 22 三横线图标；`flutter analyze` 无问题。
+- 筛选行距收紧到 6、项距 10，chip 左右 padding 12；四行均可横向回弹滑动。
+- 第 4 行仅最热/最新在滚动区内，44 圆形筛选按钮固定在滚动区外；`flutter analyze` 无问题。
+- 四行统一复用 `_filterRow` 构建，筛选区仅保留一层左右 12 padding。
+- 新增量化测试断言四行首项 x 均为 12、相邻 chip 间距均为 10；`flutter analyze` 无问题。
+- 修复横向 viewport 对短内容居中：滚动内容最小宽度撑满视口后由 Row.start 排列。
+- `flutter test test/recommend/all_dramas_filter_alignment_test.dart`：1 项测试通过。
+
+## 2026-10-22 首页二级标签移除筛选按钮
+
+- 首页二级标签行改为纯横向滑动，右侧三横线按钮不渲染也不占位。
+- 删除不再使用的筛选回调、尺寸 token、颜色和 CustomPainter；全部短剧页筛选按钮保持不变。
+- `flutter analyze`：No issues found。
+- 按后续更正恢复首页透明三横线按钮（26、无背景、`#7A7A7E`），删除全部短剧第 4 行圆形按钮及回调链路。
+
+## 2026-10-22 追剧页三列改造
+
+- 追剧页移除预约 tab，改为追剧/播放历史双页横向切换，并保留各自滚动位置。
+- 追剧与历史统一三列卡片，新增固定加号卡片，历史进度与编辑删除能力保留。
+- 按最新口径调整列距 6、行距 12、封面圆角 6；`flutter analyze`：No issues found。
+
+## 2026-10-22 播放历史单列列表
+
+- 追剧保持三列网格，播放历史改为左封面右信息的单列列表，行距 16。
+- 历史卡片补充 96×128 封面、观看进度、已看百分比、继续观看和编辑删除。
+- 追剧加号卡片移到全部追剧卡片之后，空列表时仍在左上角。
+- 加号改为 `#8E8E93`、28 尺寸、1.5 描边，卡片底色与圆角不变。
+- 刷新、分页与各页独立滚动位置保持；`flutter analyze`：No issues found。
+
+## 2026-10-22 追剧页切换与编辑按钮修正
+
+- 追剧与历史页增加 keep-alive，tab 与编辑态改用局部 ValueNotifier 更新，切换不再重建整个页面。
+- 编辑图标调整为 20、`#B0B0B0`，热区 40×40，保持右侧 14 边距和垂直居中。
+- 列表刷新期间保留已有数据与各页滚动位置；`flutter analyze`：No issues found。
+
+## 2026-10-22 播放历史继续观看按钮微调
+
+- 继续观看改为无边框、无底色的纯文字按钮，默认 `#B0B0B0`、12/w500，按压态使用品牌色。
+- 保持 28 高点击热区和右侧零间距；未执行测试或 analyze。
+
+## 2026-10-22 我的页渐变与图标网格
+
+- 页面背景改为暖黑三段纵向渐变，用户区与 VIP 卡布局保持不变。
+- 行式入口替换为 4 列图标网格，7 个原入口按顺序保留，第 8 格为空占位。
+- 网格使用 14 边距、半透明深灰底、圆角 12 和仅内部 1px 分隔线；`flutter analyze`：No issues found。
+- 渐变增强为 `#3A1B0E`/`#1A0C07`/黑色并叠加顶部品牌橙径向光晕，同时移除页面级「我的」标题栏。
+- 7 个宫格图标分别使用金币金、天蓝、薄荷绿、粉红、紫色、青色和冷灰；`flutter analyze`：No issues found。
+
+## 2026-10-22 我的页补充内容
+
+- VIP 与宫格之间新增继续观看横向列表、追剧/观看记录/金币统计面板，继续观看最多 10 条。
+- 宫格后新增常见问题与关于我们入口；关于页版本暂用与 pubspec 同步的常量占位。
+- 继续观看全部入口可切到追剧页播放历史 tab；`flutter analyze`：No issues found。
+- 用户区昵称与 UID 收紧为 4 间距，昵称列相对头像垂直居中；UID 12、复制图标 14。
+- UID 行改用 GestureDetector 并锁定 16 高，昵称与 UID 间距 2、昵称行高 1.15，避免 Material 热区撑高；`flutter analyze`：No issues found。
+
+## 2026-10-22 推荐剧单渐变背景
+
+- 仅为推荐页「剧单」子页增加暖黑三段渐变和品牌橙径向光晕，推荐视频与全部短剧背景不变。
+- 渐变复用「我的」页色值，光晕使用 `#26FF6B2C`；分区与卡片样式保持原样；`flutter analyze`：No issues found。
+
+## 2026-10-22 全站深色视觉统一
+
+- 全局 token 改为纯黑页面、`#16161A` 卡片、`#1C1C1E` 描边/分割线与 B0/8E 文本层级，旧深蓝页面渐变替换为暖黑渐变。
+- 普通二级页标题栏改为透明、白色标题与返回图标；统一卡片 12 圆角、1px 描边和无阴影策略。
+- 覆盖新剧、筛选、榜单、预约、收藏、观看历史、下载、设置、钱包、VIP、通知、详情、登录、关于；播放器沉浸区保持纯黑。
+- `flutter analyze`：No issues found。
+
+## 2026-10-22 统一下拉与加载指示器
+
+- 下拉刷新统一为 40×40、60% 黑底圆角指示器内嵌 20 白色加载圈，不再显示任何状态文字。
+- 网络分页与本地分页 footer 统一仅显示白色加载圈，无更多状态完全隐藏；通知页补触底自动加载。
+- 移除不再使用的刷新提示与无更多文案；`flutter analyze`：No issues found。
+
+## 2026-10-22 首页热播榜重做
+
+- 首页榜单 tab 改为独立领奖台 + 单列排行布局，不再复用三列网格。
+- 前三名按 2/1/3 排列，冠军放大并上移；第 4 名起使用大号描边名次与横向信息行。
+- 榜单沿用现有播放热度排序、分页和播放逻辑；`flutter analyze`：No issues found。
+
+## 2026-10-22 播放器双击点赞与飘心
+
+- 沉浸式播放器改用 onTapUp + 280ms Timer 判定双击，双击取消单击，长按左右倍速与中间更多保持不变。
+- 双击和右侧心形共用点赞方法，成功后控制器通知并点亮红色实心心形，失败由 controller 回滚并使用 Toast。
+- 飘心层使用独立 IgnorePointer Stack，动画完成后自动移除；`flutter analyze`：No issues found。
+- `flutter test test/player/double_tap_like_test.dart`：2 项测试全部通过。
+- 移除视频表面点击识别器，双击后增加 300ms 暂停防护；飘心收敛为 3~4 颗、20~26、±18、90~120dp、600~700ms。
+- 双击窗口延长至 320ms，单击 Timer 使用点击序号校验，双击后保留 350ms 播放切换保护。
+- `double_tap_like_test.dart` 覆盖 120/250/300ms 双击与 500ms 单击恢复：2 项测试全部通过。
+
+## 2026-10-22 统一二级搜索页
+
+- 首页与推荐/剧单/全部短剧搜索入口统一 push SearchPage，不再切换推荐 tab 聚焦。
+- 搜索页提供返回、自动聚焦输入框与取消，复用 `/app/search` 逻辑和首页三列卡片。
+- 清理旧的 searchRequest/focusSearch/syncSearch 参数；`flutter analyze`：No issues found。
+- 搜索页结果改为独立两列卡片，左右 14、列距 12、行距 16，并移除 HomeFeedCard 复用。
+- 搜索结果支持下拉刷新：保留旧结果按当前关键词重取第一页，空关键词直接回弹且不改变焦点。
+
+## 2026-10-22 App 图标与开屏更新
+
+- Launcher/Android 12 启动背景统一纯黑，自适应图标背景改为品牌橙。
+- Android/iOS 图标与启动资源已重新生成；应用内开屏固定 splash_logo，宽 200 等比居中。
+- `flutter analyze`：No issues found。
+- 移除 Flutter 内 `_startupSplash` 与 `startup-splash`，只保留系统原生开屏；最新斜体字标素材已重新生成。

ios/Runner/AppDelegate.swift

@@ -2,6 +2,8 @@ import Flutter
 import UIKit
 import AVFoundation
 
+private let thumbnailHTTPHeaderFieldsKey = "AVURLAssetHTTPHeaderFieldsKey"
+
 private final class ThumbnailResponseGate {
   private let lock = NSLock()
   private var completed = false
@@ -29,7 +31,7 @@ final class RunnerFlutterViewController: FlutterViewController {
 
   override func viewDidLoad() {
     super.viewDidLoad()
-    view.backgroundColor = UIColor(red: 16.0 / 255.0, green: 12.0 / 255.0, blue: 10.0 / 255.0, alpha: 1)
+    view.backgroundColor = .black
   }
 }
 
@@ -104,7 +106,7 @@ final class RunnerFlutterViewController: FlutterViewController {
 
       let options: [String: Any]? = headers.isEmpty
         ? nil
-        : [AVURLAssetHTTPHeaderFieldsKey: headers]
+        : [thumbnailHTTPHeaderFieldsKey: headers]
       let asset = AVURLAsset(url: assetUrl, options: options)
       let generator = AVAssetImageGenerator(asset: asset)
       generator.appliesPreferredTrackTransform = true

ios/Runner/Base.lproj/LaunchScreen.storyboard

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

ios/Runner/Info.plist

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

lib/app.dart

@@ -53,13 +53,15 @@ import 'core/theme/app_colors.dart';
 import 'l10n/app_localizations.dart';
 import 'pages/home/home_view.dart';
 
-/// 全局系统栏样式：浅暖导航栏、关闭 Android 对比遮罩。
-final SystemUiOverlayStyle appSystemOverlayStyle = SystemUiOverlayStyle.dark
+/// 全局系统栏样式：深色底 + 浅色图标，关闭 Android 对比遮罩。
+final SystemUiOverlayStyle appSystemOverlayStyle = SystemUiOverlayStyle.light
     .copyWith(
-      statusBarColor: Colors.transparent,
+      statusBarColor: AppColors.transparent,
+      statusBarIconBrightness: Brightness.light,
+      statusBarBrightness: Brightness.dark,
       systemNavigationBarColor: AppColors.ink,
-      systemNavigationBarDividerColor: Colors.transparent,
-      systemNavigationBarIconBrightness: Brightness.dark,
+      systemNavigationBarDividerColor: AppColors.transparent,
+      systemNavigationBarIconBrightness: Brightness.light,
       systemNavigationBarContrastEnforced: false,
     );
 
@@ -280,9 +282,9 @@ class _LumaDramaAppState extends State<LumaDramaApp> {
           localeResolutionCallback: (deviceLocale, _) =>
               resolveAppLocale(deviceLocale),
           debugShowCheckedModeBanner: false,
-          themeMode: ThemeMode.light,
-          theme: AppTheme.light(),
-          darkTheme: AppTheme.light(),
+          themeMode: ThemeMode.dark,
+          theme: AppTheme.dark(),
+          darkTheme: AppTheme.dark(),
           builder: (context, child) => AnnotatedRegion<SystemUiOverlayStyle>(
             value: appSystemOverlayStyle,
             child: child ?? const SizedBox.shrink(),

lib/core/config/app_config.dart

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

lib/core/data/models/drama.dart

@@ -86,6 +86,8 @@ class Drama {
     this.favoriteCount,
     this.commentCount,
     this.language = '',
+    this.dramaType = '',
+    this.createdAt,
     this.detailLoaded = false,
   });
 
@@ -109,6 +111,12 @@ class Drama {
   /// 卡片语种（如 zh-CN / id），用于剧场语言筛选。
   final String language;
 
+  /// 内容类型：ANIME 漫剧，LIVE 真人剧。
+  final String dramaType;
+
+  /// 上架时间；卡片接口未直接下发时可由 Snowflake id 估算。
+  final DateTime? createdAt;
+
   /// 详情接口是否已经取过完整剧集列表。
   /// 列表卡片只带一集可播预览，需要完整剧集时再进详情。
   final bool detailLoaded;
@@ -137,6 +145,8 @@ class Drama {
       favoriteCount: _optionalInt(json['favoriteCount']),
       commentCount: _optionalInt(json['commentCount']),
       language: json['language'] as String? ?? '',
+      dramaType: json['dramaType'] as String? ?? '',
+      createdAt: DateTime.tryParse(json['createdAt']?.toString() ?? ''),
     );
   }
 
@@ -157,6 +167,8 @@ class Drama {
       favoriteCount: _optionalInt(json['favoriteCount']),
       commentCount: _optionalInt(json['commentCount']),
       language: json['language'] as String? ?? '',
+      dramaType: json['dramaType'] as String? ?? '',
+      createdAt: DateTime.tryParse(json['createdAt']?.toString() ?? ''),
       detailLoaded: true,
       episodes: (json['episodes'] as List? ?? const [])
           .whereType<Map<String, dynamic>>()

lib/core/data/models/page_result.dart

@@ -3,6 +3,8 @@
 import 'json_numbers.dart';
 
 /// 服务端标准分页响应 `{total, list}`。
+///
+/// 兼容旧版「data 直接是数组」的响应：按数组长度作为 total，避免列表空白。
 class PageResult<T> {
   const PageResult({this.total = 0, this.list = const []});
 
@@ -14,10 +16,32 @@ class PageResult<T> {
     Map<String, dynamic> json,
     T Function(Map<String, dynamic>) parseItem,
   ) {
-    final items = (json['list'] as List? ?? const [])
-        .whereType<Map<String, dynamic>>()
-        .map(parseItem)
-        .toList(growable: false);
+    final items = _parseItemMaps(json['list']).map(parseItem).toList(
+      growable: false,
+    );
     return PageResult(total: jsonToInt(json['total']), list: items);
   }
+
+  /// 兼容分页 Map 与旧版纯 List；其它类型视为空页。
+  factory PageResult.parse(
+    Object? data,
+    T Function(Map<String, dynamic>) parseItem,
+  ) {
+    if (data is Map) {
+      return PageResult.fromJson(Map<String, dynamic>.from(data), parseItem);
+    }
+    if (data is List) {
+      final items = _parseItemMaps(data).map(parseItem).toList(growable: false);
+      return PageResult(total: items.length, list: items);
+    }
+    return PageResult<T>();
+  }
+}
+
+List<Map<String, dynamic>> _parseItemMaps(Object? raw) {
+  if (raw is! List) return const [];
+  return [
+    for (final item in raw)
+      if (item is Map) Map<String, dynamic>.from(item),
+  ];
 }

lib/core/data/models/play_ticket.dart

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

lib/core/data/models/watch_progress.dart

@@ -18,6 +18,7 @@ class WatchProgress {
     this.totalEpisodes,
     this.finished = false,
     this.playCount = 0,
+    this.viewCount,
     this.updatedAt,
   });
 
@@ -31,6 +32,9 @@ class WatchProgress {
   final Duration duration;
   final bool finished;
   final int playCount;
+
+  /// 短剧热度。历史列表没下发时为空，不能拿用户自己的 playCount 冒充。
+  final int? viewCount;
   final DateTime? updatedAt;
 
   bool get hasPosition => position > Duration.zero;
@@ -57,6 +61,9 @@ class WatchProgress {
       duration: Duration(milliseconds: jsonToInt(json['durationMs'])),
       finished: json['finished'] == true,
       playCount: jsonToInt(json['playCount']),
+      viewCount: json['viewCount'] == null
+          ? null
+          : jsonToInt(json['viewCount']),
       updatedAt: DateTime.tryParse(json['updatedAt'] as String? ?? ''),
     );
   }
@@ -72,6 +79,7 @@ class WatchProgress {
     'durationMs': duration.inMilliseconds,
     'finished': finished,
     'playCount': playCount,
+    if (viewCount != null) 'viewCount': viewCount,
     if (updatedAt != null) 'updatedAt': updatedAt!.toIso8601String(),
   };
 }

lib/core/data/remote/api_client.dart

@@ -148,7 +148,8 @@ class ApiClient {
             skipAuthRetry: skipAuthRetry,
           );
         }
-        onUnauthorized?.call();
+        final token = accessTokenReader?.call();
+        if (token == null || token.isEmpty) onUnauthorized?.call();
         throw ApiException(401, cause.message ?? '登录已过期');
       }
       if (cause is ApiException) {

lib/core/data/remote/auth_api.dart

@@ -33,6 +33,7 @@ class AuthApi {
     required String code,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -43,6 +44,7 @@ class AuthApi {
         'code': code,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -55,6 +57,7 @@ class AuthApi {
     required String code,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -65,6 +68,7 @@ class AuthApi {
         'code': code,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -76,6 +80,7 @@ class AuthApi {
     required String password,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -87,6 +92,7 @@ class AuthApi {
         'countryCode': 'ID',
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
@@ -98,6 +104,7 @@ class AuthApi {
     required String password,
     required String deviceId,
     String platform = '',
+    String osVersion = '',
     String appVersion = '',
   }) async {
     final data = await _client.post(
@@ -108,18 +115,25 @@ class AuthApi {
         'password': password,
         'deviceId': deviceId,
         'platform': platform,
+        'osVersion': osVersion,
         'appVersion': appVersion,
       },
     );
     return AuthSession.fromJson((data as Map).cast<String, dynamic>());
   }
 
-  Future<AuthSession> refresh(String refreshToken) async {
+  Future<AuthSession> refresh(
+    String refreshToken, {
+    String platform = '',
+    String osVersion = '',
+  }) async {
     final data = await _client.post(
       '/app/auth/refresh',
-      body: {'refreshToken': refreshToken},
-      // 刷新请求本身不带旧令牌重试，失败就是失败
-      skipAuthRetry: true,
+      body: {
+        'refreshToken': refreshToken,
+        'platform': platform,
+        'osVersion': osVersion,
+      },
     );
     return AuthSession.fromJson((data as Map).cast<String, dynamic>());
   }

lib/core/data/remote/library_api.dart

@@ -29,20 +29,16 @@ class LibraryApi {
       '/app/favorites',
       query: {'pageIndex': '$pageIndex', 'pageSize': '$pageSize'},
     );
-    if (data is Map<String, dynamic>) {
-      return PageResult.fromJson(data, Drama.fromCardJson);
-    }
-    if (data is List) {
-      final list = data
-          .whereType<Map<String, dynamic>>()
-          .map(Drama.fromCardJson)
-          .toList(growable: false);
-      return PageResult(total: list.length, list: list);
-    }
-    return const PageResult();
+    // 线上可能仍返回 List；分页壳与纯数组都要能渲染。
+    return PageResult.parse(data, Drama.fromCardJson);
   }
 
   Future<void> removeFavorite(String dramaId) async {
     await _client.delete('/app/favorites/$dramaId');
   }
+
+  /// 一次取消多部短剧，请求体为 dramaIds 数组。
+  Future<void> removeFavorites(List<String> dramaIds) async {
+    await _client.post('/app/favorites/remove', body: {'dramaIds': dramaIds});
+  }
 }

lib/core/data/remote/watch_api.dart

@@ -40,7 +40,7 @@ class WatchApi {
     return data is Map<String, dynamic> ? WatchProgress.fromJson(data) : null;
   }
 
-  /// 最近观看分页（服务端已按更新时间倒序）。
+  /// 最近观看分页：`pageIndex`/`pageSize`，解包 `PageResult`。
   Future<PageResult<WatchProgress>> recent({
     int pageIndex = 1,
     int pageSize = 20,
@@ -49,17 +49,13 @@ class WatchApi {
       '/app/watch/recent',
       query: {'pageIndex': '$pageIndex', 'pageSize': '$pageSize'},
     );
-    if (data is Map<String, dynamic>) {
-      return PageResult.fromJson(data, WatchProgress.fromJson);
+    if (data is! Map) {
+      return const PageResult();
     }
-    if (data is List) {
-      final list = data
-          .whereType<Map<String, dynamic>>()
-          .map(WatchProgress.fromJson)
-          .toList(growable: false);
-      return PageResult(total: list.length, list: list);
-    }
-    return const PageResult();
+    return PageResult.fromJson(
+      Map<String, dynamic>.from(data),
+      WatchProgress.fromJson,
+    );
   }
 
   /// 删除某部剧的观看记录（记录页清单条用）。

lib/core/data/repositories/favorite_repository.dart

@@ -13,6 +13,9 @@ abstract interface class FavoriteRepository {
   Future<PageResult<Drama>> page({int pageIndex = 1, int pageSize = 20});
 
   Future<void> remove(String dramaId);
+
+  /// 一次取消多部短剧。
+  Future<void> removeMany(List<String> dramaIds);
 }
 
 class HttpFavoriteRepository implements FavoriteRepository {
@@ -36,6 +39,10 @@ class HttpFavoriteRepository implements FavoriteRepository {
 
   @override
   Future<void> remove(String dramaId) => _api.removeFavorite(dramaId);
+
+  @override
+  Future<void> removeMany(List<String> dramaIds) =>
+      _api.removeFavorites(dramaIds);
 }
 
 /// 内存实现：单测与 widget 测试注入用。
@@ -51,6 +58,7 @@ class InMemoryFavoriteRepository implements FavoriteRepository {
   bool failRemove = false;
   int toggleCalls = 0;
   int pageCalls = 0;
+  int removeManyCalls = 0;
 
   @override
   Future<bool> toggle(String dramaId) async {
@@ -80,4 +88,11 @@ class InMemoryFavoriteRepository implements FavoriteRepository {
     if (failRemove) throw StateError('favorite unavailable');
     _saved.remove(dramaId);
   }
+
+  @override
+  Future<void> removeMany(List<String> dramaIds) async {
+    removeManyCalls += 1;
+    if (failRemove) throw StateError('favorite unavailable');
+    _saved.removeAll(dramaIds);
+  }
 }

lib/core/data/services/auth_controller.dart

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

lib/core/data/services/favorite_controller.dart

@@ -161,6 +161,37 @@ class FavoriteController extends ChangeNotifier {
     }
   }
 
+  /// 一次取消多部收藏。失败时整批回滚。
+  Future<bool> removeMany(List<String> dramaIds) async {
+    final ids = dramaIds.toSet();
+    if (ids.isEmpty) return true;
+    final previousCards = cards;
+    final previousTotal = total;
+    final previousHasMore = hasMore;
+    final removed = cards.where((drama) => ids.contains(drama.id)).toList();
+    if (removed.isEmpty) return true;
+    cards = cards.where((drama) => !ids.contains(drama.id)).toList();
+    for (final id in ids) {
+      _saved.remove(id);
+    }
+    total = total > removed.length ? total - removed.length : 0;
+    hasMore = cards.length < total;
+    notify();
+    try {
+      await _repository.removeMany(dramaIds);
+      return true;
+    } catch (_) {
+      cards = previousCards;
+      total = previousTotal;
+      hasMore = previousHasMore;
+      for (final drama in removed) {
+        _saved.add(drama.id);
+      }
+      notify();
+      return false;
+    }
+  }
+
   /// 取消收藏（"我的"页列表里删除某条）。
   Future<bool> remove(String dramaId) async {
     final index = cards.indexWhere((drama) => drama.id == dramaId);

lib/core/data/services/home_feed_controller.dart

@@ -18,7 +18,7 @@ class HomeFeedController extends ChangeNotifier {
            channel: _ChannelFeedState(),
        };
 
-  static const int pageSize = 10;
+  static const int pageSize = 20;
   static const Duration defaultRequestTimeout = Duration(seconds: 10);
 
   final CatalogRepository _repository;

lib/core/data/services/playback_session.dart

@@ -5,6 +5,10 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import '../models/drama.dart';
 import '../models/player_port.dart';
+import 'video_player_port.dart';
+
+/// 新纹理第一帧常是黑的，旧画面只盖住这一小段。
+const Duration _qualityHandoffHold = Duration(milliseconds: 200);
 
 typedef PlayerFactory = PlayerPort Function(Episode episode);
 typedef PlayerPreparation =
@@ -66,6 +70,7 @@ class PlaybackSession extends ChangeNotifier {
   final Set<_PlayerSlot> _live = {};
   _PlayerSlot? _active;
   _PlayerSlot? _next;
+  _PlayerSlot? _handoff;
   Future<void> _operations = Future<void>.value();
   Future<void> _preloadTask = Future<void>.value();
   int _generation = 0;
@@ -127,6 +132,15 @@ class PlaybackSession extends ChangeNotifier {
     return null;
   }
 
+  /// 清晰度切换时盖住黑帧的旧播放器。只在仍由会话持有时交给界面。
+  PlayerPort? handoffAt(int index) {
+    final slot = _handoff;
+    if (_closed || slot == null || slot.retiring || slot.index != index) {
+      return null;
+    }
+    return slot.player;
+  }
+
   /// 队列重排后把当前仍在播放的 slot 映射到新索引，不重新创建播放器。
   void remapCurrentIndex(int index, {int? preloadIndex}) {
     if (_closed || index < 0 || index >= episodes.length) return;
@@ -184,9 +198,10 @@ class PlaybackSession extends ChangeNotifier {
   Future<void> _retire(_PlayerSlot? slot) async {
     if (slot == null || !_live.contains(slot)) return;
     slot.retiring = true;
-    final cleared = _active == slot || _next == slot;
+    final cleared = _active == slot || _next == slot || _handoff == slot;
     if (_active == slot) _active = null;
     if (_next == slot) _next = null;
+    if (_handoff == slot) _handoff = null;
     if (cleared) _notify();
     await waitForFrame?.call();
     await slot.ready;
@@ -235,6 +250,7 @@ class PlaybackSession extends ChangeNotifier {
     _PlayerSlot? target;
     await _enqueue(() async {
       if (_closed || request != _generation) return;
+      await _retire(_handoff);
       final old = _active;
       if (old != null &&
           old.index == index &&
@@ -272,6 +288,108 @@ class PlaybackSession extends ChangeNotifier {
     if (!_closed && request == _generation) _schedulePreload();
   }
 
+  /// 后台准备新片源，成功后再替换当前播放器。失败时原播放器保持不动。
+  Future<bool> replaceCurrent() async {
+    if (_closed || !_selected) return false;
+    final index = _currentIndex;
+    if (index < 0 || index >= episodes.length || isLocked) return false;
+    if (!canPlay(episodes[index])) return false;
+    final request = _generation;
+    final slot = await _prepareReplacement(index, request);
+    if (slot == null) {
+      await _resumeActive();
+      return false;
+    }
+    await slot.ready;
+    if (!_replacementReady(slot, request)) {
+      await _dropReplacement(slot);
+      await _resumeActive();
+      return false;
+    }
+    final previous = await _showReplacement(slot, request);
+    if (_active != slot) {
+      await _dropReplacement(slot);
+      return false;
+    }
+    await _enqueue(() => _start(slot, request));
+    await Future<void>.delayed(_qualityHandoffHold);
+    if (previous != null && _handoff == previous && _active == slot) {
+      await _enqueue(() => _retire(previous));
+    }
+    if (!_closed && request == _generation) _schedulePreload();
+    return _active == slot && slot.failure == null;
+  }
+
+  Future<_PlayerSlot?> _prepareReplacement(int index, int request) async {
+    _PlayerSlot? created;
+    await _enqueue(() async {
+      if (_closed || request != _generation || _active == null) return;
+      final warm = _next;
+      _next = null;
+      await _retire(_handoff);
+      await _retire(warm);
+      if (_closed || request != _generation || _active == null) return;
+      try {
+        created = _create(index);
+      } catch (_) {
+        created = null;
+      }
+    });
+    return created;
+  }
+
+  bool _replacementReady(_PlayerSlot slot, int request) {
+    return !_closed &&
+        request == _generation &&
+        _active != null &&
+        slot.failure == null &&
+        slot.prepared;
+  }
+
+  Future<void> _resumeActive() async {
+    final slot = _active;
+    if (slot == null || !_userWantsPlay || _closed) return;
+    await _enqueue(() => _applyPlayback(slot));
+  }
+
+  Future<void> _dropReplacement(_PlayerSlot slot) {
+    return _enqueue(() async {
+      if (_live.contains(slot)) await _retire(slot);
+    });
+  }
+
+  /// 先把已出画的新播放器交到界面上，旧播放器留给调用方稍后释放。
+  Future<_PlayerSlot?> _showReplacement(_PlayerSlot slot, int request) async {
+    _PlayerSlot? previous;
+    var shown = false;
+    await _enqueue(() async {
+      if (!_replacementReady(slot, request)) return;
+      previous = _active;
+      await _catchUp(slot, previous);
+      _handoff = previous;
+      _active = slot;
+      shown = true;
+      if (previous != null) await previous!.player.pause();
+      _notify();
+    });
+    if (!shown || _active != slot) return null;
+    return previous;
+  }
+
+  /// 旧片仍在播，把新片对齐到当前进度，盖住时画面才接得上。
+  Future<void> _catchUp(_PlayerSlot slot, _PlayerSlot? previous) async {
+    final next = slot.player;
+    final current = previous?.player;
+    if (next is! VideoPlayerPort || current is! VideoPlayerPort) return;
+    final position = current.controller.value.position;
+    if (position <= Duration.zero) return;
+    try {
+      await next.seekTo(position);
+    } catch (_) {
+      // 对齐失败仍用准备阶段的进度，不因此放弃切换。
+    }
+  }
+
   Future<void> _start(_PlayerSlot slot, int request) async {
     bool valid() => !_closed && request == _generation && _active == slot;
     if (!valid()) return;
@@ -387,7 +505,7 @@ class PlaybackSession extends ChangeNotifier {
   Future<void> _releasePlayers() {
     _generation++;
     return _enqueue(() async {
-      _active = _next = null;
+      _active = _next = _handoff = null;
       _loading = false;
       _notify();
       for (final slot in _live.toList()) {

lib/core/data/services/sprite_thumbnail_axis.dart

@@ -122,6 +122,8 @@ abstract interface class SpriteThumbnailAxisSource implements Listenable {
   SpriteThumbnailFrame? cachedFrameAt(String? thumbnailsUrl, Duration position);
 
   bool hasAxis(String? thumbnailsUrl);
+
+  Future<void> prepareAt(String? thumbnailsUrl, Duration position);
 }
 
 /// VTT 时间轴、cue 二分与 sprite ui.Image LRU 缓存。
@@ -153,6 +155,7 @@ class SpriteThumbnailAxisService extends ChangeNotifier
   List<String> get spriteCacheKeys => _spriteCache.keys.toList();
 
   /// 播放器就绪时预取当前 cue 与相邻 sprite，拖动帧不触发网络或解码。
+  @override
   Future<void> prepareAt(String? thumbnailsUrl, Duration position) async {
     final url = _normalizeUrl(thumbnailsUrl);
     if (_disposed || url == null) return;

lib/core/data/services/watch_records_controller.dart

@@ -130,6 +130,15 @@ class WatchRecordsController extends ChangeNotifier {
     _notify();
   }
 
+  /// 点击有标题的记录时再按需加载详情，避免列表阶段产生 N+1。
+  Future<Drama?> detailForOpen(String dramaId) async {
+    final cached = _detailCache[dramaId];
+    if (cached != null) return cached;
+    await _loadDetail(dramaId);
+    _notify();
+    return _detailCache[dramaId];
+  }
+
   /// 删除单条记录，先更新 UI，失败按原位置回滚。
   Future<bool> remove(String dramaId) async {
     final index = _recordIndex(dramaId);
@@ -201,11 +210,12 @@ class WatchRecordsController extends ChangeNotifier {
   }
 
   Future<void> _hydrate(List<String> dramaIds) async {
-    for (final id in dramaIds) {
+    final missingTitles = dramaIds.where(_hasMissingTitle).toSet().toList();
+    for (final id in missingTitles) {
       if (_detailCache.containsKey(id)) await _loadDetail(id);
     }
     final queue = [
-      for (final id in dramaIds)
+      for (final id in missingTitles)
         if (!_detailCache.containsKey(id)) id,
     ];
     final workerCount = queue.length < detailConcurrency
@@ -222,9 +232,15 @@ class WatchRecordsController extends ChangeNotifier {
     ]);
   }
 
-  Future<void> _loadDetail(String dramaId) async {
+  bool _hasMissingTitle(String dramaId) {
     final index = _recordIndex(dramaId);
-    if (index < 0) return;
+    if (index < 0) return false;
+    return (records[index].progress.dramaTitle?.trim() ?? '').isEmpty;
+  }
+
+  Future<Drama?> _loadDetail(String dramaId) async {
+    final index = _recordIndex(dramaId);
+    if (index < 0) return null;
     final cached = _detailCache[dramaId];
     if (cached != null) {
       _replaceAt(
@@ -235,14 +251,14 @@ class WatchRecordsController extends ChangeNotifier {
           detailFailed: false,
         ),
       );
-      return;
+      return cached;
     }
     try {
       final detail = await _catalog.fetchDrama(dramaId);
-      if (_disposed) return;
+      if (_disposed) return null;
       _detailCache[dramaId] = detail;
       final current = _recordIndex(dramaId);
-      if (current < 0) return;
+      if (current < 0) return detail;
       _replaceAt(
         current,
         records[current].copyWith(
@@ -251,6 +267,7 @@ class WatchRecordsController extends ChangeNotifier {
           detailFailed: false,
         ),
       );
+      return detail;
     } catch (failure, stackTrace) {
       debugPrint(
         '[WatchRecordsController] detail failed dramaId=$dramaId '
@@ -260,13 +277,14 @@ class WatchRecordsController extends ChangeNotifier {
         stackTrace: stackTrace,
         label: '[WatchRecordsController] detail failed dramaId=$dramaId',
       );
-      if (_disposed) return;
+      if (_disposed) return null;
       final current = _recordIndex(dramaId);
-      if (current < 0) return;
+      if (current < 0) return null;
       _replaceAt(
         current,
         records[current].copyWith(detailLoading: false, detailFailed: true),
       );
+      return null;
     }
   }
 

lib/core/formatting/count_format.dart

@@ -7,3 +7,11 @@ String formatInteractionCount(int count) {
   if (count < 10000) return '$count';
   return '${(count / 10000).toStringAsFixed(1)}万';
 }
+
+/// 播放量展示：以 w 为单位，整数不保留小数，非整数保留一位。
+String formatPlayCount(int count) {
+  if (count < 10000) return '$count';
+  final value = count / 10000;
+  if (value == value.roundToDouble()) return '${value.toInt()}w';
+  return '${value.toStringAsFixed(1)}w';
+}

lib/core/formatting/error_text.dart

@@ -2,6 +2,37 @@
 
 import '../../l10n/app_localizations.dart';
 
+/// 按后端 `ErrorCode` 取当前语言文案。未收录的业务码回退服务端 message。
+String userFacingApiMessage(AppLocalizations l10n, int code, String message) {
+  final localized = _apiMessage(l10n, code);
+  if (localized != null) return localized;
+  if (message.isEmpty) return l10n.authServerError;
+  return message;
+}
+
+/// 已定义错误码。500 用服务繁忙，不展示「系统异常」。
+String? _apiMessage(AppLocalizations l10n, int code) {
+  return switch (code) {
+    400 => l10n.apiErrorBadRequest,
+    401 => l10n.apiErrorUnauthorized,
+    403 => l10n.apiErrorForbidden,
+    404 => l10n.apiErrorNotFound,
+    429 => l10n.apiErrorTooManyRequests,
+    500 => l10n.authServerError,
+    100000 => l10n.apiErrorLoginFailed,
+    100001 => l10n.apiErrorAccountDisabled,
+    100002 => l10n.apiErrorCoinNotEnough,
+    100003 => l10n.apiErrorEpisodeUnavailable,
+    100004 => l10n.apiErrorEpisodeUnlocked,
+    100005 => l10n.apiErrorOrderInvalid,
+    100006 => l10n.apiErrorVipExpired,
+    200001 => l10n.apiErrorDataExists,
+    200002 => l10n.apiErrorDataNotFound,
+    200003 => l10n.apiErrorNotAllowed,
+    _ => null,
+  };
+}
+
 /// logic 里的错误在两种情况下是"哨兵值"：本地网络异常（读不到后端提示语）与
 /// 我们自己包装的失败。这里统一翻译成当前语言的文案；服务端给的中文提示原样展示。
 String errorText(AppLocalizations l10n, String? code, String fallback) {

lib/core/legal/legal_article_view.dart

@@ -0,0 +1,127 @@
+// Author: fruit.com.cn
+
+import 'package:flutter/material.dart';
+import 'package:html/dom.dart' as dom;
+import 'package:html/parser.dart' as html_parser;
+
+import '../theme/app_colors.dart';
+
+const double _bodySize = 16;
+const double _headingSize = 18;
+const double _blockGap = 12;
+const double _lineHeight = 1.7;
+
+const TextStyle _bodyStyle = TextStyle(
+  color: AppColors.textPrimary,
+  fontSize: _bodySize,
+  height: _lineHeight,
+);
+
+/// 把协议页的 HTML 正文画成普通控件。
+class LegalArticleView extends StatelessWidget {
+  const LegalArticleView({super.key, required this.html});
+
+  final String html;
+
+  @override
+  Widget build(BuildContext context) {
+    final fragment = html_parser.parseFragment(html);
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        for (final node in fragment.nodes) _block(node),
+      ],
+    );
+  }
+}
+
+Widget _block(dom.Node node) {
+  if (node is! dom.Element) {
+    return _paragraph(node.text ?? '');
+  }
+  switch (node.localName) {
+    case 'h1':
+    case 'h2':
+    case 'h3':
+      return _heading(node.text);
+    case 'ul':
+    case 'ol':
+      return _list(node);
+    case 'pre':
+      return _paragraph(node.text);
+    case 'blockquote':
+      return _paragraph(node.text);
+    default:
+      return _paragraphSpan(node);
+  }
+}
+
+Widget _heading(String text) {
+  return Padding(
+    padding: const EdgeInsets.only(bottom: _blockGap),
+    child: Text(
+      text.trim(),
+      style: const TextStyle(
+        color: AppColors.textPrimary,
+        fontSize: _headingSize,
+        height: 1.4,
+        fontWeight: FontWeight.w700,
+      ),
+    ),
+  );
+}
+
+Widget _list(dom.Element element) {
+  final items = element.children.where((child) => child.localName == 'li');
+  return Padding(
+    padding: const EdgeInsets.only(bottom: _blockGap),
+    child: Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        for (final item in items)
+          Padding(
+            padding: const EdgeInsets.only(bottom: 4),
+            child: Text('• ${item.text.trim()}', style: _bodyStyle),
+          ),
+      ],
+    ),
+  );
+}
+
+Widget _paragraph(String text) {
+  final value = text.trim();
+  if (value.isEmpty) return const SizedBox.shrink();
+  return Padding(
+    padding: const EdgeInsets.only(bottom: _blockGap),
+    child: Text(value, style: _bodyStyle),
+  );
+}
+
+Widget _paragraphSpan(dom.Element element) {
+  return Padding(
+    padding: const EdgeInsets.only(bottom: _blockGap),
+    child: Text.rich(TextSpan(style: _bodyStyle, children: _inlines(element))),
+  );
+}
+
+List<InlineSpan> _inlines(dom.Node node) {
+  if (node is dom.Text) {
+    return [TextSpan(text: node.text)];
+  }
+  if (node is! dom.Element) return const [];
+  final children = node.nodes.expand(_inlines).toList();
+  switch (node.localName) {
+    case 'strong':
+    case 'b':
+      return [TextSpan(style: const TextStyle(fontWeight: FontWeight.w700), children: children)];
+    case 'em':
+    case 'i':
+      return [TextSpan(style: const TextStyle(fontStyle: FontStyle.italic), children: children)];
+    case 'a':
+      return [TextSpan(style: const TextStyle(color: AppColors.blue), children: children)];
+    case 'br':
+      return const [TextSpan(text: '\n')];
+    default:
+      return children;
+  }
+}

lib/core/legal/legal_html.dart

@@ -0,0 +1,36 @@
+// Author: fruit.com.cn
+
+import 'package:dio/dio.dart';
+
+import '../config/app_config.dart';
+
+final RegExp _articlePattern = RegExp(
+  '<article>([\\s\\S]*)</article>',
+  caseSensitive: false,
+);
+
+/// 从协议页里取出正文。没有 article 时退回整页。
+String legalArticle(String html) {
+  final match = _articlePattern.firstMatch(html);
+  final body = match?.group(1);
+  if (body == null || body.trim().isEmpty) return html;
+  return body.trim();
+}
+
+/// 拉取协议页 HTML。不走业务 JSON 包装。
+Future<String> fetchLegalArticle(String url) async {
+  final dio = Dio(
+    BaseOptions(
+      connectTimeout: AppConfig.requestTimeout,
+      receiveTimeout: AppConfig.requestTimeout,
+      responseType: ResponseType.plain,
+      validateStatus: (code) => code != null && code >= 200 && code < 300,
+    ),
+  );
+  final response = await dio.get<String>(url);
+  final body = response.data;
+  if (body == null || body.trim().isEmpty) {
+    throw StateError('empty legal page');
+  }
+  return legalArticle(body);
+}