timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/monitoring/rules/analytics.md

@@ -0,0 +1,227 @@
+---
+title: Analytics Event Taxonomy & Screen Tracking
+impact: HIGH
+impactDescription: "이벤트 미설계 → 무의미한 데이터 축적, 의사결정 근거 부재"
+tags: firebase-analytics, event, screen-view, user-property, observer
+---
+
+## Analytics Event Taxonomy & Screen Tracking
+
+**Impact: HIGH (이벤트 미설계 → 무의미한 데이터 축적, 의사결정 근거 부재)**
+
+Firebase Analytics 초기화, 이벤트 택소노미 설계, 사용자 속성,
+AnalyticsObserver를 통한 화면 추적, 디버그 모드.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  firebase_core: ^3.8.0
+  firebase_analytics: ^11.4.0
+```
+
+### 이벤트 택소노미 설계
+
+**Incorrect (무분별한 이벤트 로깅):**
+```dart
+// 이벤트 이름이 일관성 없고 파라미터 미정의
+analytics.logEvent(name: 'clicked_button');
+analytics.logEvent(name: 'user_did_something');
+analytics.logEvent(name: 'pageView', parameters: {'p': 'home'});
+// → 분석 불가능한 데이터 축적
+```
+
+**Correct (구조화된 택소노미):**
+```dart
+/// 이벤트 이름 상수 (snake_case, 40자 이하)
+abstract class AnalyticsEvents {
+  // 화면 이벤트
+  static const screenView = 'screen_view';
+
+  // 사용자 액션
+  static const buttonClick = 'button_click';
+  static const featureUse = 'feature_use';
+  static const search = 'search';
+
+  // 비즈니스 이벤트
+  static const matchCreated = 'match_created';
+  static const matchJoined = 'match_joined';
+  static const matchCompleted = 'match_completed';
+
+  // 전환 이벤트
+  static const signUp = 'sign_up';
+  static const login = 'login';
+  static const subscriptionStarted = 'subscription_started';
+
+  // 에러 이벤트
+  static const errorOccurred = 'error_occurred';
+}
+
+/// 파라미터 이름 상수
+abstract class AnalyticsParams {
+  static const screenName = 'screen_name';
+  static const screenClass = 'screen_class';
+  static const buttonName = 'button_name';
+  static const featureName = 'feature_name';
+  static const sportType = 'sport_type';
+  static const errorType = 'error_type';
+  static const errorMessage = 'error_message';
+  static const source = 'source';
+}
+```
+
+### Analytics 서비스
+
+```dart
+class AnalyticsService {
+  final FirebaseAnalytics _analytics = FirebaseAnalytics.instance;
+
+  /// 화면 조회
+  Future<void> logScreenView({
+    required String screenName,
+    String? screenClass,
+  }) async {
+    await _analytics.logScreenView(
+      screenName: screenName,
+      screenClass: screenClass ?? screenName,
+    );
+  }
+
+  /// 버튼 클릭
+  Future<void> logButtonClick({
+    required String buttonName,
+    required String screenName,
+  }) async {
+    await _analytics.logEvent(
+      name: AnalyticsEvents.buttonClick,
+      parameters: {
+        AnalyticsParams.buttonName: buttonName,
+        AnalyticsParams.screenName: screenName,
+      },
+    );
+  }
+
+  /// 기능 사용
+  Future<void> logFeatureUse({
+    required String featureName,
+    Map<String, Object>? extra,
+  }) async {
+    await _analytics.logEvent(
+      name: AnalyticsEvents.featureUse,
+      parameters: {
+        AnalyticsParams.featureName: featureName,
+        ...?extra,
+      },
+    );
+  }
+
+  /// 비즈니스 이벤트
+  Future<void> logMatchCreated({
+    required String sportType,
+    required int maxPlayers,
+  }) async {
+    await _analytics.logEvent(
+      name: AnalyticsEvents.matchCreated,
+      parameters: {
+        AnalyticsParams.sportType: sportType,
+        'max_players': maxPlayers,
+      },
+    );
+  }
+}
+
+// Riverpod Provider
+final analyticsServiceProvider = Provider<AnalyticsService>((ref) {
+  return AnalyticsService();
+});
+```
+
+### 사용자 속성
+
+```dart
+/// 사용자 세그먼트 설정 (최대 25개 속성)
+Future<void> setUserProperties({
+  required String userId,
+  String? userType,
+  String? subscriptionTier,
+  String? preferredSport,
+  String? region,
+}) async {
+  final analytics = FirebaseAnalytics.instance;
+
+  await analytics.setUserId(id: userId);
+
+  if (userType != null) {
+    await analytics.setUserProperty(name: 'user_type', value: userType);
+  }
+  if (subscriptionTier != null) {
+    await analytics.setUserProperty(
+      name: 'subscription_tier',
+      value: subscriptionTier,
+    );
+  }
+  if (preferredSport != null) {
+    await analytics.setUserProperty(
+      name: 'preferred_sport',
+      value: preferredSport,
+    );
+  }
+  if (region != null) {
+    await analytics.setUserProperty(name: 'region', value: region);
+  }
+}
+```
+
+### go_router 화면 추적 (AnalyticsObserver)
+
+```dart
+// GoRouter 설정에 observer 추가
+final goRouter = GoRouter(
+  routes: [...],
+  observers: [
+    FirebaseAnalyticsObserver(
+      analytics: FirebaseAnalytics.instance,
+      nameExtractor: (settings) {
+        // route 이름을 screen_name으로 매핑
+        return settings.name ?? settings.arguments?.toString() ?? 'unknown';
+      },
+    ),
+  ],
+);
+
+// GoRoute에 name 명시 (observer가 이름 추출)
+GoRoute(
+  path: '/match/:id',
+  name: 'match_detail',
+  builder: (context, state) => MatchDetailScreen(
+    matchId: state.pathParameters['id']!,
+  ),
+),
+```
+
+### 디버그 모드
+
+```
+# Android: DebugView 활성화
+adb shell setprop debug.firebase.analytics.app <package_name>
+
+# 이벤트가 실시간으로 Firebase Console > DebugView에 표시
+# 비활성화:
+adb shell setprop debug.firebase.analytics.app .none.
+
+# iOS: Xcode Scheme > Arguments
+-FIRDebugEnabled   # 활성화
+-FIRDebugDisabled  # 비활성화
+```
+
+### 규칙
+
+- 이벤트 택소노미 → 구현 전에 문서화 (이름, 파라미터, 트리거 조건)
+- 이벤트 이름 → snake_case, 40자 이하, 자동 수집 이벤트와 충돌 금지
+- 파라미터 → 최대 25개/이벤트, 값 100자 이하
+- 사용자 속성 → 세그먼트 기준만 (최대 25개, 값 36자 이하)
+- `AnalyticsObserver` → go_router 연동으로 화면 전환 자동 추적
+- `setUserId` → 로그인 시 설정, 로그아웃 시 `null` 로 해제
+- 디버그 → DebugView로 실시간 이벤트 검증 후 프로덕션 배포
+- PII (개인식별정보) → 이벤트 파라미터에 이름/이메일/전화번호 금지

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

@@ -0,0 +1,195 @@
+---
+title: Crashlytics Setup & Error Capture
+impact: CRITICAL
+impactDescription: "크래시 미수집 → 프로덕션 장애 감지 불가, 사용자 이탈 원인 파악 불가"
+tags: crashlytics, firebase, crash, error, fatal
+---
+
+## Crashlytics Setup & Error Capture
+
+**Impact: CRITICAL (크래시 미수집 → 프로덕션 장애 감지 불가, 사용자 이탈 원인 파악 불가)**
+
+Firebase Crashlytics 초기화, Flutter/Dart 에러 캡처, 비치명 에러 기록,
+사용자 식별자 및 커스텀 키 설정.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  firebase_core: ^3.8.0
+  firebase_crashlytics: ^4.3.0
+```
+
+### 초기화
+
+**Incorrect (에러 핸들러 미연결):**
+```dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+  // Crashlytics 에러 핸들러 미등록 → 크래시 미수집
+  runApp(const MyApp());
+}
+```
+
+**Correct (완전한 에러 캡처 파이프라인):**
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+
+  // 1. Flutter 프레임워크 에러 (위젯 빌드 에러 등)
+  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;
+
+  // 2. 비동기 에러 (Future, Isolate 등)
+  PlatformDispatcher.instance.onError = (error, stack) {
+    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
+    return true;
+  };
+
+  // 3. Dart Zone 에러 (runZonedGuarded)
+  runZonedGuarded<Future<void>>(
+    () async {
+      runApp(const ProviderScope(child: MyApp()));
+    },
+    (error, stack) {
+      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
+    },
+  );
+}
+```
+
+### 디버그 모드 제어
+
+```dart
+// 개발 중 Crashlytics 비활성화 (크래시 대시보드 오염 방지)
+await FirebaseCrashlytics.instance
+    .setCrashlyticsCollectionEnabled(!kDebugMode);
+
+// 또는 환경별 분리
+final isProduction = const String.fromEnvironment('ENV') == 'production';
+await FirebaseCrashlytics.instance
+    .setCrashlyticsCollectionEnabled(isProduction);
+```
+
+### 비치명 에러 기록
+
+**Incorrect (try-catch만 하고 기록 안 함):**
+```dart
+try {
+  await apiService.fetchData();
+} catch (e) {
+  debugPrint('Error: $e');
+  // → 프로덕션에서 에러 발생 사실을 알 수 없음
+}
+```
+
+**Correct (비치명 에러 Crashlytics 기록):**
+```dart
+try {
+  await apiService.fetchData();
+} catch (error, stack) {
+  // fatal: false → 비치명 에러 (앱 크래시 아님)
+  await FirebaseCrashlytics.instance.recordError(
+    error,
+    stack,
+    fatal: false,
+    reason: 'fetchData API call failed',
+  );
+  // 사용자에게 에러 UI 표시
+  rethrow; // 또는 적절한 에러 핸들링
+}
+```
+
+### 사용자 식별자
+
+```dart
+class CrashlyticsService {
+  final FirebaseCrashlytics _crashlytics = FirebaseCrashlytics.instance;
+
+  /// 로그인 시 사용자 식별자 설정
+  Future<void> setUser(String userId) async {
+    await _crashlytics.setUserIdentifier(userId);
+  }
+
+  /// 로그아웃 시 식별자 제거
+  Future<void> clearUser() async {
+    await _crashlytics.setUserIdentifier('');
+  }
+
+  /// 커스텀 키 설정 (크래시 컨텍스트)
+  Future<void> setContext({
+    required String appVersion,
+    required String buildNumber,
+    String? subscriptionTier,
+    bool? isOnboarded,
+  }) async {
+    await _crashlytics.setCustomKey('app_version', appVersion);
+    await _crashlytics.setCustomKey('build_number', buildNumber);
+    if (subscriptionTier != null) {
+      await _crashlytics.setCustomKey('subscription_tier', subscriptionTier);
+    }
+    if (isOnboarded != null) {
+      await _crashlytics.setCustomKey('is_onboarded', isOnboarded);
+    }
+  }
+
+  /// 커스텀 로그 (크래시 발생 직전 흐름 추적)
+  void log(String message) {
+    _crashlytics.log(message);
+  }
+
+  /// 비치명 에러 기록
+  Future<void> recordNonFatal(
+    dynamic error,
+    StackTrace stack, {
+    String? reason,
+  }) async {
+    await _crashlytics.recordError(
+      error,
+      stack,
+      fatal: false,
+      reason: reason,
+    );
+  }
+}
+
+// Riverpod Provider
+final crashlyticsServiceProvider = Provider<CrashlyticsService>((ref) {
+  return CrashlyticsService();
+});
+```
+
+### dSYM / ProGuard 설정
+
+```
+iOS (dSYM 업로드):
+  Xcode > Build Settings > Debug Information Format = DWARF with dSYM File
+  firebase_crashlytics가 빌드 스크립트 자동 추가 (Run Script Phase)
+  수동: firebase crashlytics:symbols:upload --app=<APP_ID> path/to/dSYMs
+
+Android (ProGuard/R8 mapping):
+  android/app/build.gradle:
+    buildTypes {
+      release {
+        minifyEnabled true
+        shrinkResources true
+        // firebase_crashlytics Gradle 플러그인이 mapping 자동 업로드
+      }
+    }
+  android/build.gradle:
+    plugins { id 'com.google.firebase.crashlytics' }
+```
+
+### 규칙
+
+- `FlutterError.onError` → Crashlytics 연결 필수 (Flutter 프레임워크 에러)
+- `PlatformDispatcher.instance.onError` → 비동기 에러 캡처 필수
+- `runZonedGuarded` → Dart Zone 에러까지 포괄 (선택이지만 강력 권장)
+- 디버그 모드 → `setCrashlyticsCollectionEnabled(false)` (대시보드 오염 방지)
+- 비치명 에러 → `recordError(fatal: false)` + reason 명시
+- `setUserIdentifier` → 로그인/로그아웃 시 설정/해제
+- `setCustomKey` → 구독 등급, 기능 플래그 등 비즈니스 컨텍스트
+- `log()` → 크래시 직전 사용자 흐름 기록 (최대 64KB)
+- dSYM (iOS) / ProGuard mapping (Android) → 릴리스 빌드 심볼 업로드 필수

package/templates/base/skills/mobile/flutter/monitoring/rules/logging.md

@@ -0,0 +1,258 @@
+---
+title: Structured Logging & Sensitive Data Masking
+impact: MEDIUM
+impactDescription: "로그 미관리 → 프로덕션 디버깅 불가, 민감 데이터 유출 위험"
+tags: logger, structured-logging, masking, remote-logging, log-level
+---
+
+## Structured Logging & Sensitive Data Masking
+
+**Impact: MEDIUM (로그 미관리 → 프로덕션 디버깅 불가, 민감 데이터 유출 위험)**
+
+logger 패키지를 활용한 레벨별 로깅, JSON 구조화된 로그 출력,
+릴리스 빌드 레벨 필터, 원격 로깅 연동, 민감 데이터 마스킹.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  logger: ^2.5.0
+```
+
+### 기본 설정
+
+**Incorrect (print/debugPrint 직접 사용):**
+```dart
+print('User logged in: ${user.email}');
+debugPrint('API response: ${response.data}');
+// → 레벨 구분 없음, 릴리스에서 제거 불가, PII 노출
+```
+
+**Correct (구조화된 로거):**
+```dart
+class AppLogger {
+  static final AppLogger instance = AppLogger._();
+  AppLogger._();
+
+  late final Logger _logger;
+  final List<LogOutput> _outputs = [];
+
+  void initialize({bool isRelease = false}) {
+    _logger = Logger(
+      filter: isRelease ? ProductionFilter() : DevelopFilter(),
+      printer: isRelease
+          ? JsonPrinter()        // 프로덕션: JSON 구조화
+          : PrettyPrinter(       // 개발: 색상 + 포맷팅
+              methodCount: 2,
+              errorMethodCount: 8,
+              lineLength: 120,
+              colors: true,
+              printEmojis: false,
+              dateTimeFormat: DateTimeFormat.onlyTimeAndSinceStart,
+            ),
+      output: MultiOutput(_outputs),
+    );
+  }
+
+  void addOutput(LogOutput output) => _outputs.add(output);
+
+  void verbose(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.t(message, error: error, stackTrace: stack);
+
+  void debug(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.d(message, error: error, stackTrace: stack);
+
+  void info(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.i(message, error: error, stackTrace: stack);
+
+  void warning(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.w(message, error: error, stackTrace: stack);
+
+  void error(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.e(message, error: error, stackTrace: stack);
+
+  void fatal(String message, [dynamic error, StackTrace? stack]) =>
+      _logger.f(message, error: error, stackTrace: stack);
+}
+
+// 사용
+final log = AppLogger.instance;
+log.info('User logged in', null, null);
+log.error('API call failed', exception, stackTrace);
+```
+
+### 릴리스 빌드 필터
+
+```dart
+/// 프로덕션: warning 이상만 출력
+class ProductionFilter extends LogFilter {
+  @override
+  bool shouldLog(LogEvent event) {
+    return event.level.index >= Level.warning.index;
+  }
+}
+
+/// 개발: 모든 레벨 출력
+class DevelopFilter extends LogFilter {
+  @override
+  bool shouldLog(LogEvent event) {
+    return true;
+  }
+}
+```
+
+### JSON 구조화 프린터
+
+```dart
+/// 프로덕션용 JSON 출력 (원격 로깅 시스템과 호환)
+class JsonPrinter extends LogPrinter {
+  @override
+  List<String> log(LogEvent event) {
+    final output = {
+      'timestamp': DateTime.now().toUtc().toIso8601String(),
+      'level': event.level.name,
+      'message': event.message,
+    };
+
+    if (event.error != null) {
+      output['error'] = event.error.toString();
+    }
+    if (event.stackTrace != null) {
+      output['stackTrace'] = event.stackTrace.toString();
+    }
+
+    return [jsonEncode(output)];
+  }
+}
+```
+
+### 원격 로깅
+
+```dart
+/// Sentry breadcrumb로 원격 로깅
+class SentryLogOutput extends LogOutput {
+  @override
+  void output(OutputEvent event) {
+    // warning 이상만 Sentry breadcrumb으로 전송
+    if (event.level.index < Level.warning.index) return;
+
+    final level = switch (event.level) {
+      Level.warning => SentryLevel.warning,
+      Level.error => SentryLevel.error,
+      Level.fatal => SentryLevel.fatal,
+      _ => SentryLevel.info,
+    };
+
+    Sentry.addBreadcrumb(Breadcrumb(
+      message: event.lines.join('\n'),
+      level: level,
+      category: 'app.log',
+      timestamp: DateTime.now().toUtc(),
+    ));
+  }
+}
+
+/// Crashlytics 커스텀 로그
+class CrashlyticsLogOutput extends LogOutput {
+  @override
+  void output(OutputEvent event) {
+    if (event.level.index < Level.info.index) return;
+
+    // Crashlytics log → 크래시 발생 시 컨텍스트로 포함 (최대 64KB)
+    FirebaseCrashlytics.instance.log(
+      event.lines.join('\n'),
+    );
+  }
+}
+
+// 초기화 시 출력 추가
+void initializeLogging() {
+  final log = AppLogger.instance;
+  log.initialize(isRelease: kReleaseMode);
+
+  if (kReleaseMode) {
+    log.addOutput(SentryLogOutput());
+    log.addOutput(CrashlyticsLogOutput());
+  }
+}
+```
+
+### 민감 데이터 마스킹
+
+```dart
+/// 민감 데이터 마스킹 유틸리티
+class LogSanitizer {
+  static final _patterns = <RegExp, String>{
+    // 이메일
+    RegExp(r'[\w.+-]+@[\w-]+\.[\w.]+'):
+        '***@***.***',
+    // 전화번호
+    RegExp(r'\+?\d{10,15}'):
+        '***-****-****',
+    // 토큰/키 (Bearer, API key 등)
+    RegExp(r'(Bearer\s+|token[=:]\s*|api[_-]?key[=:]\s*)[A-Za-z0-9\-._~+/]+=*',
+           caseSensitive: false):
+        r'$1[REDACTED]',
+    // 카드 번호 (16자리)
+    RegExp(r'\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'):
+        '****-****-****-****',
+  };
+
+  /// 문자열 내 민감 데이터 마스킹
+  static String sanitize(String input) {
+    var result = input;
+    for (final entry in _patterns.entries) {
+      result = result.replaceAll(entry.key, entry.value);
+    }
+    return result;
+  }
+
+  /// Map 내 민감 키 마스킹
+  static Map<String, dynamic> sanitizeMap(Map<String, dynamic> data) {
+    const sensitiveKeys = {
+      'password', 'token', 'secret', 'api_key', 'apiKey',
+      'authorization', 'credit_card', 'ssn', 'email', 'phone',
+    };
+
+    return data.map((key, value) {
+      if (sensitiveKeys.contains(key.toLowerCase())) {
+        return MapEntry(key, '[REDACTED]');
+      }
+      if (value is String) {
+        return MapEntry(key, sanitize(value));
+      }
+      if (value is Map<String, dynamic>) {
+        return MapEntry(key, sanitizeMap(value));
+      }
+      return MapEntry(key, value);
+    });
+  }
+}
+
+// HTTP 로깅에 마스킹 적용
+class SanitizedLogInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    final sanitizedHeaders = LogSanitizer.sanitizeMap(
+      options.headers.cast<String, dynamic>(),
+    );
+    AppLogger.instance.debug(
+      'HTTP ${options.method} ${options.uri}\n'
+      'Headers: $sanitizedHeaders',
+    );
+    handler.next(options);
+  }
+}
+```
+
+### 규칙
+
+- `print`/`debugPrint` 직접 사용 금지 → `AppLogger` 래퍼 사용
+- 릴리스 빌드 → verbose/debug 레벨 비활성화 (ProductionFilter)
+- 프로덕션 → JSON 구조화 출력 (원격 로깅 시스템 호환)
+- 원격 로깅 → Sentry breadcrumb + Crashlytics log 연동
+- warning 이상 → 원격 전송, info → Crashlytics 컨텍스트만
+- 민감 데이터 → `LogSanitizer`로 마스킹 (토큰, PII, 카드번호)
+- HTTP 로깅 → 헤더/바디 마스킹 후 출력
+- 로그 레벨 가이드: verbose(개발 추적), debug(디버깅), info(흐름), warning(주의), error(복구 가능), fatal(복구 불가)