timsquad 2.1.0 → 3.4.0

package/templates/base/skills/mobile/flutter/i18n/rules/localization-setup.md

@@ -0,0 +1,137 @@
+---
+title: Localization Setup (flutter_localizations + intl)
+impact: CRITICAL
+impactDescription: "설정 누락 → 번역 미적용, 런타임 에러, 날짜/숫자 포맷 불일치"
+tags: flutter-localizations, intl, l10n-yaml, pubspec, setup
+---
+
+## Localization Setup (flutter_localizations + intl)
+
+**Impact: CRITICAL (설정 누락 → 번역 미적용, 런타임 에러, 날짜/숫자 포맷 불일치)**
+
+flutter_localizations + intl 패키지 설정, pubspec.yaml generate 플래그, l10n.yaml 구성,
+MaterialApp delegate 등록. 프로젝트 초기에 반드시 완료해야 하는 i18n 인프라.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  intl: any  # flutter_localizations가 버전 관리
+
+# 코드 생성 활성화 (필수!)
+flutter:
+  generate: true
+```
+
+### l10n.yaml 설정
+
+**Incorrect (l10n.yaml 없이 수동 관리):**
+```dart
+// ARB 파일을 직접 파싱하거나 하드코딩된 Map 사용
+// → 타입 안전성 없음, 키 오타 런타임까지 발견 불가
+final Map<String, String> translations = {
+  'hello': 'Hello',
+  'welcome': 'Welcome, $name',
+};
+```
+
+**Correct (l10n.yaml로 자동 코드 생성):**
+```yaml
+# l10n.yaml (프로젝트 루트)
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+output-class: AppLocalizations
+# nullable-getter: false  # null 안전 접근 (선택, 기본 true)
+# synthetic-package: true  # .dart_tool/에 생성 (기본 true)
+```
+
+### MaterialApp 설정
+
+**Incorrect (delegate 누락):**
+```dart
+MaterialApp(
+  // localizationsDelegates 없음 → AppLocalizations.of(context) 실패
+  // supportedLocales 없음 → 시스템 로캘 무시
+  home: const HomeScreen(),
+);
+```
+
+**Correct (완전한 delegate 등록):**
+```dart
+import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+
+class MyApp extends ConsumerWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final locale = ref.watch(localeProvider);
+
+    return MaterialApp.router(
+      // 1. Localization Delegates (3종 필수)
+      localizationsDelegates: const [
+        AppLocalizations.delegate,              // 앱 번역
+        GlobalMaterialLocalizations.delegate,   // Material 위젯 번역
+        GlobalWidgetsLocalizations.delegate,    // 기본 위젯 방향성
+        GlobalCupertinoLocalizations.delegate,  // Cupertino 위젯 번역
+      ],
+      // 2. 지원 로캘 목록
+      supportedLocales: AppLocalizations.supportedLocales,
+      // 3. 현재 로캘 (null → 시스템 로캘 사용)
+      locale: locale,
+      routerConfig: ref.watch(routerProvider),
+    );
+  }
+}
+```
+
+### 번역 사용
+
+```dart
+// 위젯에서 번역 접근
+class WelcomeScreen extends StatelessWidget {
+  const WelcomeScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    // AppLocalizations.of(context) → nullable (로캘 미지원 시 null)
+    final l10n = AppLocalizations.of(context)!;
+    // 또는 extension 사용:
+    // final l10n = context.l10n;
+
+    return Text(l10n.welcomeMessage('Tim'));
+  }
+}
+
+// 편의 Extension (선택)
+extension BuildContextL10n on BuildContext {
+  AppLocalizations get l10n => AppLocalizations.of(this)!;
+}
+```
+
+### 코드 생성 실행
+
+```bash
+# ARB 파일 추가/수정 후 코드 생성
+flutter gen-l10n
+
+# 또는 빌드 시 자동 생성 (generate: true 설정 시)
+flutter run  # 자동으로 gen-l10n 실행
+flutter build  # 마찬가지
+```
+
+### 규칙
+
+- `pubspec.yaml` → `flutter: generate: true` 필수 (자동 코드 생성 활성화)
+- `l10n.yaml` → 프로젝트 루트에 반드시 생성, `arb-dir` + `template-arb-file` 지정
+- `localizationsDelegates` → 4개 등록 (App + Material + Widgets + Cupertino)
+- `supportedLocales` → `AppLocalizations.supportedLocales` 사용 (ARB 파일에서 자동 유도)
+- 하드코딩된 문자열 Map 사용 금지 → ARB + 코드 생성으로 타입 안전 접근
+- `context.l10n` Extension → 반복적인 `AppLocalizations.of(context)!` 줄이기
+- `flutter gen-l10n` → ARB 파일 변경 후 반드시 실행 (빌드 시 자동이지만 IDE 지원용)

package/templates/base/skills/mobile/flutter/i18n/rules/plural-gender.md

@@ -0,0 +1,159 @@
+---
+title: Plural & Gender (ICU MessageFormat)
+impact: HIGH
+impactDescription: "복수형 미처리 → '1 items' 문법 오류, 성별 미처리 → 포용성 저하"
+tags: icu, plural, gender, select, ordinal, message-format
+---
+
+## Plural & Gender (ICU MessageFormat)
+
+**Impact: HIGH (복수형 미처리 → '1 items' 문법 오류, 성별 미처리 → 포용성 저하)**
+
+ICU MessageFormat 기반 복수형, 성별, 서수 처리. ARB 파일에 직접 ICU 구문 작성,
+intl 패키지가 자동 파싱. 언어별 복수형 규칙 차이를 올바르게 처리.
+
+### 복수형 (Plural)
+
+**Incorrect (조건문으로 복수형 처리):**
+```dart
+// 코드에서 직접 분기 → 번역 불가, 언어별 규칙 대응 불가
+String getItemText(int count) {
+  if (count == 0) return 'No items';
+  if (count == 1) return '1 item';
+  return '$count items';
+}
+// → 러시아어는 1, 2-4, 5-20, 21 등 복수형 규칙이 다름
+// → 아랍어는 6가지 복수형 (zero, one, two, few, many, other)
+```
+
+**Correct (ARB 파일에 ICU plural 구문):**
+```json
+{
+  "matchCount": "{count, plural, =0{No matches} =1{1 match} other{{count} matches}}",
+  "@matchCount": {
+    "description": "Number of available matches on the board",
+    "placeholders": {
+      "count": {
+        "type": "int",
+        "example": "5"
+      }
+    }
+  }
+}
+```
+
+### 복수형 카테고리
+
+```
+ICU 복수형 카테고리 (언어별로 사용하는 카테고리가 다름):
+
+  =0     → 정확히 0 (선택, 없으면 other 사용)
+  =1     → 정확히 1 (선택, 없으면 one 사용)
+  =2     → 정확히 2 (선택)
+  zero   → 0 범주 (아랍어 등)
+  one    → 1 범주 (대부분 언어의 단수)
+  two    → 2 범주 (아랍어, 웨일스어)
+  few    → 소수 범주 (슬라브어: 2-4, 아랍어: 3-10)
+  many   → 다수 범주 (슬라브어: 5+, 아랍어: 11-99)
+  other  → 기본 (필수! 모든 언어에서 폴백)
+```
+
+### 언어별 복수형 예시
+
+```json
+// English (en) — one, other
+{
+  "messageCount": "{count, plural, =0{No messages} one{1 message} other{{count} messages}}"
+}
+
+// Korean (ko) — other만 사용 (복수형 구분 없음)
+{
+  "messageCount": "{count, plural, =0{메시지 없음} other{메시지 {count}개}}"
+}
+
+// Russian (ru) — one, few, many, other
+{
+  "messageCount": "{count, plural, =0{Нет сообщений} one{{count} сообщение} few{{count} сообщения} many{{count} сообщений} other{{count} сообщений}}"
+}
+
+// Arabic (ar) — zero, one, two, few, many, other
+{
+  "messageCount": "{count, plural, zero{لا رسائل} one{رسالة واحدة} two{رسالتان} few{{count} رسائل} many{{count} رسالة} other{{count} رسالة}}"
+}
+```
+
+### 성별 (Select)
+
+```json
+{
+  "profileGreeting": "{gender, select, male{He joined} female{She joined} other{They joined}} the match",
+  "@profileGreeting": {
+    "description": "Greeting text when a player joins a match",
+    "placeholders": {
+      "gender": {
+        "type": "String",
+        "example": "male"
+      }
+    }
+  }
+}
+
+// Korean (성별 구분 불필요한 언어)
+{
+  "profileGreeting": "{gender, select, male{매치에 참가했습니다} female{매치에 참가했습니다} other{매치에 참가했습니다}}"
+}
+```
+
+### 복합 (Plural + 다른 변수)
+
+```json
+{
+  "matchInvite": "{userName} invited you to {count, plural, =1{a match} other{{count} matches}}",
+  "@matchInvite": {
+    "description": "Match invitation notification text",
+    "placeholders": {
+      "userName": { "type": "String", "example": "Tim" },
+      "count": { "type": "int", "example": "2" }
+    }
+  }
+}
+```
+
+### 서수 (Ordinal — 선택)
+
+```json
+{
+  "rankPosition": "You are {position, select, 1{1st} 2{2nd} 3{3rd} other{{position}th}} place",
+  "@rankPosition": {
+    "description": "User ranking position in leaderboard",
+    "placeholders": {
+      "position": { "type": "int", "example": "3" }
+    }
+  }
+}
+```
+
+### Dart 코드에서 사용
+
+```dart
+// 자동 생성된 AppLocalizations 메서드 사용
+Text(context.l10n.matchCount(0));      // "No matches"
+Text(context.l10n.matchCount(1));      // "1 match"
+Text(context.l10n.matchCount(42));     // "42 matches"
+
+Text(context.l10n.profileGreeting('female'));  // "She joined the match"
+Text(context.l10n.profileGreeting('other'));   // "They joined the match"
+
+Text(context.l10n.matchInvite('Tim', 3));  // "Tim invited you to 3 matches"
+```
+
+### 규칙
+
+- 복수형 → ARB 파일에 ICU `{count, plural, ...}` 구문 사용, 코드 분기 금지
+- `other` 카테고리 → 필수 (모든 복수형/select에서 폴백)
+- 언어별 복수형 규칙 → 번역가에게 언어 규칙 안내 (CLDR 참조)
+- 성별 → `{gender, select, male{...} female{...} other{...}}` 사용
+- `other` in select → 성 중립 표현 (포용성)
+- 복합 구문 → plural + 변수 결합 가능, 중첩은 가독성 위해 최소화
+- placeholder type → `int` (plural), `String` (select) 정확히 지정
+- 한국어/일본어 등 → 복수형 구분 불필요해도 `other` 필수 (ICU 규격)

package/templates/base/skills/mobile/flutter/i18n/rules/text-direction.md

@@ -0,0 +1,199 @@
+---
+title: Text Direction & RTL Layout Support
+impact: HIGH
+impactDescription: "RTL 미대응 → 아랍어/히브리어 사용자 UX 파괴, 레이아웃 반전 오류"
+tags: rtl, ltr, directionality, edge-insets-directional, alignment-directional
+---
+
+## Text Direction & RTL Layout Support
+
+**Impact: HIGH (RTL 미대응 → 아랍어/히브리어 사용자 UX 파괴, 레이아웃 반전 오류)**
+
+RTL (Right-to-Left) 레이아웃 지원. Directionality 위젯, EdgeInsetsDirectional,
+AlignmentDirectional, 아이콘 미러링. RTL 로캘 지원 시 필수.
+
+### Directional 위젯 사용
+
+**Incorrect (하드코딩된 left/right):**
+```dart
+Container(
+  padding: const EdgeInsets.only(left: 16, right: 8),
+  alignment: Alignment.centerLeft,
+  child: Row(
+    children: [
+      const Icon(Icons.arrow_back),  // RTL에서도 왼쪽 화살표
+      const SizedBox(width: 8),
+      Text(title),
+    ],
+  ),
+);
+```
+
+**Correct (Directional 위젯으로 RTL 자동 대응):**
+```dart
+Container(
+  padding: const EdgeInsetsDirectional.only(start: 16, end: 8),
+  alignment: AlignmentDirectional.centerStart,
+  child: Row(
+    children: [
+      Icon(
+        // RTL에서는 자동으로 arrow_forward (오른쪽→왼쪽 방향)
+        Directionality.of(context) == TextDirection.rtl
+            ? Icons.arrow_forward
+            : Icons.arrow_back,
+      ),
+      const SizedBox(width: 8),
+      Text(title),
+    ],
+  ),
+);
+```
+
+### EdgeInsets → EdgeInsetsDirectional 변환
+
+```dart
+// ❌ 물리적 방향 (RTL에서 반전 안 됨)
+EdgeInsets.only(left: 16)
+EdgeInsets.fromLTRB(16, 8, 0, 8)
+EdgeInsets.symmetric(horizontal: 16)  // ✅ 대칭은 OK
+
+// ✅ 논리적 방향 (RTL에서 자동 반전)
+EdgeInsetsDirectional.only(start: 16)
+EdgeInsetsDirectional.fromSTEB(16, 8, 0, 8)  // Start, Top, End, Bottom
+EdgeInsetsDirectional.only(start: 16, end: 8)
+
+// Padding 위젯도 동일
+Padding(
+  padding: const EdgeInsetsDirectional.only(start: 16),
+  child: child,
+);
+```
+
+### Alignment → AlignmentDirectional 변환
+
+```dart
+// ❌ 물리적 정렬
+Alignment.centerLeft
+Alignment.topRight
+
+// ✅ 논리적 정렬
+AlignmentDirectional.centerStart  // LTR: left, RTL: right
+AlignmentDirectional.topEnd       // LTR: right, RTL: left
+
+// Container, Align, Positioned 등에 적용
+Container(
+  alignment: AlignmentDirectional.centerStart,
+  child: child,
+);
+
+Align(
+  alignment: AlignmentDirectional.topEnd,
+  child: badge,
+);
+```
+
+### Positioned → PositionedDirectional
+
+```dart
+// ❌ 물리적 위치 (RTL 미대응)
+Positioned(
+  left: 16,
+  top: 8,
+  child: badge,
+);
+
+// ✅ 논리적 위치 (RTL 자동 반전)
+PositionedDirectional(
+  start: 16,
+  top: 8,
+  child: badge,
+);
+```
+
+### 아이콘 미러링
+
+```dart
+/// 방향성을 가진 아이콘 (화살표, 체브론 등)은 RTL에서 미러링
+class DirectionalIcon extends StatelessWidget {
+  final IconData icon;
+  final double? size;
+  final Color? color;
+
+  const DirectionalIcon(this.icon, {super.key, this.size, this.color});
+
+  @override
+  Widget build(BuildContext context) {
+    final isRtl = Directionality.of(context) == TextDirection.rtl;
+
+    // 방향성 아이콘만 미러링 (체크마크, 플러스 등은 미러링 X)
+    if (isRtl) {
+      return Transform.flip(
+        flipX: true,
+        child: Icon(icon, size: size, color: color),
+      );
+    }
+
+    return Icon(icon, size: size, color: color);
+  }
+}
+
+// 사용 예
+DirectionalIcon(Icons.arrow_forward_ios, size: 16),  // RTL에서 자동 반전
+Icon(Icons.check, size: 16),                          // 방향 무관 → 미러링 불필요
+```
+
+### RTL 테스트
+
+```dart
+// 테스트에서 RTL 환경 시뮬레이션
+testWidgets('renders correctly in RTL', (tester) async {
+  await tester.pumpWidget(
+    Directionality(
+      textDirection: TextDirection.rtl,
+      child: MediaQuery(
+        data: const MediaQueryData(),
+        child: Material(
+          child: MyWidget(),
+        ),
+      ),
+    ),
+  );
+
+  // start padding이 RTL에서 오른쪽에 적용되는지 확인
+  final container = tester.widget<Container>(find.byType(Container));
+  // ...assertions
+});
+
+// 전체 앱을 RTL로 실행 (디버그 확인용)
+MaterialApp(
+  locale: const Locale('ar'),  // 아랍어 → RTL 자동 적용
+  // ...
+);
+```
+
+### Row/Column 방향
+
+```dart
+// Row는 TextDirection을 자동 반영
+// LTR: [icon] [text] [chevron →]
+// RTL: [← chevron] [text] [icon]
+Row(
+  children: [
+    const Icon(Icons.person),
+    Expanded(child: Text(context.l10n.profileLabel)),
+    const DirectionalIcon(Icons.chevron_right),
+  ],
+);
+// → Row 내부 순서 변경 불필요, Flutter가 자동 반전
+```
+
+### 규칙
+
+- `EdgeInsets` → `EdgeInsetsDirectional` 로 교체 (left/right → start/end)
+- `Alignment` → `AlignmentDirectional` 로 교체 (centerLeft → centerStart)
+- `Positioned` → `PositionedDirectional` 로 교체 (left → start)
+- 대칭 padding/margin (`symmetric`) → 그대로 사용 가능 (반전 불필요)
+- 방향성 아이콘 (화살표, 체브론) → RTL에서 `Transform.flip` 미러링
+- 방향 무관 아이콘 (체크, 플러스, 검색) → 미러링 금지
+- RTL 테스트 → `Directionality(textDirection: TextDirection.rtl)` 로 래핑
+- `Row`/`ListView` → TextDirection 자동 반영, 순서 변경 불필요

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

@@ -0,0 +1,81 @@
+---
+name: monitoring
+description: |
+  Flutter 모니터링 & 분석 가이드라인.
+  Firebase Crashlytics, Analytics, Performance Monitoring,
+  Sentry 통합, 구조화된 로깅.
+version: "1.0.0"
+tags: [flutter, crashlytics, analytics, performance, sentry, monitoring, logging]
+user-invocable: false
+---
+
+# Monitoring & Analytics
+
+Flutter 앱 모니터링 통합 가이드.
+Firebase Crashlytics + Analytics + Performance, Sentry, 구조화된 로깅으로
+프로덕션 품질을 수치로 관리.
+
+## Philosophy
+
+- 크래시는 0순위 — Crashlytics 비활성화 금지, 모든 비치명 에러도 기록
+- 이벤트는 설계 — 무분별한 로깅 금지, 이벤트 택소노미 먼저 정의
+- 성능은 측정 — 체감이 아닌 custom trace와 HTTP metric으로 수치화
+
+## Resources
+
+5개 규칙 + 1개 참조. 크래시부터 로깅까지 모니터링 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [crashlytics-setup](rules/crashlytics-setup.md) | Crashlytics 초기화, 에러 캡처, 사용자 식별 |
+| HIGH | rule | [analytics](rules/analytics.md) | Analytics 이벤트 택소노미, 사용자 속성, 화면 추적 |
+| HIGH | rule | [performance-monitoring](rules/performance-monitoring.md) | Performance custom trace, HTTP metric, 프레임 모니터링 |
+| MEDIUM | rule | [sentry-integration](rules/sentry-integration.md) | Sentry 초기화, breadcrumbs, scope, Crashlytics 공존 |
+| MEDIUM | rule | [logging](rules/logging.md) | 구조화된 로깅, 레벨 관리, 민감 데이터 마스킹 |
+| — | ref | [monitoring-architecture](references/monitoring-architecture.md) | 모니터링 레이어, 대시보드, 알림, 데이터 보존 |
+
+## Quick Rules
+
+### Crashlytics
+- `FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError`
+- `PlatformDispatcher.instance.onError` → 비동기 에러 캡처
+- 비치명 에러 → `recordError(error, stack, fatal: false)`
+- `setUserIdentifier` → 크래시와 사용자 매핑
+- `setCustomKey` → 디바이스 상태, 기능 플래그 등 컨텍스트
+
+### Analytics
+- 이벤트 택소노미 먼저 정의 (screen_view, button_click, feature_use)
+- `setUserProperty` → user_type, subscription_tier 등 세그먼트 기준
+- `AnalyticsObserver` → go_router 화면 전환 자동 추적
+- 디버그 → `adb shell setprop debug.firebase.analytics.app <package>`
+
+### Performance
+- `FirebasePerformance.instance.newTrace('name')` → custom trace
+- HTTP metric → 자동 수집 (dio interceptor 또는 http_client)
+- 느린 프레임 임계값 16ms (60fps), 8ms (120fps)
+
+### Sentry
+- `SentryFlutter.init` → DSN 환경별 분리 (dev/staging/prod)
+- `Sentry.addBreadcrumb` → 네비게이션, HTTP, 사용자 액션 추적
+- Crashlytics + Sentry 공존 → 각자 역할 분리 (crash vs context)
+
+### Logging
+- `logger` 패키지 → 레벨별 색상 출력 (개발), JSON 구조화 (프로덕션)
+- 릴리스 빌드 → verbose/debug 레벨 비활성화
+- 민감 데이터 (토큰, PII) → 마스킹 필수
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `FlutterError.onError` + `PlatformDispatcher.onError` 연동 |
+| CRITICAL | Crashlytics 디버그 모드 비활성화 (`setCrashlyticsCollectionEnabled`) |
+| CRITICAL | 릴리스 빌드에서 dSYM / ProGuard mapping 업로드 설정 |
+| HIGH | Analytics 이벤트 택소노미 문서화 후 구현 |
+| HIGH | `AnalyticsObserver` go_router 연동 |
+| HIGH | Performance custom trace 핵심 플로우에 적용 |
+| HIGH | HTTP metric 수집 (dio interceptor) |
+| MEDIUM | Sentry DSN 환경별 분리 |
+| MEDIUM | Sentry breadcrumb 네비게이션/HTTP 자동 기록 |
+| MEDIUM | 구조화된 로깅 + 릴리스 레벨 필터 |
+| MEDIUM | 민감 데이터 마스킹 검증 |