sam-docs/dev/changes/20251230_react_fcm_push_notification.md

변경 내용 요약

날짜: 2025-12-30 14:30 작업자: Claude Code 관련 문서: docs/dev_plans/react-fcm-push-notification-plan.md

📋 변경 개요

React 프로젝트에 FCM 푸시 알림 기능 추가. Capacitor 네이티브 앱(iOS/Android)에서 dev.sam.kr 웹뷰 로드 시 푸시 알림을 지원합니다.

• 포팅 원본: mng/public/js/fcm.js
• 백엔드 API 변경 없음 (기존 /push/* 엔드포인트 재사용)

📁 수정된 파일

신규 생성 (4개)

파일	용량	용도
react/src/lib/capacitor/fcm.ts	9.1KB	FCM 핵심 로직 (토큰 관리, 알림 처리)
react/src/hooks/useFCM.ts	3.3KB	React 훅 (sonner 토스트 연동)
react/src/contexts/FCMProvider.tsx	1.8KB	앱 전역 FCM 초기화 Provider
react/public/sounds/*.wav	1.6MB	알림 사운드 (mng에서 복사)

수정 (2개)

파일	변경 내용
react/src/app/[locale]/(protected)/layout.tsx	FCMProvider 추가
react/src/lib/auth/logout.ts	로그아웃 시 FCM 토큰 해제 연동

의존성 추가 (3개)

패키지	버전	용도
@capacitor/core	^8.0.0	Capacitor 코어
@capacitor/push-notifications	^8.0.0	푸시 알림 플러그인
@capacitor/app	^8.0.0	앱 상태 감지

🔧 상세 변경 사항

1. FCM 유틸리티 (fcm.ts)

주요 함수:

• initializeFCM(): FCM 초기화 (권한 요청, 토큰 발급, 리스너 등록)
• unregisterFCMToken(): 토큰 해제 (로그아웃 시)
• isCapacitorNative(): 네이티브 환경 체크

특징:

• Next.js 프록시 패턴 사용 (/api/proxy/v1/push/*)
• HttpOnly 쿠키 자동 포함 (credentials: 'include')
• 포그라운드 알림 콜백 지원

2. useFCM 훅

기능:

• 로그인 상태에서 자동 FCM 초기화
• 포그라운드 알림 → sonner 토스트
• 알림 타입별 스타일 (error, warning, success, info)

3. FCMProvider

위치: (protected)/layout.tsx

• RootProvider 안에서 FCM 초기화
• 인증된 페이지에서만 동작

4. 로그아웃 연동

logout.ts 변경:

// 4. FCM 토큰 해제 (Capacitor 네이티브 앱에서만 실행)
if (isCapacitorNative()) {
  await unregisterFCMToken();
  console.log('[Logout] FCM token unregistered');
}

✅ 테스트 체크리스트

• Capacitor 앱에서 dev.sam.kr 로드 확인
• 로그인 후 FCM 토큰 등록 확인 (콘솔 로그)
• 포그라운드 알림 수신 → sonner 토스트 표시
• 알림 사운드 재생 확인
• 알림 클릭 → URL 이동 확인
• 로그아웃 → FCM 토큰 해제 확인
• 웹 브라우저에서는 FCM 로직 스킵 확인

⚠️ 배포 시 주의사항

1. iOS: Xcode에서 Push Notification Capability 활성화 필요
2. Android: google-services.json 설정 확인
3. 프록시: /api/proxy/v1/push/* 라우트 존재 확인

🔗 관련 문서

• FCM 연동 계획
• Capacitor Push Notifications
• mng/public/js/fcm.js (포팅 원본)