timsquad 3.3.0 → 3.5.0

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` 미생성 → 컴파일 에러

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

@@ -0,0 +1,212 @@
+---
+title: HTTP Caching Strategy
+impact: MEDIUM
+impactDescription: "캐시 미사용 → 불필요한 네트워크 호출, 느린 로딩, 데이터 요금 낭비"
+tags: cache, dio-cache-interceptor, etag, offline, performance
+---
+
+## HTTP Caching Strategy
+
+**Impact: MEDIUM (캐시 미사용 → 불필요한 네트워크 호출, 느린 로딩, 데이터 요금 낭비)**
+
+dio_cache_interceptor로 HTTP 응답 캐시.
+ETag/Last-Modified 검증, 오프라인 fallback, 정책별 캐시 전략.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  dio: ^5.7.0
+  dio_cache_interceptor: ^3.5.0
+  dio_cache_interceptor_hive_store: ^3.2.0  # 영구 저장소
+```
+
+### 캐시 인터셉터 설정
+
+**Incorrect (캐시 없이 매번 네트워크 호출):**
+```dart
+final dio = Dio();
+// → 동일 데이터 반복 요청, 배터리 + 데이터 낭비
+// → 오프라인 시 데이터 표시 불가
+```
+
+**Correct (dio_cache_interceptor 통합):**
+```dart
+/// 캐시 저장소 초기화
+Future<CacheStore> initCacheStore() async {
+  final dir = await getApplicationDocumentsDirectory();
+  return HiveCacheStore(
+    '${dir.path}/http_cache',
+    hiveBoxName: 'dio_cache',
+  );
+}
+
+/// 캐시 옵션 팩토리
+class CacheConfig {
+  /// 기본 캐시 정책 — 네트워크 우선, 실패 시 캐시
+  static CacheOptions defaultPolicy(CacheStore store) {
+    return CacheOptions(
+      store: store,
+      policy: CachePolicy.request, // 네트워크 요청 + 캐시 갱신
+      maxStale: const Duration(days: 7), // 오프라인 시 7일간 캐시 유효
+      hitCacheOnErrorExcept: [401, 403], // 에러 시 캐시 반환 (인증 에러 제외)
+    );
+  }
+
+  /// 강제 캐시 — 네트워크 미사용 (빠른 로딩)
+  static CacheOptions forceCache(CacheStore store) {
+    return CacheOptions(
+      store: store,
+      policy: CachePolicy.forceCache,
+    );
+  }
+
+  /// 캐시 무시 — 항상 최신 데이터
+  static CacheOptions noCache(CacheStore store) {
+    return CacheOptions(
+      store: store,
+      policy: CachePolicy.noCache,
+    );
+  }
+
+  /// stale-while-revalidate — 캐시 먼저 반환, 백그라운드 갱신
+  static CacheOptions refreshIfStale(CacheStore store) {
+    return CacheOptions(
+      store: store,
+      policy: CachePolicy.refreshForceCache,
+      maxStale: const Duration(hours: 1),
+    );
+  }
+}
+
+/// Dio에 캐시 인터셉터 추가
+final cacheStoreProvider = FutureProvider<CacheStore>((ref) async {
+  return await initCacheStore();
+});
+
+final cacheDioProvider = Provider<Dio>((ref) {
+  final dio = ref.watch(dioProvider);
+  final cacheStore = ref.watch(cacheStoreProvider).valueOrNull;
+
+  if (cacheStore != null) {
+    final cacheOptions = CacheConfig.defaultPolicy(cacheStore);
+    dio.interceptors.add(
+      DioCacheInterceptor(options: cacheOptions),
+    );
+  }
+
+  return dio;
+});
+```
+
+### 요청별 캐시 정책 오버라이드
+
+```dart
+/// API에서 요청별 캐시 정책 지정
+class ProductRepository {
+  final Dio _dio;
+  final CacheStore _cacheStore;
+
+  ProductRepository({required Dio dio, required CacheStore cacheStore})
+      : _dio = dio,
+        _cacheStore = cacheStore;
+
+  /// 상품 목록 — 기본 캐시 (네트워크 + 캐시 갱신)
+  Future<Result<List<Product>>> getProducts() async {
+    try {
+      final response = await _dio.get('/products');
+      return Success(_parseProducts(response.data));
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+
+  /// 상품 상세 — 캐시 우선 (자주 변경되지 않음)
+  Future<Result<Product>> getProduct(String id) async {
+    try {
+      final response = await _dio.get(
+        '/products/$id',
+        options: CacheConfig.refreshIfStale(_cacheStore).toOptions(),
+      );
+      return Success(Product.fromJson(response.data));
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+
+  /// 결제 정보 — 캐시 금지 (항상 최신)
+  Future<Result<PaymentInfo>> getPaymentInfo() async {
+    try {
+      final response = await _dio.get(
+        '/payment/info',
+        options: CacheConfig.noCache(_cacheStore).toOptions(),
+      );
+      return Success(PaymentInfo.fromJson(response.data));
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+}
+```
+
+### ETag / Last-Modified 활용
+
+```dart
+// dio_cache_interceptor가 자동 처리하는 HTTP 헤더:
+//
+// 서버 응답:
+//   ETag: "abc123"
+//   Last-Modified: Wed, 15 Jan 2026 10:00:00 GMT
+//   Cache-Control: max-age=3600
+//
+// 클라이언트 재요청 (자동):
+//   If-None-Match: "abc123"
+//   If-Modified-Since: Wed, 15 Jan 2026 10:00:00 GMT
+//
+// 서버 응답:
+//   304 Not Modified → 캐시된 데이터 사용 (전송 비용 없음)
+//   200 OK → 새 데이터로 캐시 갱신
+
+// 서버가 ETag/Last-Modified를 지원하면 자동으로 최적화됨
+// 별도 클라이언트 코드 필요 없음
+```
+
+### 캐시 관리
+
+```dart
+/// 캐시 클리어 (로그아웃 시, 디버깅 시)
+class CacheManager {
+  final CacheStore _store;
+
+  CacheManager({required CacheStore store}) : _store = store;
+
+  /// 전체 캐시 클리어
+  Future<void> clearAll() async {
+    await _store.clean();
+  }
+
+  /// 특정 URL 캐시 삭제
+  Future<void> invalidate(String url) async {
+    await _store.delete(CacheOptions.defaultCacheKeyBuilder(
+      RequestOptions(path: url),
+    ));
+  }
+}
+
+final cacheManagerProvider = Provider<CacheManager>((ref) {
+  final store = ref.watch(cacheStoreProvider).valueOrNull;
+  if (store == null) throw StateError('Cache store not initialized');
+  return CacheManager(store: store);
+});
+```
+
+### 규칙
+
+- GET 요청에만 캐시 적용 — POST/PUT/DELETE는 캐시 금지
+- 기본 정책: 네트워크 우선 + 실패 시 캐시 fallback (`hitCacheOnErrorExcept`)
+- 결제/인증 관련 API는 `CachePolicy.noCache` 강제
+- `maxStale: 7일` — 오프라인 시 캐시 유효 기간
+- 인증 에러(401, 403)는 캐시 반환 제외 — 만료 토큰으로 캐시된 데이터 방지
+- 로그아웃 시 전체 캐시 클리어 — 사용자 데이터 잔류 방지
+- HiveCacheStore 사용 — 앱 재시작 후에도 캐시 유지 (메모리 캐시보다 안정)