feat(theater): 剧场分类列表服务端分页

lib/core/data/remote/catalog_api.dart

@@ -18,9 +18,10 @@ class CatalogApi {
     return HomeFeed.fromJson(_asMap(await _client.get('/app/discover/feed')));
   }
 
-  /// 内容类型推荐流；types 为空表示推荐全部，cursor 为上一页末条。
+  /// 推荐流；types/categoryId 为空表示不过滤，cursor 为上一页末条。
   Future<FeedPage> feed({
     List<String> types = const [],
+    String? categoryId,
     String? cursor,
     int size = 10,
   }) async {
@@ -30,6 +31,8 @@ class CatalogApi {
           '/app/feed',
           query: {
             if (types.isNotEmpty) 'types': types.join(','),
+            if (categoryId != null && categoryId.isNotEmpty)
+              'categoryId': categoryId,
             if (cursor != null && cursor.isNotEmpty) 'cursor': cursor,
             'size': '$size',
           },

lib/core/data/repositories/catalog_repository.dart

@@ -16,6 +16,7 @@ abstract interface class CatalogRepository {
 
   Future<FeedPage> fetchFeed({
     List<String> types = const [],
+    String? categoryId,
     String? cursor,
     int size = 10,
   });
@@ -37,9 +38,15 @@ class HttpCatalogRepository implements CatalogRepository {
   @override
   Future<FeedPage> fetchFeed({
     List<String> types = const [],
+    String? categoryId,
     String? cursor,
     int size = 10,
-  }) => _api.feed(types: types, cursor: cursor, size: size);
+  }) => _api.feed(
+    types: types,
+    categoryId: categoryId,
+    cursor: cursor,
+    size: size,
+  );
 
   @override
   Future<Drama> fetchDrama(String dramaId) => _api.dramaDetail(dramaId);

lib/core/data/services/theater_feed_controller.dart

@@ -0,0 +1,187 @@
+// Author: fruit.com.cn
+
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+
+import '../../data/models/drama.dart';
+import '../../data/repositories/catalog_repository.dart';
+
+/// 剧场页服务端分类列表：按 categoryId 独立缓存、刷新和游标分页。
+class TheaterFeedController extends ChangeNotifier {
+  TheaterFeedController(
+    this._repository, {
+    this.requestTimeout = defaultRequestTimeout,
+  });
+
+  static const int pageSize = 20;
+  static const Duration defaultRequestTimeout = Duration(seconds: 10);
+
+  final CatalogRepository _repository;
+  final Duration requestTimeout;
+  final Map<String?, _CategoryFeedState> _states = {};
+  String? _categoryId;
+  bool _initialized = false;
+  bool _disposed = false;
+
+  String? get categoryId => _categoryId;
+  String? get lastError => _state(_categoryId).lastError;
+  List<Drama> get dramas => _state(_categoryId).dramas;
+  String? get cursor => _state(_categoryId).cursor;
+  bool get hasMore => _state(_categoryId).hasMore;
+  bool get loaded => _state(_categoryId).loaded;
+  bool get loadingMore => _state(_categoryId).loadingMore;
+  bool get loadingFirstPage => !loaded && _state(_categoryId).loading;
+
+  /// 同步切换分类；有缓存先渲染，无缓存时等待或发起首屏请求。
+  Future<void> select(String? next) async {
+    if (_initialized && next == _categoryId) return;
+    _categoryId = next;
+    _initialized = true;
+    _notify();
+
+    final state = _state(next);
+    if (state.dramas.isNotEmpty) {
+      if (!state.loading) {
+        unawaited(_refresh(next, keepData: true));
+      }
+      return;
+    }
+    if (state.loading) {
+      final inFlight = state.inFlight;
+      if (inFlight != null) await inFlight;
+      return;
+    }
+    await _refresh(next, keepData: false);
+  }
+
+  /// 刷新当前分类；失败时保留已有列表。
+  Future<bool> refreshCurrent() async {
+    final state = _state(_categoryId);
+    if (state.loading) {
+      return await state.inFlight ?? false;
+    }
+    return _refresh(_categoryId, keepData: true);
+  }
+
+  /// 加载当前分类下一页并去重追加。
+  Future<void> loadMore() async {
+    final categoryId = _categoryId;
+    final state = _state(categoryId);
+    if (!state.hasMore || state.loadingMore || state.cursor == null) return;
+    final sequence = ++state.requestSeq;
+    state.loadingMore = true;
+    _notifyIfCurrent(categoryId);
+    try {
+      final page = await _repository
+          .fetchFeed(
+            categoryId: categoryId,
+            cursor: state.cursor,
+            size: pageSize,
+          )
+          .timeout(requestTimeout);
+      if (!_acceptSequence(categoryId, sequence)) return;
+      final seen = state.dramas.map((drama) => drama.id).toSet();
+      final appended = page.dramas
+          .where((drama) => seen.add(drama.id))
+          .toList();
+      state
+        ..dramas = List.unmodifiable([...state.dramas, ...appended])
+        ..cursor = page.nextCursor
+        ..hasMore = page.hasMore
+        ..loaded = true
+        ..lastError = null;
+    } catch (error) {
+      if (_acceptSequence(categoryId, sequence)) {
+        state.lastError = error.toString();
+      }
+    } finally {
+      state.loadingMore = false;
+      _notifyIfCurrent(categoryId);
+    }
+  }
+
+  Future<bool> _refresh(String? categoryId, {required bool keepData}) {
+    final state = _state(categoryId);
+    final operation = _performRefresh(categoryId, keepData: keepData);
+    state.inFlight = operation;
+    unawaited(_clearInFlight(state, operation));
+    return operation;
+  }
+
+  Future<bool> _performRefresh(
+    String? categoryId, {
+    required bool keepData,
+  }) async {
+    final state = _state(categoryId);
+    final sequence = ++state.requestSeq;
+    state
+      ..loading = true
+      ..lastError = null;
+    _notifyIfCurrent(categoryId);
+    try {
+      final page = await _repository
+          .fetchFeed(categoryId: categoryId, size: pageSize)
+          .timeout(requestTimeout);
+      if (!_acceptSequence(categoryId, sequence)) return false;
+      state
+        ..dramas = List.unmodifiable(page.dramas)
+        ..cursor = page.nextCursor
+        ..hasMore = page.hasMore
+        ..loaded = true
+        ..loading = false
+        ..lastError = null;
+      _notifyIfCurrent(categoryId);
+      return true;
+    } catch (error) {
+      if (!_acceptSequence(categoryId, sequence)) return false;
+      if (!keepData) state.dramas = const [];
+      state
+        ..loaded = true
+        ..loading = false
+        ..lastError = error.toString();
+      _notifyIfCurrent(categoryId);
+      return false;
+    }
+  }
+
+  Future<void> _clearInFlight(
+    _CategoryFeedState state,
+    Future<bool> operation,
+  ) async {
+    await operation;
+    if (identical(state.inFlight, operation)) state.inFlight = null;
+  }
+
+  _CategoryFeedState _state(String? categoryId) =>
+      _states.putIfAbsent(categoryId, _CategoryFeedState.new);
+
+  bool _acceptSequence(String? categoryId, int sequence) =>
+      !_disposed && _state(categoryId).requestSeq == sequence;
+
+  void _notifyIfCurrent(String? categoryId) {
+    if (!_disposed && categoryId == _categoryId) _notify();
+  }
+
+  void _notify() {
+    if (!_disposed) notifyListeners();
+  }
+
+  @override
+  void dispose() {
+    _disposed = true;
+    super.dispose();
+  }
+}
+
+class _CategoryFeedState {
+  List<Drama> dramas = const [];
+  String? cursor;
+  bool hasMore = true;
+  bool loaded = false;
+  bool loading = false;
+  bool loadingMore = false;
+  String? lastError;
+  int requestSeq = 0;
+  Future<bool>? inFlight;
+}