timsquad 3.3.0 → 3.4.0

package/templates/base/skills/mobile/flutter/monitoring/references/monitoring-architecture.md

@@ -0,0 +1,269 @@
+---
+title: Monitoring Architecture & Dashboard Configuration
+category: reference
+source: internal
+tags: architecture, dashboard, alerting, data-retention, crashlytics, sentry, analytics
+---
+
+# Monitoring Architecture & Dashboard Configuration
+
+모니터링 레이어 구조, 대시보드 구성, 알림 설정, 데이터 보존 정책.
+프로덕션 운영 시 참조.
+
+## Key Concepts
+
+- **레이어 모델**: crash → error → performance → analytics → logging (우선순위 순)
+- **대시보드 분리**: Firebase Console (크래시/성능) + Sentry (에러 컨텍스트)
+- **알림 전략**: 크래시 스파이크, ANR, 성능 저하에 대한 자동 알림
+- **데이터 보존**: 도구별 보존 기간 + 비용 최적화
+
+## Monitoring Layer Model
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Monitoring Layers                     │
+├─────────┬───────────────┬───────────────┬───────────────┤
+│ Layer   │ Tool          │ Priority      │ Purpose       │
+├─────────┼───────────────┼───────────────┼───────────────┤
+│ L1      │ Crashlytics   │ CRITICAL      │ 앱 크래시     │
+│ Crash   │               │               │ ANR/프리징    │
+│         │               │               │ 안정성 %      │
+├─────────┼───────────────┼───────────────┼───────────────┤
+│ L2      │ Sentry        │ HIGH          │ 비치명 에러   │
+│ Error   │ + Crashlytics │               │ 에러 컨텍스트 │
+│         │               │               │ breadcrumbs   │
+├─────────┼───────────────┼───────────────┼───────────────┤
+│ L3      │ Firebase      │ HIGH          │ 앱 시작 시간  │
+│ Perf    │ Performance   │               │ HTTP 응답     │
+│         │               │               │ 프레임 렌더링 │
+├─────────┼───────────────┼───────────────┼───────────────┤
+│ L4      │ Firebase      │ MEDIUM        │ 사용자 행동   │
+│ Analyt  │ Analytics     │               │ 전환 퍼널     │
+│         │               │               │ 리텐션        │
+├─────────┼───────────────┼───────────────┼───────────────┤
+│ L5      │ logger +      │ LOW           │ 디버깅 추적   │
+│ Logging │ Sentry/Crash  │               │ 원격 컨텍스트 │
+│         │               │               │ 감사 로그     │
+└─────────┴───────────────┴───────────────┴───────────────┘
+```
+
+## Directory Structure
+
+```
+lib/
+├── core/
+│   └── monitoring/
+│       ├── monitoring_service.dart           # 통합 초기화 + Facade
+│       ├── crashlytics/
+│       │   ├── crashlytics_service.dart      # Crashlytics 래퍼
+│       │   └── crashlytics_error_handler.dart # 에러 핸들러 체인
+│       ├── analytics/
+│       │   ├── analytics_service.dart        # Analytics 래퍼
+│       │   ├── analytics_events.dart         # 이벤트 상수
+│       │   └── analytics_observer.dart       # GoRouter observer
+│       ├── performance/
+│       │   ├── performance_service.dart      # Custom trace 래퍼
+│       │   └── performance_interceptor.dart  # Dio HTTP metric
+│       ├── sentry/
+│       │   ├── sentry_service.dart           # Sentry 래퍼
+│       │   ├── sentry_breadcrumb_service.dart # Breadcrumb 관리
+│       │   └── sentry_navigator_observer.dart # 네비게이션 추적
+│       ├── logging/
+│       │   ├── app_logger.dart               # Logger 래퍼
+│       │   ├── log_sanitizer.dart            # 민감 데이터 마스킹
+│       │   └── remote_log_output.dart        # 원격 로그 출력
+│       └── providers/
+│           └── monitoring_providers.dart      # Riverpod providers
+```
+
+## Initialization Order
+
+```
+main.dart 초기화 순서:
+  │
+  ├─ 1. WidgetsFlutterBinding.ensureInitialized()
+  ├─ 2. Firebase.initializeApp()
+  ├─ 3. FlutterError.onError = Crashlytics.recordFlutterFatalError
+  ├─ 4. PlatformDispatcher.instance.onError → Crashlytics.recordError
+  ├─ 5. SentryFlutter.init(appRunner: ...)
+  │     └─ 내부에서 runApp() 호출
+  │        │
+  │        └─ App 초기화 시:
+  │            ├─ MonitoringService.initialize()
+  │            │   ├─ CrashlyticsService.setUser()
+  │            │   ├─ AnalyticsService.setUserProperties()
+  │            │   ├─ PerformanceService.enable()
+  │            │   └─ AppLogger.initialize()
+  │            └─ GoRouter observers: [AnalyticsObserver, SentryObserver]
+```
+
+## Dashboard Configuration
+
+### Firebase Console
+
+```
+Firebase Console > Crashlytics:
+  ├─ Overview: 크래시 없는 사용자 % (목표: 99.5% 이상)
+  ├─ Issues: 크래시 목록 (발생 빈도, 영향 사용자 수)
+  ├─ Trends: 버전별 안정성 추이
+  └─ Velocity alerts: 크래시 급증 알림
+
+Firebase Console > Performance:
+  ├─ Dashboard: 앱 시작 시간, 화면 렌더링
+  ├─ Network: HTTP 요청 성능 (응답 시간, 성공률)
+  ├─ Custom traces: 비즈니스 로직 성능
+  └─ Threshold alerts: 성능 임계값 알림
+
+Firebase Console > Analytics:
+  ├─ Dashboard: 활성 사용자, 세션
+  ├─ Events: 이벤트 발생 빈도
+  ├─ Funnels: 전환 퍼널 (가입 → 매치 생성 → 완료)
+  ├─ Retention: 일별/주별 리텐션
+  └─ Audiences: 사용자 세그먼트
+```
+
+### Sentry Dashboard
+
+```
+Sentry > Issues:
+  ├─ 에러 목록 (발생 빈도, 영향 사용자, 첫 발생/마지막 발생)
+  ├─ 에러 상세 (breadcrumbs, 태그, 디바이스 정보)
+  └─ 에러 그룹화 (fingerprint 기반)
+
+Sentry > Performance:
+  ├─ 트랜잭션 목록 (p50, p75, p95)
+  ├─ 느린 트랜잭션 식별
+  └─ Web Vitals (웹뷰 사용 시)
+
+Sentry > Alerts:
+  ├─ Issue alerts: 새 에러 발생 시
+  ├─ Metric alerts: 에러율 임계값 초과 시
+  └─ Integrations: Slack, PagerDuty, Email
+```
+
+## Alerting Strategy
+
+```
+┌──────────────────┬────────────┬──────────────────────────────┐
+│ Alert Type       │ Severity   │ Action                       │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ Crash spike      │ P0         │ Slack #alerts + PagerDuty    │
+│ (>1% 사용자 영향) │            │ 즉시 대응 (핫픽스 검토)       │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ ANR rate >0.5%   │ P1         │ Slack #alerts                │
+│                  │            │ 24시간 내 조사               │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ New fatal crash  │ P1         │ Slack #alerts                │
+│                  │            │ 다음 스프린트 수정            │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ Performance      │ P2         │ Slack #monitoring            │
+│ degradation      │            │ 앱 시작 >3s, API p95 >2s     │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ Error rate       │ P2         │ Sentry alert                 │
+│ spike (비치명)    │            │ 다음 스프린트 우선순위 검토    │
+├──────────────────┼────────────┼──────────────────────────────┤
+│ Drop in daily    │ P3         │ Weekly review                │
+│ active users     │            │ Analytics 퍼널 분석           │
+└──────────────────┴────────────┴──────────────────────────────┘
+```
+
+## Data Retention Policy
+
+```
+┌────────────────┬──────────────┬────────────┬─────────────────┐
+│ Tool           │ Free Tier    │ Paid Tier  │ Recommendation  │
+├────────────────┼──────────────┼────────────┼─────────────────┤
+│ Crashlytics    │ 90일         │ 90일       │ 그대로 사용      │
+│ Analytics      │ 14개월       │ 14개월     │ BigQuery 연동    │
+│ Performance    │ 자동 관리     │ 자동 관리   │ 그대로 사용      │
+│ Sentry (Free)  │ 30일         │ 90일       │ 주요 이슈 북마크  │
+│ App logs       │ 세션 내       │ —          │ 원격 로깅 연동   │
+└────────────────┴──────────────┴────────────┴─────────────────┘
+
+BigQuery 연동 (Analytics 장기 보존):
+  Firebase Console > Project Settings > Integrations > BigQuery
+  - 일별 raw event export
+  - SQL 쿼리로 커스텀 분석
+  - Data Studio / Looker 대시보드 연동
+```
+
+## Monitoring Service (Facade)
+
+```dart
+/// 모니터링 통합 초기화 Facade
+class MonitoringService {
+  final CrashlyticsService _crashlytics;
+  final AnalyticsService _analytics;
+  final PerformanceService _performance;
+  final SentryScopeManager _sentry;
+  final AppLogger _logger;
+
+  MonitoringService({
+    required CrashlyticsService crashlytics,
+    required AnalyticsService analytics,
+    required PerformanceService performance,
+    required SentryScopeManager sentry,
+    required AppLogger logger,
+  })  : _crashlytics = crashlytics,
+        _analytics = analytics,
+        _performance = performance,
+        _sentry = sentry,
+        _logger = logger;
+
+  /// 사용자 로그인 시 모든 서비스에 사용자 설정
+  Future<void> identifyUser({
+    required String userId,
+    String? email,
+    Map<String, String>? properties,
+  }) async {
+    await _crashlytics.setUser(userId);
+    await _analytics.setUserId(userId);
+    await _sentry.setUser(id: userId, email: email);
+    _logger.info('User identified: $userId');
+
+    if (properties != null) {
+      await _crashlytics.setContext(
+        appVersion: properties['app_version'] ?? '',
+        buildNumber: properties['build_number'] ?? '',
+        subscriptionTier: properties['tier'],
+      );
+      for (final entry in properties.entries) {
+        await _analytics.setUserProperty(
+          name: entry.key,
+          value: entry.value,
+        );
+      }
+    }
+  }
+
+  /// 로그아웃 시 모든 서비스 정리
+  Future<void> clearUser() async {
+    await _crashlytics.clearUser();
+    await _analytics.setUserId(null);
+    await _sentry.clearUser();
+    _logger.info('User cleared from monitoring');
+  }
+}
+
+/// Riverpod Provider
+final monitoringServiceProvider = Provider<MonitoringService>((ref) {
+  return MonitoringService(
+    crashlytics: ref.watch(crashlyticsServiceProvider),
+    analytics: ref.watch(analyticsServiceProvider),
+    performance: ref.watch(performanceServiceProvider),
+    sentry: ref.watch(sentryScopeManagerProvider),
+    logger: AppLogger.instance,
+  );
+});
+```
+
+## Common Pitfalls
+
+1. **초기화 순서**: Firebase → Crashlytics 핸들러 → Sentry → 나머지 (순서 중요)
+2. **디버그 데이터 오염**: 개발 중 크래시/이벤트가 프로덕션 대시보드에 혼합 → 환경 분리
+3. **이벤트 쿼터**: Sentry 무료 5K/월, Analytics 500이벤트/사용자/일 → 필터링 필수
+4. **PII 유출**: 로그/이벤트에 이메일/전화번호 포함 → 마스킹 + sendDefaultPii:false
+5. **소스맵 미업로드**: 난독화된 스택트레이스 → dSYM/ProGuard mapping 업로드 자동화
+6. **과도한 breadcrumb**: Sentry 기본 100개 제한 → 중요한 것만 기록
+7. **성능 오버헤드**: 모니터링 SDK 자체가 성능에 영향 → 샘플링률 조절
+8. **알림 피로**: 모든 에러에 알림 → 임계값 기반 알림으로 전환

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) → 릴리스 빌드 심볼 업로드 필수