nomadcode/agent-ops/rules/domain/push-notification/rules.md

name	description	type
push-notification	FCM 기반 푸시 알림 수신, 표시, ACK 처리 담당 (Core Domain)	core

Push Notification

목적 / 책임

• Firebase Cloud Messaging(FCM) 메시지 수신 및 처리
• 포그라운드/백그라운드/종료 상태별 알림 표시
• 알림 수신 ACK를 Mattermost 서버로 전달
• Flutter ↔ Android 간 이벤트 채널 통신

포함 경로

• android/app/src/main/java/com/tokilabs/mattermost/MattermostFirebaseMessagingService.kt
• android/app/src/main/java/com/tokilabs/mattermost/helpers/CustomPushNotificationHelper.java
• android/app/src/main/java/com/tokilabs/mattermost/helpers/NotificationHelper.kt
• android/app/src/main/java/com/tokilabs/mattermost/NotificationReplyBroadcastReceiver.java
• android/app/src/main/java/com/tokilabs/mattermost/NotificationDismissService.java
• android/app/src/main/java/com/tokilabs/mattermost/ReceiptDelivery.java
• lib/services/push_notification_service.dart
• lib/services/push_notification_background.dart

제외 경로

• lib/ 내 UI 화면 관련 코드 (flutter-app 도메인)
• android/.../db/ (database 도메인)
• android/.../helpers/Network.kt (network 도메인)

주요 구성 요소

• MattermostFirebaseMessagingService: FCM 메시지 수신 진입점, 포그라운드/백그라운드 분기
• CustomPushNotificationHelper: 알림 UI 빌드, 아바타 이미지 처리
• NotificationHelper: 알림 ID, 그룹 요약 관리
• ReceiptDelivery: /api/v4/notifications/ack ACK 전송
• PushNotificationService: Flutter 싱글톤 서비스, EventChannel 수신
• push_notification_background.dart: 백그라운드 FCM 핸들러

유지할 패턴

• FCM 수신 → MattermostFirebaseMessagingService → CustomPushNotificationHelper 흐름
• EventChannel을 통한 Android → Flutter 이벤트 전달
• 알림 표시 전 반드시 ACK 전송 (ReceiptDelivery)
• Singleton 패턴: PushNotificationService.instance

다른 도메인과의 경계

• database: push-notification은 알림 데이터를 읽기만 하고, DB 스키마/쿼리 구현은 database 도메인
• network: HTTP 통신 구현은 network 도메인의 Network.kt 사용
• flutter-app: 알림 탭 시 화면 라우팅은 flutter-app 도메인

금지 사항

• DB 스키마 변경을 이 도메인에서 직접 하지 않는다.
• 알림 채널 설정은 MainApplication.kt(android-native 도메인)에서 한다.