🚀 [기능개선][알림] FCM 토픽(Topic) 기반 알림 구독/발송 기능 추가

[Chuseok22]

🚀 [기능개선][알림] FCM 토픽(Topic) 기반 알림 구독/발송 기능 추가

📝 현재 문제점

현재 알림은 FcmToken(RedisHash)에 저장된 토큰 단위로만 발송되고 있습니다. 코드상으로는 WebNotificationService가

• 단일 사용자(sendToMember)
• 사용자 리스트(sendToMemberList)
• 전체(sendToAll)

를 모두 “토큰 반복(loop)” 방식으로 처리합니다.
이 방식은 동일 관심사를 가진 대규모 사용자에게 선택적/효율적 브로드캐스트가 어렵고, 토픽별(예: 공연 카테고리, 지역, 아티스트)로 구독/해지를 제공하지 못합니다. 또한 운영 관점에서 “구독자 수, 구독 현황, 실패율” 등을 주제별로 모니터링하기가 제한적입니다.

🛠️ 해결 방안 / 제안 기능

목표: FCM Topic을 활용해 ‘구독/해지 + 토픽 발송’을 지원하고, 대규모/고효율 운영이 가능하도록 서비스 레이어와 저장 구조를 정리합니다.

1. 서버 API 설계 (App/Web 공용)

• POST /api/v1/notifications/topics/subscribe
  • Body: memberId, deviceType, topicName
  • 기능: 토큰(들)을 해당 토픽에 구독. (토큰 조회: 기존 FcmTokenService)
• POST /api/v1/notifications/topics/unsubscribe
  • Body: memberId, deviceType, topicName
  • 기능: 토큰(들)을 해당 토픽에서 해지.
• GET /api/v1/notifications/topics/my
  • Query: memberId
  • 기능: 사용자의 현재 구독 토픽 목록 조회.
• (내부/운영) POST /api/v1/notifications/topics/{topicName}/send
  • Body: NotificationPayload
  • 기능: 해당 토픽 구독자 전체에 토픽 발송.

권한: topics/{topicName}/send는 관리자/운영 권한만 허용(RBAC 적용).

2. 서비스 레이어 및 책임 분리 (SRP)

• TopicSubscriptionService (신규)
  • subscribe(memberId, deviceType, topicName)
  • unsubscribe(memberId, deviceType, topicName)
  • 내부에서 FcmTokenService로 토큰 조회 → FirebaseMessaging.subscribeToTopic(...) / unsubscribeFromTopic(...) 호출
  • **배치 처리(FCM 허용 한도 내)**로 성능 최적화 및 부분 실패 리포트 수집
• TopicNotificationService (신규)
  • sendToTopic(topicName, NotificationPayload payload)
  • 내부에서 Message.builder().setTopic(topicName) 구성 후 발송
  • 전송 결과/실패율 메트릭 기록
• 기존 WebNotificationService는 “토큰 직접 발송”에 집중 → 토픽 발송은 분리하여 단일 책임 유지.

3. 데이터 모델링/저장

• 옵션 A (Lightweight): 서버 측 구독 상태는 저장하지 않고, FCM 상태만 신뢰.
  • 장점: 구현 간단, 저장소 추가 불필요
  • 단점: 구독 현황/통계/감사 로그 취약
• 옵션 B (권장): 로컬 영속화로 감사 및 운영 편의성 확보
  • RDB 테이블(예: notification_topic_subscription) 제안
    • id(PK), member_id(UUID), device_type, topic_name, fcm_token_id, subscribed_at, unsubscribed_at, is_active
  • 사유: 현재 FcmToken은 Redis TTL 구조로 단기 캐시 성격이 강함. 토픽 구독은 장기 상태이므로 RDB가 운영/통계에 적합.
• 정합성: 서버 상태와 FCM 상태 간 불일치 시 주기적 리컨실리에이션 잡(선택).

4. 토픽 네이밍 및 검증

• 허용 문자/길이 등 FCM 규칙에 맞는 토픽명 밸리데이션 적용.
• 사전 정의된 업무 표준 토픽 스키마(예: artist.{id}, genre.{code}, region.{code}) 확정 후 화이트리스트/패턴 검사.

5. 운영/관찰 가능성(Observability)

• 구독/해지/발송에 대해 구조화 로그, 메트릭(요청 수, 성공/실패 수, 지연 시간), 알람 연동
• 부분 실패 발생 시 상세 리포트(실패 토큰 목록, 사유 코드) 저장

6. 에러 처리/내결함성

• 부분 실패 시 재시도 전략(지수 백오프), Idempotency-Key(요청 중복 방지), 운영자용 재처리 엔드포인트 제공

7. 보안/권한

• 토픽 발송 엔드포인트는 관리자 역할만 허용, API 키/권한 토큰 요구
• 사용자의 memberId는 인증 컨텍스트에서 확인(스푸핑 방지)

8. 점진적 적용(마이그레이션)

• 초기에는 특정 토픽(파일럿)으로 시작 → 안정화 후 범위 확장
• 기존 “전체 발송”은 토픽 all로 대체 가능(이행 기간 병행 운영)

🙋‍♂️ 담당자

• 백엔드: @Chuseok22
• 프론트엔드: @heesu52
• 디자인: 이름

[github-actions]

Chuseok22 Issue Helper

브랜치명

20251111_#623_FCM_토픽_Topic_기반_알림_구독_발송_기능_추가

커밋 메시지

FCM_토픽_Topic_기반_알림_구독_발송_기능_추가 : feat : {변경 사항에 대한 설명} https://github.com/Team-TicketMate/ticketmate-server/issues/623