timsquad 2.1.0 → 3.4.0

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

@@ -0,0 +1,308 @@
+---
+title: Background Processing
+impact: HIGH
+impactDescription: "백그라운드 미처리 → 데이터 미동기화, 사용자 재진입 시 stale 데이터"
+tags: workmanager, background-fetch, isolate, periodic-task
+---
+
+## Background Processing
+
+**Impact: HIGH (백그라운드 미처리 → 데이터 미동기화, 사용자 재진입 시 stale 데이터)**
+
+workmanager 패키지 기반 백그라운드 태스크. 주기적 동기화, 데이터 프리페치, 오프라인 큐 처리.
+
+### 의존성
+
+```yaml
+dependencies:
+  workmanager: ^0.5.2
+```
+
+### 초기화
+
+**Incorrect (콜백을 클래스 메서드로 등록):**
+```dart
+class BackgroundService {
+  // 클래스 인스턴스 메서드 → top-level 아니므로 실패
+  void callbackDispatcher() {
+    Workmanager().executeTask((task, inputData) async {
+      return true;
+    });
+  }
+}
+```
+
+**Correct (top-level 함수로 콜백 등록):**
+```dart
+// background_tasks.dart — top-level 함수 필수
+@pragma('vm:entry-point')
+void callbackDispatcher() {
+  Workmanager().executeTask((taskName, inputData) async {
+    // 백그라운드 Isolate에서 실행
+    // → 앱 상태, Provider, Navigator 접근 불가
+    // → DB, SharedPreferences, HTTP 직접 사용
+
+    switch (taskName) {
+      case BackgroundTasks.syncMatches:
+        return await _syncMatches();
+      case BackgroundTasks.cleanCache:
+        return await _cleanCache();
+      case BackgroundTasks.uploadPendingData:
+        return await _uploadPendingData(inputData);
+      case Workmanager.iOSBackgroundTask:
+        // iOS 백그라운드 fetch (시스템이 자동 호출)
+        return await _syncMatches();
+      default:
+        return Future.value(true);
+    }
+  });
+}
+
+/// 태스크 이름 상수
+abstract class BackgroundTasks {
+  static const syncMatches = 'sync_matches';
+  static const cleanCache = 'clean_cache';
+  static const uploadPendingData = 'upload_pending_data';
+}
+
+// main.dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // Workmanager 초기화
+  await Workmanager().initialize(
+    callbackDispatcher,
+    isInDebugMode: kDebugMode, // 디버그 시 알림으로 태스크 실행 확인
+  );
+
+  runApp(const ProviderScope(child: MyApp()));
+}
+```
+
+### 주기적 태스크 등록
+
+```dart
+class BackgroundTaskManager {
+  /// 앱 시작 시 또는 로그인 후 등록
+  Future<void> registerPeriodicTasks() async {
+    // === 매치 데이터 동기화 (15분 간격) ===
+    await Workmanager().registerPeriodicTask(
+      'sync-matches-periodic',  // uniqueName (취소용)
+      BackgroundTasks.syncMatches,
+      frequency: const Duration(minutes: 15), // 최소 15분 (OS 제어)
+      constraints: Constraints(
+        networkType: NetworkType.connected, // 네트워크 필요
+        requiresBatteryNotLow: true,        // 배터리 부족 시 스킵
+      ),
+      existingWorkPolicy: ExistingWorkPolicy.keep, // 기존 등록 유지
+      backoffPolicy: BackoffPolicy.exponential,
+      initialDelay: const Duration(minutes: 5),
+    );
+
+    // === 캐시 정리 (1일 간격) ===
+    await Workmanager().registerPeriodicTask(
+      'clean-cache-daily',
+      BackgroundTasks.cleanCache,
+      frequency: const Duration(hours: 24),
+      constraints: Constraints(
+        requiresCharging: true,    // 충전 중일 때만
+        requiresDeviceIdle: true,  // 유휴 상태일 때만 (Android)
+      ),
+    );
+  }
+
+  /// 1회성 태스크 (즉시 또는 지연 실행)
+  Future<void> scheduleOneOffTask({
+    required String data,
+  }) async {
+    await Workmanager().registerOneOffTask(
+      'upload-pending-${DateTime.now().millisecondsSinceEpoch}',
+      BackgroundTasks.uploadPendingData,
+      inputData: {'data': data}, // 태스크에 전달할 데이터
+      constraints: Constraints(
+        networkType: NetworkType.connected,
+      ),
+      initialDelay: const Duration(seconds: 10),
+    );
+  }
+
+  /// 모든 태스크 취소 (로그아웃 시)
+  Future<void> cancelAll() async {
+    await Workmanager().cancelAll();
+  }
+
+  /// 특정 태스크 취소
+  Future<void> cancelTask(String uniqueName) async {
+    await Workmanager().cancelByUniqueName(uniqueName);
+  }
+}
+```
+
+### 백그라운드 태스크 구현
+
+```dart
+/// 매치 데이터 동기화 (백그라운드 Isolate에서 실행)
+Future<bool> _syncMatches() async {
+  try {
+    // 직접 HTTP 호출 (Dio/http 패키지)
+    // Provider/Repository 사용 불가 → 직접 구현
+    final client = http.Client();
+    final prefs = await SharedPreferences.getInstance();
+    final token = prefs.getString('auth_token');
+
+    if (token == null) return true; // 미로그인 → 스킵
+
+    final response = await client.get(
+      Uri.parse('https://api.example.com/matches/sync'),
+      headers: {'Authorization': 'Bearer $token'},
+    );
+
+    if (response.statusCode == 200) {
+      final data = jsonDecode(response.body) as List;
+      // 로컬 DB에 저장 (SQLite/Hive 직접 접근)
+      final db = await openDatabase('app.db');
+      for (final match in data) {
+        await db.insert(
+          'matches',
+          match as Map<String, dynamic>,
+          conflictAlgorithm: ConflictAlgorithm.replace,
+        );
+      }
+    }
+
+    client.close();
+    return true; // 성공
+  } catch (e) {
+    debugPrint('Background sync failed: $e');
+    return false; // 실패 → OS가 재시도 스케줄
+  }
+}
+
+/// 오프라인 데이터 업로드 (네트워크 복구 시)
+Future<bool> _uploadPendingData(Map<String, dynamic>? inputData) async {
+  try {
+    final prefs = await SharedPreferences.getInstance();
+    final pendingJson = prefs.getString('pending_uploads');
+    if (pendingJson == null) return true;
+
+    final pendingList = jsonDecode(pendingJson) as List;
+    final client = http.Client();
+    final token = prefs.getString('auth_token');
+
+    for (final item in pendingList) {
+      await client.post(
+        Uri.parse('https://api.example.com/data'),
+        headers: {
+          'Authorization': 'Bearer $token',
+          'Content-Type': 'application/json',
+        },
+        body: jsonEncode(item),
+      );
+    }
+
+    // 업로드 완료 → 대기열 비우기
+    await prefs.remove('pending_uploads');
+    client.close();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/// 캐시 정리
+Future<bool> _cleanCache() async {
+  try {
+    final cacheDir = await getTemporaryDirectory();
+    final now = DateTime.now();
+
+    await for (final entity in cacheDir.list()) {
+      if (entity is File) {
+        final stat = await entity.stat();
+        // 7일 이상 된 캐시 파일 삭제
+        if (now.difference(stat.modified).inDays > 7) {
+          await entity.delete();
+        }
+      }
+    }
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+```
+
+### iOS 백그라운드 설정
+
+```dart
+// iOS는 BGTaskScheduler 기반
+// Info.plist에 등록 필요:
+// <key>BGTaskSchedulerPermittedIdentifiers</key>
+// <array>
+//   <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+// </array>
+//
+// Runner/AppDelegate.swift에서 추가 설정 불필요 (workmanager가 자동 처리)
+//
+// iOS 제약사항:
+// - 주기적 태스크 최소 간격: OS가 결정 (15분보다 길 수 있음)
+// - 실행 시점: OS 최적화에 따라 지연 가능
+// - 배터리/네트워크 상태에 따라 스킵 가능
+// - Background App Refresh가 꺼져 있으면 미실행
+```
+
+### Isolate 직접 사용 (무거운 연산)
+
+```dart
+/// 이미지 처리, 대량 데이터 파싱 등 CPU 집약적 태스크
+Future<List<MatchSummary>> processMatchDataInBackground(
+    String rawJson) async {
+  // compute() → 별도 Isolate에서 실행 (UI 스레드 블로킹 방지)
+  return await compute(_parseMatchData, rawJson);
+}
+
+// top-level 또는 static 함수만 가능
+List<MatchSummary> _parseMatchData(String rawJson) {
+  final data = jsonDecode(rawJson) as List;
+  return data.map((e) => MatchSummary.fromJson(e)).toList();
+}
+
+/// 장기 실행 Isolate (양방향 통신)
+Future<void> startLongRunningIsolate() async {
+  final receivePort = ReceivePort();
+  await Isolate.spawn(_isolateEntryPoint, receivePort.sendPort);
+
+  receivePort.listen((message) {
+    if (message is SendPort) {
+      // 메인 → Isolate 통신용 SendPort
+      message.send({'action': 'process', 'data': '...'});
+    } else {
+      // Isolate → 메인 결과 수신
+      debugPrint('Isolate result: $message');
+    }
+  });
+}
+
+void _isolateEntryPoint(SendPort mainSendPort) {
+  final receivePort = ReceivePort();
+  mainSendPort.send(receivePort.sendPort);
+
+  receivePort.listen((message) {
+    // 메인에서 받은 데이터 처리
+    final result = _heavyComputation(message);
+    mainSendPort.send(result);
+  });
+}
+```
+
+### 규칙
+
+- `callbackDispatcher` → top-level 함수, `@pragma('vm:entry-point')` 필수
+- 백그라운드 태스크 → Provider/Navigator/BuildContext 접근 불가
+- HTTP/DB → 직접 인스턴스 생성 (앱 상태와 독립)
+- 주기적 태스크 최소 간격 → 15분 (OS가 실제 실행 시점 결정)
+- `constraints` → 네트워크/배터리/충전 조건 설정 (배터리 소모 방지)
+- `existingWorkPolicy.keep` → 중복 등록 방지 (앱 재시작 시)
+- 태스크 반환값 → `true` (성공), `false` (실패 → OS 재시도)
+- 로그아웃 시 → `cancelAll()` 로 모든 백그라운드 태스크 해제
+- CPU 집약적 작업 → `compute()` 또는 `Isolate.spawn` (UI 스레드 보호)
+- iOS → Background App Refresh 설정에 의존, 실행 보장 없음

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

@@ -0,0 +1,217 @@
+---
+title: Deep Linking from Notifications
+impact: HIGH
+impactDescription: "탭 후 홈으로만 이동 → 전환율 30% 하락, 딥링크 → 전환율 2-3x"
+tags: deep-link, go-router, payload, navigation
+---
+
+## Deep Linking from Notifications
+
+**Impact: HIGH (탭 후 홈으로만 이동 → 전환율 30% 하락, 딥링크 → 전환율 2-3x)**
+
+알림 탭 → 특정 화면 네비게이션. FCM 페이로드 → go_router 딥링크 통합.
+
+### 페이로드 설계
+
+**Incorrect (구조 없는 페이로드):**
+```dart
+// 서버에서 보내는 데이터
+// { "data": { "screen": "match_detail_123" } }
+// → 파싱 로직이 복잡해지고, 새 화면 추가 시 분기문 증가
+```
+
+**Correct (타입 + ID 분리, 라우트 매핑):**
+```dart
+// 서버에서 보내는 데이터 구조
+// {
+//   "data": {
+//     "type": "match",       // 알림 카테고리
+//     "id": "match_123",     // 리소스 ID
+//     "action": "invite",    // 세부 액션 (선택)
+//     "route": "/match/match_123"  // 직접 라우트 (선택, 백업)
+//   }
+// }
+
+/// 페이로드 모델
+class NotificationPayload {
+  final String type;
+  final String? id;
+  final String? action;
+  final String? route;
+
+  const NotificationPayload({
+    required this.type,
+    this.id,
+    this.action,
+    this.route,
+  });
+
+  factory NotificationPayload.fromMap(Map<String, dynamic> data) {
+    return NotificationPayload(
+      type: data['type'] as String? ?? 'default',
+      id: data['id'] as String?,
+      action: data['action'] as String?,
+      route: data['route'] as String?,
+    );
+  }
+
+  /// 페이로드 → go_router 경로 변환
+  String toRoute() {
+    // 직접 라우트가 있으면 우선 사용
+    if (route != null) return route!;
+
+    // 타입 + ID 기반 라우트 생성
+    return switch (type) {
+      'match' => id != null ? '/match/$id' : '/matches',
+      'chat' => id != null ? '/chat/$id' : '/chat',
+      'profile' => id != null ? '/profile/$id' : '/profile',
+      'announcement' => '/announcements',
+      'reminder' => id != null ? '/match/$id' : '/matches',
+      _ => '/notifications',
+    };
+  }
+}
+```
+
+### go_router 통합
+
+```dart
+/// 알림 딥링크 네비게이션 서비스
+class NotificationNavigator {
+  final GoRouter _router;
+
+  NotificationNavigator({required GoRouter router}) : _router = router;
+
+  /// FCM RemoteMessage에서 네비게이션
+  void navigateFromMessage(RemoteMessage message) {
+    final payload = NotificationPayload.fromMap(message.data);
+    _navigate(payload);
+  }
+
+  /// flutter_local_notifications 페이로드에서 네비게이션
+  void navigateFromLocalPayload(String? payloadJson) {
+    if (payloadJson == null) return;
+    try {
+      final data = jsonDecode(payloadJson) as Map<String, dynamic>;
+      final payload = NotificationPayload.fromMap(data);
+      _navigate(payload);
+    } catch (e) {
+      debugPrint('Invalid notification payload: $e');
+      _router.go('/notifications');
+    }
+  }
+
+  void _navigate(NotificationPayload payload) {
+    final route = payload.toRoute();
+
+    // push vs go 결정:
+    // - go: 스택을 교체 (뒤로가기 시 홈으로)
+    // - push: 스택에 추가 (뒤로가기 시 이전 화면으로)
+    // 알림에서는 push가 일반적 (사용자가 돌아갈 수 있도록)
+    _router.push(route);
+  }
+}
+
+// Riverpod Provider
+final notificationNavigatorProvider = Provider<NotificationNavigator>((ref) {
+  return NotificationNavigator(router: ref.watch(routerProvider));
+});
+```
+
+### 3가지 앱 상태에서 딥링크 처리
+
+```dart
+class NotificationDeepLinkHandler {
+  final NotificationNavigator _navigator;
+  final FirebaseMessaging _messaging = FirebaseMessaging.instance;
+  final FlutterLocalNotificationsPlugin _localPlugin;
+
+  NotificationDeepLinkHandler({
+    required NotificationNavigator navigator,
+    required FlutterLocalNotificationsPlugin localPlugin,
+  })  : _navigator = navigator,
+        _localPlugin = localPlugin;
+
+  Future<void> initialize() async {
+    // === 1. 종료 상태 (Terminated) → 알림 탭으로 앱 시작 ===
+    final initialMessage = await _messaging.getInitialMessage();
+    if (initialMessage != null) {
+      // 라우터 초기화 대기
+      await Future.delayed(const Duration(milliseconds: 800));
+      _navigator.navigateFromMessage(initialMessage);
+    }
+
+    // === 2. 백그라운드 → 알림 탭으로 앱 복귀 ===
+    FirebaseMessaging.onMessageOpenedApp.listen((message) {
+      _navigator.navigateFromMessage(message);
+    });
+
+    // === 3. 로컬 알림 탭 처리 ===
+    // flutter_local_notifications의 앱 시작 시 탭 확인
+    final launchDetails =
+        await _localPlugin.getNotificationAppLaunchDetails();
+    if (launchDetails?.didNotificationLaunchApp == true) {
+      final response = launchDetails!.notificationResponse;
+      if (response != null) {
+        await Future.delayed(const Duration(milliseconds: 800));
+        _navigator.navigateFromLocalPayload(response.payload);
+      }
+    }
+  }
+}
+```
+
+### 인증 가드와 딥링크 조합
+
+```dart
+// go_router redirect에서 딥링크 보존
+GoRouter(
+  redirect: (context, state) {
+    final isLoggedIn = /* auth check */;
+    final isAuthRoute = state.matchedLocation.startsWith('/auth');
+
+    if (!isLoggedIn && !isAuthRoute) {
+      // 딥링크 목적지를 쿼리 파라미터로 보존
+      final redirectTo = state.matchedLocation;
+      return '/auth/login?redirect=${Uri.encodeComponent(redirectTo)}';
+    }
+    if (isLoggedIn && isAuthRoute) {
+      // 로그인 완료 → 원래 딥링크 목적지로 이동
+      final redirect = state.uri.queryParameters['redirect'];
+      return redirect != null ? Uri.decodeComponent(redirect) : '/';
+    }
+    return null;
+  },
+  // ...routes
+);
+```
+
+### 알림 분석 (Analytics)
+
+```dart
+/// 알림 탭 이벤트 추적
+void _navigate(NotificationPayload payload) {
+  // 분석 이벤트 기록
+  AnalyticsService.instance.logEvent(
+    'notification_opened',
+    parameters: {
+      'type': payload.type,
+      'action': payload.action ?? 'tap',
+      'source': 'push',
+    },
+  );
+
+  final route = payload.toRoute();
+  _router.push(route);
+}
+```
+
+### 규칙
+
+- 페이로드 구조 → `type` + `id` + `action` 표준화, 서버와 합의
+- `toRoute()` → 중앙 라우트 매핑 (분산 switch 문 방지)
+- 3가지 상태 모두 처리: `getInitialMessage` + `onMessageOpenedApp` + 로컬 알림 launch
+- `getInitialMessage()` → cold start 시 라우터 초기화 대기 후 네비게이션
+- 인증 가드 → 딥링크 목적지 보존 (`?redirect=` 쿼리 파라미터)
+- 알림 탭 시 `push` 사용 (스택 추가 → 뒤로가기 가능)
+- 알림 탭 분석 이벤트 필수 (열림률, 전환율 측정)

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

@@ -0,0 +1,164 @@
+---
+title: FCM Setup & Token Management
+impact: CRITICAL
+impactDescription: "알림 미수신 → 사용자 이탈, 토큰 미갱신 → 전달률 하락"
+tags: fcm, firebase, token, setup
+---
+
+## FCM Setup & Token Management
+
+**Impact: CRITICAL (알림 미수신 → 사용자 이탈, 토큰 미갱신 → 전달률 하락)**
+
+FCM 초기화, 토큰 관리, 서버 동기화. 앱 시작 시 반드시 설정해야 하는 핵심 인프라.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  firebase_core: ^3.8.0
+  firebase_messaging: ^15.1.0
+  flutter_local_notifications: ^18.0.0
+```
+
+### 초기화
+
+**Incorrect (순서 무시, 백그라운드 핸들러 미등록):**
+```dart
+void main() {
+  runApp(const MyApp());
+  // Firebase 초기화 없이 FCM 사용 → 크래시
+}
+```
+
+**Correct (완전한 초기화 순서):**
+```dart
+// top-level 함수 — 클래스 멤버/클로저 불가
+@pragma('vm:entry-point')
+Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
+  await Firebase.initializeApp();
+  // 백그라운드 메시지 처리 (DB 저장, 로컬 알림 등)
+  // 주의: 여기서 UI 코드, Navigator, BuildContext 접근 불가
+  debugPrint('Background message: ${message.messageId}');
+}
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // 1. Firebase 초기화
+  await Firebase.initializeApp();
+
+  // 2. 백그라운드 메시지 핸들러 등록 (main 에서 1회)
+  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
+
+  // 3. 로컬 알림 초기화 (포그라운드 표시용)
+  await NotificationService.instance.initialize();
+
+  runApp(const ProviderScope(child: MyApp()));
+}
+```
+
+### FCM 토큰 관리
+
+**Incorrect (토큰 갱신 미처리):**
+```dart
+// 앱 시작 시 토큰 1번만 가져오고 끝
+final token = await FirebaseMessaging.instance.getToken();
+await sendTokenToServer(token!);
+// → 토큰 갱신되면 서버에 잘못된 토큰 → 알림 전달 실패
+```
+
+**Correct (토큰 갱신 구독 + 서버 동기화):**
+```dart
+class FcmTokenManager {
+  final FirebaseMessaging _messaging = FirebaseMessaging.instance;
+  final AuthRepository _authRepo;
+
+  FcmTokenManager({required AuthRepository authRepo}) : _authRepo = authRepo;
+
+  /// 초기 토큰 등록 + 갱신 구독
+  Future<void> initialize() async {
+    // 초기 토큰
+    final token = await _messaging.getToken();
+    if (token != null) {
+      await _syncTokenToServer(token);
+    }
+
+    // 토큰 갱신 구독 (앱 재설치, OS 토큰 리프레시 등)
+    _messaging.onTokenRefresh.listen(_syncTokenToServer);
+  }
+
+  Future<void> _syncTokenToServer(String token) async {
+    try {
+      await _authRepo.updateFcmToken(token);
+    } catch (e) {
+      // 실패 시 로컬 저장 → 다음 앱 시작 시 재시도
+      await _saveTokenLocally(token);
+    }
+  }
+
+  /// 로그아웃 시 토큰 해제
+  Future<void> deleteToken() async {
+    await _messaging.deleteToken();
+    await _authRepo.removeFcmToken();
+  }
+
+  Future<void> _saveTokenLocally(String token) async {
+    // SharedPreferences 등에 저장, 다음 시작 시 재동기화
+  }
+}
+
+// Riverpod Provider
+final fcmTokenManagerProvider = Provider<FcmTokenManager>((ref) {
+  return FcmTokenManager(authRepo: ref.watch(authRepositoryProvider));
+});
+```
+
+### iOS APNs 토큰 (선택)
+
+```dart
+// iOS에서 APNs 토큰 직접 필요한 경우 (서버에서 APNs 직접 발송 시)
+final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
+// 대부분의 경우 FCM이 APNs 토큰을 자동 관리하므로 직접 사용 불필요
+```
+
+### 토픽 구독
+
+```dart
+class TopicManager {
+  final FirebaseMessaging _messaging = FirebaseMessaging.instance;
+
+  /// 사용자 관심사 기반 토픽 구독
+  Future<void> subscribeToUserTopics(UserPreferences prefs) async {
+    // 전체 공지
+    await _messaging.subscribeToTopic('announcements');
+
+    // 관심 스포츠
+    for (final sport in prefs.favoriteSports) {
+      await _messaging.subscribeToTopic('sport_${sport.name}');
+    }
+
+    // 지역
+    if (prefs.region != null) {
+      await _messaging.subscribeToTopic('region_${prefs.region}');
+    }
+  }
+
+  /// 로그아웃 시 토픽 해제
+  Future<void> unsubscribeAll(UserPreferences prefs) async {
+    await _messaging.unsubscribeFromTopic('announcements');
+    for (final sport in prefs.favoriteSports) {
+      await _messaging.unsubscribeFromTopic('sport_${sport.name}');
+    }
+  }
+}
+```
+
+### 규칙
+
+- `Firebase.initializeApp()` → `WidgetsFlutterBinding.ensureInitialized()` 직후
+- `onBackgroundMessage` → `main()` 에서 등록, top-level 함수만 가능
+- `@pragma('vm:entry-point')` → 백그라운드 핸들러에 필수 (트리쉐이킹 방지)
+- FCM 토큰 → 서버 동기화 필수 + `onTokenRefresh` 구독
+- 로그아웃 시 `deleteToken()` + 서버에서 토큰 제거
+- 토픽 구독 → 사용자 설정 변경 시 구독/해제 동기화