chore(client): 归档原型阶段未提交改动（binding/logic/view 分层与各页迭代）

为什么：客户端原型在 14d7bd3 之后又做了一轮（页面分层、发现页、分类滑动、播放器控件等），
一直留在工作区没入库。下一批账号链路要改其中的 app.dart / home_view / player_view / mine_view，
先归档这批既存改动，本批的实际 diff 才说得清边界。

只归档，不改行为：当前工作区 flutter analyze 0 问题、flutter test 148 全过。

lib/core/data/models/drama.dart

@@ -1,19 +1,51 @@
-enum DramaFormat { animated, liveAction }
-
+/// 短剧与剧集，字段与后端 `/app/**` 的下发结构对应。
+///
+/// 封面与播放地址都是后端返回的相对路径（`/files/...`），
+/// 渲染前用 `AppConfig.mediaUrl` 补上服务地址。
 class Episode {
   const Episode({
     required this.id,
     required this.number,
     required this.title,
-    required this.assetPath,
     required this.isFree,
+    this.videoUrl = '',
+    this.durationSec = 0,
+    this.locked = false,
   });
 
   final String id;
   final int number;
   final String title;
-  final String assetPath;
   final bool isFree;
+
+  /// 播放地址：详情接口不下发，由 `/app/episodes/{id}/play` 返回后写入。
+  final String videoUrl;
+  final int durationSec;
+
+  /// 后端判定需要解锁；解锁能力（金币/VIP）在 M3 接入。
+  final bool locked;
+
+  Episode withVideoUrl(String url) => Episode(
+    id: id,
+    number: number,
+    title: title,
+    isFree: isFree,
+    videoUrl: url,
+    durationSec: durationSec,
+    locked: locked,
+  );
+
+  factory Episode.fromJson(Map<String, dynamic> json) {
+    return Episode(
+      id: (json['id'] ?? '').toString(),
+      number: (json['number'] as num?)?.toInt() ?? 0,
+      title: json['title'] as String? ?? '',
+      isFree: json['isFree'] == true,
+      durationSec: (json['durationSec'] as num?)?.toInt() ?? 0,
+      locked: json['locked'] == true,
+      videoUrl: json['playUrl'] as String? ?? '',
+    );
+  }
 }
 
 class Drama {
@@ -21,15 +53,73 @@ class Drama {
     required this.id,
     required this.title,
     required this.synopsis,
-    required this.posterAsset,
-    required this.episodes,
-    this.format = DramaFormat.liveAction,
+    required this.posterUrl,
+    this.episodes = const [],
+    this.category = '',
+    this.genre = '',
+    this.totalEpisodes = 0,
+    this.freeEpisodes = 0,
+    this.isHot = false,
+    this.viewCount = 0,
+    this.detailLoaded = false,
   });
 
   final String id;
   final String title;
   final String synopsis;
-  final String posterAsset;
+  final String posterUrl;
   final List<Episode> episodes;
-  final DramaFormat format;
+  final String category;
+  final String genre;
+  final int totalEpisodes;
+  final int freeEpisodes;
+  final bool isHot;
+  final int viewCount;
+
+  /// 详情接口是否已经取过完整剧集列表。
+  /// 列表卡片只带一集可播预览，需要完整剧集时再进详情。
+  final bool detailLoaded;
+
+  /// 卡片只带一集预览，集数以后端给的总集数为准。
+  int get episodeCount => totalEpisodes > 0 ? totalEpisodes : episodes.length;
+
+  /// 列表卡片：带一集可播预览（首页直接起播），完整剧集进详情再取。
+  factory Drama.fromCardJson(Map<String, dynamic> json) {
+    final preview = json['preview'];
+    return Drama(
+      id: (json['id'] ?? '').toString(),
+      title: json['title'] as String? ?? '',
+      synopsis: json['synopsis'] as String? ?? '',
+      posterUrl: json['cover'] as String? ?? '',
+      episodes: preview is Map<String, dynamic>
+          ? [Episode.fromJson(preview)]
+          : const [],
+      category: json['category'] as String? ?? '',
+      genre: json['genre'] as String? ?? '',
+      totalEpisodes: (json['totalEpisodes'] as num?)?.toInt() ?? 0,
+      isHot: json['isHot'] == true,
+      viewCount: (json['viewCount'] as num?)?.toInt() ?? 0,
+    );
+  }
+
+  /// 详情：带剧集列表。
+  factory Drama.fromDetailJson(Map<String, dynamic> json) {
+    return Drama(
+      id: (json['id'] ?? '').toString(),
+      title: json['title'] as String? ?? '',
+      synopsis: json['synopsis'] as String? ?? '',
+      posterUrl: json['cover'] as String? ?? '',
+      category: json['category'] as String? ?? '',
+      genre: json['genre'] as String? ?? '',
+      totalEpisodes: (json['totalEpisodes'] as num?)?.toInt() ?? 0,
+      freeEpisodes: (json['freeEpisodes'] as num?)?.toInt() ?? 0,
+      isHot: json['isHot'] == true,
+      viewCount: (json['viewCount'] as num?)?.toInt() ?? 0,
+      detailLoaded: true,
+      episodes: (json['episodes'] as List? ?? const [])
+          .whereType<Map<String, dynamic>>()
+          .map(Episode.fromJson)
+          .toList(),
+    );
+  }
 }

lib/core/data/repositories/catalog_repository.dart

@@ -1,104 +1,36 @@
 import '../models/drama.dart';
+import '../models/home_feed.dart';
+import '../models/play_ticket.dart';
+import '../remote/catalog_api.dart';
 
+/// 目录数据来源：首页/发现页聚合、详情、播放票据。
+///
+/// 首页卡片不带剧集，进详情或播放时才按需取，保证列表接口足够轻。
 abstract interface class CatalogRepository {
-  Future<List<Drama>> fetchDramas();
+  Future<HomeFeed> fetchHomeFeed();
+
+  Future<HomeFeed> fetchDiscoverFeed();
+
+  Future<Drama> fetchDrama(String dramaId);
+
+  Future<PlayTicket> resolvePlay(String episodeId);
 }
 
-class DemoCatalogRepository implements CatalogRepository {
+class HttpCatalogRepository implements CatalogRepository {
+  HttpCatalogRepository(this._api);
+
+  final CatalogApi _api;
+
   @override
-  Future<List<Drama>> fetchDramas() async => const [
-    Drama(
-      id: 'the-signal-demo',
-      title: 'The Signal',
-      synopsis:
-          'A mock series for testing vertical episode playback with one reused local clip.',
-      posterAsset: 'assets/images/stitch_signal_poster_clean.png',
-      format: DramaFormat.animated,
-      episodes: [
-        Episode(
-          id: 'signal-01',
-          number: 1,
-          title: 'Episode 1',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'signal-02',
-          number: 2,
-          title: 'Episode 2',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'signal-03',
-          number: 3,
-          title: 'Episode 3',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-      ],
-    ),
-    Drama(
-      id: 'city-lights-demo',
-      title: 'City Lights & Velvet Nights',
-      synopsis:
-          'A mock romance series using the same local video for navigation testing.',
-      posterAsset: 'assets/images/stitch_city_poster_clean.png',
-      format: DramaFormat.liveAction,
-      episodes: [
-        Episode(
-          id: 'city-01',
-          number: 1,
-          title: 'Episode 1',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'city-02',
-          number: 2,
-          title: 'Episode 2',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'city-03',
-          number: 3,
-          title: 'Episode 3',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-      ],
-    ),
-    Drama(
-      id: 'vengeance-demo',
-      title: 'Vengeance Rising',
-      synopsis:
-          'A mock action series using the same local video for navigation testing.',
-      posterAsset: 'assets/images/stitch_vengeance_poster_clean.png',
-      format: DramaFormat.liveAction,
-      episodes: [
-        Episode(
-          id: 'vengeance-01',
-          number: 1,
-          title: 'Episode 1',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'vengeance-02',
-          number: 2,
-          title: 'Episode 2',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-        Episode(
-          id: 'vengeance-03',
-          number: 3,
-          title: 'Episode 3',
-          assetPath: 'assets/media/demo_clip.mp4',
-          isFree: true,
-        ),
-      ],
-    ),
-  ];
+  Future<HomeFeed> fetchHomeFeed() => _api.homeFeed();
+
+  @override
+  Future<HomeFeed> fetchDiscoverFeed() => _api.discoverFeed();
+
+  @override
+  Future<Drama> fetchDrama(String dramaId) => _api.dramaDetail(dramaId);
+
+  @override
+  Future<PlayTicket> resolvePlay(String episodeId) =>
+      _api.playTicket(episodeId);
 }

lib/core/data/repositories/watch_history_repository.dart

@@ -1,5 +1,7 @@
 import 'package:shared_preferences/shared_preferences.dart';
 
+import '../models/drama.dart';
+
 const demoProfileId = 'demo-local-v1';
 
 abstract interface class WatchHistoryRepository {
@@ -60,6 +62,17 @@ class SharedPreferencesWatchHistoryRepository
   }
 }
 
+/// 续看位置：列表卡片没有剧集列表，取不到首集时退回最近观看的那一集。
+extension WatchHistoryResume on WatchHistoryRepository {
+  Future<Duration?> resumePositionFor(String profileId, Drama drama) async {
+    final episodeId = drama.episodes.isNotEmpty
+        ? drama.episodes.first.id
+        : await lastEpisodeId(profileId, drama.id);
+    if (episodeId == null) return null;
+    return positionFor(profileId, drama.id, episodeId);
+  }
+}
+
 Duration clampResumePosition(Duration saved, Duration duration) {
   if (duration <= const Duration(milliseconds: 500)) return Duration.zero;
   if (saved <= Duration.zero) return Duration.zero;

lib/core/data/services/catalog_controller.dart

@@ -1,26 +1,72 @@
 import 'package:flutter/foundation.dart';
-import '../models/drama.dart';
-import '../repositories/catalog_repository.dart';
 
+import '../models/drama.dart';
+import '../models/home_feed.dart';
+import '../repositories/catalog_repository.dart';
+import '../remote/api_client.dart';
+
+/// 目录状态：首页/发现页聚合数据 + 详情按需加载。
+///
+/// 列表卡片不含剧集，只有进详情或播放时才取一次详情，
+/// 这样首页接口能保持很小的响应体。
 class CatalogController extends ChangeNotifier {
   CatalogController(this.repository);
+
   final CatalogRepository repository;
 
-  List<Drama> dramas = const [];
+  HomeFeed feed = const HomeFeed();
   bool loading = false;
   String? error;
 
+  List<Drama> get dramas => feed.dramas;
+  List<FeedBanner> get banners => feed.banners;
+  List<FeedSection> get sections => feed.sections;
+
   Future<void> load() async {
     loading = true;
     error = null;
     notifyListeners();
     try {
-      dramas = await repository.fetchDramas();
+      feed = await repository.fetchHomeFeed();
+    } on ApiException catch (exception) {
+      error = exception.message;
     } catch (_) {
-      error = 'The catalog could not be loaded.';
+      error = 'catalogError';
     } finally {
       loading = false;
       notifyListeners();
     }
   }
+
+  /// 需要完整剧集时补一次详情；已加载过则直接返回，避免重复请求。
+  Future<Drama> requireDetail(Drama drama) async {
+    if (drama.detailLoaded) return drama;
+    final detail = await repository.fetchDrama(drama.id);
+    _replace(detail);
+    return detail;
+  }
+
+  /// 播放前解析票据：返回带播放地址的剧集，锁定集保持无地址。
+  Future<Episode> resolvePlay(Episode episode) async {
+    if (episode.videoUrl.isNotEmpty) return episode;
+    final ticket = await repository.resolvePlay(episode.id);
+    return ticket.accessible ? episode.withVideoUrl(ticket.playUrl) : episode;
+  }
+
+  void _replace(Drama detail) {
+    final sections = feed.sections
+        .map(
+          (section) => FeedSection(
+            code: section.code,
+            title: section.title,
+            dramas: [
+              for (final drama in section.dramas)
+                if (drama.id == detail.id) detail else drama,
+            ],
+          ),
+        )
+        .toList();
+    feed = HomeFeed(banners: feed.banners, sections: sections);
+    notifyListeners();
+  }
 }

lib/core/data/services/playback_session.dart

@@ -128,6 +128,9 @@ class PlaybackSession extends ChangeNotifier {
         if (!slot.retiring && !_closed) slot.prepared = true;
       } catch (error) {
         slot.failure = error;
+        if (kDebugMode) {
+          debugPrint('片源准备失败 ${episodes[index].videoUrl}: $error');
+        }
       }
     }();
     return slot;
@@ -149,14 +152,23 @@ class PlaybackSession extends ChangeNotifier {
   /// use exactly the same mechanism without warming an unrelated episode.
   Future<void> select(int index, {int? preloadIndex}) async {
     if (_closed || index < 0 || index >= episodes.length) return;
+    // 切到另一集时，上一集按下的暂停不跟着走：滑过去就应该自动播放。
+    // 重复选中同一集（例如页面重新可见）不在这里恢复，尊重用户按下的暂停。
+    if (!_selected || index != _currentIndex) {
+      _userWantsPlay = true;
+    }
     final request = ++_generation;
     _selected = true;
     _currentIndex = index;
     _nextIndex = preloadIndex;
     _error = null;
+    if (!_visible) {
+      _loading = false;
+      _notify();
+      return;
+    }
     _loading = preparedPlayerAt(index) == null && !isLocked;
     _notify();
-    if (!_visible) return;
     final acquired = await _coordinator._acquire(
       this,
       () => _visible && request == _generation,

lib/core/data/services/video_player_port.dart

@@ -1,5 +1,6 @@
 import 'package:video_player/video_player.dart';
 
+import '../../config/app_config.dart';
 import '../models/drama.dart';
 import '../models/player_port.dart';
 
@@ -7,11 +8,25 @@ class VideoPlayerPort implements PlayerPort {
   VideoPlayerPort(
     Episode episode, {
     Future<ClosedCaptionFile>? closedCaptionFile,
-  }) : controller = VideoPlayerController.asset(
-         episode.assetPath,
-         closedCaptionFile: closedCaptionFile,
-         videoPlayerOptions: VideoPlayerOptions(mixWithOthers: false),
-       );
+  }) : controller = _open(episode, closedCaptionFile);
+
+  /// 后端下发的是相对路径（`/files/...`），交给播放器前补上服务地址。
+  /// 否则 Uri 没有 scheme/host，AVPlayer 和 ExoPlayer 都加载不了。
+  static Uri resolveUri(Episode episode) =>
+      Uri.parse(AppConfig.mediaUrl(episode.videoUrl));
+
+  static VideoPlayerController _open(
+    Episode episode,
+    Future<ClosedCaptionFile>? closedCaptionFile,
+  ) {
+    final options = VideoPlayerOptions(mixWithOthers: false);
+    // 片源统一由后端下发（详情里的可播放地址 / 播放票据）
+    return VideoPlayerController.networkUrl(
+      resolveUri(episode),
+      closedCaptionFile: closedCaptionFile,
+      videoPlayerOptions: options,
+    );
+  }
 
   final VideoPlayerController controller;
   Future<void>? _initialization;