timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/i18n/rules/text-direction.md

@@ -0,0 +1,199 @@
+---
+title: Text Direction & RTL Layout Support
+impact: HIGH
+impactDescription: "RTL 미대응 → 아랍어/히브리어 사용자 UX 파괴, 레이아웃 반전 오류"
+tags: rtl, ltr, directionality, edge-insets-directional, alignment-directional
+---
+
+## Text Direction & RTL Layout Support
+
+**Impact: HIGH (RTL 미대응 → 아랍어/히브리어 사용자 UX 파괴, 레이아웃 반전 오류)**
+
+RTL (Right-to-Left) 레이아웃 지원. Directionality 위젯, EdgeInsetsDirectional,
+AlignmentDirectional, 아이콘 미러링. RTL 로캘 지원 시 필수.
+
+### Directional 위젯 사용
+
+**Incorrect (하드코딩된 left/right):**
+```dart
+Container(
+  padding: const EdgeInsets.only(left: 16, right: 8),
+  alignment: Alignment.centerLeft,
+  child: Row(
+    children: [
+      const Icon(Icons.arrow_back),  // RTL에서도 왼쪽 화살표
+      const SizedBox(width: 8),
+      Text(title),
+    ],
+  ),
+);
+```
+
+**Correct (Directional 위젯으로 RTL 자동 대응):**
+```dart
+Container(
+  padding: const EdgeInsetsDirectional.only(start: 16, end: 8),
+  alignment: AlignmentDirectional.centerStart,
+  child: Row(
+    children: [
+      Icon(
+        // RTL에서는 자동으로 arrow_forward (오른쪽→왼쪽 방향)
+        Directionality.of(context) == TextDirection.rtl
+            ? Icons.arrow_forward
+            : Icons.arrow_back,
+      ),
+      const SizedBox(width: 8),
+      Text(title),
+    ],
+  ),
+);
+```
+
+### EdgeInsets → EdgeInsetsDirectional 변환
+
+```dart
+// ❌ 물리적 방향 (RTL에서 반전 안 됨)
+EdgeInsets.only(left: 16)
+EdgeInsets.fromLTRB(16, 8, 0, 8)
+EdgeInsets.symmetric(horizontal: 16)  // ✅ 대칭은 OK
+
+// ✅ 논리적 방향 (RTL에서 자동 반전)
+EdgeInsetsDirectional.only(start: 16)
+EdgeInsetsDirectional.fromSTEB(16, 8, 0, 8)  // Start, Top, End, Bottom
+EdgeInsetsDirectional.only(start: 16, end: 8)
+
+// Padding 위젯도 동일
+Padding(
+  padding: const EdgeInsetsDirectional.only(start: 16),
+  child: child,
+);
+```
+
+### Alignment → AlignmentDirectional 변환
+
+```dart
+// ❌ 물리적 정렬
+Alignment.centerLeft
+Alignment.topRight
+
+// ✅ 논리적 정렬
+AlignmentDirectional.centerStart  // LTR: left, RTL: right
+AlignmentDirectional.topEnd       // LTR: right, RTL: left
+
+// Container, Align, Positioned 등에 적용
+Container(
+  alignment: AlignmentDirectional.centerStart,
+  child: child,
+);
+
+Align(
+  alignment: AlignmentDirectional.topEnd,
+  child: badge,
+);
+```
+
+### Positioned → PositionedDirectional
+
+```dart
+// ❌ 물리적 위치 (RTL 미대응)
+Positioned(
+  left: 16,
+  top: 8,
+  child: badge,
+);
+
+// ✅ 논리적 위치 (RTL 자동 반전)
+PositionedDirectional(
+  start: 16,
+  top: 8,
+  child: badge,
+);
+```
+
+### 아이콘 미러링
+
+```dart
+/// 방향성을 가진 아이콘 (화살표, 체브론 등)은 RTL에서 미러링
+class DirectionalIcon extends StatelessWidget {
+  final IconData icon;
+  final double? size;
+  final Color? color;
+
+  const DirectionalIcon(this.icon, {super.key, this.size, this.color});
+
+  @override
+  Widget build(BuildContext context) {
+    final isRtl = Directionality.of(context) == TextDirection.rtl;
+
+    // 방향성 아이콘만 미러링 (체크마크, 플러스 등은 미러링 X)
+    if (isRtl) {
+      return Transform.flip(
+        flipX: true,
+        child: Icon(icon, size: size, color: color),
+      );
+    }
+
+    return Icon(icon, size: size, color: color);
+  }
+}
+
+// 사용 예
+DirectionalIcon(Icons.arrow_forward_ios, size: 16),  // RTL에서 자동 반전
+Icon(Icons.check, size: 16),                          // 방향 무관 → 미러링 불필요
+```
+
+### RTL 테스트
+
+```dart
+// 테스트에서 RTL 환경 시뮬레이션
+testWidgets('renders correctly in RTL', (tester) async {
+  await tester.pumpWidget(
+    Directionality(
+      textDirection: TextDirection.rtl,
+      child: MediaQuery(
+        data: const MediaQueryData(),
+        child: Material(
+          child: MyWidget(),
+        ),
+      ),
+    ),
+  );
+
+  // start padding이 RTL에서 오른쪽에 적용되는지 확인
+  final container = tester.widget<Container>(find.byType(Container));
+  // ...assertions
+});
+
+// 전체 앱을 RTL로 실행 (디버그 확인용)
+MaterialApp(
+  locale: const Locale('ar'),  // 아랍어 → RTL 자동 적용
+  // ...
+);
+```
+
+### Row/Column 방향
+
+```dart
+// Row는 TextDirection을 자동 반영
+// LTR: [icon] [text] [chevron →]
+// RTL: [← chevron] [text] [icon]
+Row(
+  children: [
+    const Icon(Icons.person),
+    Expanded(child: Text(context.l10n.profileLabel)),
+    const DirectionalIcon(Icons.chevron_right),
+  ],
+);
+// → Row 내부 순서 변경 불필요, Flutter가 자동 반전
+```
+
+### 규칙
+
+- `EdgeInsets` → `EdgeInsetsDirectional` 로 교체 (left/right → start/end)
+- `Alignment` → `AlignmentDirectional` 로 교체 (centerLeft → centerStart)
+- `Positioned` → `PositionedDirectional` 로 교체 (left → start)
+- 대칭 padding/margin (`symmetric`) → 그대로 사용 가능 (반전 불필요)
+- 방향성 아이콘 (화살표, 체브론) → RTL에서 `Transform.flip` 미러링
+- 방향 무관 아이콘 (체크, 플러스, 검색) → 미러링 금지
+- RTL 테스트 → `Directionality(textDirection: TextDirection.rtl)` 로 래핑
+- `Row`/`ListView` → TextDirection 자동 반영, 순서 변경 불필요

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

@@ -0,0 +1,81 @@
+---
+name: monitoring
+description: |
+  Flutter 모니터링 & 분석 가이드라인.
+  Firebase Crashlytics, Analytics, Performance Monitoring,
+  Sentry 통합, 구조화된 로깅.
+version: "1.0.0"
+tags: [flutter, crashlytics, analytics, performance, sentry, monitoring, logging]
+user-invocable: false
+---
+
+# Monitoring & Analytics
+
+Flutter 앱 모니터링 통합 가이드.
+Firebase Crashlytics + Analytics + Performance, Sentry, 구조화된 로깅으로
+프로덕션 품질을 수치로 관리.
+
+## Philosophy
+
+- 크래시는 0순위 — Crashlytics 비활성화 금지, 모든 비치명 에러도 기록
+- 이벤트는 설계 — 무분별한 로깅 금지, 이벤트 택소노미 먼저 정의
+- 성능은 측정 — 체감이 아닌 custom trace와 HTTP metric으로 수치화
+
+## Resources
+
+5개 규칙 + 1개 참조. 크래시부터 로깅까지 모니터링 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [crashlytics-setup](rules/crashlytics-setup.md) | Crashlytics 초기화, 에러 캡처, 사용자 식별 |
+| HIGH | rule | [analytics](rules/analytics.md) | Analytics 이벤트 택소노미, 사용자 속성, 화면 추적 |
+| HIGH | rule | [performance-monitoring](rules/performance-monitoring.md) | Performance custom trace, HTTP metric, 프레임 모니터링 |
+| MEDIUM | rule | [sentry-integration](rules/sentry-integration.md) | Sentry 초기화, breadcrumbs, scope, Crashlytics 공존 |
+| MEDIUM | rule | [logging](rules/logging.md) | 구조화된 로깅, 레벨 관리, 민감 데이터 마스킹 |
+| — | ref | [monitoring-architecture](references/monitoring-architecture.md) | 모니터링 레이어, 대시보드, 알림, 데이터 보존 |
+
+## Quick Rules
+
+### Crashlytics
+- `FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError`
+- `PlatformDispatcher.instance.onError` → 비동기 에러 캡처
+- 비치명 에러 → `recordError(error, stack, fatal: false)`
+- `setUserIdentifier` → 크래시와 사용자 매핑
+- `setCustomKey` → 디바이스 상태, 기능 플래그 등 컨텍스트
+
+### Analytics
+- 이벤트 택소노미 먼저 정의 (screen_view, button_click, feature_use)
+- `setUserProperty` → user_type, subscription_tier 등 세그먼트 기준
+- `AnalyticsObserver` → go_router 화면 전환 자동 추적
+- 디버그 → `adb shell setprop debug.firebase.analytics.app <package>`
+
+### Performance
+- `FirebasePerformance.instance.newTrace('name')` → custom trace
+- HTTP metric → 자동 수집 (dio interceptor 또는 http_client)
+- 느린 프레임 임계값 16ms (60fps), 8ms (120fps)
+
+### Sentry
+- `SentryFlutter.init` → DSN 환경별 분리 (dev/staging/prod)
+- `Sentry.addBreadcrumb` → 네비게이션, HTTP, 사용자 액션 추적
+- Crashlytics + Sentry 공존 → 각자 역할 분리 (crash vs context)
+
+### Logging
+- `logger` 패키지 → 레벨별 색상 출력 (개발), JSON 구조화 (프로덕션)
+- 릴리스 빌드 → verbose/debug 레벨 비활성화
+- 민감 데이터 (토큰, PII) → 마스킹 필수
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `FlutterError.onError` + `PlatformDispatcher.onError` 연동 |
+| CRITICAL | Crashlytics 디버그 모드 비활성화 (`setCrashlyticsCollectionEnabled`) |
+| CRITICAL | 릴리스 빌드에서 dSYM / ProGuard mapping 업로드 설정 |
+| HIGH | Analytics 이벤트 택소노미 문서화 후 구현 |
+| HIGH | `AnalyticsObserver` go_router 연동 |
+| HIGH | Performance custom trace 핵심 플로우에 적용 |
+| HIGH | HTTP metric 수집 (dio interceptor) |
+| MEDIUM | Sentry DSN 환경별 분리 |
+| MEDIUM | Sentry breadcrumb 네비게이션/HTTP 자동 기록 |
+| MEDIUM | 구조화된 로깅 + 릴리스 레벨 필터 |
+| MEDIUM | 민감 데이터 마스킹 검증 |

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. **알림 피로**: 모든 에러에 알림 → 임계값 기반 알림으로 전환