timsquad 3.3.0 → 3.4.0

package/templates/base/skills/mobile/flutter/push-notifications/rules/local-notifications.md

@@ -0,0 +1,262 @@
+---
+title: Local Notifications
+impact: CRITICAL
+impactDescription: "채널 미설정 → Android 8+ 알림 미표시, 초기화 누락 → 런타임 크래시"
+tags: flutter-local-notifications, channel, schedule, timezone
+---
+
+## Local Notifications
+
+**Impact: CRITICAL (채널 미설정 → Android 8+ 알림 미표시, 초기화 누락 → 런타임 크래시)**
+
+flutter_local_notifications 설정, Android 채널, 스케줄 알림, FCM 포그라운드 연동.
+
+### 초기화
+
+**Incorrect (플랫폼 설정 불완전):**
+```dart
+final plugin = FlutterLocalNotificationsPlugin();
+await plugin.initialize(const InitializationSettings());
+// → Android: 아이콘 미지정 → 크래시
+// → iOS: 권한 미요청 → 알림 미표시
+```
+
+**Correct (완전한 초기화):**
+```dart
+class NotificationService {
+  static final NotificationService instance = NotificationService._();
+  NotificationService._();
+
+  final FlutterLocalNotificationsPlugin _plugin =
+      FlutterLocalNotificationsPlugin();
+
+  Future<void> initialize() async {
+    // Android 설정
+    const androidSettings = AndroidInitializationSettings(
+      '@mipmap/ic_notification', // res/mipmap 또는 res/drawable
+    );
+
+    // iOS 설정
+    const iosSettings = DarwinInitializationSettings(
+      requestAlertPermission: false,  // 별도 타이밍에 요청
+      requestBadgePermission: false,
+      requestSoundPermission: false,
+      // 포그라운드 알림 표시 콜백
+      notificationCategories: [
+        DarwinNotificationCategory(
+          'match_invite',
+          actions: [
+            DarwinNotificationAction.plain('accept', 'Accept'),
+            DarwinNotificationAction.plain('decline', 'Decline'),
+          ],
+        ),
+      ],
+    );
+
+    await _plugin.initialize(
+      const InitializationSettings(
+        android: androidSettings,
+        iOS: iosSettings,
+      ),
+      // 알림 탭 콜백
+      onDidReceiveNotificationResponse: _onNotificationTap,
+      // 백그라운드 알림 탭 콜백
+      onDidReceiveBackgroundNotificationResponse: _onBackgroundNotificationTap,
+    );
+
+    // Android 알림 채널 생성
+    await _createNotificationChannels();
+  }
+
+  void _onNotificationTap(NotificationResponse response) {
+    final payload = response.payload;
+    if (payload != null) {
+      // 페이로드 파싱 → 딥링크 네비게이션
+      final data = jsonDecode(payload) as Map<String, dynamic>;
+      // NavigationService 또는 GoRouter로 네비게이션
+      NavigationService.instance.navigateFromPayload(data);
+    }
+  }
+
+  // 백그라운드 탭 핸들러 — top-level 또는 static 필수
+  @pragma('vm:entry-point')
+  static void _onBackgroundNotificationTap(NotificationResponse response) {
+    // 백그라운드에서 알림 탭 시 호출
+    // 앱이 다시 열리면 getInitialMessage 또는 onMessageOpenedApp에서 처리
+  }
+}
+```
+
+### Android 알림 채널
+
+```dart
+Future<void> _createNotificationChannels() async {
+  final androidPlugin =
+      _plugin.resolvePlatformSpecificImplementation<
+          AndroidFlutterLocalNotificationsPlugin>();
+
+  if (androidPlugin == null) return;
+
+  // 매치 알림 (높은 중요도 → 헤드업 알림)
+  await androidPlugin.createNotificationChannel(
+    const AndroidNotificationChannel(
+      'matches',           // channelId
+      'Match Alerts',      // channelName
+      description: 'Notifications for match invites and updates',
+      importance: Importance.high,
+      enableVibration: true,
+      playSound: true,
+    ),
+  );
+
+  // 채팅 메시지 (기본 중요도)
+  await androidPlugin.createNotificationChannel(
+    const AndroidNotificationChannel(
+      'chat',
+      'Chat Messages',
+      description: 'New chat messages',
+      importance: Importance.defaultImportance,
+    ),
+  );
+
+  // 시스템 공지 (낮은 중요도 → 소리 없음)
+  await androidPlugin.createNotificationChannel(
+    const AndroidNotificationChannel(
+      'system',
+      'System Notifications',
+      description: 'App updates and system alerts',
+      importance: Importance.low,
+      playSound: false,
+    ),
+  );
+
+  // 사일런트 (최소 중요도 → 상태바에만)
+  await androidPlugin.createNotificationChannel(
+    const AndroidNotificationChannel(
+      'silent',
+      'Background Sync',
+      description: 'Silent data synchronization',
+      importance: Importance.min,
+      playSound: false,
+      enableVibration: false,
+    ),
+  );
+}
+```
+
+### 알림 표시
+
+```dart
+/// FCM 포그라운드 메시지를 로컬 알림으로 표시
+Future<void> showNotification({
+  required int id,
+  required String title,
+  required String body,
+  String? payload,
+  String? imageUrl,
+  String channelId = 'matches',
+}) async {
+  // Android 상세 설정
+  final androidDetails = AndroidNotificationDetails(
+    channelId,
+    _getChannelName(channelId),
+    importance: Importance.high,
+    priority: Priority.high,
+    // 큰 이미지 (선택)
+    styleInformation: imageUrl != null
+        ? BigPictureStyleInformation(
+            FilePathAndroidBitmap(await _downloadImage(imageUrl)),
+            contentTitle: title,
+            summaryText: body,
+          )
+        : BigTextStyleInformation(body),
+  );
+
+  // iOS 상세 설정
+  const iosDetails = DarwinNotificationDetails(
+    presentAlert: true,
+    presentBadge: true,
+    presentSound: true,
+  );
+
+  await _plugin.show(
+    id,
+    title,
+    body,
+    NotificationDetails(
+      android: androidDetails,
+      iOS: iosDetails,
+    ),
+    payload: payload,
+  );
+}
+```
+
+### 스케줄 알림
+
+```dart
+import 'package:timezone/timezone.dart' as tz;
+import 'package:timezone/data/latest_all.dart' as tz;
+
+/// 초기화 시 timezone 설정
+Future<void> initializeTimezone() async {
+  tz.initializeTimeZones();
+  // flutter_timezone 패키지로 디바이스 타임존 감지
+  final timeZoneName = await FlutterTimezone.getLocalTimezone();
+  tz.setLocalLocation(tz.getLocation(timeZoneName));
+}
+
+/// 매치 시작 30분 전 리마인더
+Future<void> scheduleMatchReminder({
+  required String matchId,
+  required String matchTitle,
+  required DateTime matchTime,
+}) async {
+  final scheduledTime = tz.TZDateTime.from(
+    matchTime.subtract(const Duration(minutes: 30)),
+    tz.local,
+  );
+
+  // 과거 시간이면 스킵
+  if (scheduledTime.isBefore(tz.TZDateTime.now(tz.local))) return;
+
+  await _plugin.zonedSchedule(
+    matchId.hashCode,  // 알림 ID (취소용)
+    'Match Reminder',
+    '$matchTitle starts in 30 minutes!',
+    scheduledTime,
+    const NotificationDetails(
+      android: AndroidNotificationDetails(
+        'reminders',
+        'Reminders',
+        importance: Importance.high,
+      ),
+      iOS: DarwinNotificationDetails(),
+    ),
+    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
+    matchDateTimeComponents: null, // 1회성
+    payload: jsonEncode({'type': 'match', 'id': matchId}),
+  );
+}
+
+/// 특정 알림 취소
+Future<void> cancelReminder(String matchId) async {
+  await _plugin.cancel(matchId.hashCode);
+}
+
+/// 모든 알림 취소
+Future<void> cancelAll() async {
+  await _plugin.cancelAll();
+}
+```
+
+### 규칙
+
+- Android 알림 아이콘 → `res/mipmap` 또는 `res/drawable` 에 배치 (벡터 X, PNG 필수)
+- Android 8+ → 채널 미생성 시 알림 미표시 (앱 시작 시 채널 생성 필수)
+- 채널 중요도 → `high`(헤드업), `default`(소리), `low`(소리 X), `min`(사일런트)
+- 스케줄 알림 → `timezone` + `flutter_timezone` 패키지 필수
+- `zonedSchedule` → `exactAllowWhileIdle` (Doze 모드에서도 정확한 알림)
+- 알림 ID → 고유값 사용 (같은 ID 시 덮어쓰기), 취소 시 동일 ID
+- iOS `DarwinInitializationSettings` → 초기화 시 권한 요청 false, 별도 타이밍에 요청
+- 백그라운드 탭 콜백 → `@pragma('vm:entry-point')` + static/top-level

package/templates/base/skills/mobile/flutter/push-notifications/rules/notification-handling.md

@@ -0,0 +1,210 @@
+---
+title: Notification Handling (All App States)
+impact: CRITICAL
+impactDescription: "상태별 미처리 → 알림 누락/중복, 사용자 혼란"
+tags: fcm, foreground, background, terminated, onMessage
+---
+
+## Notification Handling (All App States)
+
+**Impact: CRITICAL (상태별 미처리 → 알림 누락/중복, 사용자 혼란)**
+
+FCM 메시지는 앱 상태(포그라운드/백그라운드/종료)에 따라 처리 경로가 다름.
+3가지 상태 모두 빠짐없이 처리해야 알림 누락 없음.
+
+### 앱 상태별 메시지 수신 경로
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    FCM Message 도착                       │
+├──────────────┬──────────────────┬────────────────────────┤
+│  Foreground  │   Background     │    Terminated          │
+│  (앱 활성)    │  (앱 최소화)      │   (앱 종료)             │
+├──────────────┼──────────────────┼────────────────────────┤
+│ onMessage    │ onBackgroundMsg  │ onBackgroundMsg        │
+│ 스트림 수신   │ top-level 함수   │ top-level 함수          │
+│              │                  │                        │
+│ 자동 표시 X   │ 자동 표시 O       │ 자동 표시 O             │
+│ → 로컬 알림   │ (notification    │ (notification          │
+│   직접 표시   │  payload 있으면)  │  payload 있으면)        │
+├──────────────┼──────────────────┼────────────────────────┤
+│       알림 탭 시                                          │
+├──────────────┬──────────────────┬────────────────────────┤
+│ (이미 활성)   │ onMessageOpened  │ getInitialMessage      │
+│              │ App 스트림       │ (1회, cold start)       │
+└──────────────┴──────────────────┴────────────────────────┘
+```
+
+### 포그라운드 메시지 처리
+
+**Incorrect (포그라운드에서 알림 미표시):**
+```dart
+FirebaseMessaging.onMessage.listen((message) {
+  // 데이터만 처리하고 사용자에게 알림 미표시
+  print('Got message: ${message.notification?.title}');
+  // → 사용자는 알림이 왔는지 모름
+});
+```
+
+**Correct (로컬 알림으로 포그라운드 표시):**
+```dart
+class NotificationHandler {
+  final FirebaseMessaging _messaging = FirebaseMessaging.instance;
+  final NotificationService _notificationService;
+  final GoRouter _router;
+
+  NotificationHandler({
+    required NotificationService notificationService,
+    required GoRouter router,
+  })  : _notificationService = notificationService,
+        _router = router;
+
+  void initialize() {
+    // 1. 포그라운드 메시지 → 로컬 알림 표시
+    FirebaseMessaging.onMessage.listen(_handleForegroundMessage);
+
+    // 2. 백그라운드에서 알림 탭 → 네비게이션
+    FirebaseMessaging.onMessageOpenedApp.listen(_handleNotificationTap);
+
+    // 3. 종료 상태에서 알림 탭 → 네비게이션 (cold start)
+    _handleInitialMessage();
+  }
+
+  Future<void> _handleForegroundMessage(RemoteMessage message) async {
+    final notification = message.notification;
+    if (notification == null) {
+      // data-only 메시지 → 사일런트 처리 (데이터 동기화 등)
+      await _handleDataMessage(message.data);
+      return;
+    }
+
+    // 포그라운드: FCM이 자동 표시하지 않으므로 로컬 알림으로 직접 표시
+    await _notificationService.showNotification(
+      id: message.hashCode,
+      title: notification.title ?? '',
+      body: notification.body ?? '',
+      payload: jsonEncode(message.data),
+      imageUrl: notification.android?.imageUrl ?? notification.apple?.imageUrl,
+    );
+  }
+
+  Future<void> _handleNotificationTap(RemoteMessage message) async {
+    _navigateFromPayload(message.data);
+  }
+
+  Future<void> _handleInitialMessage() async {
+    // 종료 상태에서 알림 탭으로 앱 시작 시
+    // getInitialMessage()는 1회만 값을 반환 (이후 null)
+    final initialMessage = await _messaging.getInitialMessage();
+    if (initialMessage != null) {
+      // 약간의 지연 — 라우터 초기화 대기
+      await Future.delayed(const Duration(milliseconds: 500));
+      _navigateFromPayload(initialMessage.data);
+    }
+  }
+
+  void _navigateFromPayload(Map<String, dynamic> data) {
+    final type = data['type'] as String?;
+    final id = data['id'] as String?;
+
+    switch (type) {
+      case 'match':
+        if (id != null) _router.push('/match/$id');
+      case 'chat':
+        if (id != null) _router.push('/chat/$id');
+      case 'announcement':
+        _router.push('/announcements');
+      default:
+        _router.push('/notifications');
+    }
+  }
+
+  Future<void> _handleDataMessage(Map<String, dynamic> data) async {
+    // 사일런트 푸시: 데이터 동기화, 캐시 무효화 등
+    final action = data['action'] as String?;
+    switch (action) {
+      case 'sync_matches':
+        // 매치 데이터 새로고침 트리거
+        break;
+      case 'invalidate_cache':
+        // 특정 캐시 무효화
+        break;
+    }
+  }
+}
+```
+
+### 백그라운드 메시지 핸들러
+
+```dart
+// main.dart (또는 별도 파일) — 반드시 top-level
+@pragma('vm:entry-point')
+Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
+  // 백그라운드에서는 별도 Isolate로 실행
+  // → 앱 상태, Provider, 싱글톤 인스턴스 접근 불가
+  await Firebase.initializeApp();
+
+  // 가벼운 처리만 수행
+  // 1. 로컬 DB 저장 (SQLite/Hive 직접 접근)
+  // 2. 알림 배지 카운트 업데이트
+  // 3. 로컬 알림 표시 (커스텀 알림 필요 시)
+
+  debugPrint('Background message: ${message.messageId}');
+}
+```
+
+### iOS 포그라운드 표시 옵션
+
+```dart
+// iOS에서 포그라운드 알림을 시스템 배너로 표시하려면:
+await FirebaseMessaging.instance.setForegroundNotificationPresentationOptions(
+  alert: true,  // 배너 표시
+  badge: true,  // 뱃지 업데이트
+  sound: true,  // 사운드 재생
+);
+// 이 옵션 사용 시 flutter_local_notifications 포그라운드 표시 불필요 (iOS만)
+// Android는 여전히 flutter_local_notifications 필요
+```
+
+### 메시지 타입별 처리 전략
+
+```dart
+// FCM 메시지 구조:
+// 1. notification + data → 알림 표시 + 데이터 전달
+// 2. data-only → 사일런트 (앱이 직접 처리)
+// 3. notification-only → 단순 알림
+
+// 서버에서 보내는 JSON 예시 (notification + data):
+// {
+//   "message": {
+//     "token": "device_token",
+//     "notification": {
+//       "title": "새 매치 초대",
+//       "body": "오후 3시 테니스 매치에 초대되었습니다"
+//     },
+//     "data": {
+//       "type": "match",
+//       "id": "match_123",
+//       "action": "invite"
+//     },
+//     "android": {
+//       "notification": { "channel_id": "matches" }
+//     },
+//     "apns": {
+//       "payload": {
+//         "aps": { "sound": "default", "badge": 1 }
+//       }
+//     }
+//   }
+// }
+```
+
+### 규칙
+
+- 포그라운드 → `onMessage` + 로컬 알림 직접 표시 (FCM은 포그라운드 자동 표시 안 함)
+- 백그라운드 핸들러 → top-level 함수, `@pragma('vm:entry-point')` 필수
+- 백그라운드 핸들러 → Provider/싱글톤 접근 불가, DB 직접 접근만
+- `getInitialMessage()` → cold start 시 1회 체크, 라우터 준비 후 네비게이션
+- `onMessageOpenedApp` → 백그라운드 탭 처리, `getInitialMessage` 와 중복 방지
+- data-only 메시지 → 사일런트 데이터 동기화에 활용 (알림 미표시)
+- iOS `setForegroundNotificationPresentationOptions` → iOS 전용 포그라운드 배너