feat(flutter): 增加目录加载诊断与前台重试

lib/core/config/app_config.dart

@@ -80,9 +80,17 @@ class AppConfig {
     Future<bool> Function(String baseUrl)? probe,
     String? fallbackBaseUrl,
   }) async {
-    final candidateProbe = probe ?? _probeBaseUrl;
     for (final candidate in _probeCandidates) {
-      if (await candidateProbe(candidate)) {
+      final result = probe == null
+          ? await _probeBaseUrl(candidate)
+          : await _runInjectedProbe(candidate, probe);
+      if (kDebugMode) {
+        final status = result.ok
+            ? 'ok'
+            : 'fail(${result.reason ?? 'request failed'})';
+        debugPrint('[probe] $candidate -> $status');
+      }
+      if (result.ok) {
         applyRuntimeBaseUrl(candidate);
         return;
       }
@@ -90,25 +98,43 @@ class AppConfig {
     applyRuntimeBaseUrl(fallbackBaseUrl ?? defaultBaseUrl);
   }
 
-  static Future<bool> _probeBaseUrl(String baseUrl) async {
+  static Future<_ProbeResult> _runInjectedProbe(
+    String baseUrl,
+    Future<bool> Function(String baseUrl) probe,
+  ) async {
+    try {
+      return _ProbeResult(ok: await probe(baseUrl));
+    } catch (error) {
+      return _ProbeResult(ok: false, reason: error.toString());
+    }
+  }
+
+  static Future<_ProbeResult> _probeBaseUrl(String baseUrl) async {
     final client = HttpClient()..connectionTimeout = _probeTimeout;
     try {
       return await _requestCategories(
         client,
         Uri.parse('$baseUrl/app/categories'),
       ).timeout(_probeTimeout);
-    } catch (_) {
-      return false;
+    } catch (error) {
+      return _ProbeResult(ok: false, reason: error.toString());
     } finally {
       client.close(force: true);
     }
   }
 
-  static Future<bool> _requestCategories(HttpClient client, Uri uri) async {
+  static Future<_ProbeResult> _requestCategories(
+    HttpClient client,
+    Uri uri,
+  ) async {
     final request = await client.getUrl(uri);
     final response = await request.close();
     await response.drain<void>();
-    return response.statusCode == 200;
+    final ok = response.statusCode == 200;
+    return _ProbeResult(
+      ok: ok,
+      reason: ok ? null : 'HTTP ${response.statusCode}',
+    );
   }
 
   /// 后端返回的是相对路径（/files/...），这里补上服务地址。
@@ -118,3 +144,10 @@ class AppConfig {
     return '$apiBaseUrl$path';
   }
 }
+
+class _ProbeResult {
+  const _ProbeResult({required this.ok, this.reason});
+
+  final bool ok;
+  final String? reason;
+}

lib/core/data/services/catalog_controller.dart

@@ -2,6 +2,7 @@
 
 import 'package:flutter/foundation.dart';
 
+import '../../config/app_config.dart';
 import '../models/drama.dart';
 import '../models/home_feed.dart';
 import '../repositories/catalog_repository.dart';
@@ -22,6 +23,7 @@ class CatalogController extends ChangeNotifier {
   /// 第一次首页请求结束后为 true。之后的重试不再回到开屏。
   bool settled = false;
   String? error;
+  String? debugError;
 
   List<Drama> get dramas => feed.dramas;
   List<FeedBanner> get banners => feed.banners;
@@ -30,13 +32,18 @@ class CatalogController extends ChangeNotifier {
   Future<void> load() async {
     loading = true;
     error = null;
+    debugError = null;
     notifyListeners();
     try {
       feed = await repository.fetchHomeFeed();
     } on ApiException catch (exception) {
       error = exception.message;
-    } catch (_) {
+      debugError = exception.toString();
+      _logFailure(exception);
+    } catch (exception) {
       error = 'catalogError';
+      debugError = exception.toString();
+      _logFailure(exception);
     } finally {
       loading = false;
       settled = true;
@@ -52,11 +59,18 @@ class CatalogController extends ChangeNotifier {
       feed = await repository.fetchHomeFeed();
       notifyListeners();
       return true;
-    } catch (_) {
+    } catch (exception) {
+      _logFailure(exception);
       return false;
     }
   }
 
+  void _logFailure(Object error) {
+    if (kDebugMode) {
+      debugPrint('[catalog] base=${AppConfig.apiBaseUrl} error=$error');
+    }
+  }
+
   /// 需要完整剧集时补一次详情；已加载过则直接返回，避免重复请求。
   Future<Drama> requireDetail(Drama drama) async {
     if (drama.detailLoaded) return drama;

lib/core/data/services/catalog_retry.dart

@@ -0,0 +1,12 @@
+// Author: fruit.com.cn
+
+import '../../config/app_config.dart';
+
+/// 重新探测服务地址后再加载指定目录数据。
+Future<void> retryCatalogLoad({
+  required Future<void> Function() reload,
+  Future<void> Function()? probe,
+}) async {
+  await (probe ?? AppConfig.probeAndApplyBaseUrl)();
+  await reload();
+}

lib/core/data/services/category_controller.dart

@@ -2,6 +2,7 @@
 
 import 'package:flutter/foundation.dart';
 
+import '../../config/app_config.dart';
 import '../models/content_category.dart';
 import '../models/drama.dart';
 import '../models/home_feed.dart';
@@ -17,6 +18,7 @@ class CategoryController extends ChangeNotifier {
   HomeFeed feed = const HomeFeed();
   bool loading = false;
   String? error;
+  String? debugError;
   bool _disposed = false;
 
   /// 分类九宫格点击后读取该分类的剧目；缺失分区返回空列表。
@@ -32,6 +34,7 @@ class CategoryController extends ChangeNotifier {
   Future<void> load() async {
     loading = true;
     error = null;
+    debugError = null;
     _notify();
     try {
       final results = await Future.wait<Object>([
@@ -40,8 +43,12 @@ class CategoryController extends ChangeNotifier {
       ]);
       categories = results[0] as List<ContentCategory>;
       feed = results[1] as HomeFeed;
-    } catch (_) {
+    } catch (exception) {
       error = 'categoriesError';
+      debugError = exception.toString();
+      if (kDebugMode) {
+        debugPrint('[catalog] base=${AppConfig.apiBaseUrl} error=$exception');
+      }
     } finally {
       loading = false;
       _notify();

lib/core/widgets/catalog_debug_info.dart

@@ -0,0 +1,47 @@
+// Author: fruit.com.cn
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+import '../config/app_config.dart';
+import '../theme/app_colors.dart';
+
+const TextStyle _debugStyle = TextStyle(
+  color: AppColors.subtle,
+  fontSize: 12,
+  height: 1.35,
+);
+
+/// 仅 debug 展示当前服务地址与目录请求的原始错误。
+class CatalogDebugInfo extends StatelessWidget {
+  const CatalogDebugInfo({super.key, required this.error});
+
+  final String? error;
+
+  @override
+  Widget build(BuildContext context) {
+    if (!kDebugMode) return const SizedBox.shrink();
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Text(
+          '服务地址：${AppConfig.apiBaseUrl}',
+          key: const Key('catalog-debug-endpoint'),
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+          textAlign: TextAlign.center,
+          style: _debugStyle,
+        ),
+        const SizedBox(height: 2),
+        Text(
+          '错误：${error ?? 'unknown'}',
+          key: const Key('catalog-debug-error'),
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+          textAlign: TextAlign.center,
+          style: _debugStyle,
+        ),
+      ],
+    );
+  }
+}

lib/core/widgets/empty_state.dart

@@ -25,6 +25,7 @@ class EmptyState extends StatelessWidget {
     this.actionLabel,
     this.actionKey,
     this.onAction,
+    this.footer,
     this.compact = false,
   });
 
@@ -34,6 +35,7 @@ class EmptyState extends StatelessWidget {
   final String? actionLabel;
   final Key? actionKey;
   final VoidCallback? onAction;
+  final Widget? footer;
   final bool compact;
 
   @override
@@ -65,6 +67,7 @@ class EmptyState extends StatelessWidget {
                   actionLabel: hasAction ? actionLabel : null,
                   actionKey: actionKey,
                   onAction: hasAction ? onAction : null,
+                  footer: footer,
                 ),
               ],
             ),
@@ -101,6 +104,7 @@ class _EmptyCopy extends StatelessWidget {
     required this.actionLabel,
     required this.actionKey,
     required this.onAction,
+    required this.footer,
   });
 
   final String title;
@@ -108,6 +112,7 @@ class _EmptyCopy extends StatelessWidget {
   final String? actionLabel;
   final Key? actionKey;
   final VoidCallback? onAction;
+  final Widget? footer;
 
   @override
   Widget build(BuildContext context) {
@@ -162,6 +167,7 @@ class _EmptyCopy extends StatelessWidget {
             ),
           ),
         ],
+        if (footer != null) ...[const SizedBox(height: 12), footer!],
       ],
     );
   }