feat(library): 收藏与观看历史支持分页

test/integration/live_watch_flow_test.dart

@@ -14,7 +14,8 @@ import 'package:fruitshorts/core/data/remote/watch_api.dart';
 /// 用一个一次性邮箱注册（需要登录态的接口才会通）；服务没起时自动跳过。
 void main() {
   const baseUrl = 'http://127.0.0.1:8081';
-  final email = 'k1.selftest.${DateTime.now().millisecondsSinceEpoch}@example.com';
+  final email =
+      'k1.selftest.${DateTime.now().millisecondsSinceEpoch}@example.com';
   const password = 'Passw0rd!23';
 
   AuthSession? session;
@@ -98,17 +99,17 @@ void main() {
     expect(resume?.position, position);
 
     // 最近观看里能看到这部剧
-    final recent = await watch.recent(limit: 20);
-    expect(recent.map((item) => item.dramaId), contains(card.id));
+    final recent = await watch.recent(pageSize: 20);
+    expect(recent.list.map((item) => item.dramaId), contains(card.id));
 
     // 5) 收藏 → 出现在收藏列表 → 取消收藏
     final savedState = await library.toggleFavorite(card.id);
     expect(savedState, isTrue);
     final favorites = await library.favorites();
-    expect(favorites.map((drama) => drama.id), contains(card.id));
+    expect(favorites.list.map((drama) => drama.id), contains(card.id));
 
     await library.removeFavorite(card.id);
     final afterRemove = await library.favorites();
-    expect(afterRemove.map((drama) => drama.id), isNot(contains(card.id)));
+    expect(afterRemove.list.map((drama) => drama.id), isNot(contains(card.id)));
   });
 }

test/library/favorite_controller_test.dart

@@ -2,6 +2,7 @@
 
 import 'package:flutter_test/flutter_test.dart';
 import 'package:fruitshorts/core/data/models/drama.dart';
+import 'package:fruitshorts/core/data/models/page_result.dart';
 import 'package:fruitshorts/core/data/repositories/favorite_repository.dart';
 import 'package:fruitshorts/core/data/services/favorite_controller.dart';
 
@@ -49,7 +50,7 @@ void main() {
   });
 
   test('should_expose_error_and_keep_old_state_when_list_fails', () async {
-    final repository = InMemoryFavoriteRepository()..failList = true;
+    final repository = InMemoryFavoriteRepository()..failPage = true;
     final controller = FavoriteController(repository);
 
     await controller.load();
@@ -115,4 +116,66 @@ void main() {
     expect(controller.savedIds, isEmpty);
     expect(controller.cards, isEmpty);
   });
+
+  test('should_append_unique_cards_and_stop_when_no_more_pages', () async {
+    final repository = _PagedFavoriteRepository({
+      1: PageResult(total: 3, list: [_card('a'), _card('b')]),
+      2: PageResult(total: 3, list: [_card('b'), _card('c')]),
+    });
+    final controller = FavoriteController(repository, pageSize: 2);
+
+    await controller.load();
+    await controller.loadMore();
+    await controller.loadMore();
+
+    expect(controller.cards.map((card) => card.id), ['a', 'b', 'c']);
+    expect(controller.total, 3);
+    expect(controller.hasMore, isFalse);
+    expect(repository.pageRequests, [1, 2]);
+  });
+
+  test('should_retry_next_page_when_load_more_fails', () async {
+    final repository = _PagedFavoriteRepository({
+      1: PageResult(total: 2, list: [_card('a')]),
+      2: PageResult(total: 2, list: [_card('b')]),
+    })..failPages.add(2);
+    final controller = FavoriteController(repository, pageSize: 1);
+
+    await controller.load();
+    await controller.loadMore();
+
+    expect(controller.cards.map((card) => card.id), ['a']);
+    expect(controller.loadMoreError, 'favoritesError');
+    expect(controller.hasMore, isTrue);
+
+    repository.failPages.clear();
+    await controller.loadMore();
+
+    expect(controller.cards.map((card) => card.id), ['a', 'b']);
+    expect(controller.loadMoreError, isNull);
+    expect(repository.pageRequests, [1, 2, 2]);
+  });
+}
+
+class _PagedFavoriteRepository implements FavoriteRepository {
+  _PagedFavoriteRepository(this.pages);
+
+  final Map<int, PageResult<Drama>> pages;
+  final List<int> pageRequests = [];
+  final Set<int> failPages = {};
+
+  @override
+  Future<PageResult<Drama>> page({int pageIndex = 1, int pageSize = 20}) async {
+    pageRequests.add(pageIndex);
+    if (failPages.contains(pageIndex)) {
+      throw StateError('page unavailable');
+    }
+    return pages[pageIndex] ?? const PageResult();
+  }
+
+  @override
+  Future<void> remove(String dramaId) async {}
+
+  @override
+  Future<bool> toggle(String dramaId) async => true;
 }

test/library/favorites_page_test.dart

@@ -137,7 +137,7 @@ void main() {
 
   testWidgets('should_show_retry_when_favorite_list_fails', (tester) async {
     final auth = await _auth(signedIn: true);
-    final repository = InMemoryFavoriteRepository()..failList = true;
+    final repository = InMemoryFavoriteRepository()..failPage = true;
     final favorites = FavoriteController(repository);
 
     await _pumpPage(tester, auth: auth, favorites: favorites);
@@ -159,7 +159,7 @@ void main() {
       await _pumpPage(tester, auth: auth, favorites: favorites);
 
       expect(find.byKey(const Key('auth-gate-panel')), findsOneWidget);
-      expect(repository.listCalls, 0);
+      expect(repository.pageCalls, 0);
     },
   );
 

test/library/library_api_test.dart

@@ -0,0 +1,66 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:fruitshorts/core/data/remote/api_client.dart';
+import 'package:fruitshorts/core/data/remote/library_api.dart';
+
+import '../support/fake_http_adapter.dart';
+
+void main() {
+  test('should_request_favorites_with_page_and_parse_page_result', () async {
+    final adapter = FakeHttpAdapter(
+      (_) async => FakeHttpResponse(
+        jsonEncode({
+          'code': 0,
+          'message': 'ok',
+          'data': {
+            'total': '21',
+            'list': [
+              {'id': '9', 'title': '收藏剧', 'cover': '/files/9.png'},
+            ],
+          },
+        }),
+      ),
+    );
+    final api = LibraryApi(
+      ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter),
+    );
+
+    final page = await api.favorites(pageIndex: 2, pageSize: 10);
+
+    final request = adapter.requests.single;
+    expect(request.uri.path, '/app/favorites');
+    expect(request.queryParameters['pageIndex'], '2');
+    expect(request.queryParameters['pageSize'], '10');
+    expect(page.total, 21);
+    expect(page.list.single.id, '9');
+    expect(page.list.single.title, '收藏剧');
+  });
+
+  test(
+    'should_wrap_legacy_list_when_backend_has_not_deployed_paging',
+    () async {
+      final adapter = FakeHttpAdapter(
+        (_) async => FakeHttpResponse(
+          jsonEncode({
+            'code': 0,
+            'message': 'ok',
+            'data': [
+              {'id': '3', 'title': '旧收藏'},
+            ],
+          }),
+        ),
+      );
+      final api = LibraryApi(
+        ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter),
+      );
+
+      final page = await api.favorites();
+
+      expect(page.total, 1);
+      expect(page.list.single.title, '旧收藏');
+    },
+  );
+}

test/support/fake_watch_history.dart

@@ -1,4 +1,7 @@
+// Author: fruit.com.cn
+
 import 'package:fruitshorts/core/data/repositories/watch_history_repository.dart';
+import 'package:fruitshorts/core/data/models/page_result.dart';
 import 'package:fruitshorts/core/data/models/watch_progress.dart';
 
 /// 记录每次进度读取/上报，方便断言"读了哪部剧、上报了哪一集"。
@@ -57,9 +60,19 @@ class FakeWatchHistory implements WatchHistoryRepository {
   }
 
   @override
-  Future<List<WatchProgress>> recent({int limit = 20}) async {
+  Future<PageResult<WatchProgress>> recent({
+    int pageIndex = 1,
+    int pageSize = 20,
+  }) async {
     if (failReads) throw StateError('history unavailable');
-    return recentRecords.take(limit).toList();
+    final offset = (pageIndex - 1) * pageSize;
+    if (offset >= recentRecords.length) {
+      return PageResult(total: recentRecords.length);
+    }
+    return PageResult(
+      total: recentRecords.length,
+      list: recentRecords.skip(offset).take(pageSize).toList(),
+    );
   }
 
   @override

test/watch/watch_api_test.dart

@@ -0,0 +1,83 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:fruitshorts/core/data/remote/api_client.dart';
+import 'package:fruitshorts/core/data/remote/watch_api.dart';
+
+import '../support/fake_http_adapter.dart';
+
+void main() {
+  test('should_request_recent_with_page_and_parse_display_fields', () async {
+    final adapter = FakeHttpAdapter(
+      (_) async => FakeHttpResponse(
+        jsonEncode({
+          'code': 0,
+          'message': 'ok',
+          'data': {
+            'total': '18',
+            'list': [
+              {
+                'dramaId': '12',
+                'episodeId': '88',
+                'dramaTitle': '剧名',
+                'dramaCover': '/files/12.png',
+                'episodeNumber': 6,
+                'totalEpisodes': 68,
+                'positionMs': '80000',
+                'durationMs': '120000',
+              },
+            ],
+          },
+        }),
+      ),
+    );
+    final api = WatchApi(
+      ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter),
+    );
+
+    final page = await api.recent(pageIndex: 2, pageSize: 10);
+
+    final request = adapter.requests.single;
+    expect(request.uri.path, '/app/watch/recent');
+    expect(request.queryParameters['pageIndex'], '2');
+    expect(request.queryParameters['pageSize'], '10');
+    expect(request.queryParameters.containsKey('limit'), isFalse);
+    expect(page.total, 18);
+    expect(page.list.single.dramaTitle, '剧名');
+    expect(page.list.single.dramaCover, '/files/12.png');
+    expect(page.list.single.episodeNumber, 6);
+    expect(page.list.single.totalEpisodes, 68);
+  });
+
+  test(
+    'should_wrap_legacy_list_when_backend_has_not_deployed_paging',
+    () async {
+      final adapter = FakeHttpAdapter(
+        (_) async => FakeHttpResponse(
+          jsonEncode({
+            'code': 0,
+            'message': 'ok',
+            'data': [
+              {
+                'dramaId': '5',
+                'episodeId': '7',
+                'positionMs': '1000',
+                'durationMs': '2000',
+              },
+            ],
+          }),
+        ),
+      );
+      final api = WatchApi(
+        ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter),
+      );
+
+      final page = await api.recent();
+
+      expect(page.total, 1);
+      expect(page.list.single.dramaId, '5');
+    },
+  );
+}

test/watch/watch_records_controller_test.dart

@@ -6,6 +6,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:fruitshorts/core/data/models/drama.dart';
 import 'package:fruitshorts/core/data/models/feed_page.dart';
 import 'package:fruitshorts/core/data/models/home_feed.dart';
+import 'package:fruitshorts/core/data/models/page_result.dart';
 import 'package:fruitshorts/core/data/models/watch_progress.dart';
 import 'package:fruitshorts/core/data/repositories/catalog_repository.dart';
 import 'package:fruitshorts/core/data/repositories/watch_history_repository.dart';
@@ -93,6 +94,55 @@ void main() {
     );
   });
 
+  test('should_append_unique_records_and_stop_when_no_more_pages', () async {
+    final history = _PagedWatchHistory({
+      1: PageResult(total: 3, list: [_progress('1'), _progress('2')]),
+      2: PageResult(total: 3, list: [_progress('2'), _progress('3')]),
+    });
+    final catalog = ScriptedWatchCatalog();
+    final controller = WatchRecordsController(
+      history: history,
+      catalog: catalog,
+      pageSize: 2,
+    );
+
+    await controller.load();
+    await controller.loadMore();
+    await controller.loadMore();
+
+    expect(controller.records.map((record) => record.dramaId), ['1', '2', '3']);
+    expect(controller.total, 3);
+    expect(controller.hasMore, isFalse);
+    expect(history.pageRequests, [1, 2]);
+    expect(catalog.calls, ['1', '2', '3']);
+  });
+
+  test('should_retry_next_page_when_watch_load_more_fails', () async {
+    final history = _PagedWatchHistory({
+      1: PageResult(total: 2, list: [_progress('1')]),
+      2: PageResult(total: 2, list: [_progress('2')]),
+    })..failPages.add(2);
+    final controller = WatchRecordsController(
+      history: history,
+      catalog: ScriptedWatchCatalog(),
+      pageSize: 1,
+    );
+
+    await controller.load();
+    await controller.loadMore();
+
+    expect(controller.records.map((record) => record.dramaId), ['1']);
+    expect(controller.loadMoreError, 'progressError');
+    expect(controller.hasMore, isTrue);
+
+    history.failPages.clear();
+    await controller.loadMore();
+
+    expect(controller.records.map((record) => record.dramaId), ['1', '2']);
+    expect(controller.loadMoreError, isNull);
+    expect(history.pageRequests, [1, 2, 2]);
+  });
+
   test('should_keep_existing_records_when_refresh_fails', () async {
     final history = ControlledWatchHistory([_progress('1')]);
     final controller = WatchRecordsController(
@@ -213,6 +263,7 @@ class ControlledWatchHistory implements WatchHistoryRepository {
   final List<WatchProgress> items;
   bool failRecent = false;
   Object? recentError;
+  final List<int> recentPages = [];
   bool failRemove = false;
   bool failClear = false;
   Completer<void>? removeGate;
@@ -230,10 +281,21 @@ class ControlledWatchHistory implements WatchHistoryRepository {
   }) async => null;
 
   @override
-  Future<List<WatchProgress>> recent({int limit = 20}) async {
+  Future<PageResult<WatchProgress>> recent({
+    int pageIndex = 1,
+    int pageSize = 20,
+  }) async {
+    recentPages.add(pageIndex);
     if (recentError != null) throw recentError!;
     if (failRecent) throw StateError('recent unavailable');
-    return items.take(limit).toList();
+    final offset = (pageIndex - 1) * pageSize;
+    if (offset >= items.length) {
+      return PageResult(total: items.length);
+    }
+    return PageResult(
+      total: items.length,
+      list: items.skip(offset).take(pageSize).toList(),
+    );
   }
 
   @override
@@ -285,3 +347,40 @@ class ScriptedWatchCatalog implements CatalogRepository {
     return _detail(dramaId);
   }
 }
+
+class _PagedWatchHistory implements WatchHistoryRepository {
+  _PagedWatchHistory(this.pages);
+
+  final Map<int, PageResult<WatchProgress>> pages;
+  final List<int> pageRequests = [];
+  final Set<int> failPages = {};
+
+  @override
+  Future<PageResult<WatchProgress>> recent({
+    int pageIndex = 1,
+    int pageSize = 20,
+  }) async {
+    pageRequests.add(pageIndex);
+    if (failPages.contains(pageIndex)) {
+      throw StateError('page unavailable');
+    }
+    return pages[pageIndex] ?? const PageResult();
+  }
+
+  @override
+  Future<WatchProgress?> progressFor(String dramaId) async => null;
+
+  @override
+  Future<WatchProgress?> save({
+    required String episodeId,
+    required Duration position,
+    Duration? duration,
+    bool finished = false,
+  }) async => null;
+
+  @override
+  Future<void> remove(String dramaId) async {}
+
+  @override
+  Future<void> clear() async {}
+}

test/watch/watch_records_page_test.dart

@@ -6,6 +6,7 @@ import 'package:fruitshorts/app.dart';
 import 'package:fruitshorts/core/data/models/drama.dart';
 import 'package:fruitshorts/core/data/models/feed_page.dart';
 import 'package:fruitshorts/core/data/models/home_feed.dart';
+import 'package:fruitshorts/core/data/models/page_result.dart';
 import 'package:fruitshorts/core/data/models/watch_progress.dart';
 import 'package:fruitshorts/core/data/remote/api_client.dart';
 import 'package:fruitshorts/core/data/remote/auth_api.dart';
@@ -98,6 +99,56 @@ void main() {
     expect(list.physics, AppPullToRefresh.physics);
   });
 
+  testWidgets('should_render_backend_title_episode_and_cover_metadata', (
+    tester,
+  ) async {
+    final auth = await _auth(signedIn: true);
+    final history = CountingWatchHistory([
+      _progress(
+        'metadata',
+        dramaTitle: 'Backend Title',
+        dramaCover: '/files/backend.png',
+        episodeNumber: 3,
+      ),
+    ]);
+
+    await _pumpPage(
+      tester,
+      auth: auth,
+      history: history,
+      catalog: _AlwaysFailingWatchCatalog(),
+    );
+
+    expect(find.text('Backend Title'), findsOneWidget);
+    expect(find.text('Episode 3'), findsOneWidget);
+    expect(
+      find.byKey(const Key('watch-record-cover-metadata')),
+      findsOneWidget,
+    );
+  });
+
+  testWidgets('should_fallback_to_episode_title_and_cover_placeholder', (
+    tester,
+  ) async {
+    final auth = await _auth(signedIn: true);
+    final history = CountingWatchHistory([
+      _progress('fallback', dramaTitle: '', episodeNumber: 4),
+    ]);
+
+    await _pumpPage(
+      tester,
+      auth: auth,
+      history: history,
+      catalog: _AlwaysFailingWatchCatalog(),
+    );
+
+    expect(find.text('Episode 4'), findsOneWidget);
+    expect(
+      find.byKey(const Key('watch-record-cover-placeholder-fallback')),
+      findsOneWidget,
+    );
+  });
+
   testWidgets(
     'should_show_failed_placeholder_and_keep_other_cards_when_detail_fails',
     (tester) async {
@@ -238,9 +289,17 @@ void main() {
   });
 }
 
-WatchProgress _progress(String dramaId) => WatchProgress(
+WatchProgress _progress(
+  String dramaId, {
+  String? dramaTitle,
+  String? dramaCover,
+  int? episodeNumber,
+}) => WatchProgress(
   dramaId: dramaId,
   episodeId: '$dramaId-1',
+  dramaTitle: dramaTitle,
+  dramaCover: dramaCover,
+  episodeNumber: episodeNumber,
   position: const Duration(seconds: 12),
   duration: const Duration(seconds: 60),
   updatedAt: DateTime(2026, 10, 17, 12),
@@ -300,9 +359,19 @@ class CountingWatchHistory extends InMemoryWatchHistoryRepository {
   int clearCalls = 0;
 
   @override
-  Future<List<WatchProgress>> recent({int limit = 20}) async {
+  Future<PageResult<WatchProgress>> recent({
+    int pageIndex = 1,
+    int pageSize = 20,
+  }) async {
     recentCalls++;
-    return visibleRecords.take(limit).toList();
+    final offset = (pageIndex - 1) * pageSize;
+    if (offset >= visibleRecords.length) {
+      return PageResult(total: visibleRecords.length);
+    }
+    return PageResult(
+      total: visibleRecords.length,
+      list: visibleRecords.skip(offset).take(pageSize).toList(),
+    );
   }
 
   @override
@@ -314,7 +383,10 @@ class CountingWatchHistory extends InMemoryWatchHistoryRepository {
 
 class _FailingRecentHistory extends InMemoryWatchHistoryRepository {
   @override
-  Future<List<WatchProgress>> recent({int limit = 20}) async {
+  Future<PageResult<WatchProgress>> recent({
+    int pageIndex = 1,
+    int pageSize = 20,
+  }) async {
     throw const ApiException(100000, '账号不存在，请先注册');
   }
 }
@@ -347,3 +419,24 @@ class _FailingWatchCatalog implements CatalogRepository {
     return _delegate.fetchDrama(dramaId);
   }
 }
+
+class _AlwaysFailingWatchCatalog implements CatalogRepository {
+  @override
+  Future<Drama> fetchDrama(String dramaId) async {
+    throw StateError('missing detail');
+  }
+
+  @override
+  Future<HomeFeed> fetchDiscoverFeed() async => const HomeFeed();
+
+  @override
+  Future<FeedPage> fetchFeed({
+    List<String> types = const [],
+    String? categoryId,
+    String? cursor,
+    int size = 10,
+  }) async => const FeedPage();
+
+  @override
+  Future<HomeFeed> fetchHomeFeed() async => const HomeFeed();
+}