timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/monitoring/rules/performance-monitoring.md

@@ -0,0 +1,248 @@
+---
+title: Performance Monitoring & Custom Traces
+impact: HIGH
+impactDescription: "성능 미측정 → 느린 화면 방치, ANR/프리징 원인 파악 불가"
+tags: firebase-performance, trace, http-metric, frame, startup
+---
+
+## Performance Monitoring & Custom Traces
+
+**Impact: HIGH (성능 미측정 → 느린 화면 방치, ANR/프리징 원인 파악 불가)**
+
+Firebase Performance Monitoring 초기화, custom trace, HTTP metric 수집,
+프레임 렌더링 모니터링, 앱 시작 시간 추적.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  firebase_core: ^3.8.0
+  firebase_performance: ^0.10.0
+  firebase_performance_dio: ^0.6.0  # dio 사용 시
+```
+
+### 초기화
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+
+  // Performance Monitoring은 별도 초기화 불필요 (Firebase init 시 자동 활성화)
+  // 디버그 모드에서 비활성화 (선택)
+  if (kDebugMode) {
+    await FirebasePerformance.instance
+        .setPerformanceCollectionEnabled(false);
+  }
+
+  runApp(const ProviderScope(child: MyApp()));
+}
+```
+
+### Custom Trace
+
+**Incorrect (시작/종료 미매칭):**
+```dart
+final trace = FirebasePerformance.instance.newTrace('load_data');
+await trace.start();
+await fetchData();
+// trace.stop() 누락 → 데이터 미전송, 메모리 누수
+```
+
+**Correct (안전한 trace 래핑):**
+```dart
+class PerformanceService {
+  final FirebasePerformance _performance = FirebasePerformance.instance;
+
+  /// 안전한 trace 실행 (자동 start/stop)
+  Future<T> trace<T>(
+    String name,
+    Future<T> Function() operation, {
+    Map<String, String>? attributes,
+    Map<String, int>? metrics,
+  }) async {
+    final trace = _performance.newTrace(name);
+
+    // 속성 설정 (최대 5개)
+    attributes?.forEach((key, value) {
+      trace.putAttribute(key, value);
+    });
+
+    await trace.start();
+    try {
+      final result = await operation();
+
+      // 메트릭 설정 (최대 32개)
+      metrics?.forEach((key, value) {
+        trace.setMetric(key, value);
+      });
+
+      return result;
+    } catch (e) {
+      trace.putAttribute('error', e.runtimeType.toString());
+      rethrow;
+    } finally {
+      await trace.stop(); // 항상 stop 보장
+    }
+  }
+}
+
+// 사용 예시
+final perfService = ref.read(performanceServiceProvider);
+final matches = await perfService.trace(
+  'fetch_matches',
+  () => matchRepository.getMatches(page: 1),
+  attributes: {'sport': 'tennis', 'region': 'sg'},
+  metrics: {'page': 1},
+);
+```
+
+### 핵심 플로우 trace 예시
+
+```dart
+/// 앱 시작 시간 추적
+class AppStartupTrace {
+  static Trace? _trace;
+
+  static Future<void> start() async {
+    _trace = FirebasePerformance.instance.newTrace('app_startup');
+    await _trace?.start();
+  }
+
+  static Future<void> markMilestone(String name) async {
+    _trace?.putAttribute(name, DateTime.now().toIso8601String());
+  }
+
+  static Future<void> stop() async {
+    await _trace?.stop();
+    _trace = null;
+  }
+}
+
+// main.dart
+Future<void> main() async {
+  await AppStartupTrace.start();
+  WidgetsFlutterBinding.ensureInitialized();
+  await AppStartupTrace.markMilestone('binding_initialized');
+
+  await Firebase.initializeApp();
+  await AppStartupTrace.markMilestone('firebase_initialized');
+
+  runApp(const ProviderScope(child: MyApp()));
+}
+
+// 첫 화면 렌더링 완료 시
+class HomeScreen extends ConsumerStatefulWidget {
+  @override
+  ConsumerState<HomeScreen> createState() => _HomeScreenState();
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      AppStartupTrace.stop(); // 첫 프레임 렌더링 완료
+    });
+  }
+}
+```
+
+### HTTP Metric (Dio Interceptor)
+
+```dart
+/// Dio에 Performance interceptor 추가
+final dio = Dio()
+  ..interceptors.add(
+    DioFirebasePerformanceInterceptor(), // firebase_performance_dio
+  );
+
+/// 또는 수동 HTTP metric
+class PerformanceInterceptor extends Interceptor {
+  final Map<String, HttpMetric> _metrics = {};
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    final metric = FirebasePerformance.instance.newHttpMetric(
+      options.uri.toString(),
+      _toHttpMethod(options.method),
+    );
+    metric.start();
+    _metrics[options.hashCode.toString()] = metric;
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    final metric = _metrics.remove(response.requestOptions.hashCode.toString());
+    if (metric != null) {
+      metric
+        ..responseContentType = response.headers.value('content-type')
+        ..httpResponseCode = response.statusCode
+        ..responsePayloadSize = response.data.toString().length;
+      metric.stop();
+    }
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    final metric = _metrics.remove(err.requestOptions.hashCode.toString());
+    if (metric != null) {
+      metric.httpResponseCode = err.response?.statusCode;
+      metric.putAttribute('error', err.type.name);
+      metric.stop();
+    }
+    handler.next(err);
+  }
+
+  HttpMethod _toHttpMethod(String method) {
+    return switch (method.toUpperCase()) {
+      'GET' => HttpMethod.Get,
+      'POST' => HttpMethod.Post,
+      'PUT' => HttpMethod.Put,
+      'DELETE' => HttpMethod.Delete,
+      'PATCH' => HttpMethod.Patch,
+      _ => HttpMethod.Get,
+    };
+  }
+}
+```
+
+### 프레임 렌더링 모니터링
+
+```dart
+/// 느린 프레임 감지 (개발/QA용)
+class FrameMonitor {
+  static void start() {
+    if (!kDebugMode) return;
+
+    WidgetsBinding.instance.addTimingsCallback((timings) {
+      for (final timing in timings) {
+        // 60fps 기준: 16.67ms 이상이면 느린 프레임
+        final buildDuration = timing.buildDuration.inMilliseconds;
+        final rasterDuration = timing.rasterDuration.inMilliseconds;
+        final totalDuration = timing.totalSpan.inMilliseconds;
+
+        if (totalDuration > 16) {
+          debugPrint(
+            'Slow frame: total=${totalDuration}ms '
+            'build=${buildDuration}ms raster=${rasterDuration}ms',
+          );
+        }
+      }
+    });
+  }
+}
+```
+
+### 규칙
+
+- Custom trace → `start()`/`stop()` 반드시 매칭 (try-finally 패턴)
+- Trace 이름 → 소문자 + 언더스코어, 100자 이하
+- Trace 속성 → 최대 5개 (key 32자, value 100자)
+- Trace 메트릭 → 최대 32개 (정수값)
+- HTTP metric → dio interceptor 또는 수동 래핑으로 API 응답 시간 수집
+- 앱 시작 trace → main() 시작 ~ 첫 프레임 렌더링 완료
+- 핵심 플로우 (로그인, 검색, 매치 생성) → custom trace 적용
+- 디버그 모드 → `setPerformanceCollectionEnabled(false)` (선택)
+- 프레임 모니터링 → 16ms (60fps) / 8ms (120fps) 초과 시 경고

package/templates/base/skills/mobile/flutter/monitoring/rules/sentry-integration.md

@@ -0,0 +1,249 @@
+---
+title: Sentry Integration & Breadcrumbs
+impact: MEDIUM
+impactDescription: "에러 컨텍스트 부족 → 재현 불가, 크래시 원인 추적 지연"
+tags: sentry, breadcrumb, scope, dsn, error-tracking
+---
+
+## Sentry Integration & Breadcrumbs
+
+**Impact: MEDIUM (에러 컨텍스트 부족 → 재현 불가, 크래시 원인 추적 지연)**
+
+sentry_flutter 초기화, DSN 환경별 분리, breadcrumbs 자동/수동 기록,
+scope 설정, Crashlytics와의 공존 전략.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  sentry_flutter: ^8.12.0
+  sentry_dio: ^8.12.0        # dio HTTP breadcrumbs
+```
+
+### 초기화
+
+**Incorrect (하드코딩된 DSN, 기본 설정만):**
+```dart
+await SentryFlutter.init((options) {
+  options.dsn = 'https://key@sentry.io/123'; // 하드코딩 → 환경 구분 불가
+});
+```
+
+**Correct (환경별 DSN + 상세 설정):**
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+
+  await SentryFlutter.init(
+    (options) {
+      // DSN 환경별 분리 (--dart-define으로 주입)
+      options.dsn = const String.fromEnvironment(
+        'SENTRY_DSN',
+        defaultValue: '',  // 빈 문자열 → Sentry 비활성화
+      );
+
+      // 환경 태그
+      options.environment = const String.fromEnvironment(
+        'ENV',
+        defaultValue: 'development',
+      );
+
+      // 샘플링 (프로덕션에서 100%는 비용 과다)
+      options.tracesSampleRate = kDebugMode ? 1.0 : 0.3;
+      options.profilesSampleRate = kDebugMode ? 1.0 : 0.1;
+
+      // 릴리스 버전 (소스맵 매핑)
+      options.release = '${packageInfo.version}+${packageInfo.buildNumber}';
+
+      // 디버그 모드
+      options.debug = kDebugMode;
+
+      // 자동 breadcrumb 수집
+      options.enableAutoNativeBreadcrumbs = true;
+      options.enableAutoPerformanceTracing = true;
+
+      // PII 전송 비활성화
+      options.sendDefaultPii = false;
+
+      // 에러 필터링 (무시할 에러 타입)
+      options.beforeSend = (event, hint) {
+        // 네트워크 끊김 에러는 무시
+        if (event.throwable is SocketException) return null;
+        return event;
+      };
+    },
+    appRunner: () => runApp(
+      const ProviderScope(child: MyApp()),
+    ),
+  );
+}
+```
+
+### Breadcrumbs
+
+```dart
+class SentryBreadcrumbService {
+  /// 네비게이션 breadcrumb (수동 — go_router 연동)
+  static void navigationBreadcrumb({
+    required String from,
+    required String to,
+  }) {
+    Sentry.addBreadcrumb(Breadcrumb(
+      type: 'navigation',
+      category: 'navigation',
+      data: {'from': from, 'to': to},
+    ));
+  }
+
+  /// 사용자 액션 breadcrumb
+  static void userActionBreadcrumb({
+    required String action,
+    required String target,
+    Map<String, dynamic>? data,
+  }) {
+    Sentry.addBreadcrumb(Breadcrumb(
+      type: 'user',
+      category: 'user.action',
+      message: '$action on $target',
+      data: data,
+    ));
+  }
+
+  /// 상태 변경 breadcrumb
+  static void stateBreadcrumb({
+    required String category,
+    required String message,
+    Map<String, dynamic>? data,
+  }) {
+    Sentry.addBreadcrumb(Breadcrumb(
+      type: 'info',
+      category: category,
+      message: message,
+      data: data,
+      level: SentryLevel.info,
+    ));
+  }
+}
+
+// go_router NavigatorObserver로 자동 네비게이션 breadcrumb
+class SentryNavigatorObserver extends NavigatorObserver {
+  @override
+  void didPush(Route route, Route? previousRoute) {
+    SentryBreadcrumbService.navigationBreadcrumb(
+      from: previousRoute?.settings.name ?? 'unknown',
+      to: route.settings.name ?? 'unknown',
+    );
+  }
+
+  @override
+  void didPop(Route route, Route? previousRoute) {
+    SentryBreadcrumbService.navigationBreadcrumb(
+      from: route.settings.name ?? 'unknown',
+      to: previousRoute?.settings.name ?? 'unknown',
+    );
+  }
+}
+```
+
+### Scope 설정
+
+```dart
+/// 사용자 정보 + 태그 설정
+class SentryScopeManager {
+  /// 로그인 시 사용자 설정
+  static Future<void> setUser({
+    required String id,
+    String? email,
+    String? username,
+    Map<String, String>? extras,
+  }) async {
+    Sentry.configureScope((scope) {
+      scope.setUser(SentryUser(
+        id: id,
+        email: email,      // PII — sendDefaultPii: true 필요
+        username: username,
+      ));
+      // 태그 (필터링/검색용)
+      scope.setTag('subscription_tier', extras?['tier'] ?? 'free');
+      scope.setTag('region', extras?['region'] ?? 'unknown');
+      // 추가 데이터 (상세 컨텍스트)
+      extras?.forEach((key, value) {
+        scope.setExtra(key, value);
+      });
+    });
+  }
+
+  /// 로그아웃 시 정리
+  static Future<void> clearUser() async {
+    Sentry.configureScope((scope) {
+      scope.setUser(null);
+      scope.removeTag('subscription_tier');
+      scope.removeTag('region');
+    });
+  }
+}
+```
+
+### Dio HTTP Breadcrumbs
+
+```dart
+/// sentry_dio로 HTTP 요청/응답 자동 breadcrumb
+final dio = Dio()
+  ..addSentry(); // sentry_dio 확장 메서드
+
+// 또는 수동 interceptor
+class SentryDioInterceptor extends Interceptor {
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    Sentry.addBreadcrumb(Breadcrumb(
+      type: 'http',
+      category: 'http',
+      data: {
+        'url': response.requestOptions.uri.toString(),
+        'method': response.requestOptions.method,
+        'status_code': response.statusCode,
+        'duration_ms': response.requestOptions.extra['start_time'] != null
+            ? DateTime.now().difference(
+                response.requestOptions.extra['start_time'] as DateTime,
+              ).inMilliseconds
+            : null,
+      },
+    ));
+    handler.next(response);
+  }
+}
+```
+
+### Crashlytics + Sentry 공존 전략
+
+```
+역할 분리:
+┌──────────────┬────────────────────────┬──────────────────────┐
+│              │ Firebase Crashlytics   │ Sentry               │
+├──────────────┼────────────────────────┼──────────────────────┤
+│ 강점         │ 크래시 집계, 안정성 %   │ 에러 컨텍스트, 검색   │
+│ 크래시       │ O (primary)            │ O (backup)           │
+│ 비치명 에러   │ O (recordError)        │ O (captureException) │
+│ Breadcrumbs  │ X (log만 가능)          │ O (풍부한 컨텍스트)  │
+│ 알림         │ Firebase Console        │ Slack/Email 통합     │
+│ 비용         │ 무료                    │ 무료 (5K 이벤트/월)  │
+└──────────────┴────────────────────────┴──────────────────────┘
+
+공존 시 주의:
+- 에러를 양쪽 모두에 전송하면 이벤트 쿼터 소모 → 역할 기반 필터링
+- Crashlytics = 크래시 대시보드 (안정성 %)
+- Sentry = 에러 디버깅 (breadcrumb, context, 검색)
+```
+
+### 규칙
+
+- DSN → `--dart-define`으로 환경별 주입, 하드코딩 금지
+- `tracesSampleRate` → 프로덕션 0.1~0.3 (비용 절감)
+- `beforeSend` → 불필요한 에러 (SocketException 등) 필터링
+- Breadcrumb → 네비게이션, HTTP, 사용자 액션 자동 기록
+- Scope → 로그인/로그아웃 시 사용자 정보 설정/해제
+- PII → `sendDefaultPii: false` 기본, 필요 시 명시적 활성화
+- Crashlytics 공존 → 각 도구의 강점에 맞는 역할 분리
+- 릴리스 → `options.release` 설정 + 소스맵/디버그 심볼 업로드

package/templates/base/skills/mobile/flutter/networking/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: networking
+description: |
+  Flutter 네트워크 통신 가이드라인.
+  Dio HTTP 클라이언트, Retrofit 코드 생성, 인터셉터 체인,
+  에러 핸들링, 연결 상태 관리, 캐시 전략.
+version: "1.0.0"
+tags: [flutter, dio, retrofit, http, api, interceptor, connectivity]
+user-invocable: false
+---
+
+# Networking
+
+Flutter Dio + Retrofit + Interceptor + Connectivity 통합 가이드.
+HTTP 클라이언트 설정부터 오프라인 캐시까지, API 통신 전체 파이프라인.
+
+## Philosophy
+
+- API 클라이언트는 서비스 — Feature-first 구조에서 `core/networking/` 중앙화
+- 에러는 도메인 타입 — DioException을 앱 도메인 에러(NetworkFailure)로 변환
+- 오프라인은 기본 — connectivity 감지 + 캐시 + 재시도를 기본 탑재
+- 인터셉터는 레이어 — 인증, 재시도, 로깅, 에러 변환을 체인으로 분리
+
+## Resources
+
+6개 규칙 + 1개 참조. 네트워크 통신 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [dio-setup](rules/dio-setup.md) | Dio 싱글톤, BaseOptions, Riverpod Provider |
+| CRITICAL | rule | [interceptors](rules/interceptors.md) | Interceptor chain 순서: Auth → Retry → Logging → Error |
+| CRITICAL | rule | [error-handling](rules/error-handling.md) | DioException → NetworkFailure sealed class, Result 패턴 |
+| HIGH | rule | [retrofit-patterns](rules/retrofit-patterns.md) | @RestApi, 코드 생성, freezed 모델 연동 |
+| HIGH | rule | [connectivity](rules/connectivity.md) | connectivity_plus, 오프라인 큐, 자동 재시도 |
+| MEDIUM | rule | [caching](rules/caching.md) | dio_cache_interceptor, ETag, 오프라인 fallback |
+| — | ref | [api-client-architecture](references/api-client-architecture.md) | 디렉토리 구조, Provider 구성, Repository 연동, Mock 테스트 |
+
+## Quick Rules
+
+### Dio 설정
+- `Dio(BaseOptions(...))` 싱글톤 — Riverpod Provider로 전역 관리
+- `connectTimeout: 15s`, `receiveTimeout: 15s` 기본값
+- `baseUrl` 은 환경별 분리 (dev/staging/prod)
+- `contentType: 'application/json'` 기본 헤더
+
+### 인터셉터 체인
+- 순서: Auth → Retry → Logging → Error Transform
+- Auth: 토큰 주입 + 401 시 리프레시
+- Retry: 지수 백오프, 최대 3회, 5xx/timeout만
+- Logging: debug 빌드에서만 활성화
+
+### 에러 핸들링
+- `DioException` → `NetworkFailure` sealed class 변환
+- `connectionTimeout/sendTimeout` → `TimeoutFailure`
+- `badResponse` → `ServerFailure(statusCode, message)`
+- `connectionError` → `NoConnectionFailure`
+- Repository에서 `Result<T, Failure>` 패턴 반환
+
+### Retrofit 코드 생성
+- `@RestApi(baseUrl: '')` — baseUrl은 Dio에서 관리
+- 응답 모델은 freezed + json_serializable
+- `build_runner watch` 로 개발 중 자동 생성
+
+### 연결 상태
+- `connectivity_plus` → 네트워크 상태 실시간 감지
+- 오프라인 시 요청 큐잉, 연결 복구 시 자동 재시도
+- UI에 오프라인 배너 표시
+
+### 캐시
+- `dio_cache_interceptor` → GET 응답 캐시
+- `ETag`/`Last-Modified` 헤더 활용
+- 오프라인 시 캐시 fallback
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | Dio 싱글톤 인스턴스 Riverpod Provider로 관리 |
+| CRITICAL | Interceptor 순서: Auth → Retry → Logging → Error Transform |
+| CRITICAL | DioException → 도메인 NetworkFailure 변환 처리 |
+| HIGH | Auth 인터셉터에서 401 → 토큰 리프레시 → 재요청 |
+| HIGH | Retry 인터셉터: 지수 백오프, 5xx/timeout만, 최대 3회 |
+| HIGH | Retrofit @RestApi 응답 타입을 freezed 모델로 정의 |
+| HIGH | connectivity_plus로 오프라인 감지 + UI 배너 |
+| MEDIUM | 오프라인 요청 큐 + 연결 복구 시 자동 재시도 |
+| MEDIUM | GET 응답 캐시 (dio_cache_interceptor) |
+| MEDIUM | 환경별 baseUrl 분리 (dev/staging/prod) |
+| MEDIUM | Release 빌드에서 Logging 인터셉터 비활성화 |