timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/references/freezed-patterns.md

@@ -0,0 +1,162 @@
+---
+title: Freezed + JSON Serializable Patterns
+category: guide
+tags: freezed, json-serializable, immutable, dto
+---
+
+## Freezed + JSON Serializable
+
+불변 데이터 모델 + JSON 직렬화 패턴. Domain Entity와 DTO 분리.
+
+### 기본 설정
+
+```yaml
+# pubspec.yaml
+dependencies:
+  freezed_annotation: ^2.4.0
+  json_annotation: ^4.9.0
+
+dev_dependencies:
+  freezed: ^2.5.0
+  json_serializable: ^6.8.0
+  build_runner: ^2.4.0
+```
+
+```bash
+# 코드 생성
+dart run build_runner build --delete-conflicting-outputs
+
+# 감시 모드 (개발 중)
+dart run build_runner watch --delete-conflicting-outputs
+```
+
+### Domain Entity (freezed)
+
+```dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'match.freezed.dart';
+
+@freezed
+class Match with _$Match {
+  const factory Match({
+    required String id,
+    required Sport sport,
+    required String title,
+    required DateTime scheduledAt,
+    required MatchLocation location,
+    required int maxPlayers,
+    @Default([]) List<String> playerIds,
+    @Default(MatchStatus.open) MatchStatus status,
+  }) = _Match;
+
+  // 커스텀 getter (const factory 밑에 private 생성자 필요)
+  const Match._();
+
+  bool get isFull => playerIds.length >= maxPlayers;
+  bool get isUpcoming => scheduledAt.isAfter(DateTime.now());
+  int get availableSlots => maxPlayers - playerIds.length;
+}
+
+enum Sport { tennis, badminton, pickleball, paddle }
+enum MatchStatus { open, full, inProgress, completed, cancelled }
+```
+
+### DTO (freezed + json_serializable)
+
+```dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'match_dto.freezed.dart';
+part 'match_dto.g.dart';
+
+@freezed
+class MatchDto with _$MatchDto {
+  const factory MatchDto({
+    required String id,
+    required String sport,
+    required String title,
+    @JsonKey(name: 'scheduled_at') required String scheduledAt,
+    required MatchLocationDto location,
+    @JsonKey(name: 'max_players') required int maxPlayers,
+    @JsonKey(name: 'player_ids') @Default([]) List<String> playerIds,
+    @Default('open') String status,
+  }) = _MatchDto;
+
+  factory MatchDto.fromJson(Map<String, dynamic> json) =>
+      _$MatchDtoFromJson(json);
+
+  const MatchDto._();
+
+  /// DTO → Domain 변환
+  Match toDomain() => Match(
+    id: id,
+    sport: Sport.values.byName(sport),
+    title: title,
+    scheduledAt: DateTime.parse(scheduledAt),
+    location: location.toDomain(),
+    maxPlayers: maxPlayers,
+    playerIds: playerIds,
+    status: MatchStatus.values.byName(status),
+  );
+
+  /// Domain → DTO 변환
+  factory MatchDto.fromDomain(Match match) => MatchDto(
+    id: match.id,
+    sport: match.sport.name,
+    title: match.title,
+    scheduledAt: match.scheduledAt.toIso8601String(),
+    location: MatchLocationDto.fromDomain(match.location),
+    maxPlayers: match.maxPlayers,
+    playerIds: match.playerIds,
+    status: match.status.name,
+  );
+}
+```
+
+### Sealed Class + Freezed (상태)
+
+```dart
+@freezed
+sealed class AuthState with _$AuthState {
+  const factory AuthState.initial() = AuthInitial;
+  const factory AuthState.loading() = AuthLoading;
+  const factory AuthState.authenticated(User user) = AuthAuthenticated;
+  const factory AuthState.unauthenticated() = AuthUnauthenticated;
+  const factory AuthState.error(String message) = AuthError;
+}
+
+// 사용: 패턴 매칭
+Widget build(BuildContext context) {
+  final authState = ref.watch(authProvider);
+
+  return authState.when(
+    initial: () => const SplashScreen(),
+    loading: () => const LoadingScreen(),
+    authenticated: (user) => const HomeScreen(),
+    unauthenticated: () => const LoginScreen(),
+    error: (msg) => ErrorScreen(message: msg),
+  );
+}
+```
+
+### copyWith (불변 업데이트)
+
+```dart
+// freezed가 자동 생성하는 copyWith
+final updatedMatch = match.copyWith(
+  status: MatchStatus.full,
+  playerIds: [...match.playerIds, newPlayerId],
+);
+// 원본 match는 변경 없음 (불변)
+```
+
+### 규칙
+
+- Domain Entity: `@freezed` (JSON 직렬화 없음, 순수 도메인)
+- DTO: `@freezed` + `@JsonKey` + `fromJson`/`toJson`
+- DTO → Domain: `.toDomain()` 메서드
+- Domain → DTO: `DTO.fromDomain()` factory
+- API 응답 key naming: `@JsonKey(name: 'snake_case')`
+- 상태 모델: `@freezed sealed class` + `.when()` 패턴 매칭
+- `build_runner watch` 개발 중 항상 실행

package/templates/base/skills/mobile/flutter/references/project-structure.md

@@ -0,0 +1,170 @@
+---
+title: Project Structure (Feature-First + Melos)
+category: guide
+tags: structure, monorepo, melos, feature-first
+---
+
+## Project Structure
+
+Flutter Feature-first 디렉토리 구조 + Melos 모노레포 관리.
+
+### 단일 앱 구조
+
+```
+my_app/
+├── lib/
+│   ├── main.dart                    # 엔트리포인트
+│   ├── app.dart                     # MaterialApp + ProviderScope
+│   ├── core/
+│   │   ├── constants/
+│   │   │   ├── app_colors.dart
+│   │   │   ├── app_spacing.dart
+│   │   │   └── api_endpoints.dart
+│   │   ├── extensions/
+│   │   │   ├── context_ext.dart     # BuildContext 확장
+│   │   │   └── string_ext.dart
+│   │   ├── router/
+│   │   │   ├── app_router.dart      # GoRouter 정의
+│   │   │   └── route_names.dart     # 경로 상수
+│   │   ├── theme/
+│   │   │   ├── app_theme.dart       # ThemeData
+│   │   │   └── typography.dart
+│   │   ├── network/
+│   │   │   ├── api_client.dart      # Dio/http 설정
+│   │   │   └── api_interceptor.dart
+│   │   └── providers/
+│   │       ├── auth_provider.dart   # 전역 인증 상태
+│   │       └── locale_provider.dart
+│   │
+│   ├── features/
+│   │   ├── auth/
+│   │   │   ├── data/
+│   │   │   │   ├── datasources/
+│   │   │   │   │   └── auth_remote_datasource.dart
+│   │   │   │   ├── dtos/
+│   │   │   │   │   └── auth_response_dto.dart
+│   │   │   │   │   └── auth_response_dto.g.dart    # json_serializable
+│   │   │   │   │   └── auth_response_dto.freezed.dart
+│   │   │   │   └── repositories/
+│   │   │   │       └── auth_repository_impl.dart
+│   │   │   ├── domain/
+│   │   │   │   ├── entities/
+│   │   │   │   │   └── user.dart
+│   │   │   │   │   └── user.freezed.dart
+│   │   │   │   └── repositories/
+│   │   │   │       └── auth_repository.dart  # abstract
+│   │   │   └── presentation/
+│   │   │       ├── providers/
+│   │   │       │   └── auth_provider.dart
+│   │   │       ├── screens/
+│   │   │       │   ├── login_screen.dart
+│   │   │       │   └── signup_screen.dart
+│   │   │       └── widgets/
+│   │   │           └── social_login_buttons.dart
+│   │   │
+│   │   ├── match/
+│   │   │   ├── data/...
+│   │   │   ├── domain/...
+│   │   │   └── presentation/...
+│   │   │
+│   │   └── community/
+│   │       ├── data/...
+│   │       ├── domain/...
+│   │       └── presentation/...
+│   │
+│   └── shared/
+│       ├── widgets/
+│       │   ├── app_button.dart
+│       │   ├── app_text_field.dart
+│       │   └── loading_indicator.dart
+│       └── utils/
+│           ├── date_formatter.dart
+│           └── validators.dart
+│
+├── test/
+│   ├── features/
+│   │   ├── auth/
+│   │   │   ├── data/repositories/auth_repository_impl_test.dart
+│   │   │   └── presentation/providers/auth_provider_test.dart
+│   │   └── match/...
+│   ├── fixtures/
+│   │   └── test_data.dart           # 공유 테스트 데이터
+│   └── helpers/
+│       └── pump_app.dart            # testWidgets 헬퍼
+│
+├── integration_test/
+│   └── match_flow_test.dart
+│
+├── assets/
+│   ├── images/
+│   ├── icons/
+│   └── translations/                # ARB 파일 (i18n)
+│
+├── pubspec.yaml
+├── analysis_options.yaml
+└── l10n.yaml                        # 국제화 설정
+```
+
+### Melos 모노레포 구조
+
+```
+project_root/
+├── melos.yaml
+├── apps/
+│   ├── mobile/                      # Flutter 앱
+│   │   ├── lib/
+│   │   └── pubspec.yaml
+│   └── admin/                       # 관리자 웹 (선택)
+│       ├── lib/
+│       └── pubspec.yaml
+├── packages/
+│   ├── core/                        # 공유 코어 (모델, 유틸)
+│   │   ├── lib/
+│   │   └── pubspec.yaml
+│   ├── ui_kit/                      # 공유 UI 컴포넌트
+│   │   ├── lib/
+│   │   └── pubspec.yaml
+│   ├── api_client/                  # API 클라이언트
+│   │   ├── lib/
+│   │   └── pubspec.yaml
+│   └── auth/                        # 인증 모듈
+│       ├── lib/
+│       └── pubspec.yaml
+└── tools/
+    └── custom_lint_rules/           # 프로젝트 커스텀 린트
+```
+
+### melos.yaml
+
+```yaml
+name: my_project
+packages:
+  - apps/*
+  - packages/*
+
+scripts:
+  analyze:
+    exec: dart analyze --fatal-infos
+  test:
+    exec: flutter test --coverage
+  format:
+    exec: dart format --set-exit-if-changed .
+  build_runner:
+    exec: dart run build_runner build --delete-conflicting-outputs
+    packageFilters:
+      dependsOn: build_runner
+  clean:
+    exec: flutter clean
+
+command:
+  bootstrap:
+    usePubspecOverrides: true
+```
+
+### 규칙
+
+- feature 안에서 다른 feature 직접 import 금지
+- 공유 로직은 `core/` 또는 `shared/`
+- 모노레포: `melos bootstrap`으로 의존성 연결
+- 테스트 디렉토리는 `lib/` 미러링 구조
+- generated 파일 (`.g.dart`, `.freezed.dart`) → `.gitignore`에 추가하지 않음 (CI에서 재생성 비용)

package/templates/base/skills/mobile/flutter/rules/animations.md

@@ -0,0 +1,112 @@
+---
+title: Animations
+impact: MEDIUM
+tags: animation, implicit, explicit, hero
+---
+
+## Animations
+
+Flutter 애니메이션 패턴. 암시적(간단) → 명시적(복잡) 선택 기준.
+
+### 선택 기준
+
+| 복잡도 | 사용 | 예시 |
+|--------|------|------|
+| 단순 속성 변경 | `AnimatedContainer`, `AnimatedOpacity` | 페이드, 크기 변경 |
+| 여러 위젯 전환 | `AnimatedSwitcher` | 탭 전환, 상태 전환 |
+| 화면 간 공유 요소 | `Hero` | 카드 → 상세 전환 |
+| 커스텀 곡선/시퀀스 | `AnimationController` + `Tween` | 복잡한 모션 |
+| 반복/물리 기반 | `AnimationController` + `SpringSimulation` | 풀투리프레시 |
+
+### 암시적 애니메이션 (간단)
+
+```dart
+// 상태에 따라 자동 전환
+AnimatedContainer(
+  duration: const Duration(milliseconds: 300),
+  curve: Curves.easeInOut,
+  width: isExpanded ? 200 : 100,
+  height: isExpanded ? 200 : 100,
+  decoration: BoxDecoration(
+    color: isSelected ? Colors.blue : Colors.grey,
+    borderRadius: BorderRadius.circular(isExpanded ? 16 : 8),
+  ),
+  child: content,
+);
+
+// 위젯 교체 시 전환
+AnimatedSwitcher(
+  duration: const Duration(milliseconds: 200),
+  child: isLoading
+      ? const CircularProgressIndicator(key: ValueKey('loading'))
+      : ContentView(key: ValueKey('content'), data: data),
+);
+```
+
+### Hero 전환
+
+```dart
+// 리스트 아이템
+Hero(
+  tag: 'match-${match.id}',
+  child: MatchCard(match: match),
+);
+
+// 상세 화면
+Hero(
+  tag: 'match-${match.id}',
+  child: MatchDetailHeader(match: match),
+);
+```
+
+### 명시적 애니메이션 (복잡)
+
+```dart
+class PulseWidget extends StatefulWidget {
+  const PulseWidget({super.key, required this.child});
+  final Widget child;
+
+  @override
+  State<PulseWidget> createState() => _PulseWidgetState();
+}
+
+class _PulseWidgetState extends State<PulseWidget>
+    with SingleTickerProviderStateMixin {
+  late final AnimationController _controller;
+  late final Animation<double> _scale;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = AnimationController(
+      duration: const Duration(milliseconds: 1000),
+      vsync: this,
+    )..repeat(reverse: true);
+
+    _scale = Tween(begin: 1.0, end: 1.1).animate(
+      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
+    );
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return ScaleTransition(scale: _scale, child: widget.child);
+  }
+}
+```
+
+### 규칙
+
+- 단순 속성 변경 → 암시적 (`Animated*` 위젯) 우선
+- 위젯 교체 → `AnimatedSwitcher` + `key` 필수
+- 화면 전환 공유 요소 → `Hero` (동일 tag)
+- 커스텀 애니메이션 → `AnimationController` + `dispose()` 필수
+- duration: 200-300ms (UI), 300-500ms (페이지 전환)
+- `vsync: this` + `TickerProviderStateMixin` (프레임 동기화)
+- 복잡한 시퀀스는 `staggered_animations` 패키지 검토

package/templates/base/skills/mobile/flutter/rules/architecture.md

@@ -0,0 +1,121 @@
+---
+title: Architecture (Feature-First + MVVM)
+impact: CRITICAL
+tags: architecture, feature-first, mvvm, clean-architecture
+---
+
+## Architecture (Feature-First + MVVM)
+
+Flutter 공식 아키텍처 가이드(MVVM) + VGV 4-layer + Feature-first 구조 종합.
+
+### 3-Layer 아키텍처
+
+```
+┌─ Presentation (UI) ─────────────────┐
+│  Widget → ViewModel (Notifier)      │  UI 렌더링 + 사용자 입력
+│  ref.watch로 상태 구독              │
+└─────────────────────────────────────┘
+          ↕ (Domain Model)
+┌─ Domain ────────────────────────────┐
+│  Entity, ValueObject, UseCase       │  비즈니스 규칙 (선택 레이어)
+│  플랫폼/프레임워크 의존성 없음       │
+└─────────────────────────────────────┘
+          ↕ (Domain Model)
+┌─ Data ──────────────────────────────┐
+│  Repository → DataSource            │  API/DB/캐시 접근
+│  DTO ↔ Domain Model 변환            │
+└─────────────────────────────────────┘
+```
+
+### Feature-First 디렉토리
+
+**Incorrect:**
+```
+lib/
+  models/         # 모든 모델이 한 폴더
+  screens/        # 모든 화면이 한 폴더
+  services/       # 모든 서비스가 한 폴더
+  widgets/        # 모든 위젯이 한 폴더
+```
+
+**Correct:**
+```
+lib/
+  core/                     # 공유 인프라
+    constants/
+    extensions/
+    router/
+    theme/
+    providers/              # 전역 provider (auth, locale 등)
+  features/
+    auth/
+      data/
+        datasources/        # AuthRemoteDataSource
+        dtos/               # AuthResponseDto (JSON 매핑)
+        repositories/       # AuthRepositoryImpl
+      domain/
+        entities/           # User
+        repositories/       # AuthRepository (abstract)
+      presentation/
+        providers/          # authProvider, loginNotifier
+        screens/            # LoginScreen, SignUpScreen
+        widgets/            # AuthForm, SocialLoginButtons
+    match/
+      data/...
+      domain/...
+      presentation/...
+  shared/
+    widgets/                # 재사용 UI 컴포넌트
+    utils/                  # 순수 유틸리티 함수
+```
+
+### Repository 패턴
+
+```dart
+// Domain layer — 추상 인터페이스
+abstract class MatchRepository {
+  Future<List<Match>> getMatches({required Sport sport});
+  Future<void> joinMatch(String matchId);
+  Stream<Match> watchMatch(String matchId);
+}
+
+// Data layer — 구현
+class MatchRepositoryImpl implements MatchRepository {
+  const MatchRepositoryImpl({
+    required this.remoteDataSource,
+    required this.localDataSource,
+  });
+
+  final MatchRemoteDataSource remoteDataSource;
+  final MatchLocalDataSource localDataSource;
+
+  @override
+  Future<List<Match>> getMatches({required Sport sport}) async {
+    try {
+      final dtos = await remoteDataSource.fetchMatches(sport.name);
+      final matches = dtos.map((dto) => dto.toDomain()).toList();
+      await localDataSource.cacheMatches(matches);
+      return matches;
+    } on NetworkException {
+      return localDataSource.getCachedMatches(sport);
+    }
+  }
+}
+
+// Provider 연결
+final matchRepositoryProvider = Provider<MatchRepository>((ref) {
+  return MatchRepositoryImpl(
+    remoteDataSource: ref.watch(matchRemoteDataSourceProvider),
+    localDataSource: ref.watch(matchLocalDataSourceProvider),
+  );
+});
+```
+
+### 규칙
+
+- **Feature-first**: `lib/features/{name}/` 구조 필수
+- **레이어 방향**: Presentation → Domain ← Data (의존성 역전)
+- **Domain layer**: Flutter import 금지 (`dart:` 만 허용)
+- **DTO ↔ Model 분리**: API 응답 구조와 도메인 모델 분리
+- **Repository**: abstract (domain) + impl (data) 분리
+- **1 feature = 1 독립 단위**: feature 간 직접 import 금지 → 공유 도메인은 `core/`

package/templates/base/skills/mobile/flutter/rules/navigation-routing.md

@@ -0,0 +1,117 @@
+---
+title: Navigation & Routing
+impact: HIGH
+tags: go-router, navigation, deep-link, routing
+---
+
+## Navigation & Routing
+
+go_router 기반 선언적 라우팅. 딥링크, 가드, 중첩 네비게이션.
+
+### 라우터 설정
+
+```dart
+final routerProvider = Provider<GoRouter>((ref) {
+  final authState = ref.watch(authStateProvider);
+
+  return GoRouter(
+    initialLocation: '/',
+    redirect: (context, state) {
+      final isLoggedIn = authState.valueOrNull != null;
+      final isAuthRoute = state.matchedLocation.startsWith('/auth');
+
+      if (!isLoggedIn && !isAuthRoute) return '/auth/login';
+      if (isLoggedIn && isAuthRoute) return '/';
+      return null; // 리다이렉트 불필요
+    },
+    routes: [
+      // 인증 라우트 (바텀 네비 없음)
+      GoRoute(
+        path: '/auth/login',
+        builder: (context, state) => const LoginScreen(),
+      ),
+      // 메인 앱 (바텀 네비 + 중첩 라우팅)
+      StatefulShellRoute.indexedStack(
+        builder: (context, state, child) => MainShell(child: child),
+        branches: [
+          StatefulShellBranch(routes: [
+            GoRoute(
+              path: '/',
+              builder: (_, __) => const HomeScreen(),
+              routes: [
+                GoRoute(
+                  path: 'match/:id',
+                  builder: (_, state) => MatchDetailScreen(
+                    matchId: state.pathParameters['id']!,
+                  ),
+                ),
+              ],
+            ),
+          ]),
+          StatefulShellBranch(routes: [
+            GoRoute(
+              path: '/community',
+              builder: (_, __) => const CommunityScreen(),
+            ),
+          ]),
+          StatefulShellBranch(routes: [
+            GoRoute(
+              path: '/profile',
+              builder: (_, __) => const ProfileScreen(),
+            ),
+          ]),
+        ],
+      ),
+    ],
+  );
+});
+```
+
+### 네비게이션 호출
+
+**Incorrect:**
+```dart
+// 명령형 — 히스토리 관리 어려움
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (_) => MatchDetailScreen(id: matchId)),
+);
+```
+
+**Correct:**
+```dart
+// 선언적 — URL 기반
+context.go('/match/$matchId');        // 교체
+context.push('/match/$matchId');      // 스택 추가
+context.pop();                         // 뒤로가기
+```
+
+### 딥링크 설정
+
+```dart
+// go_router는 자동으로 URL 파싱
+// Android: AndroidManifest.xml
+// <intent-filter android:autoVerify="true">
+//   <data android:scheme="https" android:host="app.example.com" />
+// </intent-filter>
+
+// iOS: Info.plist
+// Associated Domains: applinks:app.example.com
+
+// Flutter 측: 라우트만 정의하면 딥링크 자동 처리
+GoRoute(
+  path: '/match/:id',
+  builder: (_, state) => MatchDetailScreen(
+    matchId: state.pathParameters['id']!,
+  ),
+),
+```
+
+### 규칙
+
+- `go_router` 선언적 라우팅 사용 (Navigator.push 금지)
+- 라우트 정의는 `core/router/` 에 중앙화
+- `redirect` 로 인증 가드 구현 (미들웨어 패턴)
+- `StatefulShellRoute` 로 바텀 네비 + 각 탭 스택 유지
+- path parameter는 `/:id` 패턴, query는 `state.uri.queryParameters`
+- 라우트 경로 상수화 (`RouteNames` 또는 `RoutePaths` 클래스)