권혁성
db63fcff85
- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동) - 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/) - 기획팀 폴더 requests/ 생성 - plans/ → dev/dev_plans/ 이름 변경 - README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용) - resources.md 신규 (노션 링크용, assets/brochure 이관 예정) - CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동 - 전체 참조 경로 업데이트 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
95 lines
3.2 KiB
Markdown
95 lines
3.2 KiB
Markdown
# 변경 내용 요약
|
|
|
|
**날짜:** 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) (포팅 원본) |