feat(web): PWA 푸시 알림 시스템 구현

[choihooo]

🎯 Summary

이 PR의 목적을 한 줄로 요약해주세요
Firebase Cloud Messaging(FCM) 기반 PWA 푸시 알림 시스템 구현 - 댓글/답글/공지사항 알림 지원

---

🔴 AS-IS

기존 상태 또는 문제점

• 사용자가 새 댓글/답글/공지사항을 확인하려면 직접 사이트에 방문해야 함
• 실시간 알림이 없어서 소통 지연 발생
• 모바일 PWA 환경에서 네이티브 앱처럼 알림을 받을 수 없음

🟢 TO-BE

변경 후 상태 또는 개선점

• FCM 기반 푸시 알림: 브라우저 알림으로 실시간 수신
• 알림 종류별 설정: 5가지 알림 타입 개별 켜기/끄기
  • 게시판 댓글 (내 게시글에 댓글)
  • 게시판 답글 (내 댓글에 답글)
  • 포스트 댓글 (내 포스트에 댓글)
  • 포스트 답글 (내 댓글에 답글)
  • 공지사항 (새 공지사항 게시)
• 포그라운드/백그라운드 지원: 앱이 켜져 있을 때는 sonner 토스트, 꺼져 있을 때는 시스템 알림
• 알림 설정 페이지: /profile/notifications에서 개인 설정 관리
• DB 연동: 토큰 저장, 알림 선호도 관리
• 환경변수 분리: Firebase Service Account를 6개 개별 환경변수로 설정

---

💬 참고사항

리뷰어가 알아야 할 내용, 논의 포인트, 주의사항 등

기술 스택

• Firebase Admin SDK (서버): 메시지 전송
• Firebase Cloud Messaging: 푸시 알림 플랫폼
• Service Worker: 백그라운드 메시지 수신
• Supabase: notification_push_tokens, notification_preferences 테이블

환경 변수 추가 필요 (6개)

# Firebase Admin Service Account (JSON → 개별 환경변수)
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_PRIVATE_KEY_ID=1234567890abcdef
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=firebase-adminsdk@your-project.iam.gserviceaccount.com
FIREBASE_CLIENT_ID=123456789012345678901

# Firebase Web App
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_VAPID_KEY=

구현 파일

• packages/web/src/app/api/notification-preferences/ - 알림 설정 API
• packages/web/src/app/api/push/ - 토큰 구독/해지 API
• packages/web/src/components/settings/push-notification-settings.tsx - 설정 UI
• packages/web/src/hooks/use-push-notification.ts - 푸시 알림 훅
• packages/web/src/lib/push.ts - 서버사이드 전송 로직
• packages/web/src/lib/firebase/client.ts - FCM 클라이언트
• packages/web/src/lib/firebase/admin.ts - FCM Admin SDK (환경변수 분리)
• packages/shared/src/db/schema.ts - DB 스키마 추가

주의사항

• Firebase Service Account Key: .gitignore로 보안 처리됨
• 환경변수 분리: JSON 하나 대신 6개 개별 변수로 설정 (더 명확)
• private_key 처리: 환경변수의 \\n을 \n으로 자동 변환
• Safari PWA: Service Worker 제약으로 백그라운드 알림 제한적
• 알림 권한: 브라우저 설정에서 차단 시 재요청 불가

테스트 플랜

• 브라우저 알림 권한 요청 동작 확인
• 댓글 작성 시 상대방에게 알림 전송 확인
• 알림 설정 켜기/끄기 동작 확인
• 포그라운드/백그라운드 알림 각각 확인
• 여러 디바이스에서 토큰 관리 확인

---

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
study-admin-web	Ready	Preview, Comment	Mar 16, 2026 5:17pm