timsquad 3.3.0 → 3.5.0

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 환경에서만 활성화

package/templates/base/skills/mobile/flutter/networking/rules/error-handling.md

@@ -0,0 +1,209 @@
+---
+title: Network Error Handling
+impact: CRITICAL
+impactDescription: "에러 미변환 → DioException UI 노출, 사용자 혼란, 디버깅 불가"
+tags: dio, error, failure, sealed-class, result-pattern
+---
+
+## Network Error Handling
+
+**Impact: CRITICAL (에러 미변환 → DioException UI 노출, 사용자 혼란, 디버깅 불가)**
+
+DioException을 앱 도메인 NetworkFailure로 변환.
+Repository에서 Result 패턴으로 래핑하여 UI까지 안전하게 전달.
+
+### NetworkFailure Sealed Class
+
+**Incorrect (DioException 직접 노출):**
+```dart
+class UserRepository {
+  Future<User> getUser(String id) async {
+    final response = await dio.get('/users/$id');
+    return User.fromJson(response.data);
+    // → DioException이 그대로 UI까지 전파
+    // → try-catch 누락 시 앱 크래시
+  }
+}
+```
+
+**Correct (도메인 에러 변환 + Result 패턴):**
+```dart
+/// 네트워크 에러 도메인 모델
+sealed class NetworkFailure {
+  final String message;
+  final int? statusCode;
+  final dynamic originalError;
+
+  const NetworkFailure({
+    required this.message,
+    this.statusCode,
+    this.originalError,
+  });
+
+  /// DioException → NetworkFailure 팩토리
+  factory NetworkFailure.fromDioException(DioException e) {
+    return switch (e.type) {
+      DioExceptionType.connectionTimeout ||
+      DioExceptionType.sendTimeout ||
+      DioExceptionType.receiveTimeout =>
+        TimeoutFailure(
+          message: '서버 응답 시간이 초과되었습니다',
+          originalError: e,
+        ),
+      DioExceptionType.connectionError => NoConnectionFailure(
+          message: '인터넷 연결을 확인해주세요',
+          originalError: e,
+        ),
+      DioExceptionType.badResponse => ServerFailure(
+          message: _extractServerMessage(e.response),
+          statusCode: e.response?.statusCode,
+          originalError: e,
+        ),
+      DioExceptionType.cancel => RequestCancelledFailure(
+          message: '요청이 취소되었습니다',
+          originalError: e,
+        ),
+      _ => UnknownNetworkFailure(
+          message: '알 수 없는 네트워크 오류가 발생했습니다',
+          originalError: e,
+        ),
+    };
+  }
+
+  static String _extractServerMessage(Response? response) {
+    try {
+      final data = response?.data;
+      if (data is Map<String, dynamic>) {
+        return data['message'] as String? ??
+            data['error'] as String? ??
+            'Server error';
+      }
+    } catch (_) {}
+    return 'Server error (${response?.statusCode})';
+  }
+}
+
+class TimeoutFailure extends NetworkFailure {
+  const TimeoutFailure({required super.message, super.originalError});
+}
+
+class NoConnectionFailure extends NetworkFailure {
+  const NoConnectionFailure({required super.message, super.originalError});
+}
+
+class ServerFailure extends NetworkFailure {
+  const ServerFailure({
+    required super.message,
+    super.statusCode,
+    super.originalError,
+  });
+
+  bool get isUnauthorized => statusCode == 401;
+  bool get isForbidden => statusCode == 403;
+  bool get isNotFound => statusCode == 404;
+  bool get isConflict => statusCode == 409;
+  bool get isValidationError => statusCode == 422;
+  bool get isRateLimited => statusCode == 429;
+}
+
+class RequestCancelledFailure extends NetworkFailure {
+  const RequestCancelledFailure({required super.message, super.originalError});
+}
+
+class UnknownNetworkFailure extends NetworkFailure {
+  const UnknownNetworkFailure({required super.message, super.originalError});
+}
+```
+
+### Result 패턴
+
+```dart
+/// 범용 Result 타입
+sealed class Result<T> {
+  const Result();
+}
+
+class Success<T> extends Result<T> {
+  final T data;
+  const Success(this.data);
+}
+
+class Failure<T> extends Result<T> {
+  final NetworkFailure failure;
+  const Failure(this.failure);
+}
+
+/// Repository에서 사용
+class UserRepository {
+  final Dio _dio;
+
+  UserRepository({required Dio dio}) : _dio = dio;
+
+  Future<Result<User>> getUser(String id) async {
+    try {
+      final response = await _dio.get('/users/$id');
+      final user = User.fromJson(response.data);
+      return Success(user);
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+
+  Future<Result<List<User>>> getUsers({int page = 1}) async {
+    try {
+      final response = await _dio.get('/users', queryParameters: {'page': page});
+      final users = (response.data as List)
+          .map((json) => User.fromJson(json))
+          .toList();
+      return Success(users);
+    } on DioException catch (e) {
+      return Failure(NetworkFailure.fromDioException(e));
+    }
+  }
+}
+```
+
+### UI에서 Result 처리
+
+```dart
+/// Provider에서 Result 소비
+class UserNotifier extends AsyncNotifier<User> {
+  @override
+  Future<User> build() async {
+    final result = await ref.read(userRepositoryProvider).getUser('me');
+    return switch (result) {
+      Success(data: final user) => user,
+      Failure(failure: final f) => throw f, // AsyncError로 전환
+    };
+  }
+}
+
+/// Widget에서 에러 표시
+Widget build(BuildContext context, WidgetRef ref) {
+  final userAsync = ref.watch(userProvider);
+
+  return userAsync.when(
+    data: (user) => UserProfile(user: user),
+    loading: () => const LoadingIndicator(),
+    error: (error, _) {
+      if (error is NoConnectionFailure) {
+        return const OfflineWidget();
+      }
+      if (error is ServerFailure && error.isNotFound) {
+        return const UserNotFoundWidget();
+      }
+      return ErrorWidget(message: (error as NetworkFailure).message);
+    },
+  );
+}
+```
+
+### 규칙
+
+- DioException을 UI 레이어까지 전파 금지 — 반드시 NetworkFailure로 변환
+- `NetworkFailure.fromDioException()` 팩토리 단일 변환 지점
+- Repository 메서드는 `Result<T>` 반환 — 절대 throw 하지 않음
+- sealed class 사용 — switch 완전성 검사로 누락 방지
+- 서버 에러 메시지 추출 → 사용자 친화적 메시지로 매핑
+- 401 → 토큰 리프레시는 Auth 인터셉터 담당 (Repository 아님)
+- 에러 로깅은 Logging 인터셉터에서 처리 (Repository에서 중복 로깅 금지)