timsquad 2.1.0 → 3.4.0

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 사용 — 앱 재시작 후에도 캐시 유지 (메모리 캐시보다 안정)

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

@@ -0,0 +1,213 @@
+---
+title: Connectivity & Offline Queue
+impact: HIGH
+impactDescription: "오프라인 미처리 → 요청 유실, 무한 로딩, 사용자 혼란"
+tags: connectivity, offline, queue, retry, connectivity-plus
+---
+
+## Connectivity & Offline Queue
+
+**Impact: HIGH (오프라인 미처리 → 요청 유실, 무한 로딩, 사용자 혼란)**
+
+connectivity_plus로 네트워크 상태 실시간 감지.
+오프라인 시 요청 큐잉, 연결 복구 시 자동 재시도.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  connectivity_plus: ^6.1.0
+  flutter_riverpod: ^2.6.0
+```
+
+### ConnectivityNotifier
+
+**Incorrect (단발 체크만):**
+```dart
+Future<bool> isOnline() async {
+  final result = await Connectivity().checkConnectivity();
+  return result != ConnectivityResult.none;
+  // → 상태 변화 미감지, UI 갱신 없음
+}
+```
+
+**Correct (Riverpod + 실시간 스트림):**
+```dart
+/// 연결 상태 열거형
+enum NetworkStatus { online, offline }
+
+/// 연결 상태 Provider — 앱 전역 스트림
+final connectivityProvider =
+    StreamNotifierProvider<ConnectivityNotifier, NetworkStatus>(
+  ConnectivityNotifier.new,
+);
+
+class ConnectivityNotifier extends StreamNotifier<NetworkStatus> {
+  @override
+  Stream<NetworkStatus> build() {
+    return Connectivity().onConnectivityChanged.map((results) {
+      final hasConnection = results.any((r) => r != ConnectivityResult.none);
+      return hasConnection ? NetworkStatus.online : NetworkStatus.offline;
+    });
+  }
+}
+
+/// 현재 온라인 여부 (동기 체크용)
+final isOnlineProvider = Provider<bool>((ref) {
+  final status = ref.watch(connectivityProvider).valueOrNull;
+  return status == NetworkStatus.online;
+});
+```
+
+### 오프라인 배너 UI
+
+```dart
+/// 오프라인 상태 배너 — 앱 최상단에 배치
+class OfflineBanner extends ConsumerWidget {
+  const OfflineBanner({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final isOnline = ref.watch(isOnlineProvider);
+
+    if (isOnline) return const SizedBox.shrink();
+
+    return MaterialBanner(
+      content: const Text('인터넷 연결이 끊어졌습니다'),
+      leading: const Icon(Icons.wifi_off, color: Colors.white),
+      backgroundColor: Colors.red.shade700,
+      actions: [
+        TextButton(
+          onPressed: () async {
+            // 수동 재시도
+            final result = await Connectivity().checkConnectivity();
+            if (result.any((r) => r != ConnectivityResult.none)) {
+              ref.invalidate(connectivityProvider);
+            }
+          },
+          child: const Text('재시도', style: TextStyle(color: Colors.white)),
+        ),
+      ],
+    );
+  }
+}
+```
+
+### 오프라인 요청 큐
+
+```dart
+/// 오프라인 시 보류된 요청
+class PendingRequest {
+  final String id;
+  final RequestOptions options;
+  final DateTime createdAt;
+  final int retryCount;
+
+  const PendingRequest({
+    required this.id,
+    required this.options,
+    required this.createdAt,
+    this.retryCount = 0,
+  });
+
+  bool get isExpired =>
+      DateTime.now().difference(createdAt) > const Duration(hours: 1);
+}
+
+/// 오프라인 큐 매니저
+class OfflineQueueManager {
+  final Dio _dio;
+  final List<PendingRequest> _queue = [];
+  bool _isProcessing = false;
+
+  OfflineQueueManager({required Dio dio}) : _dio = dio;
+
+  /// 오프라인 시 큐에 추가
+  void enqueue(RequestOptions options) {
+    _queue.add(PendingRequest(
+      id: const Uuid().v4(),
+      options: options,
+      createdAt: DateTime.now(),
+    ));
+  }
+
+  /// 연결 복구 시 큐 처리
+  Future<void> processQueue() async {
+    if (_isProcessing || _queue.isEmpty) return;
+    _isProcessing = true;
+
+    try {
+      // 만료된 요청 제거
+      _queue.removeWhere((r) => r.isExpired);
+
+      final pending = List<PendingRequest>.from(_queue);
+      for (final request in pending) {
+        try {
+          await _dio.fetch(request.options);
+          _queue.remove(request);
+        } on DioException {
+          // 실패 → 큐에 유지, 다음 복구 시 재시도
+          break; // 첫 실패 시 중단 (아직 불안정할 수 있음)
+        }
+      }
+    } finally {
+      _isProcessing = false;
+    }
+  }
+
+  int get pendingCount => _queue.length;
+  bool get hasPending => _queue.isNotEmpty;
+}
+
+/// Provider
+final offlineQueueProvider = Provider<OfflineQueueManager>((ref) {
+  final queue = OfflineQueueManager(dio: ref.watch(dioProvider));
+
+  // 온라인 복구 시 자동 처리
+  ref.listen(connectivityProvider, (prev, next) {
+    if (next.valueOrNull == NetworkStatus.online) {
+      queue.processQueue();
+    }
+  });
+
+  return queue;
+});
+```
+
+### Connectivity Interceptor
+
+```dart
+/// Dio 인터셉터로 오프라인 감지 (선택적)
+class ConnectivityInterceptor extends Interceptor {
+  final OfflineQueueManager _queueManager;
+  final Ref _ref;
+
+  ConnectivityInterceptor({
+    required OfflineQueueManager queueManager,
+    required Ref ref,
+  })  : _queueManager = queueManager,
+        _ref = ref;
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    if (err.type == DioExceptionType.connectionError) {
+      // POST/PUT 요청을 큐에 추가 (GET은 캐시 fallback)
+      if (err.requestOptions.method != 'GET') {
+        _queueManager.enqueue(err.requestOptions);
+      }
+    }
+    handler.next(err);
+  }
+}
+```
+
+### 규칙
+
+- `connectivity_plus` 스트림으로 실시간 감지 — 단발 체크 금지
+- 오프라인 배너를 앱 최상단에 항상 표시
+- 오프라인 큐: POST/PUT/DELETE 요청만 큐잉 (GET은 캐시 fallback)
+- 만료된 큐 요청 자동 제거 (1시간 기본)
+- 연결 복구 시 큐 자동 처리 — `ref.listen(connectivityProvider)` 활용
+- 큐 처리 중 실패 시 중단 (네트워크 아직 불안정할 수 있음)
+- Wi-Fi 연결 ≠ 인터넷 접속 — 실제 HTTP 핑으로 검증 고려

package/templates/base/skills/mobile/flutter/networking/rules/dio-setup.md

@@ -0,0 +1,159 @@
+---
+title: Dio Setup & Configuration
+impact: CRITICAL
+impactDescription: "잘못된 Dio 설정 → 타임아웃 누락, 인스턴스 중복 생성, 메모리 낭비"
+tags: dio, http, setup, riverpod, baseOptions
+---
+
+## Dio Setup & Configuration
+
+**Impact: CRITICAL (잘못된 Dio 설정 → 타임아웃 누락, 인스턴스 중복 생성, 메모리 낭비)**
+
+Dio 싱글톤 인스턴스 관리, BaseOptions 설정, 환경별 분리.
+모든 네트워크 통신의 기반이 되는 핵심 인프라.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  dio: ^5.7.0
+  flutter_riverpod: ^2.6.0
+  # 또는 riverpod (non-Flutter)
+```
+
+### Dio 인스턴스 관리
+
+**Incorrect (매번 새 인스턴스 생성):**
+```dart
+class UserRepository {
+  Future<User> getUser(String id) async {
+    // 매 호출마다 Dio 생성 → 인터셉터 미적용, 커넥션 풀 미활용
+    final dio = Dio();
+    final response = await dio.get('https://api.example.com/users/$id');
+    return User.fromJson(response.data);
+  }
+}
+```
+
+**Correct (Riverpod Provider로 싱글톤 관리):**
+```dart
+/// 환경 설정
+enum AppEnvironment { dev, staging, prod }
+
+class AppConfig {
+  final AppEnvironment environment;
+  final String baseUrl;
+
+  const AppConfig({required this.environment, required this.baseUrl});
+
+  static const dev = AppConfig(
+    environment: AppEnvironment.dev,
+    baseUrl: 'https://dev-api.example.com/v1',
+  );
+
+  static const staging = AppConfig(
+    environment: AppEnvironment.staging,
+    baseUrl: 'https://staging-api.example.com/v1',
+  );
+
+  static const prod = AppConfig(
+    environment: AppEnvironment.prod,
+    baseUrl: 'https://api.example.com/v1',
+  );
+}
+
+/// 앱 설정 Provider
+final appConfigProvider = Provider<AppConfig>((ref) {
+  // main.dart에서 ProviderScope overrides로 주입
+  return AppConfig.dev;
+});
+
+/// Dio Provider — 앱 전역 싱글톤
+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',
+    },
+    validateStatus: (status) => status != null && status < 500,
+  ));
+
+  // 인터셉터 체인 (순서 중요)
+  dio.interceptors.addAll([
+    ref.watch(authInterceptorProvider),
+    ref.watch(retryInterceptorProvider),
+    if (config.environment == AppEnvironment.dev)
+      ref.watch(loggingInterceptorProvider),
+    ref.watch(errorTransformInterceptorProvider),
+  ]);
+
+  return dio;
+});
+```
+
+### main.dart 환경 주입
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // 환경 결정 (빌드 플래그, .env 등)
+  const config = String.fromEnvironment('ENV') == 'prod'
+      ? AppConfig.prod
+      : AppConfig.dev;
+
+  runApp(
+    ProviderScope(
+      overrides: [
+        appConfigProvider.overrideWithValue(config),
+      ],
+      child: const MyApp(),
+    ),
+  );
+}
+```
+
+### BaseOptions 상세
+
+```dart
+BaseOptions(
+  // 서버 기본 URL — 환경별 분리 필수
+  baseUrl: 'https://api.example.com/v1',
+
+  // 타임아웃 — 15초 권장 (모바일 네트워크 고려)
+  connectTimeout: const Duration(seconds: 15),
+  receiveTimeout: const Duration(seconds: 15),
+  sendTimeout: const Duration(seconds: 15),
+
+  // 기본 헤더
+  headers: {
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+    'X-App-Version': appVersion, // 서버 호환성 체크용
+    'X-Platform': Platform.isIOS ? 'ios' : 'android',
+  },
+
+  // 응답 타입
+  responseType: ResponseType.json,
+
+  // 상태 코드 검증 — 5xx는 DioException으로 처리
+  validateStatus: (status) => status != null && status < 500,
+)
+```
+
+### 규칙
+
+- Dio 인스턴스는 Riverpod Provider로 싱글톤 관리 — 직접 생성 금지
+- `connectTimeout`, `receiveTimeout`, `sendTimeout` 모두 15초 설정
+- `baseUrl` 은 환경별 분리 (dev/staging/prod) — 하드코딩 금지
+- `Content-Type: application/json` 기본 헤더
+- `validateStatus` — 5xx만 에러, 4xx는 응답 데이터로 처리
+- Interceptor 등록은 Dio Provider 내에서 순서대로
+- Logging 인터셉터는 dev 환경에서만 활성화