timsquad 2.1.0 → 3.4.0

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(복구 불가)

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) 초과 시 경고