timsquad 2.1.0 → 3.4.0

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 인터셉터 비활성화 |

package/templates/base/skills/mobile/flutter/networking/references/api-client-architecture.md

@@ -0,0 +1,305 @@
+---
+title: API Client Architecture
+category: reference
+source: internal
+tags: architecture, directory, provider, repository, mock, testing
+---
+
+# API Client Architecture
+
+네트워크 레이어 전체 아키텍처. 디렉토리 구조, Provider 그래프, Repository 패턴, Mock 테스트 전략.
+
+## Key Concepts
+
+- **중앙화**: 네트워크 관련 코드를 `core/networking/` 에 집중 (feature 횡단 관심사)
+- **계층 분리**: Dio → Interceptor → API Client → Repository → Provider → UI
+- **테스트 가능성**: API Client 추상화로 Mock 구현 용이
+- **오프라인 우선**: 캐시 + 큐 + connectivity 감지를 기본 탑재
+
+## Directory Structure
+
+```
+lib/
+├── core/
+│   └── networking/
+│       ├── dio_provider.dart              # Dio 싱글톤 Provider
+│       ├── app_config.dart                # 환경 설정 (baseUrl 등)
+│       ├── interceptors/
+│       │   ├── auth_interceptor.dart       # 토큰 주입 + 401 리프레시
+│       │   ├── retry_interceptor.dart      # 지수 백오프 재시도
+│       │   ├── logging_interceptor.dart    # 요청/응답 로깅
+│       │   └── error_transform_interceptor.dart  # DioException → NetworkFailure
+│       ├── errors/
+│       │   ├── network_failure.dart        # sealed class 에러 타입
+│       │   └── result.dart                # Result<T> 타입
+│       ├── cache/
+│       │   ├── cache_config.dart           # 캐시 정책 팩토리
+│       │   ├── cache_store_provider.dart   # HiveCacheStore Provider
+│       │   └── cache_manager.dart          # 캐시 클리어/무효화
+│       ├── connectivity/
+│       │   ├── connectivity_notifier.dart  # 연결 상태 스트림
+│       │   ├── offline_queue.dart          # 오프라인 요청 큐
+│       │   └── offline_banner.dart         # 오프라인 UI 위젯
+│       └── api/
+│           ├── user_api.dart              # @RestApi 클라이언트
+│           ├── match_api.dart             # @RestApi 클라이언트
+│           └── ...
+│
+├── features/
+│   └── user/
+│       ├── data/
+│       │   ├── models/
+│       │   │   ├── user_response.dart     # freezed 응답 모델
+│       │   │   └── create_user_request.dart  # freezed 요청 모델
+│       │   └── repositories/
+│       │       └── user_repository_impl.dart  # API 호출 + 에러 변환
+│       ├── domain/
+│       │   ├── entities/
+│       │   │   └── user.dart              # 도메인 엔티티
+│       │   └── repositories/
+│       │       └── user_repository.dart    # abstract
+│       └── presentation/
+│           └── providers/
+│               └── user_provider.dart      # UI 상태 관리
+```
+
+## Provider Dependency Graph
+
+```
+AppConfig
+    │
+    ▼
+DioProvider ──────────────────────────────────┐
+    │                                          │
+    ├─ AuthInterceptor ← TokenStorage          │
+    ├─ RetryInterceptor                        │
+    ├─ LoggingInterceptor (dev only)           │
+    ├─ ErrorTransformInterceptor               │
+    └─ DioCacheInterceptor ← CacheStore        │
+                                               │
+    ┌──────────────────────────────────────────┘
+    │
+    ▼
+API Clients (Retrofit)
+    │  UserApi, MatchApi, ...
+    │
+    ▼
+Repositories
+    │  UserRepository, MatchRepository, ...
+    │  (API 호출 + Result<T> 반환)
+    │
+    ▼
+Notifiers / Providers
+    │  UserNotifier, MatchNotifier, ...
+    │  (비즈니스 로직 + UI 상태)
+    │
+    ▼
+Widgets (UI)
+
+ConnectivityNotifier ────► OfflineQueueManager
+       │                         │
+       └── OfflineBanner (UI)    └── 연결 복구 시 큐 처리
+```
+
+## Provider 코드
+
+```dart
+// core/networking/providers.dart — 네트워크 레이어 Provider 모음
+
+/// 앱 설정
+final appConfigProvider = Provider<AppConfig>((ref) => AppConfig.dev);
+
+/// Dio 싱글톤
+final dioProvider = Provider<Dio>((ref) {
+  final config = ref.watch(appConfigProvider);
+  final dio = Dio(BaseOptions(
+    baseUrl: config.baseUrl,
+    connectTimeout: const Duration(seconds: 15),
+    receiveTimeout: const Duration(seconds: 15),
+    sendTimeout: const Duration(seconds: 15),
+    headers: {'Content-Type': 'application/json', 'Accept': 'application/json'},
+  ));
+
+  dio.interceptors.addAll([
+    ref.watch(authInterceptorProvider),
+    ref.watch(retryInterceptorProvider),
+    if (config.environment == AppEnvironment.dev)
+      ref.watch(loggingInterceptorProvider),
+    ref.watch(errorTransformInterceptorProvider),
+  ]);
+
+  return dio;
+});
+
+/// API Clients
+final userApiProvider = Provider<UserApi>((ref) {
+  return UserApi(ref.watch(dioProvider));
+});
+
+/// Repositories
+final userRepositoryProvider = Provider<UserRepository>((ref) {
+  return UserRepositoryImpl(api: ref.watch(userApiProvider));
+});
+
+/// Connectivity
+final connectivityProvider =
+    StreamNotifierProvider<ConnectivityNotifier, NetworkStatus>(
+  ConnectivityNotifier.new,
+);
+
+final isOnlineProvider = Provider<bool>((ref) {
+  return ref.watch(connectivityProvider).valueOrNull == NetworkStatus.online;
+});
+```
+
+## Repository Pattern
+
+```dart
+/// Repository 추상 (domain 레이어)
+abstract class UserRepository {
+  Future<Result<User>> getUser(String id);
+  Future<Result<List<User>>> getUsers({int page = 1});
+  Future<Result<User>> createUser(CreateUserRequest request);
+  Future<Result<void>> deleteUser(String id);
+}
+
+/// Repository 구현 (data 레이어)
+class UserRepositoryImpl implements UserRepository {
+  final UserApi _api;
+
+  UserRepositoryImpl({required UserApi api}) : _api = api;
+
+  @override
+  Future<Result<User>> getUser(String id) async {
+    try {
+      final response = await _api.getUser(id);
+      return Success(response.toDomain());
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+
+  @override
+  Future<Result<List<User>>> getUsers({int page = 1}) async {
+    try {
+      final response = await _api.getUsers(page, 20);
+      return Success(response.data.map((r) => r.toDomain()).toList());
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+
+  // ... createUser, deleteUser 동일 패턴
+}
+```
+
+## Mock Testing Strategy
+
+```dart
+/// Mock API Client
+class MockUserApi implements UserApi {
+  @override
+  Future<UserResponse> getUser(String id) async {
+    return UserResponse(
+      id: id,
+      name: 'Test User',
+      email: 'test@example.com',
+      createdAt: DateTime.now(),
+    );
+  }
+
+  @override
+  Future<PaginatedResponse<UserResponse>> getUsers(int page, int limit) async {
+    return PaginatedResponse(
+      data: List.generate(limit, (i) => UserResponse(
+        id: 'user_$i',
+        name: 'User $i',
+        email: 'user$i@example.com',
+        createdAt: DateTime.now(),
+      )),
+      total: 100,
+      page: page,
+      lastPage: 5,
+    );
+  }
+
+  // ...
+}
+
+/// 테스트에서 Provider 오버라이드
+void main() {
+  group('UserNotifier', () {
+    late ProviderContainer container;
+
+    setUp(() {
+      container = ProviderContainer(overrides: [
+        userApiProvider.overrideWithValue(MockUserApi()),
+      ]);
+    });
+
+    tearDown(() => container.dispose());
+
+    test('loads user successfully', () async {
+      final repository = container.read(userRepositoryProvider);
+      final result = await repository.getUser('user_1');
+
+      expect(result, isA<Success<User>>());
+      expect((result as Success).data.name, 'Test User');
+    });
+  });
+}
+
+/// 에러 시나리오 Mock
+class ErrorUserApi implements UserApi {
+  @override
+  Future<UserResponse> getUser(String id) async {
+    throw DioException(
+      requestOptions: RequestOptions(path: '/users/$id'),
+      type: DioExceptionType.connectionTimeout,
+    );
+  }
+
+  // ...
+}
+
+/// 에러 테스트
+test('returns TimeoutFailure on connection timeout', () async {
+  final container = ProviderContainer(overrides: [
+    userApiProvider.overrideWithValue(ErrorUserApi()),
+  ]);
+
+  final repository = container.read(userRepositoryProvider);
+  final result = await repository.getUser('user_1');
+
+  expect(result, isA<Failure<User>>());
+  expect((result as Failure).failure, isA<TimeoutFailure>());
+});
+```
+
+## Initialization Flow
+
+```
+앱 시작 (main.dart)
+  │
+  ├─ 1. WidgetsFlutterBinding.ensureInitialized()
+  ├─ 2. AppConfig 결정 (환경 변수 / 빌드 플래그)
+  ├─ 3. CacheStore 초기화 (HiveCacheStore)
+  ├─ 4. ProviderScope(overrides: [appConfig, cacheStore])
+  └─ 5. runApp()
+        │
+        └─ App 위젯 build
+            ├─ DioProvider 자동 생성 (lazy)
+            ├─ ConnectivityNotifier 스트림 시작
+            └─ OfflineBanner 조건부 표시
+```
+
+## Common Pitfalls
+
+1. **Dio 다중 인스턴스**: Feature마다 Dio 생성 → 인터셉터 미적용, 토큰 누락
+2. **인터셉터 순서**: Error Transform이 Auth 앞 → 401 리프레시 불가
+3. **토큰 리프레시 순환**: Auth 인터셉터가 메인 Dio로 리프레시 → 무한 루프
+4. **캐시 + 인증 에러**: 401 응답 캐시 → 로그인 후에도 에러 반환
+5. **오프라인 큐 영속성**: 메모리 큐만 사용 → 앱 재시작 시 유실
+6. **connectTimeout vs receiveTimeout**: connect는 TCP 연결, receive는 데이터 수신 — 둘 다 설정 필수
+7. **validateStatus 미설정**: 4xx도 DioException → 정상 에러 응답 처리 불가
+8. **build_runner 미실행**: Retrofit `.g.dart` 미생성 → 컴파일 에러