refactor(app): improve AppConfig fetching logic

- Introduce background check option for AppConfig fetching
- Optimize state transitions and error handling
- Simplify event classes for better maintainability
- Enhance logging for background fetch operations

Author: fulleni

lib/app/bloc/app_bloc.dart

@@ -411,28 +411,31 @@ class AppBloc extends Bloc<AppEvent, AppState> {
       return;
     }
 
-    print(
-      '[AppBloc] Attempting to fetch AppConfig for user: ${state.user!.id}...',
-    );
-    emit(
-      state.copyWith(
-        status: AppStatus.configFetching,
-        remoteConfig: null,
-        clearAppConfig: true,
-      ),
-    );
+    // For background checks, we don't want to show a loading screen.
+    // Only for the initial fetch should we set the status to configFetching.
+    if (!event.isBackgroundCheck) {
+      print(
+        '[AppBloc] Initial config fetch. Setting status to configFetching.',
+      );
+      emit(
+        state.copyWith(
+          status: AppStatus.configFetching,
+        ),
+      );
+    } else {
+      print('[AppBloc] Background config fetch. Proceeding silently.');
+    }
 
     try {
       final remoteConfig = await _appConfigRepository.read(id: kRemoteConfigId);
       print(
         '[AppBloc] Remote Config fetched successfully. ID: ${remoteConfig.id} for user: ${state.user!.id}',
       );
 
-      // --- CRITICAL STARTUP SEQUENCE EVALUATION ---
-      // After successfully fetching the remote configuration, we must
-      // evaluate the app's status in a specific order before allowing
-      // the main UI to be built.
-
+      // --- CRITICAL STATUS EVALUATION ---
+      // For both initial and background checks, if a critical status is found,
+      // we must update the app status immediately to lock the UI.
+      
       // 1. Check for Maintenance Mode. This has the highest priority.
       if (remoteConfig.appStatus.isUnderMaintenance) {
         emit(
@@ -456,36 +459,43 @@ class AppBloc extends Bloc<AppEvent, AppState> {
         return;
       }
 
-      // 3. If no critical status is active, proceed to the normal app state.
-      // The status is determined by the user's role (authenticated/anonymous).
-      final finalStatus = state.user!.appRole == AppUserRole.standardUser
-          ? AppStatus.authenticated
-          : AppStatus.anonymous;
-
-      emit(state.copyWith(remoteConfig: remoteConfig, status: finalStatus));
+      // --- POST-CHECK STATE RESOLUTION ---
+      // If no critical status was found, we resolve the final state.
+
+      // For an initial fetch, we transition from configFetching to the correct
+      // authenticated/anonymous state.
+      if (!event.isBackgroundCheck) {
+        final finalStatus = state.user!.appRole == AppUserRole.standardUser
+            ? AppStatus.authenticated
+            : AppStatus.anonymous;
+        emit(state.copyWith(remoteConfig: remoteConfig, status: finalStatus));
+      } else {
+        // For a background check, the status is already correct (e.g., authenticated).
+        // We just need to update the remoteConfig in the state silently.
+        // The status does not need to change, preventing a disruptive UI rebuild.
+        emit(state.copyWith(remoteConfig: remoteConfig));
+      }
     } on HttpException catch (e) {
       print(
         '[AppBloc] Failed to fetch AppConfig (HttpException) for user ${state.user?.id}: ${e.runtimeType} - ${e.message}',
       );
-      emit(
-        state.copyWith(
-          status: AppStatus.configFetchFailed,
-          remoteConfig: null,
-          clearAppConfig: true,
-        ),
-      );
+      // Only show a failure screen on an initial fetch.
+      // For background checks, we fail silently to avoid disruption.
+      if (!event.isBackgroundCheck) {
+        emit(state.copyWith(status: AppStatus.configFetchFailed));
+      } else {
+        print('[AppBloc] Silent failure on background config fetch.');
+      }
     } catch (e, s) {
       print(
         '[AppBloc] Unexpected error fetching AppConfig for user ${state.user?.id}: $e',
       );
       print('[AppBloc] Stacktrace: $s');
-      emit(
-        state.copyWith(
-          status: AppStatus.configFetchFailed,
-          remoteConfig: null,
-          clearAppConfig: true,
-        ),
-      );
+      if (!event.isBackgroundCheck) {
+        emit(state.copyWith(status: AppStatus.configFetchFailed));
+      } else {
+        print('[AppBloc] Silent failure on background config fetch.');
+      }
     }
   }
 

lib/app/bloc/app_event.dart

@@ -7,6 +7,7 @@ abstract class AppEvent extends Equatable {
   List<Object?> get props => [];
 }
 
+/// Dispatched when the authentication state changes (e.g., user logs in/out).
 class AppUserChanged extends AppEvent {
   const AppUserChanged(this.user);
 
@@ -16,122 +17,81 @@ class AppUserChanged extends AppEvent {
   List<Object?> get props => [user];
 }
 
-/// {@template app_settings_refreshed}
-/// Internal event to trigger reloading of settings within AppBloc.
-/// Added when user changes or upon explicit request.
-/// {@endtemplate}
+/// Dispatched to request a refresh of the user's application settings.
 class AppSettingsRefreshed extends AppEvent {
-  /// {@macro app_settings_refreshed}
   const AppSettingsRefreshed();
 }
 
-/// {@template app_logout_requested}
-/// Event to request user logout.
-/// {@endtemplate}
+/// Dispatched to fetch the remote application configuration.
+class AppConfigFetchRequested extends AppEvent {
+  const AppConfigFetchRequested({this.isBackgroundCheck = false});
+
+  /// Whether this fetch is a silent background check.
+  ///
+  /// If `true`, the BLoC will not enter a visible loading state.
+  /// If `false` (default), it's treated as an initial fetch that shows a
+  /// loading UI.
+  final bool isBackgroundCheck;
+
+  @override
+  List<Object> get props => [isBackgroundCheck];
+}
+
+/// Dispatched when the user logs out.
 class AppLogoutRequested extends AppEvent {
-  /// {@macro app_logout_requested}
   const AppLogoutRequested();
 }
 
-/// {@template app_theme_mode_changed}
-/// Event to change the application's theme mode.
-/// {@endtemplate}
+/// Dispatched when the theme mode (light/dark/system) changes.
 class AppThemeModeChanged extends AppEvent {
-  /// {@macro app_theme_mode_changed}
   const AppThemeModeChanged(this.themeMode);
-
   final ThemeMode themeMode;
-
   @override
-  List<Object?> get props => [themeMode];
+  List<Object> get props => [themeMode];
 }
 
-/// {@template app_flex_scheme_changed}
-/// Event to change the application's FlexColorScheme.
-/// {@endtemplate}
+/// Dispatched when the accent color theme changes.
 class AppFlexSchemeChanged extends AppEvent {
-  /// {@macro app_flex_scheme_changed}
   const AppFlexSchemeChanged(this.flexScheme);
-
   final FlexScheme flexScheme;
-
   @override
-  List<Object?> get props => [flexScheme];
+  List<Object> get props => [flexScheme];
 }
 
-/// {@template app_font_family_changed}
-/// Event to change the application's font family.
-/// {@endtemplate}
+/// Dispatched when the font family changes.
 class AppFontFamilyChanged extends AppEvent {
-  /// {@macro app_font_family_changed}
   const AppFontFamilyChanged(this.fontFamily);
-
   final String? fontFamily;
-
   @override
   List<Object?> get props => [fontFamily];
 }
 
-/// {@template app_text_scale_factor_changed}
-/// Event to change the application's text scale factor.
-/// {@endtemplate}
+/// Dispatched when the text scale factor changes.
 class AppTextScaleFactorChanged extends AppEvent {
-  /// {@macro app_text_scale_factor_changed}
   const AppTextScaleFactorChanged(this.appTextScaleFactor);
-
   final AppTextScaleFactor appTextScaleFactor;
-
   @override
-  List<Object?> get props => [appTextScaleFactor];
+  List<Object> get props => [appTextScaleFactor];
 }
 
-/// {@template app_font_weight_changed}
-/// Event to change the application's font weight.
-/// {@endtemplate}
+/// Dispatched when the font weight changes.
 class AppFontWeightChanged extends AppEvent {
-  /// {@macro app_font_weight_changed}
   const AppFontWeightChanged(this.fontWeight);
-
-  /// The new font weight to apply.
   final AppFontWeight fontWeight;
-
   @override
   List<Object> get props => [fontWeight];
 }
 
-/// {@template app_config_fetch_requested}
-/// Event to trigger fetching of the global AppConfig.
-/// {@endtemplate}
-class AppConfigFetchRequested extends AppEvent {
-  /// {@macro app_config_fetch_requested}
-  const AppConfigFetchRequested();
-}
-
-/// {@template app_opened}
-/// Event triggered when the application is opened.
-/// Used to check for required updates or maintenance mode.
-/// {@endtemplate}
-class AppOpened extends AppEvent {
-  /// {@macro app_opened}
-  const AppOpened();
-}
-
-/// {@template app_user_account_action_shown}
-/// Event triggered when an AccountAction has been shown to the user,
-/// prompting an update to their `lastAccountActionShownAt` timestamp.
-/// {@endtemplate}
+/// Dispatched when a one-time user account action has been shown.
 class AppUserAccountActionShown extends AppEvent {
-  /// {@macro app_user_account_action_shown}
   const AppUserAccountActionShown({
     required this.userId,
     required this.feedActionType,
     required this.isCompleted,
   });
-
   final String userId;
   final FeedActionType feedActionType;
   final bool isCompleted;
-
   @override
   List<Object> get props => [userId, feedActionType, isCompleted];
 }

lib/app/services/app_status_service.dart

@@ -71,7 +71,9 @@ class AppStatusService with WidgetsBindingObserver {
         '[AppStatusService] Periodic check triggered. Requesting AppConfig fetch.',
       );
       // Add the event to the AppBloc to fetch the latest config.
-      _context.read<AppBloc>().add(const AppConfigFetchRequested());
+      _context
+          .read<AppBloc>()
+          .add(const AppConfigFetchRequested(isBackgroundCheck: true));
     });
   }
 
@@ -96,7 +98,9 @@ class AppStatusService with WidgetsBindingObserver {
       // When the app comes to the foreground, immediately trigger a check.
       // This is crucial for catching maintenance mode that was enabled
       // while the app was in the background.
-      _context.read<AppBloc>().add(const AppConfigFetchRequested());
+      _context
+          .read<AppBloc>()
+          .add(const AppConfigFetchRequested(isBackgroundCheck: true));
     }
   }