# 변경 내용 요약

**날짜:** 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 변경:**
```typescript
// 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 연동 계획](../plans/react-fcm-push-notification-plan.md)
- [Capacitor Push Notifications](https://capacitorjs.com/docs/apis/push-notifications)
- [mng/public/js/fcm.js](../../mng/public/js/fcm.js) (포팅 원본)