timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/networking/rules/interceptors.md

@@ -0,0 +1,205 @@
+---
+title: Interceptor Chain Architecture
+impact: CRITICAL
+impactDescription: "인터셉터 순서 오류 → 인증 누락, 무한 재시도, 에러 미변환"
+tags: dio, interceptor, auth, retry, logging, chain
+---
+
+## Interceptor Chain Architecture
+
+**Impact: CRITICAL (인터셉터 순서 오류 → 인증 누락, 무한 재시도, 에러 미변환)**
+
+Dio 인터셉터 체인 설계. Auth → Retry → Logging → Error Transform 순서.
+각 인터셉터의 책임과 구현 패턴.
+
+### 인터셉터 체인 순서
+
+```
+Request Flow:
+  Client → Auth → Retry → Logging → Error Transform → Server
+
+Response Flow:
+  Server → Error Transform → Logging → Retry → Auth → Client
+
+순서 근거:
+1. Auth: 요청에 토큰 주입 (가장 먼저)
+2. Retry: 실패 시 재시도 판단 (Auth 뒤 = 토큰 포함 상태로 재시도)
+3. Logging: 최종 요청/응답 기록 (디버깅용)
+4. Error Transform: DioException → 도메인 에러 변환 (가장 마지막)
+```
+
+### Auth Interceptor
+
+**Incorrect (토큰 만료 시 무한 실패):**
+```dart
+class BadAuthInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    options.headers['Authorization'] = 'Bearer $accessToken';
+    handler.next(options);
+    // → 토큰 만료 시 401 → 재시도 없이 실패
+  }
+}
+```
+
+**Correct (QueuedInterceptorsWrapper로 토큰 리프레시):**
+```dart
+/// Auth 인터셉터 — 토큰 주입 + 401 리프레시
+/// QueuedInterceptorsWrapper: 리프레시 중 다른 요청 큐잉 (중복 리프레시 방지)
+class AuthInterceptor extends QueuedInterceptorsWrapper {
+  final TokenStorage _tokenStorage;
+  final Dio _tokenDio; // 토큰 리프레시 전용 Dio (인터셉터 미적용)
+
+  AuthInterceptor({
+    required TokenStorage tokenStorage,
+    required Dio tokenDio,
+  })  : _tokenStorage = tokenStorage,
+        _tokenDio = tokenDio;
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    final token = await _tokenStorage.getAccessToken();
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode != 401) {
+      return handler.next(err);
+    }
+
+    // 401 → 토큰 리프레시 시도
+    try {
+      final refreshToken = await _tokenStorage.getRefreshToken();
+      if (refreshToken == null) {
+        return handler.next(err); // 리프레시 토큰 없음 → 로그아웃
+      }
+
+      final response = await _tokenDio.post('/auth/refresh', data: {
+        'refresh_token': refreshToken,
+      });
+
+      final newAccessToken = response.data['access_token'] as String;
+      final newRefreshToken = response.data['refresh_token'] as String;
+      await _tokenStorage.saveTokens(newAccessToken, newRefreshToken);
+
+      // 원래 요청 재시도 (새 토큰으로)
+      err.requestOptions.headers['Authorization'] = 'Bearer $newAccessToken';
+      final retryResponse = await _tokenDio.fetch(err.requestOptions);
+      return handler.resolve(retryResponse);
+    } catch (e) {
+      // 리프레시 실패 → 로그아웃 이벤트 발행
+      return handler.next(err);
+    }
+  }
+}
+
+final authInterceptorProvider = Provider<AuthInterceptor>((ref) {
+  return AuthInterceptor(
+    tokenStorage: ref.watch(tokenStorageProvider),
+    tokenDio: Dio(BaseOptions(
+      baseUrl: ref.watch(appConfigProvider).baseUrl,
+    )), // 인터셉터 없는 별도 Dio
+  );
+});
+```
+
+### Retry Interceptor
+
+```dart
+/// Retry 인터셉터 — 지수 백오프, 5xx/timeout만
+class RetryInterceptor extends Interceptor {
+  final Dio _dio;
+  final int maxRetries;
+
+  RetryInterceptor({required Dio dio, this.maxRetries = 3}) : _dio = dio;
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (!_shouldRetry(err) || _getRetryCount(err) >= maxRetries) {
+      return handler.next(err);
+    }
+
+    final retryCount = _getRetryCount(err) + 1;
+    final delay = Duration(milliseconds: 1000 * pow(2, retryCount - 1).toInt());
+
+    await Future.delayed(delay);
+
+    try {
+      err.requestOptions.extra['retryCount'] = retryCount;
+      final response = await _dio.fetch(err.requestOptions);
+      return handler.resolve(response);
+    } catch (e) {
+      return handler.next(err);
+    }
+  }
+
+  bool _shouldRetry(DioException err) {
+    return err.type == DioExceptionType.connectionTimeout ||
+        err.type == DioExceptionType.sendTimeout ||
+        err.type == DioExceptionType.receiveTimeout ||
+        (err.response?.statusCode != null && err.response!.statusCode! >= 500);
+  }
+
+  int _getRetryCount(DioException err) {
+    return err.requestOptions.extra['retryCount'] as int? ?? 0;
+  }
+}
+```
+
+### Logging Interceptor
+
+```dart
+/// Logging 인터셉터 — debug 빌드에서만 활성화
+class AppLoggingInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    debugPrint('→ ${options.method} ${options.uri}');
+    if (options.data != null) {
+      debugPrint('  Body: ${options.data}');
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    debugPrint('← ${response.statusCode} ${response.requestOptions.uri}');
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    debugPrint('✗ ${err.type} ${err.requestOptions.uri}');
+    debugPrint('  ${err.message}');
+    handler.next(err);
+  }
+}
+```
+
+### Error Transform Interceptor
+
+```dart
+/// Error Transform — DioException → NetworkFailure
+/// (error-handling.md 참조)
+class ErrorTransformInterceptor extends Interceptor {
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    // NetworkFailure로 변환 후 그대로 전파
+    // Repository 레이어에서 catch하여 Result로 래핑
+    handler.next(err);
+  }
+}
+```
+
+### 규칙
+
+- 인터셉터 순서: Auth → Retry → Logging → Error Transform (변경 금지)
+- Auth 인터셉터는 `QueuedInterceptorsWrapper` 사용 (동시 리프레시 방지)
+- 토큰 리프레시용 Dio는 별도 인스턴스 (인터셉터 미적용, 순환 방지)
+- Retry: 지수 백오프 (1s, 2s, 4s), 최대 3회, 5xx/timeout만
+- Retry: POST/PUT/DELETE는 멱등성 확인 후 재시도 여부 결정
+- Logging: `kDebugMode` 또는 dev 환경에서만 활성화
+- 인터셉터 내에서 BuildContext, Navigator 접근 금지

package/templates/base/skills/mobile/flutter/networking/rules/retrofit-patterns.md

@@ -0,0 +1,194 @@
+---
+title: Retrofit Code Generation Patterns
+impact: HIGH
+impactDescription: "수동 API 코드 → 오타, 타입 불일치, 유지보수 비용 증가"
+tags: retrofit, code-generation, build-runner, freezed, rest-api
+---
+
+## Retrofit Code Generation Patterns
+
+**Impact: HIGH (수동 API 코드 → 오타, 타입 불일치, 유지보수 비용 증가)**
+
+Retrofit으로 타입 안전한 API 클라이언트 자동 생성.
+freezed 모델과 연동하여 불변 데이터 클래스 + JSON 직렬화.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  dio: ^5.7.0
+  retrofit: ^4.4.0
+  json_annotation: ^4.9.0
+  freezed_annotation: ^2.4.0
+
+dev_dependencies:
+  retrofit_generator: ^9.1.0
+  build_runner: ^2.4.0
+  json_serializable: ^6.8.0
+  freezed: ^2.5.0
+```
+
+### API 클라이언트 정의
+
+**Incorrect (수동 HTTP 호출):**
+```dart
+class UserApi {
+  final Dio dio;
+  UserApi(this.dio);
+
+  Future<User> getUser(String id) async {
+    final response = await dio.get('/users/$id');
+    return User.fromJson(response.data);
+    // → 경로 오타, 파라미터 누락 가능, 타입 안전하지 않음
+  }
+}
+```
+
+**Correct (Retrofit 어노테이션 + 코드 생성):**
+```dart
+// lib/core/networking/api/user_api.dart
+import 'package:dio/dio.dart';
+import 'package:retrofit/retrofit.dart';
+
+part 'user_api.g.dart';
+
+@RestApi()
+abstract class UserApi {
+  factory UserApi(Dio dio, {String baseUrl}) = _UserApi;
+
+  @GET('/users/{id}')
+  Future<UserResponse> getUser(@Path('id') String id);
+
+  @GET('/users')
+  Future<PaginatedResponse<UserResponse>> getUsers(
+    @Query('page') int page,
+    @Query('limit') int limit,
+  );
+
+  @POST('/users')
+  Future<UserResponse> createUser(@Body() CreateUserRequest request);
+
+  @PUT('/users/{id}')
+  Future<UserResponse> updateUser(
+    @Path('id') String id,
+    @Body() UpdateUserRequest request,
+  );
+
+  @DELETE('/users/{id}')
+  Future<void> deleteUser(@Path('id') String id);
+
+  @POST('/users/{id}/avatar')
+  @MultiPart()
+  Future<AvatarResponse> uploadAvatar(
+    @Path('id') String id,
+    @Part(name: 'file') File avatar,
+  );
+}
+```
+
+### freezed 응답 모델
+
+```dart
+// lib/features/user/data/models/user_response.dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'user_response.freezed.dart';
+part 'user_response.g.dart';
+
+@freezed
+class UserResponse with _$UserResponse {
+  const factory UserResponse({
+    required String id,
+    required String name,
+    required String email,
+    String? avatarUrl,
+    @JsonKey(name: 'created_at') required DateTime createdAt,
+    @Default(false) bool isVerified,
+  }) = _UserResponse;
+
+  factory UserResponse.fromJson(Map<String, dynamic> json) =>
+      _$UserResponseFromJson(json);
+}
+
+/// 페이지네이션 래퍼
+@freezed
+class PaginatedResponse<T> with _$PaginatedResponse<T> {
+  const factory PaginatedResponse({
+    required List<T> data,
+    required int total,
+    required int page,
+    required int lastPage,
+  }) = _PaginatedResponse<T>;
+
+  factory PaginatedResponse.fromJson(
+    Map<String, dynamic> json,
+    T Function(Object?) fromJsonT,
+  ) => _$PaginatedResponseFromJson(json, fromJsonT);
+}
+```
+
+### 요청 모델
+
+```dart
+@freezed
+class CreateUserRequest with _$CreateUserRequest {
+  const factory CreateUserRequest({
+    required String name,
+    required String email,
+    String? phoneNumber,
+  }) = _CreateUserRequest;
+
+  factory CreateUserRequest.fromJson(Map<String, dynamic> json) =>
+      _$CreateUserRequestFromJson(json);
+}
+```
+
+### Riverpod Provider 구성
+
+```dart
+/// API Provider
+final userApiProvider = Provider<UserApi>((ref) {
+  return UserApi(ref.watch(dioProvider));
+});
+
+/// Repository — API + 에러 변환
+final userRepositoryProvider = Provider<UserRepository>((ref) {
+  return UserRepository(api: ref.watch(userApiProvider));
+});
+
+class UserRepository {
+  final UserApi _api;
+
+  UserRepository({required UserApi api}) : _api = api;
+
+  Future<Result<UserResponse>> getUser(String id) async {
+    try {
+      final response = await _api.getUser(id);
+      return Success(response);
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+}
+```
+
+### 코드 생성
+
+```bash
+# 1회 실행
+dart run build_runner build --delete-conflicting-outputs
+
+# 개발 중 자동 생성 (파일 변경 감지)
+dart run build_runner watch --delete-conflicting-outputs
+```
+
+### 규칙
+
+- `@RestApi(baseUrl: '')` — baseUrl은 빈 문자열, Dio BaseOptions에서 관리
+- 응답/요청 모델은 freezed + json_serializable (불변 + 자동 직렬화)
+- `@JsonKey(name: 'snake_case')` — 서버 필드명과 클라이언트 필드명 매핑
+- `@Part(name: 'file')` — multipart 업로드 시 서버 기대 필드명 명시
+- `.g.dart` 파일은 버전 관리에 포함하지 않음 (`.gitignore` 에 추가 가능)
+- `build_runner watch` 로 개발 중 자동 생성 — 수동 생성 후 커밋 잊음 방지
+- API 클라이언트와 Repository 분리 — API는 순수 HTTP, Repository에서 에러 변환

package/templates/base/skills/mobile/flutter/push-notifications/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: push-notifications
+description: |
+  Flutter 푸시 알림 + 백그라운드 처리 가이드라인.
+  FCM(Firebase Cloud Messaging) 설정, 포그라운드/백그라운드/종료 상태 메시지 핸들링,
+  flutter_local_notifications 통합, 딥링크 네비게이션, workmanager 백그라운드 태스크,
+  리치 알림(이미지, 액션 버튼, 그룹), 플랫폼별 설정(APNs, Android 채널).
+  알림 기능 구현 시 이 스킬을 참조.
+version: "1.0.0"
+tags: [flutter, fcm, push-notification, background, local-notification, deep-link]
+user-invocable: false
+---
+
+# Push Notifications & Background Processing
+
+Flutter FCM + Local Notifications + Background Processing 통합 가이드.
+iOS APNs / Android FCM 채널 기반, 모든 앱 상태에서의 알림 수신 및 처리.
+
+## Philosophy
+
+- 알림은 서비스 — Feature-first 구조에서 `core/notifications/` 로 중앙화
+- 권한은 맥락 — 앱 첫 실행이 아닌, 사용자가 가치를 인지한 순간에 요청
+- 백그라운드는 격리 — top-level 함수 + 최소 의존성, UI 코드 접근 금지
+- 플랫폼 차이 흡수 — 단일 인터페이스로 iOS/Android 분기 캡슐화
+
+## Resources
+
+7개 규칙 + 2개 참조. 알림 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [fcm-setup](rules/fcm-setup.md) | FCM 초기화, 토큰 관리, 서버 연동 |
+| CRITICAL | rule | [notification-handling](rules/notification-handling.md) | 포그라운드/백그라운드/종료 상태 메시지 처리 |
+| CRITICAL | rule | [local-notifications](rules/local-notifications.md) | flutter_local_notifications 설정, 채널, 스케줄링 |
+| HIGH | rule | [notification-permissions](rules/notification-permissions.md) | 권한 요청 타이밍, 프리프롬프트, 설정 유도 |
+| HIGH | rule | [deep-linking](rules/deep-linking.md) | 알림 탭 → 특정 화면 네비게이션, 페이로드 처리 |
+| HIGH | rule | [rich-notifications](rules/rich-notifications.md) | 이미지, 액션 버튼, 그룹 알림, 사운드 |
+| HIGH | rule | [background-processing](rules/background-processing.md) | workmanager, 백그라운드 fetch, Isolate 태스크 |
+| — | ref | [platform-setup](references/platform-setup.md) | iOS APNs + Android 채널 + 권한 설정 상세 |
+| — | ref | [notification-architecture](references/notification-architecture.md) | 알림 서비스 아키텍처, 디렉토리 구조, 테스트 전략 |
+
+## Quick Rules
+
+### FCM 설정
+- `Firebase.initializeApp()` → `main()` 에서 최우선 호출
+- FCM 토큰은 서버에 저장, `onTokenRefresh` 구독으로 갱신
+- iOS: APNs 인증 키(.p8) 방식 사용 (인증서보다 관리 용이)
+- `@pragma('vm:entry-point')` 로 백그라운드 핸들러 보호
+
+### 메시지 핸들링
+- `FirebaseMessaging.onMessage` → 포그라운드 (직접 로컬 알림 표시)
+- `FirebaseMessaging.onBackgroundMessage` → top-level 함수 필수
+- `getInitialMessage()` → 종료 상태에서 알림 탭 처리 (1회만 호출)
+- `onMessageOpenedApp` → 백그라운드에서 알림 탭 처리
+
+### 로컬 알림
+- Android: 채널 ID 필수 (Android 8+), 중요도별 분리
+- iOS: `DarwinInitializationSettings` 권한 플래그
+- 스케줄링: `zonedSchedule` (timezone 패키지 필수)
+- 페이로드: JSON 문자열로 직렬화, 탭 시 파싱
+
+### 백그라운드 처리
+- `workmanager` → periodic/one-off 백그라운드 태스크
+- iOS: `BGTaskScheduler` (최소 15분 간격, OS 제어)
+- Android: `WorkManager` (정확한 주기, 제약 조건 설정 가능)
+- 백그라운드 핸들러에서 Flutter 엔진 직접 접근 금지
+
+### 권한
+- iOS 13+: 임시 알림 (provisional) → 조용히 전달, 사용자 결정 유도
+- Android 13+: `POST_NOTIFICATIONS` 런타임 권한 필수
+- 권한 거부 시 설정 앱으로 유도 (`openAppSettings()`)
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `Firebase.initializeApp()` 호출 후 FCM 초기화 |
+| CRITICAL | 백그라운드 핸들러가 top-level 함수인지 확인 |
+| CRITICAL | Android notification channel 생성 (앱 시작 시) |
+| CRITICAL | iOS APNs capability + Background Modes 활성화 |
+| HIGH | FCM 토큰 서버 동기화 + 갱신 리스너 |
+| HIGH | 알림 탭 → 딥링크 네비게이션 3가지 상태 모두 처리 |
+| HIGH | 권한 요청 타이밍 (첫 실행 X, 가치 인지 후 O) |
+| HIGH | Android 13+ POST_NOTIFICATIONS 런타임 권한 처리 |
+| MEDIUM | 리치 알림 (이미지, 액션 버튼) 테스트 |
+| MEDIUM | 백그라운드 태스크 배터리 최적화 고려 |
+| MEDIUM | 알림 분석 (열림률, 전환율) 수집 |