timsquad 3.3.0 → 3.4.0

package/templates/base/skills/mobile/flutter/push-notifications/references/notification-architecture.md

@@ -0,0 +1,340 @@
+---
+title: Notification Service Architecture
+category: guide
+source: internal
+tags: architecture, service, directory, testing, analytics
+---
+
+# Notification Service Architecture
+
+알림 서비스 전체 아키텍처. 디렉토리 구조, 서비스 레이어, 테스트 전략, 분석.
+
+## Key Concepts
+
+- **중앙화**: 알림 관련 코드를 `core/notifications/` 에 집중 (feature 횡단 관심사)
+- **추상화**: `NotificationService` 인터페이스 → FCM/Local/Mock 구현 분리
+- **페이로드 표준화**: 서버-클라이언트 간 알림 데이터 계약
+- **테스트 가능성**: Mock 구현으로 알림 로직 단위 테스트
+
+## Directory Structure
+
+```
+lib/
+├── core/
+│   └── notifications/
+│       ├── notification_service.dart           # 추상 인터페이스
+│       ├── notification_service_impl.dart      # 통합 구현체
+│       ├── fcm/
+│       │   ├── fcm_service.dart                # FCM 초기화 + 토큰
+│       │   ├── fcm_token_manager.dart          # 토큰 서버 동기화
+│       │   └── fcm_message_handler.dart        # 메시지 라우팅
+│       ├── local/
+│       │   ├── local_notification_service.dart  # flutter_local_notifications 래퍼
+│       │   ├── notification_channels.dart       # Android 채널 정의
+│       │   └── scheduled_notification.dart      # 스케줄 알림 관리
+│       ├── models/
+│       │   ├── notification_payload.dart        # 페이로드 모델
+│       │   ├── notification_channel.dart        # 채널 enum + 설정
+│       │   └── notification_action.dart         # 액션 버튼 모델
+│       ├── navigation/
+│       │   └── notification_navigator.dart      # 딥링크 네비게이션
+│       ├── permission/
+│       │   ├── permission_service.dart          # 권한 관리
+│       │   └── permission_prompt_controller.dart # 프리프롬프트 로직
+│       ├── background/
+│       │   ├── background_tasks.dart            # top-level 콜백
+│       │   └── background_task_manager.dart     # 태스크 등록/취소
+│       └── providers/
+│           └── notification_providers.dart       # Riverpod providers
+│
+├── features/
+│   └── notifications/                           # 알림 목록 UI (feature)
+│       ├── data/
+│       │   ├── datasources/
+│       │   │   └── notification_local_datasource.dart
+│       │   └── repositories/
+│       │       └── notification_repository_impl.dart
+│       ├── domain/
+│       │   ├── entities/
+│       │   │   └── app_notification.dart        # 앱 내 알림 모델
+│       │   └── repositories/
+│       │       └── notification_repository.dart  # abstract
+│       └── presentation/
+│           ├── screens/
+│           │   └── notification_list_screen.dart
+│           ├── widgets/
+│           │   └── notification_card.dart
+│           └── providers/
+│               └── notification_list_provider.dart
+```
+
+## Service Layer Design
+
+```dart
+/// 알림 서비스 인터페이스 (테스트 용이성)
+abstract class NotificationService {
+  Future<void> initialize();
+  Future<void> showNotification({
+    required int id,
+    required String title,
+    required String body,
+    String? payload,
+    String? imageUrl,
+    String channelId,
+  });
+  Future<void> scheduleNotification({
+    required int id,
+    required String title,
+    required String body,
+    required DateTime scheduledTime,
+    String? payload,
+  });
+  Future<void> cancelNotification(int id);
+  Future<void> cancelAll();
+  Future<String?> getFcmToken();
+  Stream<String> get onTokenRefresh;
+  Future<AuthorizationStatus> requestPermission();
+  Future<AuthorizationStatus> getPermissionStatus();
+}
+
+/// 통합 구현체
+class NotificationServiceImpl implements NotificationService {
+  final FcmService _fcmService;
+  final LocalNotificationService _localService;
+  final PermissionService _permissionService;
+
+  NotificationServiceImpl({
+    required FcmService fcmService,
+    required LocalNotificationService localService,
+    required PermissionService permissionService,
+  })  : _fcmService = fcmService,
+        _localService = localService,
+        _permissionService = permissionService;
+
+  @override
+  Future<void> initialize() async {
+    await _fcmService.initialize();
+    await _localService.initialize();
+  }
+
+  @override
+  Future<void> showNotification({
+    required int id,
+    required String title,
+    required String body,
+    String? payload,
+    String? imageUrl,
+    String channelId = 'default_channel',
+  }) async {
+    await _localService.show(
+      id: id,
+      title: title,
+      body: body,
+      payload: payload,
+      imageUrl: imageUrl,
+      channelId: channelId,
+    );
+  }
+
+  // ... 나머지 구현
+}
+
+/// Riverpod Provider 구성
+final notificationServiceProvider = Provider<NotificationService>((ref) {
+  return NotificationServiceImpl(
+    fcmService: ref.watch(fcmServiceProvider),
+    localService: ref.watch(localNotificationServiceProvider),
+    permissionService: ref.watch(permissionServiceProvider),
+  );
+});
+```
+
+## Initialization Flow
+
+```
+앱 시작 (main.dart)
+  │
+  ├─ 1. WidgetsFlutterBinding.ensureInitialized()
+  ├─ 2. Firebase.initializeApp()
+  ├─ 3. FirebaseMessaging.onBackgroundMessage(handler) ← top-level 등록
+  ├─ 4. NotificationService.initialize()
+  │     ├─ FcmService.initialize()
+  │     │   ├─ FCM 토큰 획득 + 서버 동기화
+  │     │   └─ onTokenRefresh 구독
+  │     └─ LocalNotificationService.initialize()
+  │         ├─ Android 채널 생성
+  │         └─ 탭 콜백 등록
+  ├─ 5. Workmanager.initialize(callbackDispatcher)
+  └─ 6. runApp(ProviderScope(child: MyApp()))
+        │
+        └─ MyApp.initState()
+            └─ NotificationDeepLinkHandler.initialize()
+                ├─ getInitialMessage() → 딥링크 (cold start)
+                ├─ onMessageOpenedApp.listen → 딥링크 (background)
+                └─ onMessage.listen → 포그라운드 알림 표시
+```
+
+## Testing Strategy
+
+```dart
+/// Mock 알림 서비스 (단위 테스트용)
+class MockNotificationService implements NotificationService {
+  final List<Map<String, dynamic>> shownNotifications = [];
+  final List<Map<String, dynamic>> scheduledNotifications = [];
+  AuthorizationStatus _permissionStatus = AuthorizationStatus.authorized;
+
+  @override
+  Future<void> showNotification({
+    required int id,
+    required String title,
+    required String body,
+    String? payload,
+    String? imageUrl,
+    String channelId = 'default_channel',
+  }) async {
+    shownNotifications.add({
+      'id': id,
+      'title': title,
+      'body': body,
+      'payload': payload,
+      'channelId': channelId,
+    });
+  }
+
+  @override
+  Future<AuthorizationStatus> requestPermission() async {
+    return _permissionStatus;
+  }
+
+  void setPermissionStatus(AuthorizationStatus status) {
+    _permissionStatus = status;
+  }
+
+  // ... 나머지 Mock 구현
+}
+
+/// 알림 네비게이션 테스트
+void main() {
+  group('NotificationNavigator', () {
+    late MockGoRouter mockRouter;
+    late NotificationNavigator navigator;
+
+    setUp(() {
+      mockRouter = MockGoRouter();
+      navigator = NotificationNavigator(router: mockRouter);
+    });
+
+    test('match payload navigates to match detail', () {
+      navigator.navigateFromMessage(RemoteMessage(
+        data: {'type': 'match', 'id': 'match_123'},
+      ));
+
+      verify(() => mockRouter.push('/match/match_123')).called(1);
+    });
+
+    test('unknown type navigates to notifications', () {
+      navigator.navigateFromMessage(RemoteMessage(
+        data: {'type': 'unknown'},
+      ));
+
+      verify(() => mockRouter.push('/notifications')).called(1);
+    });
+  });
+
+  group('NotificationPayload', () {
+    test('toRoute generates correct path', () {
+      final payload = NotificationPayload(type: 'chat', id: 'chat_456');
+      expect(payload.toRoute(), '/chat/chat_456');
+    });
+
+    test('toRoute with explicit route overrides type', () {
+      final payload = NotificationPayload(
+        type: 'match',
+        id: 'match_123',
+        route: '/custom/path',
+      );
+      expect(payload.toRoute(), '/custom/path');
+    });
+  });
+}
+```
+
+## Notification Analytics
+
+```dart
+/// 알림 분석 이벤트
+class NotificationAnalytics {
+  final AnalyticsService _analytics;
+
+  NotificationAnalytics(this._analytics);
+
+  /// 알림 수신 (포그라운드)
+  void trackReceived(RemoteMessage message) {
+    _analytics.logEvent('notification_received', parameters: {
+      'type': message.data['type'] ?? 'unknown',
+      'source': 'fcm',
+      'app_state': 'foreground',
+    });
+  }
+
+  /// 알림 탭 (열림)
+  void trackOpened(NotificationPayload payload, String appState) {
+    _analytics.logEvent('notification_opened', parameters: {
+      'type': payload.type,
+      'action': payload.action ?? 'tap',
+      'app_state': appState, // foreground, background, terminated
+    });
+  }
+
+  /// 액션 버튼 탭
+  void trackAction(String actionId, NotificationPayload payload) {
+    _analytics.logEvent('notification_action', parameters: {
+      'action_id': actionId,
+      'type': payload.type,
+    });
+  }
+
+  /// 권한 요청 결과
+  void trackPermission(AuthorizationStatus status) {
+    _analytics.logEvent('notification_permission', parameters: {
+      'status': status.name,
+    });
+  }
+
+  /// 프리프롬프트 결과
+  void trackPrePrompt(bool accepted) {
+    _analytics.logEvent('notification_pre_prompt', parameters: {
+      'accepted': accepted.toString(),
+    });
+  }
+}
+```
+
+## Common Pitfalls
+
+1. **Provider 접근 in Background**: 백그라운드 핸들러에서 Riverpod Provider 사용 불가 → 직접 의존성 생성
+2. **초기화 순서**: Firebase → FCM 핸들러 등록 → 로컬 알림 → Workmanager (순서 중요)
+3. **딥링크 레이스 컨디션**: `getInitialMessage()` 호출 시 라우터 미준비 → 지연 후 네비게이션
+4. **토큰 갱신 누락**: `onTokenRefresh` 미구독 → 서버에 잘못된 토큰 → 전달 실패 증가
+5. **채널 중요도 변경 불가**: Android 채널 생성 후 중요도 코드 변경 무효 → 새 채널 ID 필요
+6. **iOS 시뮬레이터**: APNs 미지원 → FCM 토큰 발급 불가 → 실기기 필수
+7. **Release 빌드 차이**: Debug에서만 동작하는 로깅이 Release에서 크래시 유발 가능
+8. **동시 알림**: 같은 ID로 show() 호출 시 덮어쓰기 → 고유 ID 전략 필수
+
+## Examples
+
+### 최소 구현 체크리스트
+
+```
+[ ] pubspec.yaml: firebase_core, firebase_messaging, flutter_local_notifications
+[ ] flutterfire configure (google-services.json, GoogleService-Info.plist 자동 생성)
+[ ] iOS: Push Notifications + Background Modes capability
+[ ] Android: AndroidManifest.xml 권한 + 메타데이터
+[ ] Android: 알림 아이콘 (흰색+투명, PNG, 5종 크기)
+[ ] main.dart: 초기화 순서 (Firebase → FCM → Local → Workmanager)
+[ ] 백그라운드 핸들러: top-level, @pragma
+[ ] 알림 채널: 앱 시작 시 생성 (Android)
+[ ] FCM 토큰: 서버 동기화 + 갱신 구독
+[ ] 딥링크: 3가지 앱 상태 (foreground/background/terminated) 처리
+[ ] 권한: 맥락적 요청 + 프리프롬프트 + 설정 유도
+```

package/templates/base/skills/mobile/flutter/push-notifications/references/platform-setup.md

@@ -0,0 +1,286 @@
+---
+title: Platform-Specific Setup (iOS APNs + Android)
+category: guide
+source: internal
+tags: apns, android-channel, xcode, manifest, entitlements
+---
+
+# Platform-Specific Setup (iOS APNs + Android)
+
+iOS APNs 인증 키 설정, Xcode 설정, Android 매니페스트, 알림 채널 상세.
+프로젝트 초기 설정 시 참조.
+
+## Key Concepts
+
+- **iOS**: APNs (Apple Push Notification service) → FCM이 APNs를 통해 iOS 기기에 전달
+- **Android**: FCM이 직접 기기에 전달, Android 8+ (API 26) 채널 필수
+- **인증 방식**: APNs Auth Key (.p8) 권장 (인증서보다 관리 용이, 만료 없음)
+
+## iOS Setup
+
+### 1. Apple Developer Console
+
+```
+1. Apple Developer > Certificates, Identifiers & Profiles
+2. Keys > Create a Key
+   - Name: "FCM APNs Auth Key"
+   - Enable: Apple Push Notifications service (APNs)
+   - Download .p8 파일 (1회만 다운로드 가능!)
+   - Key ID 기록
+
+3. App ID 설정
+   - Identifiers > 앱 선택 > Capabilities
+   - Push Notifications 활성화
+
+4. Team ID 확인
+   - Membership 페이지에서 Team ID 확인
+```
+
+### 2. Firebase Console에 APNs 키 등록
+
+```
+1. Firebase Console > Project Settings > Cloud Messaging
+2. iOS app 선택
+3. APNs authentication key 업로드:
+   - .p8 파일 업로드
+   - Key ID 입력
+   - Team ID 입력
+```
+
+### 3. Xcode 설정
+
+```
+1. Runner.xcworkspace 열기
+
+2. Signing & Capabilities:
+   + Push Notifications         (알림 수신)
+   + Background Modes:
+     ✓ Background fetch         (백그라운드 데이터 가져오기)
+     ✓ Remote notifications     (사일런트 푸시)
+     ✓ Background processing    (workmanager용, iOS 13+)
+
+3. Info.plist (자동 생성되지만 확인):
+   - FirebaseAppDelegateProxyEnabled: YES (기본값)
+
+4. (선택) Notification Service Extension:
+   - File > New > Target > Notification Service Extension
+   - 리치 알림 (이미지 수정, 암호화 해제 등)에 필요
+```
+
+### 4. AppDelegate 설정
+
+```swift
+// ios/Runner/AppDelegate.swift
+import UIKit
+import Flutter
+import Firebase
+
+@main
+@objc class AppDelegate: FlutterAppDelegate {
+  override func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+  ) -> Bool {
+    FirebaseApp.configure()
+
+    // APNs 등록 (firebase_messaging이 자동 처리하지만 명시적으로 해도 무방)
+    if #available(iOS 10.0, *) {
+      UNUserNotificationCenter.current().delegate = self
+    }
+
+    GeneratedPluginRegistrant.register(with: self)
+    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+  }
+
+  // 사일런트 푸시 수신
+  override func application(
+    _ application: UIApplication,
+    didReceiveRemoteNotification userInfo: [AnyHashable : Any],
+    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
+  ) {
+    completionHandler(.newData)
+  }
+}
+```
+
+### 5. Podfile 설정
+
+```ruby
+# ios/Podfile
+platform :ios, '14.0'  # Firebase 최소 요구사항
+
+target 'Runner' do
+  use_frameworks!
+  use_modular_headers!
+
+  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
+end
+
+# Notification Service Extension (리치 알림 사용 시)
+# target 'NotificationService' do
+#   use_frameworks!
+#   pod 'Firebase/Messaging'
+# end
+
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    flutter_additional_ios_build_settings(target)
+  end
+end
+```
+
+## Android Setup
+
+### 1. Firebase Console
+
+```
+1. Firebase Console > Project Settings > 앱 추가 > Android
+2. Android 패키지명 입력 (build.gradle의 applicationId)
+3. google-services.json 다운로드
+4. android/app/google-services.json 에 배치
+```
+
+### 2. build.gradle 설정
+
+```groovy
+// android/build.gradle (프로젝트 레벨)
+buildscript {
+    dependencies {
+        classpath 'com.google.gms:google-services:4.4.2'
+    }
+}
+
+// android/app/build.gradle (앱 레벨)
+plugins {
+    id 'com.google.gms.google-services'
+}
+
+android {
+    compileSdk 35
+
+    defaultConfig {
+        minSdk 23  // FCM 최소 요구
+        targetSdk 35
+    }
+}
+```
+
+### 3. AndroidManifest.xml
+
+```xml
+<!-- android/app/src/main/AndroidManifest.xml -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- 알림 권한 (Android 13+) -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
+
+  <!-- 정확한 알림 스케줄링 (선택) -->
+  <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>
+
+  <!-- 백그라운드 작업 (workmanager) -->
+  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
+
+  <!-- 진동 (알림용) -->
+  <uses-permission android:name="android.permission.VIBRATE"/>
+
+  <application
+    android:name="${applicationName}"
+    android:icon="@mipmap/ic_launcher">
+
+    <!-- FCM 기본 알림 채널 (앱이 자체 채널 생성 전 폴백) -->
+    <meta-data
+      android:name="com.google.firebase.messaging.default_notification_channel_id"
+      android:value="default_channel" />
+
+    <!-- FCM 기본 알림 아이콘 -->
+    <meta-data
+      android:name="com.google.firebase.messaging.default_notification_icon"
+      android:resource="@mipmap/ic_notification" />
+
+    <!-- FCM 기본 알림 색상 -->
+    <meta-data
+      android:name="com.google.firebase.messaging.default_notification_color"
+      android:resource="@color/notification_color" />
+
+    <activity
+      android:name=".MainActivity"
+      android:launchMode="singleTop">
+      <!-- 딥링크 인텐트 필터 -->
+      <intent-filter>
+        <action android:name="FLUTTER_NOTIFICATION_CLICK"/>
+        <category android:name="android.intent.category.DEFAULT"/>
+      </intent-filter>
+    </activity>
+
+  </application>
+</manifest>
+```
+
+### 4. 알림 아이콘 준비
+
+```
+Android 알림 아이콘 요구사항:
+- 흰색 + 투명 배경 (시스템이 색상 적용)
+- PNG 형식 (벡터 SVG 불가)
+- 크기별 배치:
+  android/app/src/main/res/
+  ├── mipmap-mdpi/ic_notification.png      (24x24)
+  ├── mipmap-hdpi/ic_notification.png      (36x36)
+  ├── mipmap-xhdpi/ic_notification.png     (48x48)
+  ├── mipmap-xxhdpi/ic_notification.png    (72x72)
+  └── mipmap-xxxhdpi/ic_notification.png   (96x96)
+
+알림 색상:
+  android/app/src/main/res/values/colors.xml
+  <resources>
+    <color name="notification_color">#FF6B35</color>
+  </resources>
+```
+
+### 5. Android 알림 채널 가이드
+
+```
+채널 설계 원칙:
+- 사용자가 개별 제어할 수 있는 단위로 분리
+- 중요도(Importance)에 따라 분류
+- 한번 생성된 채널의 중요도는 코드로 변경 불가 (사용자만 변경 가능)
+
+권장 채널 구성:
+┌──────────────┬─────────────┬──────────────────────────────┐
+│ Channel ID   │ Importance  │ 용도                          │
+├──────────────┼─────────────┼──────────────────────────────┤
+│ matches      │ HIGH        │ 매치 초대, 변경, 시작 알림     │
+│ chat         │ DEFAULT     │ 채팅 메시지                    │
+│ reminders    │ HIGH        │ 매치 시작 전 리마인더          │
+│ system       │ LOW         │ 앱 업데이트, 공지              │
+│ silent       │ MIN         │ 백그라운드 동기화 (사용자 미표시) │
+└──────────────┴─────────────┴──────────────────────────────┘
+
+Importance 레벨:
+- MAX: 화면 상단 피크 + 소리 + 진동
+- HIGH: 헤드업 알림 + 소리 + 진동
+- DEFAULT: 소리 + 진동 (헤드업 X)
+- LOW: 소리 X, 진동 X (상태바에만)
+- MIN: 상태바에도 최소 표시 (접으면 보임)
+```
+
+## Common Pitfalls
+
+### iOS
+1. **APNs 키 vs 인증서**: .p8 Auth Key 사용 권장 (만료 없음, 모든 앱에 공유 가능)
+2. **시뮬레이터**: iOS 시뮬레이터는 APNs 미지원 → 실제 기기에서만 푸시 테스트
+3. **Provisional 알림**: iOS 12+ 임시 권한 → 알림 센터에 조용히 전달
+4. **Background Modes 누락**: Xcode에서 Remote notifications 체크 안 하면 사일런트 푸시 미수신
+5. **Production vs Sandbox**: APNs 환경 자동 전환 (Debug=Sandbox, Release=Production)
+
+### Android
+1. **채널 생성 타이밍**: 앱 시작 시 채널 생성 필수 (알림 표시 전)
+2. **알림 아이콘**: 흰색+투명이 아니면 회색 사각형으로 표시
+3. **targetSdk 34+**: `SCHEDULE_EXACT_ALARM` 권한이 기본 거부 → `canScheduleExactAlarms()` 체크
+4. **Doze 모드**: 고우선순위 FCM은 Doze 통과, 일반 메시지는 지연 가능
+5. **채널 중요도 변경**: 코드로 변경 불가 → 새 채널 ID 생성하거나 사용자가 직접 변경
+
+### 공통
+1. **google-services.json / GoogleService-Info.plist**: 반드시 .gitignore에 추가 (보안)
+2. **FlutterFire CLI**: `flutterfire configure` 로 자동 설정 권장
+3. **에뮬레이터**: Android 에뮬레이터는 Google Play Services 포함 이미지 필요