timsquad 2.1.0 → 3.4.0

package/templates/base/skills/mobile/flutter/ci-cd/rules/fastlane-setup.md

@@ -0,0 +1,105 @@
+---
+title: Fastlane Setup
+impact: HIGH
+impactDescription: "수동 배포 → 휴먼 에러, Fastlane 자동화 → 일관된 빌드/배포"
+tags: fastlane, match, supply, deliver, ios, android, automation
+---
+
+## Fastlane Setup
+
+**Impact: HIGH (수동 배포 → 휴먼 에러, Fastlane 자동화 → 일관된 빌드/배포)**
+
+Fastfile 구성, match (iOS 인증서), supply (Google Play), deliver (App Store), 환경 관리.
+
+### Fastfile 구성
+
+**Incorrect (빌드와 배포 혼합, 하드코딩):**
+```ruby
+lane :deploy do
+  build_app(scheme: "Runner")
+  upload_to_testflight(username: "me@email.com")
+  # → 인증서 관리 없음, 환경 분리 없음, 2FA 문제
+end
+```
+
+**Correct (레인 분리, API Key):**
+```ruby
+# ios/fastlane/Fastfile
+platform :ios do
+  lane :setup_signing do
+    create_keychain(name: "ci_keychain", password: ENV["KEYCHAIN_PASSWORD"],
+                    default_keychain: true, unlock: true, timeout: 3600)
+    match(type: "appstore", keychain_name: "ci_keychain",
+          keychain_password: ENV["KEYCHAIN_PASSWORD"], readonly: true)
+  end
+
+  lane :beta do
+    setup_signing
+    build_app(workspace: "Runner.xcworkspace", scheme: "Runner",
+              export_method: "app-store")
+    upload_to_testflight(
+      skip_waiting_for_build_processing: true,
+      api_key_path: "fastlane/api_key.json",
+    )
+  end
+end
+```
+
+```ruby
+# android/fastlane/Fastfile
+platform :android do
+  lane :beta do
+    sh("cd ../.. && flutter build appbundle --release")
+    supply(
+      track: "internal",
+      aab: "../build/app/outputs/bundle/release/app-release.aab",
+      json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"],
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+    )
+  end
+
+  lane :release do |options|
+    sh("cd ../.. && flutter build appbundle --release")
+    supply(
+      track: "production",
+      aab: "../build/app/outputs/bundle/release/app-release.aab",
+      json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"],
+      rollout: options[:rollout] || "0.1",
+    )
+  end
+end
+```
+
+### App Store Connect API Key
+
+```json
+// fastlane/api_key.json (CI 환경변수로 생성, .gitignore 필수)
+{
+  "key_id": "YOUR_KEY_ID",
+  "issuer_id": "YOUR_ISSUER_ID",
+  "key": "-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----",
+  "in_house": false
+}
+```
+
+### .env 관리
+
+```bash
+# ios/fastlane/.env.default (.gitignore 추가)
+APPLE_ID=ci@yourteam.com
+TEAM_ID=XXXXXXXXXX
+MATCH_GIT_URL=https://github.com/your-org/certificates
+
+# ios/fastlane/.env.production
+APP_IDENTIFIER=com.yourapp.id
+```
+
+### 규칙
+
+- `Fastfile` 레인 분리 — `setup_signing`, `beta`, `release` 독립
+- `match(readonly: true)` — CI에서 인증서 신규 생성 금지
+- App Store Connect API Key — 2FA 우회, CI 호환
+- `supply` 에 `json_key` — Google Play 서비스 계정 키
+- `.env` 로 환경 분리 — 하드코딩 금지, `.gitignore` 추가
+- 단계적 출시 — `supply(rollout: "0.1")` 소규모 배포 후 확대

package/templates/base/skills/mobile/flutter/ci-cd/rules/github-actions.md

@@ -0,0 +1,112 @@
+---
+title: GitHub Actions
+impact: HIGH
+impactDescription: "CI 없음 → 릴리스 품질 불안정, GitHub Actions → 코드 변경마다 자동 검증"
+tags: github-actions, ci, workflow, flutter-action, cache, artifact
+---
+
+## GitHub Actions
+
+**Impact: HIGH (CI 없음 → 릴리스 품질 불안정, GitHub Actions → 코드 변경마다 자동 검증)**
+
+Flutter 빌드 워크플로우, flutter-action, 테스트-빌드-업로드 파이프라인, 캐시.
+
+### 테스트 워크플로우
+
+**Incorrect (Flutter 수동 설치, 캐시 없음):**
+```yaml
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: git clone https://github.com/flutter/flutter.git
+      - run: flutter test  # 매번 전체 다운로드 → 느림
+```
+
+**Correct (flutter-action + 캐시):**
+```yaml
+# .github/workflows/test.yml
+name: Test & Analyze
+on:
+  pull_request:
+    branches: [main, develop]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.27.0"
+          cache: true
+      - uses: actions/cache@v4
+        with:
+          path: ${{ env.PUB_CACHE }}
+          key: pub-${{ runner.os }}-${{ hashFiles('**/pubspec.lock') }}
+      - run: flutter pub get
+      - run: flutter analyze --no-fatal-infos
+      - run: flutter test --coverage
+```
+
+### 릴리스 워크플로우 (iOS + Android)
+
+```yaml
+# .github/workflows/ios-release.yml — 태그 푸시 트리거
+name: iOS Release
+on: { push: { tags: ["v*"] } }
+jobs:
+  ios-build:
+    runs-on: macos-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with: { flutter-version: "3.27.0", cache: true }
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: "3.2", bundler-cache: true, working-directory: ios }
+      - run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          flutter build ipa --release --build-name=$VERSION --build-number=$GITHUB_RUN_NUMBER
+          cd ios && bundle exec fastlane beta
+        env:
+          MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
+          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
+```
+
+```yaml
+# .github/workflows/android-release.yml
+name: Android Release
+on: { push: { tags: ["v*"] } }
+jobs:
+  android-build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with: { distribution: "temurin", java-version: "17" }
+      - uses: subosito/flutter-action@v2
+        with: { flutter-version: "3.27.0", cache: true }
+      - run: echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/release.keystore
+      - run: flutter build appbundle --release --build-number=${{ github.run_number }}
+      - uses: r0adkll/upload-google-play@v1
+        with:
+          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT }}
+          packageName: com.yourapp.id
+          releaseFiles: build/app/outputs/bundle/release/app-release.aab
+          track: internal
+```
+
+### 규칙
+
+- `subosito/flutter-action@v2` — Flutter SDK 설치 + `cache: true`
+- pub 캐시 — `actions/cache@v4` + `pubspec.lock` 해시 키
+- `concurrency` — 동일 PR 중복 빌드 취소
+- `timeout-minutes` — 테스트 15분, iOS 45분, Android 30분
+- 태그 `v*` 트리거 — 릴리스 빌드, PR → 테스트만
+- 시크릿 — `${{ secrets.* }}` 로 주입, 하드코딩 금지

package/templates/base/skills/mobile/flutter/ci-cd/rules/store-deployment.md

@@ -0,0 +1,106 @@
+---
+title: Store Deployment
+impact: HIGH
+impactDescription: "배포 실수 → 심사 거절/사용자 불만, 체계적 배포 → 안정적 출시"
+tags: app-store, play-store, testflight, deployment, rollout, metadata
+---
+
+## Store Deployment
+
+**Impact: HIGH (배포 실수 → 심사 거절/사용자 불만, 체계적 배포 → 안정적 출시)**
+
+TestFlight 업로드, Play Store 트랙 관리, 메타데이터, 단계적 출시 전략.
+
+### TestFlight (iOS) 배포
+
+**Incorrect (Xcode에서 수동 업로드):**
+```
+Xcode > Archive > Distribute App → 수동 반복, 재현 불가
+```
+
+**Correct (Fastlane + API Key):**
+```ruby
+lane :beta do
+  api_key = app_store_connect_api_key(
+    key_id: ENV["ASC_KEY_ID"],
+    issuer_id: ENV["ASC_ISSUER_ID"],
+    key_filepath: ENV["ASC_KEY_PATH"],
+  )
+  build_app(workspace: "Runner.xcworkspace", scheme: "Runner",
+            export_method: "app-store")
+  upload_to_testflight(
+    api_key: api_key,
+    skip_waiting_for_build_processing: true,
+    groups: ["Internal Testers"],
+    changelog: ENV["RELEASE_NOTES"] || "Bug fixes and improvements",
+  )
+end
+```
+
+### Play Store 트랙 전략
+
+**Incorrect (바로 production):**
+```ruby
+supply(track: "production", aab: "app-release.aab")
+# → 테스트 없이 전체 배포 → 크래시 위험
+```
+
+**Correct (단계적 트랙 승격):**
+```ruby
+lane :internal do
+  supply(track: "internal", aab: "app-release.aab",
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+
+lane :promote_production do |options|
+  supply(track: "internal", track_promote_to: "production",
+         rollout: options[:rollout] || "0.01",
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+
+lane :increase_rollout do |options|
+  supply(track: "production", rollout: options[:rollout],
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+```
+
+### 단계적 출시 전략
+
+```
+Day 0:  internal (팀) → 크래시율/기능 확인
+Day 1:  closed testing → 소규모 외부 테스터
+Day 3:  production 1% → 크래시 모니터링
+Day 5:  production 5% → ANR 비율 확인
+Day 7:  production 20% → 사용자 피드백
+Day 10: production 50%
+Day 14: production 100%
+
+중단 기준: 크래시율 > 1%, ANR > 0.5%, 평점 급락
+```
+
+### 메타데이터 관리
+
+```
+fastlane/metadata/
+├── android/en-US/     # title.txt, short_description.txt, full_description.txt
+├── android/ko/
+├── ios/en-US/         # name.txt, subtitle.txt, description.txt, keywords.txt
+├── ios/ko/
+└── screenshots/en-US/ # iPhone6.5/, iPhone5.5/, iPad12.9/
+```
+
+```ruby
+lane :update_metadata do
+  deliver(skip_binary_upload: true, skip_screenshots: false,
+          overwrite_screenshots: true, api_key_path: "fastlane/api_key.json")
+end
+```
+
+### 규칙
+
+- TestFlight 자동 업로드 — `upload_to_testflight` + API Key, 수동 금지
+- Play Store 트랙 순서 — internal → closed → open → production
+- 단계적 출시 — 1%부터 시작, 크래시율 모니터링 후 확대
+- 메타데이터 코드 관리 — `fastlane/metadata/` 텍스트 파일
+- 릴리스 노트 — CHANGELOG에서 추출, 수동 작성 금지
+- 크래시율 1% 초과 → 즉시 rollout 중단

package/templates/base/skills/mobile/flutter/ci-cd/rules/versioning.md

@@ -0,0 +1,107 @@
+---
+title: Versioning
+impact: MEDIUM
+impactDescription: "버전 관리 부재 → 빌드 추적 불가, 체계적 버전 → 출시 이력 완전 추적"
+tags: versioning, semver, build-number, changelog, git-tag, pubspec
+---
+
+## Versioning
+
+**Impact: MEDIUM (버전 관리 부재 → 빌드 추적 불가, 체계적 버전 → 출시 이력 완전 추적)**
+
+pubspec.yaml 시맨틱 버저닝, 빌드 넘버 자동 증가, CHANGELOG 생성, git 태그 연동.
+
+### pubspec.yaml 버전 형식
+
+**Incorrect (빌드 넘버 누락):**
+```yaml
+version: 1.0.0  # → 스토어 업로드 시 구분 불가, 수동 관리 실수
+```
+
+**Correct (시맨틱 버전 + 빌드 넘버):**
+```yaml
+version: 1.2.3+45
+# major(1) — 호환 불가 변경
+# minor(2) — 새 기능 (하위 호환)
+# patch(3) — 버그 수정
+# build(45) — CI 빌드 넘버 (스토어 구분용, 항상 증가)
+```
+
+### 빌드 넘버 자동 증가
+
+```bash
+# 전략 1: CI 빌드 넘버 (권장)
+flutter build appbundle --build-number=${{ github.run_number }}  # GitHub Actions
+flutter build ipa --build-number=$PROJECT_BUILD_NUMBER           # Codemagic
+
+# 전략 2: 타임스탬프 (YYYYMMDDNN)
+BUILD_NUMBER=$(date +%Y%m%d)$(printf "%02d" $BUILD_COUNT)
+
+# 전략 3: Git 커밋 카운트
+BUILD_NUMBER=$(git rev-list --count HEAD)
+```
+
+### CI에서 버전 오버라이드
+
+```bash
+TAG=${GITHUB_REF#refs/tags/v}  # v1.2.3 → 1.2.3
+flutter build ipa --release \
+  --build-name=$TAG \
+  --build-number=${{ github.run_number }}
+```
+
+### 런타임 버전 접근
+
+```dart
+import 'package:package_info_plus/package_info_plus.dart';
+
+class AppVersion {
+  static Future<String> getFullVersion() async {
+    final info = await PackageInfo.fromPlatform();
+    return '${info.version}+${info.buildNumber}';  // "1.2.3+45"
+  }
+}
+```
+
+### CHANGELOG 자동 생성
+
+```yaml
+# .github/workflows/changelog.yml (태그 푸시 시)
+- uses: orhun/git-cliff-action@v3
+  with:
+    config: cliff.toml
+    args: --verbose
+  env:
+    OUTPUT: CHANGELOG.md
+- uses: softprops/action-gh-release@v2
+  with:
+    body_path: CHANGELOG.md
+```
+
+### Git 태그 전략
+
+```bash
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# 태그 규칙:
+# v1.2.3        → production
+# v1.2.3-rc1    → release candidate
+# v1.2.3-beta.1 → beta (TestFlight/Internal)
+```
+
+### 플랫폼별 주의
+
+```
+iOS:  CFBundleVersion = build-number, 동일 버전 재업로드 불가
+Android: versionCode = 정수, 감소 불가 (한번 올리면 되돌릴 수 없음)
+```
+
+### 규칙
+
+- `version: major.minor.patch+buildNumber` 형식 유지
+- 빌드 넘버는 CI에서 자동 증가 — 수동 관리 금지
+- `--build-name` + `--build-number` CI 오버라이드
+- git 태그 `v*` — 릴리스와 1:1 매핑
+- CHANGELOG 자동 생성 — conventional commits 기반
+- 빌드 넘버 절대 감소 불가 — 스토어 거부

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

@@ -0,0 +1,78 @@
+---
+name: i18n
+description: |
+  Flutter 국제화(i18n) 가이드라인.
+  flutter_localizations, intl, ARB 파일 관리,
+  RTL 레이아웃, 복수형/성별 처리, 런타임 로캘 전환.
+version: "1.0.0"
+tags: [flutter, i18n, l10n, localization, arb, intl, rtl]
+user-invocable: false
+---
+
+# Internationalization (i18n) & Localization
+
+Flutter 다국어 지원 통합 가이드.
+ARB 파일 기반 번역 관리, ICU MessageFormat, RTL 대응, 런타임 로캘 전환.
+
+## Philosophy
+
+- 텍스트는 코드에 없다 — 모든 사용자 노출 문자열은 ARB 파일에
+- 로캘은 상태 — Riverpod provider로 관리, SharedPreferences로 영속화
+- RTL은 기본 — Directionality 위젯 활용, 하드코딩된 padding/margin 금지
+- 번역은 프로세스 — 개발자 → 번역가 → 검수, CI에서 누락 키 자동 감지
+
+## Resources
+
+5개 규칙 + 1개 참조. i18n 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [localization-setup](rules/localization-setup.md) | flutter_localizations, intl, l10n.yaml, pubspec generate |
+| CRITICAL | rule | [arb-files](rules/arb-files.md) | ARB 파일 구조, @placeholder, 네이밍 컨벤션, gen-l10n |
+| HIGH | rule | [text-direction](rules/text-direction.md) | RTL 대응, EdgeInsetsDirectional, AlignmentDirectional |
+| HIGH | rule | [plural-gender](rules/plural-gender.md) | ICU MessageFormat, plural, select, ordinal |
+| MEDIUM | rule | [locale-switching](rules/locale-switching.md) | LocaleNotifier, SharedPreferences, 런타임 전환 |
+| — | ref | [i18n-architecture](references/i18n-architecture.md) | 디렉토리 구조, 번역 워크플로우, CI 검증 |
+
+## Quick Rules
+
+### 설정
+- `pubspec.yaml` 에 `generate: true` + `flutter_localizations`, `intl` 의존성
+- `l10n.yaml` 로 ARB 디렉토리, 출력 클래스, 기본 로캘 지정
+- `MaterialApp.localizationsDelegates` + `supportedLocales` 필수 설정
+
+### ARB 파일
+- `app_en.arb` 가 기본 (template ARB), `app_ko.arb` 등 로캘별 추가
+- 키 네이밍: `featureName_context` (예: `matchDetail_inviteButton`)
+- `@placeholder` 메타데이터로 동적 값 타입 명시
+- `flutter gen-l10n` 으로 자동 생성 (`AppLocalizations` 클래스)
+
+### RTL 대응
+- `EdgeInsetsDirectional.only(start: 16)` (left/right 대신 start/end)
+- `AlignmentDirectional.centerStart` (centerLeft 대신)
+- 아이콘 미러링: `Directionality` 감지 후 조건부 Transform
+
+### 복수형/성별
+- ICU `{count, plural, =0{no items} =1{1 item} other{{count} items}}`
+- `{gender, select, male{his} female{her} other{their}}`
+- ARB 파일에 직접 ICU 구문 작성, intl이 자동 파싱
+
+### 로캘 전환
+- `LocaleNotifier` (Riverpod StateNotifier) → 현재 로캘 관리
+- `SharedPreferences` 로 선택 로캘 영속화
+- 앱 재시작 없이 `MaterialApp.locale` 변경으로 즉시 반영
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `pubspec.yaml` 에 `generate: true` 설정 |
+| CRITICAL | `l10n.yaml` 생성 (arb-dir, template-arb-file, output-localization-file) |
+| CRITICAL | `MaterialApp.localizationsDelegates` 3종 등록 |
+| CRITICAL | 모든 사용자 노출 문자열이 ARB 파일에 존재 |
+| HIGH | `@placeholder` 메타데이터 완전성 (타입, 예시, 설명) |
+| HIGH | RTL 레이아웃에서 Directional 위젯 사용 |
+| HIGH | 복수형/성별 표현이 ICU MessageFormat 사용 |
+| MEDIUM | SharedPreferences 로캘 영속화 |
+| MEDIUM | CI에서 누락 키 자동 감지 |
+| MEDIUM | 번역 워크플로우 문서화 (개발자 → 번역가 → 검수) |