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

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();
+}