Merge pull request #554 from DevKor-github/feature/issue-532-notification-init-idempotent

fix: make notification initialization idempotent

Author: jjoonleo

docs/Notification-Behavior.md

@@ -6,6 +6,7 @@ This document describes the current notification behavior in OnTime across push
 
 - App startup checks current notification permission first.
 - `NotificationService.initialize()` runs at startup only when permission is already `AuthorizationStatus.authorized`.
+- `NotificationService.initialize()` is service-level idempotent: repeated sequential or concurrent calls share the same completed or in-flight setup and do not register duplicate FCM listeners.
 - If startup permission is not authorized, the app does not initialize notification handlers/tokens from `main.dart`.
 - During authenticated redirects from sign-in/onboarding entry routes, router logic checks permission and redirects to `/allowNotification` when permission is not authorized.
 - Permission can later be requested from:
@@ -21,20 +22,20 @@ Implementation notes:
 
 ### Foreground
 
-- `FirebaseMessaging.onMessage` listener is registered in `NotificationService._setupMessageHandlers()`.
+- `FirebaseMessaging.onMessage` listener is registered once per `NotificationService` lifecycle.
 - Incoming push messages are converted into in-app local notifications through `showNotification(message)`.
 - Title/body resolution supports both `message.notification` and `message.data` keys (e.g., `title`, `content`, `body`, plus case variants).
 
 ### Background (App in background, opened from notification)
 
-- `FirebaseMessaging.onMessageOpenedApp` triggers `_handleBackgroundMessage(message)`.
+- `FirebaseMessaging.onMessageOpenedApp` listener is registered once per `NotificationService` lifecycle and triggers `_handleBackgroundMessage(message)`.
 - Navigation is decided from payload fields:
   - `type` contains `5min` -> push `/scheduleStart` with `extra: {'isFiveMinutesBefore': true}`
   - `type` starts with `schedule_` or `preparation_`, or `scheduleId` exists -> push `/alarmScreen`
 
 ### Terminated (Cold start from notification tap)
 
-- `FirebaseMessaging.getInitialMessage()` is read on initialization.
+- `FirebaseMessaging.getInitialMessage()` is read once during notification service initialization.
 - If present, it is passed through the same `_handleBackgroundMessage(message)` routing logic as background open.
 
 ### Background isolate handler
@@ -78,7 +79,7 @@ Implementation notes:
   - `FirebaseMessaging.getToken()` is called.
   - If token exists, app posts to backend endpoint `/firebase-token` with payload `{ "firebaseToken": "<token>" }`.
 - On token refresh:
-  - `FirebaseMessaging.onTokenRefresh.listen(...)` posts refreshed token to the same endpoint.
+  - A single `FirebaseMessaging.onTokenRefresh` subscription posts refreshed token to the same endpoint.
 - Failures are logged and do not crash app flow.
 
 ## 6. Platform-Specific Notes (Android/iOS/Web)

lib/core/services/notification_service.dart

@@ -43,11 +43,16 @@ class NotificationService {
     FlutterLocalNotificationsPlugin? localNotifications,
     String Function()? localeProvider,
     bool? isIOSOverride,
+    Stream<RemoteMessage>? onMessage,
+    Stream<RemoteMessage>? onMessageOpenedApp,
   }) : _messaging = messaging ?? FirebaseMessaging.instance,
        _localNotifications =
            localNotifications ?? FlutterLocalNotificationsPlugin(),
        _localeProvider = localeProvider,
-       _isIOSOverride = isIOSOverride;
+       _isIOSOverride = isIOSOverride,
+       _onMessage = onMessage ?? FirebaseMessaging.onMessage,
+       _onMessageOpenedApp =
+           onMessageOpenedApp ?? FirebaseMessaging.onMessageOpenedApp;
 
   @visibleForTesting
   NotificationService.test({
@@ -57,10 +62,15 @@ class NotificationService {
     bool isFlutterLocalNotificationsInitialized = false,
     bool isTimezoneInitialized = false,
     bool? isIOSOverride,
+    Stream<RemoteMessage>? onMessage,
+    Stream<RemoteMessage>? onMessageOpenedApp,
   }) : _messaging = messaging,
        _localNotifications = localNotifications,
        _localeProvider = localeProvider,
        _isIOSOverride = isIOSOverride,
+       _onMessage = onMessage ?? FirebaseMessaging.onMessage,
+       _onMessageOpenedApp =
+           onMessageOpenedApp ?? FirebaseMessaging.onMessageOpenedApp,
        _isFlutterLocalNotificationsInitialized =
            isFlutterLocalNotificationsInitialized,
        _isTimezoneInitialized = isTimezoneInitialized;
@@ -74,8 +84,16 @@ class NotificationService {
   final FlutterLocalNotificationsPlugin _localNotifications;
   final String Function()? _localeProvider;
   final bool? _isIOSOverride;
+  final Stream<RemoteMessage> _onMessage;
+  final Stream<RemoteMessage> _onMessageOpenedApp;
   bool _isFlutterLocalNotificationsInitialized = false;
   bool _isTimezoneInitialized = false;
+  bool _isInitialized = false;
+  bool _initialMessageHandled = false;
+  Future<void>? _initializationFuture;
+  StreamSubscription<RemoteMessage>? _foregroundMessageSubscription;
+  StreamSubscription<RemoteMessage>? _openedAppMessageSubscription;
+  StreamSubscription<String>? _tokenRefreshSubscription;
 
   bool get _isIOS => !kIsWeb && (_isIOSOverride ?? Platform.isIOS);
 
@@ -92,29 +110,50 @@ class NotificationService {
     }
   }
 
-  Future<void> initialize() async {
-    try {
-      FirebaseMessaging.onBackgroundMessage(
-        _firebaseMessagingBackgroundHandler,
-      );
-      AppLogger.debug('[FCM] Background message handler 등록 완료');
-    } catch (e) {
-      AppLogger.debug('[FCM] Background message handler 등록 실패: $e');
+  Future<void> initialize() {
+    if (_isInitialized) {
+      return Future.value();
     }
 
-    await _requestPermission();
-    await setupFlutterNotifications();
-    await _setupMessageHandlers();
+    final initializationFuture = _initializationFuture;
+    if (initializationFuture != null) {
+      return initializationFuture;
+    }
 
-    await requestNotificationToken();
+    final future = _initialize();
+    _initializationFuture = future;
+    return future;
+  }
 
-    if (_isIOS) {
-      await _messaging.setForegroundNotificationPresentationOptions(
-        alert: true,
-        badge: true,
-        sound: true,
-      );
-      AppLogger.debug('[FCM] iOS 포그라운드 알림 표시 옵션 설정 완료');
+  Future<void> _initialize() async {
+    try {
+      try {
+        FirebaseMessaging.onBackgroundMessage(
+          _firebaseMessagingBackgroundHandler,
+        );
+        AppLogger.debug('[FCM] Background message handler 등록 완료');
+      } catch (e) {
+        AppLogger.debug('[FCM] Background message handler 등록 실패: $e');
+      }
+
+      await _requestPermission();
+      await setupFlutterNotifications();
+      await _setupMessageHandlers();
+
+      await requestNotificationToken();
+
+      if (_isIOS) {
+        await _messaging.setForegroundNotificationPresentationOptions(
+          alert: true,
+          badge: true,
+          sound: true,
+        );
+        AppLogger.debug('[FCM] iOS 포그라운드 알림 표시 옵션 설정 완료');
+      }
+
+      _isInitialized = true;
+    } finally {
+      _initializationFuture = null;
     }
   }
 
@@ -229,7 +268,9 @@ class NotificationService {
         }
       }
 
-      _messaging.onTokenRefresh.listen((newToken) {
+      _tokenRefreshSubscription ??= _messaging.onTokenRefresh.listen((
+        newToken,
+      ) {
         AppLogger.debug(
           '[FCM] token refreshed token=${AppLogger.redactToken(newToken)}',
         );
@@ -598,34 +639,41 @@ class NotificationService {
 
   Future<void> _setupMessageHandlers() async {
     //foreground message
-    FirebaseMessaging.onMessage.listen(
-      (message) {
-        try {
-          showNotification(message);
-        } catch (error) {
-          AppLogger.debug(
-            '[FCM Foreground] notification display failed '
-            'errorType=${error.runtimeType}',
-          );
-        }
-      },
-      onError: (error) {
-        AppLogger.debug('[FCM Foreground] 리스너 오류: $error');
-      },
-      cancelOnError: false,
-    );
-    AppLogger.debug('[FCM] Foreground message handler 등록 완료');
+    if (_foregroundMessageSubscription == null) {
+      _foregroundMessageSubscription = _onMessage.listen(
+        (message) {
+          try {
+            showNotification(message);
+          } catch (error) {
+            AppLogger.debug(
+              '[FCM Foreground] notification display failed '
+              'errorType=${error.runtimeType}',
+            );
+          }
+        },
+        onError: (error) {
+          AppLogger.debug('[FCM Foreground] 리스너 오류: $error');
+        },
+        cancelOnError: false,
+      );
+      AppLogger.debug('[FCM] Foreground message handler 등록 완료');
+    }
 
     // background message
-    FirebaseMessaging.onMessageOpenedApp.listen((message) {
-      _handleBackgroundMessage(message);
-    });
-    AppLogger.debug('[FCM] Background message handler 등록 완료');
+    if (_openedAppMessageSubscription == null) {
+      _openedAppMessageSubscription = _onMessageOpenedApp.listen((message) {
+        _handleBackgroundMessage(message);
+      });
+      AppLogger.debug('[FCM] Background message handler 등록 완료');
+    }
 
     // opened app
-    final initialMessage = await _messaging.getInitialMessage();
-    if (initialMessage != null) {
-      _handleBackgroundMessage(initialMessage);
+    if (!_initialMessageHandled) {
+      final initialMessage = await _messaging.getInitialMessage();
+      _initialMessageHandled = true;
+      if (initialMessage != null) {
+        _handleBackgroundMessage(initialMessage);
+      }
     }
   }
 

test/core/services/notification_service_test.dart

@@ -140,6 +140,98 @@ void main() {
     },
   );
 
+  test(
+    'repeated initialize handles each notification entry point once',
+    () async {
+      final messaging =
+          _FakeFirebaseMessaging(AuthorizationStatus.notDetermined)
+            ..requestedAuthorizationStatus = AuthorizationStatus.authorized
+            ..initialMessage = const RemoteMessage(
+              data: {'type': 'preparation_step', 'scheduleId': 'initial'},
+            );
+      final localNotifications = _RecordingLocalNotifications();
+      final navigationService = _FakeNavigationService();
+      final foregroundMessages = StreamController<RemoteMessage>.broadcast();
+      final openedAppMessages = StreamController<RemoteMessage>.broadcast();
+      const firebaseMessagingChannel = MethodChannel(
+        'plugins.flutter.io/firebase_messaging',
+      );
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(
+            firebaseMessagingChannel,
+            (_) async => null,
+          );
+      addTearDown(() {
+        TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(firebaseMessagingChannel, null);
+        foregroundMessages.close();
+        openedAppMessages.close();
+      });
+      getIt.registerSingleton<NavigationService>(navigationService);
+      final service = NotificationService.test(
+        messaging: messaging,
+        localNotifications: localNotifications,
+        onMessage: foregroundMessages.stream,
+        onMessageOpenedApp: openedAppMessages.stream,
+      );
+
+      await service.initialize();
+      await service.initialize();
+
+      foregroundMessages.add(
+        const RemoteMessage(data: {'title': 'Title', 'body': 'Body'}),
+      );
+      openedAppMessages.add(
+        const RemoteMessage(
+          data: {'type': 'preparation_step', 'scheduleId': 'opened'},
+        ),
+      );
+      await pumpEventQueue();
+
+      expect(messaging.getInitialMessageCount, 1);
+      expect(localNotifications.shown, hasLength(1));
+      expect(navigationService.pushedRoutes, ['/alarmScreen', '/alarmScreen']);
+    },
+  );
+
+  test('concurrent initialize shares one in-flight setup', () async {
+    final permissionBlocker = Completer<void>();
+    final messaging = _FakeFirebaseMessaging(AuthorizationStatus.notDetermined)
+      ..requestedAuthorizationStatus = AuthorizationStatus.authorized
+      ..requestPermissionBlocker = permissionBlocker
+      ..token = 'fcm-token';
+    final localNotifications = _RecordingLocalNotifications();
+    final remoteDataSource = _FakeNotificationRemoteDataSource();
+    const firebaseMessagingChannel = MethodChannel(
+      'plugins.flutter.io/firebase_messaging',
+    );
+    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+        .setMockMethodCallHandler(firebaseMessagingChannel, (_) async => null);
+    addTearDown(() {
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(firebaseMessagingChannel, null);
+    });
+    getIt
+      ..registerSingleton<AlarmRepository>(_FakeAlarmRepository())
+      ..registerSingleton<NotificationRemoteDataSource>(remoteDataSource);
+    final service = NotificationService.test(
+      messaging: messaging,
+      localNotifications: localNotifications,
+    );
+
+    final firstInitialize = service.initialize();
+    await pumpEventQueue();
+    final secondInitialize = service.initialize();
+
+    permissionBlocker.complete();
+    await Future.wait([firstInitialize, secondInitialize]);
+
+    expect(messaging.requestPermissionCount, 1);
+    expect(messaging.getInitialMessageCount, 1);
+    expect(localNotifications.initializeCount, 1);
+    expect(remoteDataSource.registeredTokens, hasLength(1));
+  });
+
   test(
     'openNotificationSettings returns false when platform launch fails',
     () async {
@@ -212,6 +304,33 @@ void main() {
     },
   );
 
+  test(
+    'repeated token requests keep one refresh registration callback',
+    () async {
+      final messaging = _FakeFirebaseMessaging(AuthorizationStatus.authorized)
+        ..token = 'initial-token';
+      final remoteDataSource = _FakeNotificationRemoteDataSource();
+      getIt
+        ..registerSingleton<AlarmRepository>(_FakeAlarmRepository())
+        ..registerSingleton<NotificationRemoteDataSource>(remoteDataSource);
+      final service = NotificationService.test(
+        messaging: messaging,
+        localNotifications: _RecordingLocalNotifications(),
+        isFlutterLocalNotificationsInitialized: true,
+      );
+
+      await service.requestNotificationToken();
+      await service.requestNotificationToken();
+      messaging.emitTokenRefresh('refreshed-token');
+      await pumpEventQueue();
+
+      expect(
+        remoteDataSource.registeredTokens.map((token) => token.firebaseToken),
+        ['initial-token', 'initial-token', 'refreshed-token'],
+      );
+    },
+  );
+
   test(
     'setupFlutterNotifications initializes local notifications once',
     () async {
@@ -522,6 +641,7 @@ class _FakeFirebaseMessaging implements FirebaseMessaging {
   AuthorizationStatus authorizationStatus;
   AuthorizationStatus requestedAuthorizationStatus =
       AuthorizationStatus.authorized;
+  Completer<void>? requestPermissionBlocker;
   int requestPermissionCount = 0;
   int getTokenCount = 0;
   int getInitialMessageCount = 0;
@@ -547,6 +667,7 @@ class _FakeFirebaseMessaging implements FirebaseMessaging {
   }) async {
     requestPermissionCount += 1;
     authorizationStatus = requestedAuthorizationStatus;
+    await requestPermissionBlocker?.future;
     return _settings(authorizationStatus);
   }