timsquad 3.3.0 → 3.4.0

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

@@ -0,0 +1,112 @@
+---
+title: Performance Optimization
+impact: HIGH
+tags: performance, rebuild, lazy-loading, impeller
+---
+
+## Performance Optimization
+
+Flutter 렌더링 파이프라인 최적화. 불필요한 리빌드 차단, lazy 로딩, 메모리 관리.
+
+### const 위젯으로 리빌드 차단
+
+**Incorrect:**
+```dart
+@override
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      // 매 빌드마다 재생성 (부모 상태 변경 시)
+      Header(),
+      Divider(),
+      Text('Fixed label'),
+      // 실제로 변경되는 부분
+      Text(counter.toString()),
+    ],
+  );
+}
+```
+
+**Correct:**
+```dart
+@override
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      const Header(),             // 리빌드 스킵
+      const Divider(),            // 리빌드 스킵
+      const Text('Fixed label'),  // 리빌드 스킵
+      Text(counter.toString()),   // 이것만 리빌드
+    ],
+  );
+}
+```
+
+### 리스트 최적화
+
+**Incorrect:**
+```dart
+// 모든 아이템을 한번에 빌드 → 메모리 + 프레임 드롭
+ListView(
+  children: matches.map((m) => MatchCard(match: m)).toList(),
+);
+```
+
+**Correct:**
+```dart
+// lazy 빌드 → 화면에 보이는 것만 생성
+ListView.builder(
+  itemCount: matches.length,
+  itemBuilder: (context, index) => MatchCard(
+    key: ValueKey(matches[index].id),
+    match: matches[index],
+  ),
+);
+
+// 무한 스크롤
+ListView.builder(
+  itemCount: matches.length + (hasMore ? 1 : 0),
+  itemBuilder: (context, index) {
+    if (index == matches.length) {
+      ref.read(matchListProvider.notifier).loadMore();
+      return const LoadingTile();
+    }
+    return MatchCard(match: matches[index]);
+  },
+);
+```
+
+### RepaintBoundary
+
+```dart
+// 자주 업데이트되는 영역 격리
+RepaintBoundary(
+  child: LiveScoreBoard(matchId: matchId), // 1초마다 갱신
+),
+// ScoreBoard 리페인트가 부모 트리에 전파되지 않음
+```
+
+### 이미지 최적화
+
+```dart
+// cached_network_image + 적절한 크기
+CachedNetworkImage(
+  imageUrl: user.avatarUrl,
+  width: 48,
+  height: 48,
+  memCacheWidth: 96,   // 2x for retina
+  memCacheHeight: 96,
+  placeholder: (_, __) => const CircleAvatar(child: Icon(Icons.person)),
+  errorWidget: (_, __, ___) => const CircleAvatar(child: Icon(Icons.error)),
+);
+```
+
+### 규칙
+
+- `const` 가능한 위젯은 반드시 `const` (lint 강제)
+- 10개 이상 아이템 → `ListView.builder` / `SliverList` (lazy)
+- `RepaintBoundary` → 자주 갱신되는 서브트리에 적용
+- 이미지: `memCacheWidth/Height` 설정 (원본 크기 로딩 방지)
+- `setState` 범위 최소화 — 변경되는 위젯만 리빌드
+- build() 안에서 `Future`/무거운 연산 금지 → Provider/Notifier에서 처리
+- DevTools Performance 뷰로 jank 프레임 확인

package/templates/base/skills/mobile/flutter/rules/platform-adaptive.md

@@ -0,0 +1,126 @@
+---
+title: Platform Adaptive UI
+impact: MEDIUM
+tags: adaptive, responsive, material, cupertino
+---
+
+## Platform Adaptive UI
+
+크로스플랫폼 적응형 UI. Material + Cupertino 자동 전환, 반응형 레이아웃.
+
+### 적응형 위젯 패턴
+
+```dart
+/// 플랫폼에 따라 Material/Cupertino 자동 선택
+class AdaptiveDialog {
+  static Future<bool?> show(
+    BuildContext context, {
+    required String title,
+    required String content,
+  }) {
+    if (Platform.isIOS || Platform.isMacOS) {
+      return showCupertinoDialog<bool>(
+        context: context,
+        builder: (_) => CupertinoAlertDialog(
+          title: Text(title),
+          content: Text(content),
+          actions: [
+            CupertinoDialogAction(
+              onPressed: () => Navigator.pop(context, false),
+              child: const Text('Cancel'),
+            ),
+            CupertinoDialogAction(
+              isDefaultAction: true,
+              onPressed: () => Navigator.pop(context, true),
+              child: const Text('OK'),
+            ),
+          ],
+        ),
+      );
+    }
+    return showDialog<bool>(
+      context: context,
+      builder: (_) => AlertDialog(
+        title: Text(title),
+        content: Text(content),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(context, false),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.pop(context, true),
+            child: const Text('OK'),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+### 반응형 레이아웃
+
+```dart
+class ResponsiveLayout extends StatelessWidget {
+  const ResponsiveLayout({
+    super.key,
+    required this.mobile,
+    this.tablet,
+    this.desktop,
+  });
+
+  final Widget mobile;
+  final Widget? tablet;
+  final Widget? desktop;
+
+  static const mobileBreakpoint = 600.0;
+  static const tabletBreakpoint = 900.0;
+
+  @override
+  Widget build(BuildContext context) {
+    final width = MediaQuery.sizeOf(context).width;
+
+    if (width >= tabletBreakpoint && desktop != null) return desktop!;
+    if (width >= mobileBreakpoint && tablet != null) return tablet!;
+    return mobile;
+  }
+}
+
+// 사용
+ResponsiveLayout(
+  mobile: const MatchListMobile(),
+  tablet: const MatchListTablet(), // 2-column
+);
+```
+
+### 플랫폼별 동작
+
+```dart
+// 스크롤 물리
+ScrollConfiguration(
+  behavior: Platform.isIOS
+      ? const CupertinoScrollBehavior() // 바운스
+      : const MaterialScrollBehavior(), // 글로우
+  child: ListView(...),
+);
+
+// 날짜 선택
+Future<DateTime?> pickDate(BuildContext context) {
+  if (Platform.isIOS) {
+    return showCupertinoModalPopup<DateTime>(
+      context: context,
+      builder: (_) => CupertinoDatePicker(...),
+    );
+  }
+  return showDatePicker(context: context, ...);
+}
+```
+
+### 규칙
+
+- 대화상자, 스위치, 날짜피커 → 플랫폼별 네이티브 위젯 사용
+- 반응형 breakpoint: mobile < 600 < tablet < 900 < desktop
+- `MediaQuery.sizeOf(context)` 사용 (`MediaQuery.of` 보다 효율적)
+- 플랫폼 분기는 유틸 함수로 캡슐화 (위젯 안에 if/else 산재 금지)
+- `Theme.of(context).platform` 으로 플랫폼 감지 (테스트 용이)

package/templates/base/skills/mobile/flutter/rules/state-management.md

@@ -0,0 +1,110 @@
+---
+title: State Management (Riverpod)
+impact: CRITICAL
+tags: riverpod, provider, notifier, state
+---
+
+## State Management (Riverpod)
+
+Riverpod 기반 상태 관리. 선언적 의존성, 자동 dispose, 타입 안전.
+
+### Provider 타입 선택
+
+| 용도 | Provider 타입 | 예시 |
+|------|-------------|------|
+| 동기 파생 값 | `Provider` | 필터링된 리스트, 계산값 |
+| 비동기 단발 | `FutureProvider` | API 호출, 초기 데이터 로드 |
+| 실시간 스트림 | `StreamProvider` | WebSocket, Firestore 스냅샷 |
+| UI 상태 (CRUD) | `NotifierProvider` | 폼 상태, 필터, 페이지네이션 |
+| 비동기 UI 상태 | `AsyncNotifierProvider` | 서버 데이터 + 뮤테이션 |
+
+### ref 사용 구분
+
+**Incorrect:**
+```dart
+class MatchListScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    // build에서 ref.read → 변경 감지 안 됨
+    final matches = ref.read(matchListProvider);
+
+    return ElevatedButton(
+      // 이벤트에서 ref.watch → 불필요한 구독
+      onPressed: () => ref.watch(matchListProvider.notifier).refresh(),
+      child: Text('Refresh'),
+    );
+  }
+}
+```
+
+**Correct:**
+```dart
+class MatchListScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    // build에서 ref.watch → 변경 시 리빌드
+    final matchesAsync = ref.watch(matchListProvider);
+
+    return matchesAsync.when(
+      data: (matches) => MatchListView(matches: matches),
+      loading: () => const MatchListSkeleton(),
+      error: (e, _) => ErrorView(error: e),
+    );
+  }
+
+  void _onRefresh(WidgetRef ref) {
+    // 이벤트에서 ref.read → 1회성 접근
+    ref.read(matchListProvider.notifier).refresh();
+  }
+}
+```
+
+### Notifier 패턴
+
+```dart
+// Domain model
+sealed class MatchListState {}
+class MatchListInitial extends MatchListState {}
+class MatchListLoaded extends MatchListState {
+  final List<Match> matches;
+  MatchListLoaded(this.matches);
+}
+
+// Provider 선언
+final matchListProvider =
+    AsyncNotifierProvider<MatchListNotifier, List<Match>>(
+  MatchListNotifier.new,
+);
+
+// Notifier 구현
+class MatchListNotifier extends AsyncNotifier<List<Match>> {
+  @override
+  Future<List<Match>> build() async {
+    // 의존성 주입: ref.watch로 다른 provider 구독
+    final sport = ref.watch(selectedSportProvider);
+    final repo = ref.watch(matchRepositoryProvider);
+    return repo.getMatches(sport: sport);
+  }
+
+  Future<void> refresh() async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() => build());
+  }
+
+  Future<void> joinMatch(String matchId) async {
+    final repo = ref.read(matchRepositoryProvider);
+    await repo.joinMatch(matchId);
+    ref.invalidateSelf(); // 데이터 새로고침
+  }
+}
+```
+
+### 규칙
+
+- `ref.watch` → build() 안에서만 (리액티브 구독)
+- `ref.read` → 이벤트 핸들러, 콜백에서 (1회 접근)
+- `ref.listen` → side effect (스낵바, 네비게이션)
+- `autoDispose` 기본 사용 (화면 벗어나면 해제)
+- Provider 파일 위치: `features/{name}/presentation/providers/`
+- 전역 상태는 `core/providers/`에 배치
+- `.when()` 패턴으로 loading/error/data 처리

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

@@ -0,0 +1,131 @@
+---
+title: Testing Strategy
+impact: HIGH
+tags: testing, widget-test, integration, mocktail
+---
+
+## Testing Strategy
+
+Flutter 3계층 테스트: Unit → Widget → Integration. mocktail + Patrol.
+
+### 테스트 피라미드
+
+```
+         ╱╲
+        ╱  ╲         Integration (Patrol)
+       ╱    ╲        - 전체 플로우 (로그인→매칭→채팅)
+      ╱──────╲       - 네이티브 상호작용 (권한, 알림)
+     ╱        ╲
+    ╱  Widget  ╲     Widget Test
+   ╱            ╲    - 개별 위젯 렌더링 + 인터랙션
+  ╱──────────────╲   - Provider override로 상태 주입
+ ╱                ╲
+╱      Unit        ╲  Unit Test
+╱──────────────────╲  - Notifier, Repository, UseCase
+                      - 순수 Dart (Flutter 의존성 없음)
+```
+
+### Unit Test (Notifier)
+
+```dart
+void main() {
+  late MockMatchRepository mockRepo;
+  late ProviderContainer container;
+
+  setUp(() {
+    mockRepo = MockMatchRepository();
+    container = ProviderContainer(overrides: [
+      matchRepositoryProvider.overrideWithValue(mockRepo),
+    ]);
+  });
+
+  tearDown(() => container.dispose());
+
+  test('초기 로드 시 매치 목록 반환', () async {
+    when(() => mockRepo.getMatches(sport: Sport.tennis))
+        .thenAnswer((_) async => [testMatch]);
+
+    final notifier = container.read(matchListProvider.notifier);
+    final state = await container.read(matchListProvider.future);
+
+    expect(state, hasLength(1));
+    expect(state.first.id, testMatch.id);
+  });
+}
+```
+
+### Widget Test
+
+```dart
+void main() {
+  testWidgets('MatchCard가 매치 정보를 표시한다', (tester) async {
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          matchProvider.overrideWithValue(AsyncData(testMatch)),
+        ],
+        child: const MaterialApp(
+          home: Scaffold(body: MatchCard()),
+        ),
+      ),
+    );
+
+    expect(find.text('Tennis Match'), findsOneWidget);
+    expect(find.text('Singapore Sports Hub'), findsOneWidget);
+
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pumpAndSettle();
+
+    expect(find.text('Joined!'), findsOneWidget);
+  });
+}
+```
+
+### Mock (mocktail)
+
+```dart
+import 'package:mocktail/mocktail.dart';
+
+// 코드 생성 불필요
+class MockMatchRepository extends Mock implements MatchRepository {}
+class MockAuthService extends Mock implements AuthService {}
+
+// 사용
+when(() => mockRepo.getMatches(sport: any(named: 'sport')))
+    .thenAnswer((_) async => [testMatch]);
+
+verify(() => mockRepo.getMatches(sport: Sport.tennis)).called(1);
+```
+
+### Integration Test (Patrol)
+
+```dart
+// integration_test/match_flow_test.dart
+patrolTest('매치 생성 → 참여 → 채팅 전체 플로우', ($) async {
+  await $.pumpWidgetAndSettle(const MyApp());
+
+  // 로그인
+  await $(#emailField).enterText('test@example.com');
+  await $(#passwordField).enterText('password');
+  await $(#loginButton).tap();
+
+  // 네이티브 권한 허용 (Patrol 고유 기능)
+  await $.native.grantPermissionWhenInUse();
+
+  // 매치 화면
+  await $.waitUntilVisible($(#matchList));
+  await $(#createMatchButton).tap();
+
+  // 확인
+  expect($(#matchCreatedSnackbar), findsOneWidget);
+});
+```
+
+### 규칙
+
+- Unit test: Notifier/Repository 100% 커버리지 목표
+- Widget test: 주요 화면 + 사용자 인터랙션
+- Mock: `mocktail` 사용 (mockito의 codegen 불필요)
+- Provider 테스트: `ProviderContainer` + `overrides`
+- Integration: 핵심 사용자 플로우만 (3-5개)
+- test fixtures: `test/fixtures/` 에 공유 테스트 데이터

package/templates/base/skills/mobile/flutter/rules/widget-conventions.md

@@ -0,0 +1,122 @@
+---
+title: Widget Conventions
+impact: CRITICAL
+tags: widget, composition, const, key
+---
+
+## Widget Conventions
+
+Flutter 위젯은 합성(composition)으로 설계. 상속보다 조합, const로 성능 확보.
+
+### 위젯 구조 템플릿
+
+```dart
+/// 사용자 프로필 카드.
+class UserProfileCard extends StatelessWidget {
+  const UserProfileCard({
+    super.key,
+    required this.user,
+    this.onTap,
+  });
+
+  final UserProfile user;
+  final VoidCallback? onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+
+    return Card(
+      child: InkWell(
+        onTap: onTap,
+        child: Padding(
+          padding: const EdgeInsets.all(16),
+          child: Row(
+            children: [
+              UserAvatar(url: user.avatarUrl),
+              const SizedBox(width: 12),
+              Expanded(
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    Text(user.name, style: theme.textTheme.titleMedium),
+                    Text(user.email, style: theme.textTheme.bodySmall),
+                  ],
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+### const 생성자
+
+**Incorrect:**
+```dart
+class AppLogo extends StatelessWidget {
+  // const 없음 → 부모 리빌드마다 재생성
+  AppLogo({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Image.asset('assets/logo.png', width: 48);
+  }
+}
+
+// 사용 시
+Column(children: [AppLogo(), ...]) // const 불가
+```
+
+**Correct:**
+```dart
+class AppLogo extends StatelessWidget {
+  const AppLogo({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Image.asset('assets/logo.png', width: 48);
+  }
+}
+
+// 사용 시
+Column(children: [const AppLogo(), ...]) // 리빌드 스킵
+```
+
+### Key 사용 기준
+
+**Incorrect:**
+```dart
+ListView(
+  children: items.map((item) => ItemTile(item: item)).toList(),
+  // Key 없음 → 순서 변경/삽입 시 위젯 상태 꼬임
+);
+```
+
+**Correct:**
+```dart
+ListView(
+  children: items.map((item) => ItemTile(
+    key: ValueKey(item.id), // 고유 식별자
+    item: item,
+  )).toList(),
+);
+```
+
+### 분리 기준
+
+- **200줄 초과** → 서브 위젯으로 추출
+- **재사용 가능** → `shared/widgets/`로 이동
+- **build() 안 조건 분기 3개 이상** → 별도 위젯
+- **GlobalKey** → 거의 사용 금지 (Form 제외). `ValueKey`/`ObjectKey` 우선
+
+### 규칙
+
+- `const` 생성자 가능하면 항상 선언 (`prefer_const_constructors` 린트)
+- `super.key` 파라미터 필수 (모든 위젯)
+- trailing comma 필수 (위젯 트리 가독성)
+- `build()` 안에서 데이터 가공/API 호출 금지
+- `SizedBox` > `Container` (빈 공간에 Container 쓰지 않기)

package/templates/base/skills/mobile/flutter/security/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: security
+description: |
+  Flutter 모바일 보안 가이드라인.
+  flutter_secure_storage, biometric 인증, SSL pinning,
+  코드 난독화, API 키 보호, 데이터 암호화.
+version: "1.0.0"
+tags: [flutter, security, encryption, biometric, ssl-pinning, obfuscation]
+user-invocable: false
+---
+
+# Security
+
+Flutter 모바일 보안 가이드. 저장소 암호화, 전송 보안, 실행 보호, 인증 강화.
+OWASP MASVS 기준 L1/L2 준수를 목표로 레이어별 독립 방어.
+
+## Philosophy
+
+- 보안은 레이어 — 저장(암호화), 전송(TLS+pinning), 실행(난독화) 각각 독립 방어
+- 키는 코드에 없다 — 빌드 시 주입, 런타임 안전 저장소
+- 인증은 로컬 + 원격 이중 — biometric은 UX, 토큰은 보안
+
+## Resources
+
+6개 규칙 + 1개 참조. 모바일 보안 전체 레이어를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [secure-storage](rules/secure-storage.md) | flutter_secure_storage (Keychain/EncryptedSharedPreferences), 민감 데이터 저장 |
+| CRITICAL | rule | [authentication](rules/authentication.md) | 토큰 라이프사이클, 자동 갱신, biometric 인증, 세션 관리 |
+| HIGH | rule | [ssl-pinning](rules/ssl-pinning.md) | Dio SecurityContext, 인증서/공개키 pinning, 핀 업데이트 전략 |
+| HIGH | rule | [api-key-protection](rules/api-key-protection.md) | --dart-define 빌드 주입, envied 패키지, 하드코딩 금지 |
+| HIGH | rule | [obfuscation](rules/obfuscation.md) | --obfuscate, ProGuard, dSYM, Crashlytics 심볼 업로드 |
+| MEDIUM | rule | [data-protection](rules/data-protection.md) | 로컬 DB 암호화, 클립보드 보호, 스크린샷 방지 |
+| — | ref | [mobile-security-checklist](references/mobile-security-checklist.md) | OWASP MASVS L1/L2 체크리스트, 추천 도구 |
+
+## Quick Rules
+
+### 저장소 보안
+- 토큰/시크릿 → `flutter_secure_storage` (Keychain iOS / EncryptedSharedPreferences Android)
+- `SharedPreferences`에 민감 데이터 저장 금지 — 평문 저장, 루팅 시 노출
+- 로컬 DB → SQLCipher 또는 encrypt 패키지로 암호화
+
+### 인증
+- Access Token (단수명) + Refresh Token (장수명) 분리
+- Dio interceptor로 401 감지 → 자동 갱신 → 재요청
+- Biometric → `local_auth` 패키지, 실패 시 PIN/패턴 폴백
+
+### 전송 보안
+- TLS 1.2+ 필수, 인증서 pinning으로 MITM 차단
+- Dio `SecurityContext` + `badCertificateCallback` 조합
+- 핀 만료 대비 → 백업 핀 + 원격 업데이트 전략
+
+### API 키 보호
+- `--dart-define=API_KEY=xxx` → 빌드 시 주입
+- `String.fromEnvironment('API_KEY')` → 런타임 참조
+- `.env` → `envied` 패키지 (코드 생성, 난독화 옵션)
+- 하드코딩 → 절대 금지 (git history에 영구 노출)
+
+### 난독화
+- `flutter build --obfuscate --split-debug-info=debug-info/`
+- Android: ProGuard/R8 shrinking 활성화
+- iOS: Bitcode (Xcode 설정) + dSYM 보관
+- Crashlytics → 디버그 심볼 업로드 (크래시 리포트 해석용)
+
+### 데이터 보호
+- 스크린샷 방지 → Android `FLAG_SECURE`, iOS `UITextField` 오버레이
+- 클립보드 → autofill 후 일정 시간 뒤 클리어
+- 앱 백그라운드 진입 시 → 스크린 블러/오버레이
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 토큰/시크릿은 flutter_secure_storage에만 저장 |
+| CRITICAL | SharedPreferences에 민감 데이터 저장하지 않음 |
+| CRITICAL | Access/Refresh Token 분리 + 자동 갱신 구현 |
+| CRITICAL | API 키 하드코딩 없음 (--dart-define 또는 envied) |
+| HIGH | SSL pinning 적용 (인증서 또는 공개키) |
+| HIGH | 릴리즈 빌드 시 --obfuscate 플래그 사용 |
+| HIGH | ProGuard/R8 shrinking 활성화 (Android) |
+| HIGH | Biometric 인증 + PIN 폴백 구현 |
+| MEDIUM | 로컬 DB 암호화 (SQLCipher) |
+| MEDIUM | 스크린샷 방지 (FLAG_SECURE) 적용 |
+| MEDIUM | Crashlytics 디버그 심볼 업로드 |
+| MEDIUM | OWASP MASVS L1 체크리스트 통과 |