project-auto-wizard 0.12.2 → 0.13.0

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD.yaml

@@ -10,7 +10,7 @@
 # RELEASE_KEYSTORE_PASSWORD: keystore 비밀번호
 # RELEASE_KEY_ALIAS: key alias
 # RELEASE_KEY_PASSWORD: key 비밀번호
-# GOOGLE_SERVICES_JSON: Firebase google-services.json
+# GOOGLE_SERVICES_JSON (선택): Firebase google-services.json
 # GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64: Play Console 서비스 계정 (base64)
 # ANDROID_PACKAGE_NAME: 앱 패키지명 (Secret 우선, 없으면 Variable) — fastlane에 PACKAGE_NAME으로 전달
 
@@ -25,7 +25,7 @@ on:
       deploy_mode:
         description: "배포 모드 (store_only=internal까지 / store_prepare=production draft / store_submit=심사 자동등록)"
         required: false
-        default: "store_only"
+        default: "store_only"  # @wizard auto:android-deploy-mode
         type: choice
         options:
           - store_only
@@ -37,7 +37,9 @@ env:
   # 프로젝트 이름
   APP_ARTIFACT_NAME: "__APP_ARTIFACT_NAME__"  # @wizard ask:@repo
   # Flutter/Java 버전
-  FLUTTER_VERSION: "3.35.5"
+  # Flutter SDK 버전 — 비워 두면 stable 채널 최신을 쓴다(최신 flutter create 프로젝트의 SDK 제약과 맞음).
+  # 특정 버전에 고정하려면 "3.38.9"처럼 적는다. pubspec.yaml의 environment.sdk 범위를 만족해야 한다.
+  FLUTTER_VERSION: ""
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   PROJECT_TYPE: "flutter"
   # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등.
@@ -67,11 +69,34 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
+      # 서명·업로드 Secret이 없으면 빌드를 한참 진행한 뒤에야 실패하므로, 빠진 이름을 먼저 모두 알려 주고 멈춘다
+      # GOOGLE_SERVICES_JSON은 선택이라 점검하지 않는다
+      - name: 배포 사전 점검 (Secret)
+        env:
+          RELEASE_KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
+          GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64 }}
+          ANDROID_PACKAGE_NAME: ${{ secrets.ANDROID_PACKAGE_NAME || vars.ANDROID_PACKAGE_NAME }}
+        run: |
+          MISSING=""
+          for NAME in RELEASE_KEYSTORE_BASE64 RELEASE_KEYSTORE_PASSWORD RELEASE_KEY_ALIAS RELEASE_KEY_PASSWORD GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64; do
+            [ -n "${!NAME}" ] || MISSING="$MISSING $NAME"
+          done
+          # 패키지명은 Secret 대신 Variable로 등록해도 된다
+          [ -n "$ANDROID_PACKAGE_NAME" ] || MISSING="$MISSING ANDROID_PACKAGE_NAME(Secret 또는 Variable)"
+          if [ -n "$MISSING" ]; then
+            echo "::error title=필수 Secret 누락::등록되지 않은 GitHub Secret:$MISSING — Settings → Secrets and variables → Actions에서 등록하세요"
+            exit 1
+          fi
+          echo "✅ 사전 점검 통과: 필수 Secret이 모두 있습니다"
+
       - name: Pull latest changes
-        run: git pull origin main
+        run: git pull origin {{MAIN_BRANCH}}
 
       - name: Prepare env file
         env:
@@ -90,6 +115,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -199,11 +225,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
       - name: Pull latest changes
-        run: git pull origin main
+        run: git pull origin {{MAIN_BRANCH}}
 
       - name: Download project files
         uses: actions/download-artifact@v8
@@ -227,9 +253,27 @@ jobs:
           fi
 
       - name: Setup Release Keystore
+        env:
+          RELEASE_KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
         run: |
+          # 빈 Secret으로 빈 keystore를 만들면 어떤 키로 서명됐는지 알 수 없거나 뒤 단계에서 엉뚱한 오류로 끝난다
+          MISSING=""
+          for name in RELEASE_KEYSTORE_BASE64 RELEASE_KEYSTORE_PASSWORD RELEASE_KEY_ALIAS RELEASE_KEY_PASSWORD; do
+            [ -n "${!name}" ] || MISSING="$MISSING $name"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "::error::서명 Secret이 비어 있습니다:$MISSING (워크플로우 상단 주석 참고)"
+            exit 1
+          fi
           mkdir -p android/app/keystore
-          echo "${{ secrets.RELEASE_KEYSTORE_BASE64 }}" | base64 -d > android/app/keystore/key.jks
+          printf '%s' "$RELEASE_KEYSTORE_BASE64" | base64 -d > android/app/keystore/key.jks
+          if [ ! -s android/app/keystore/key.jks ]; then
+            echo "::error::RELEASE_KEYSTORE_BASE64를 디코딩한 keystore가 비어 있습니다"
+            exit 1
+          fi
           echo "✅ Release Keystore 생성 완료"
           ls -la android/app/keystore/
 
@@ -242,18 +286,24 @@ jobs:
           keyPassword=${{ secrets.RELEASE_KEY_PASSWORD }}
           EOF
           echo "✅ key.properties 생성 완료"
-          cat android/key.properties
 
-      - name: Create Google-services.json
+      # google-services.json 생성 (선택) — 비어 있으면 빈 파일을 만들지 않는다
+      - name: Create google-services.json
+        env:
+          GOOGLE_SERVICES_JSON: ${{ secrets.GOOGLE_SERVICES_JSON }}
         run: |
-          cat << 'EOF' > android/app/google-services.json
-          ${{ secrets.GOOGLE_SERVICES_JSON }}
-          EOF
-          echo "✅ Google-services.json 생성 완료"
+          if [ -n "$GOOGLE_SERVICES_JSON" ]; then
+            mkdir -p android/app
+            printf '%s' "$GOOGLE_SERVICES_JSON" > android/app/google-services.json
+            echo "✅ google-services.json created"
+          else
+            echo "ℹ️ GOOGLE_SERVICES_JSON secret not provided, skipping"
+          fi
 
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -534,13 +584,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
       - name: Setup Google Play Service Account
+        env:
+          SERVICE_ACCOUNT_BASE64: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64 }}
         run: |
+          if [ -z "$SERVICE_ACCOUNT_BASE64" ]; then
+            echo "::error::GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64 Secret이 비어 있습니다"
+            exit 1
+          fi
           mkdir -p ~/.config/gcloud
-          echo "${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64 }}" | base64 --decode > ~/.config/gcloud/service-account.json
+          printf '%s' "$SERVICE_ACCOUNT_BASE64" | base64 --decode > ~/.config/gcloud/service-account.json
           echo "✅ Service Account JSON 설정 완료"
 
       - name: Download AAB artifact

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-SELFHOSTED-CICD.yaml

@@ -6,10 +6,7 @@
 #
 # 필수 GitHub Secrets
 # ENV_FILE 또는 ENV: .env 파일 내용 (둘 중 하나, ENV_FILE 우선)
-# RELEASE_KEYSTORE_BASE64: 서명용 keystore (base64)
-# RELEASE_KEYSTORE_PASSWORD: keystore 비밀번호
-# RELEASE_KEY_ALIAS: key alias
-# RELEASE_KEY_PASSWORD: key 비밀번호
+# DEBUG_KEYSTORE (선택): 서명용 keystore (base64, 비밀번호 android · alias androiddebugkey) — 없으면 빌드마다 새 debug 키로 서명
 # GOOGLE_SERVICES_JSON (선택): Firebase google-services.json
 # SERVER_HOST: 서버 호스트(SMB 접속 주소)
 # SERVER_USER: SMB 사용자명
@@ -27,7 +24,9 @@ on:
 env:
   # 프로젝트 이름 (APK 파일명, 아티팩트명, 히스토리 파일명에 사용)
   APP_ARTIFACT_NAME: "__APP_ARTIFACT_NAME__"  # @wizard ask:@repo
-  FLUTTER_VERSION: "3.35.5"
+  # Flutter SDK 버전 — 비워 두면 stable 채널 최신을 쓴다(최신 flutter create 프로젝트의 SDK 제약과 맞음).
+  # 특정 버전에 고정하려면 "3.38.9"처럼 적는다. pubspec.yaml의 environment.sdk 범위를 만족해야 한다.
+  FLUTTER_VERSION: ""
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
   FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
@@ -53,19 +52,50 @@ jobs:
         with:
           fetch-depth: 0
 
+      # 업로드 Secret이 없으면 빌드를 다 마친 뒤 SMB 업로드에서야 실패하므로, 빠진 이름을 먼저 알려 주고 멈춘다
+      # 배포 job과 같은 조건 — 배포하지 않는 브랜치의 수동 실행은 빌드만 한다
+      # DEBUG_KEYSTORE·GOOGLE_SERVICES_JSON은 선택이라 점검하지 않는다
+      - name: 배포 사전 점검 (Secret)
+        if: github.ref == 'refs/heads/{{MAIN_BRANCH}}'
+        env:
+          SERVER_HOST: ${{ secrets.SERVER_HOST }}
+          SERVER_USER: ${{ secrets.SERVER_USER }}
+          SERVER_PASSWORD: ${{ secrets.SERVER_PASSWORD }}
+        run: |
+          MISSING=""
+          for NAME in SERVER_HOST SERVER_USER SERVER_PASSWORD; do
+            [ -n "${!NAME}" ] || MISSING="$MISSING $NAME"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "::error title=필수 Secret 누락::등록되지 않은 GitHub Secret:$MISSING — Settings → Secrets and variables → Actions에서 등록하세요"
+            exit 1
+          fi
+          echo "✅ 사전 점검 통과: 필수 Secret이 모두 있습니다"
+
       - name: List repository contents
         run: |
           echo "Repository checked out"
           ls -la
 
-      # Debug Keystore 설정 (디버깅 용도 유지)
+      # Debug Keystore 설정 — 이 워크플로우는 DEBUG_KEYSTORE(비밀번호 android, alias androiddebugkey)로 서명한다
       - name: Setup Debug Keystore
+        id: signing
+        env:
+          DEBUG_KEYSTORE: ${{ secrets.DEBUG_KEYSTORE }}
         run: |
+          # 내부 배포용이라 Secret이 없어도 빌드는 진행한다 — 러너가 새로 만든 debug 키로 서명되므로
+          # 빌드마다 서명이 달라져 기존 설치본 위에 업데이트할 수 없다는 점을 경고로 남긴다.
+          if [ -z "$DEBUG_KEYSTORE" ]; then
+            echo "::warning::DEBUG_KEYSTORE Secret이 비어 있어 러너 기본 debug 키로 서명합니다 (빌드마다 서명이 달라집니다)"
+            echo "mode=default" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # 값이 있는데 깨진 keystore는 조용히 넘기지 않고 여기서 실패한다
           mkdir -p ~/.android
-          echo "${{ secrets.DEBUG_KEYSTORE }}" | base64 -d > ~/.android/debug.keystore || echo "Base64 decoding failed"
-          echo "Debug Keystore created (for debugging)"
-          ls -la ~/.android/
-          keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android || echo "Keytool failed"
+          printf '%s' "$DEBUG_KEYSTORE" | base64 -d > ~/.android/debug.keystore
+          keytool -list -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
+          echo "mode=keystore" >> "$GITHUB_OUTPUT"
+          echo "Debug Keystore created (DEBUG_KEYSTORE로 서명)"
 
       # 환경변수 준비 — ENV_MODE=dotenv면 .env 파일, dart-define이면 프로젝트 밖 임시 파일(--dart-define-from-file)
       - name: Prepare env file
@@ -83,9 +113,11 @@ jobs:
           fi
 
       - name: Setup Keystore and key.properties
+        if: steps.signing.outputs.mode == 'keystore'
         run: |
           mkdir -p android/app/keystore
-          echo "${{ secrets.DEBUG_KEYSTORE }}" | base64 -d > android/app/keystore/key.jks || echo "Base64 decoding failed"
+          # 앞 단계에서 검증한 keystore를 그대로 쓴다
+          cp ~/.android/debug.keystore android/app/keystore/key.jks
           echo "Keystore created from DEBUG_KEYSTORE"
           ls -la android/app/keystore
           echo "storeFile=app/keystore/key.jks" > android/key.properties
@@ -95,20 +127,25 @@ jobs:
           echo "key.properties created"
           ls -la android/
 
-      - name: Create Google-services.json
+      # google-services.json 생성 (선택) — 비어 있으면 빈 파일을 만들지 않는다
+      - name: Create google-services.json
+        env:
+          GOOGLE_SERVICES_JSON: ${{ secrets.GOOGLE_SERVICES_JSON }}
         run: |
-          cat << 'EOF' > android/app/google-services.json
-          ${{ secrets.GOOGLE_SERVICES_JSON }}
-          EOF
-          echo "✅ Google-services.json 생성 완료"
-          ls -la android/app/
+          if [ -n "$GOOGLE_SERVICES_JSON" ]; then
+            mkdir -p android/app
+            printf '%s' "$GOOGLE_SERVICES_JSON" > android/app/google-services.json
+            echo "✅ google-services.json created"
+          else
+            echo "ℹ️ GOOGLE_SERVICES_JSON secret not provided, skipping"
+          fi
 
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
-          cache-key: flutter-${{ runner.os }}-${{ env.FLUTTER_VERSION }}
 
       - name: Verify Flutter version
         run: |
@@ -144,8 +181,13 @@ jobs:
       - name: Setup Gradle
         working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
-          chmod +x gradlew
-          echo "Gradle wrapper permissions set"
+          # flutter create 기본 .gitignore는 gradlew를 커밋하지 않는다 — 없으면 flutter build가 만든다
+          if [ -f gradlew ]; then
+            chmod +x gradlew
+            echo "Gradle wrapper permissions set"
+          else
+            echo "ℹ️ gradlew가 저장소에 없습니다 — flutter build가 생성합니다"
+          fi
 
       - name: Set up Java
         uses: actions/setup-java@v5

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml

@@ -20,20 +20,20 @@
 # 3. "Run workflow" 버튼 클릭
 # 4. 빌드 완료 후 아티팩트에서 APK 다운로드
 #
-# 필수 GitHub Secrets
+# GitHub Secrets (모두 선택 — 하나도 없어도 테스트 APK는 빌드됩니다)
 #
-# Release Keystore (Play Store 배포와 동일):
-# RELEASE_KEYSTORE_BASE64: 릴리즈 키스토어 파일 (base64)
-# RELEASE_KEYSTORE_PASSWORD: 키스토어 비밀번호
-# RELEASE_KEY_ALIAS: 키 별칭
-# RELEASE_KEY_PASSWORD: 키 비밀번호
+# Release Keystore (Play Store 배포와 동일, 없으면 경고 후 debug 키로 서명):
+# RELEASE_KEYSTORE_BASE64 (선택): 릴리즈 키스토어 파일 (base64)
+# RELEASE_KEYSTORE_PASSWORD (선택): 키스토어 비밀번호
+# RELEASE_KEY_ALIAS (선택): 키 별칭
+# RELEASE_KEY_PASSWORD (선택): 키 비밀번호
 #
 # 환경 설정 (선택):
 # ENV_FILE (선택): .env 파일 내용
 # GOOGLE_SERVICES_JSON (선택): google-services.json 내용 (Firebase 사용 시)
 #
 # Firebase App Distribution (선택):
-# FIREBASE_SERVICE_ACCOUNT_JSON_BASE64: Firebase 서비스 계정 JSON (base64)
+# FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 (선택): Firebase 서비스 계정 JSON (base64)
 #
 # ※ 위 Secrets는 저장소 Settings → Secrets and variables → Actions에 등록하세요.
 #    Firebase 업로드를 쓰려면 아래 env의 FIREBASE_APP_ID·FIREBASE_TESTER_GROUP도 수정합니다.
@@ -49,9 +49,17 @@ on:
   repository_dispatch:
     types: [build-android-app]
 
+# 레포 기본 권한이 read여도 빌드 진행 댓글을 달 수 있게 필요한 권한을 직접 선언한다
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
 # 프로젝트별 설정 (아래 값들을 수정하세요)
 env:
-  FLUTTER_VERSION: "3.35.5"
+  # Flutter SDK 버전 — 비워 두면 stable 채널 최신을 쓴다(최신 flutter create 프로젝트의 SDK 제약과 맞음).
+  # 특정 버전에 고정하려면 "3.38.9"처럼 적는다. pubspec.yaml의 environment.sdk 범위를 만족해야 한다.
+  FLUTTER_VERSION: ""
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
   FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
@@ -321,15 +329,39 @@ jobs:
           fi
 
       - name: Setup Release Keystore
+        id: signing
         env:
-          KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
         run: |
+          # 테스트 빌드는 설정 없이도 돌아야 한다 — Secret이 비면 keystore·key.properties를 만들지 않고
+          # 프로젝트 기본 서명(flutter create 기본값은 release도 debug 키)으로 빌드한다. 어떤 키인지는 로그에 남긴다.
+          MISSING=""
+          for name in RELEASE_KEYSTORE_BASE64 RELEASE_KEYSTORE_PASSWORD RELEASE_KEY_ALIAS RELEASE_KEY_PASSWORD; do
+            [ -n "${!name}" ] || MISSING="$MISSING $name"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "::warning::서명 Secret이 비어 있어 debug 키로 서명합니다:$MISSING (스토어 업로드용 키가 아닙니다)"
+            echo "mode=debug" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # 값이 있는데 깨진 keystore는 조용히 넘기지 않고 여기서 실패한다
           mkdir -p android/keystore
-          echo "$KEYSTORE_BASE64" | base64 -d > android/keystore/key.jks
-          echo "✅ Release Keystore 생성 완료"
+          printf '%s' "$RELEASE_KEYSTORE_BASE64" | base64 -d > android/keystore/key.jks
+          if [ ! -s android/keystore/key.jks ]; then
+            echo "::error::RELEASE_KEYSTORE_BASE64를 디코딩한 keystore가 비어 있습니다"
+            exit 1
+          fi
+          # 비밀번호·alias가 keystore와 맞지 않으면 여기서 멈춘다 (gradle 서명 단계의 긴 오류 대신)
+          keytool -list -keystore android/keystore/key.jks -storepass "$RELEASE_KEYSTORE_PASSWORD" -alias "$RELEASE_KEY_ALIAS" > /dev/null
+          echo "mode=release" >> "$GITHUB_OUTPUT"
+          echo "✅ Release Keystore 생성 완료 (release 키로 서명)"
           ls -la android/keystore/
 
       - name: Create key.properties
+        if: steps.signing.outputs.mode == 'release'
         env:
           STORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
           KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
@@ -360,6 +392,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -396,8 +429,13 @@ jobs:
       - name: Setup Gradle
         working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
-          chmod +x gradlew
-          echo "✅ Gradle wrapper permissions set"
+          # flutter create 기본 .gitignore는 gradlew를 커밋하지 않는다 — 없으면 flutter build가 만든다
+          if [ -f gradlew ]; then
+            chmod +x gradlew
+            echo "✅ Gradle wrapper permissions set"
+          else
+            echo "ℹ️ gradlew가 저장소에 없습니다 — flutter build가 생성합니다"
+          fi
 
       - name: Set up Java
         uses: actions/setup-java@v5

package/payload/workflows/flutter/PROJECT-FLUTTER-CI.yaml

@@ -2,12 +2,13 @@
 # Flutter CI (코드 분석 및 빌드 검증) 워크플로우
 #
 # 이 워크플로우는 PR 생성 또는 {{MAIN_BRANCH}} 브랜치 푸시 시
-# 코드 정적 분석(flutter analyze)과 Android/iOS 앱 빌드를 검증합니다.
+# 코드 정적 분석(flutter analyze), 테스트(flutter test)와 Android/iOS 앱 빌드를 검증합니다.
 #
 # 주요 특징:
 # - PR 생성/업데이트 시 자동 실행
 # - {{MAIN_BRANCH}} 브랜치 푸시 시 자동 실행
 # - flutter analyze로 코드 품질 검사
+# - test/ 폴더에 테스트(*_test.dart)가 있으면 flutter test 실행 (없으면 건너뜀)
 # - Android/iOS 빌드 개별 활성화/비활성화 가능
 # - Analyze Only 모드: 빌드 없이 코드 분석만 실행 가능
 # - PR인 경우 진행 상황을 댓글로 실시간 업데이트
@@ -22,10 +23,10 @@
 #
 # 프로젝트별 설정
 #
-# ANALYZE_ONLY    : true면 analyze만 실행, 빌드 스킵 (기본: false)
+# ANALYZE_ONLY    : true면 analyze·test만 실행, 빌드 스킵 (기본: false)
 # ENABLE_ANDROID  : Android 빌드 활성화 여부 (ANALYZE_ONLY=false일 때)
 # ENABLE_IOS      : iOS 빌드 활성화 여부 (ANALYZE_ONLY=false일 때)
-# FLUTTER_VERSION : Flutter SDK 버전
+# FLUTTER_VERSION : Flutter SDK 버전 (빈 값 = stable 최신)
 # JAVA_VERSION    : Java 버전 (Android 빌드용)
 # XCODE_VERSION   : Xcode 버전 (iOS 빌드용)
 # ENV_FILE_PATH   : dotenv 모드에서 .env를 만들 경로 (Flutter 루트 기준, 기본값: .env)
@@ -77,14 +78,16 @@ env:
   ENV_MODE: "dart-define"  # @wizard auto:flutter-env-mode
 
   # CI 모드 설정
-  ANALYZE_ONLY: "false"     # true: analyze만 실행 (빌드 스킵), false: analyze + 빌드
+  ANALYZE_ONLY: "false"     # true: analyze·test만 실행 (빌드 스킵), false: analyze·test + 빌드
 
   # 빌드 대상 플랫폼 설정 (ANALYZE_ONLY=false일 때만 적용)
   ENABLE_ANDROID: "true"    # Android 빌드 활성화 (true/false)
   ENABLE_IOS: "true"        # iOS 빌드 활성화 (true/false)
 
   # 프로젝트별 설정
-  FLUTTER_VERSION: "3.35.5"
+  # Flutter SDK 버전 — 비워 두면 stable 채널 최신을 쓴다(최신 flutter create 프로젝트의 SDK 제약과 맞음).
+  # 특정 버전에 고정하려면 "3.38.9"처럼 적는다. pubspec.yaml의 environment.sdk 범위를 만족해야 한다.
+  FLUTTER_VERSION: ""
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   XCODE_VERSION: "26.0"
   ENV_FILE_PATH: ".env"     # dotenv 모드에서 .env를 만들 경로 (Flutter 루트 기준, 커스터마이징 가능)
@@ -112,6 +115,10 @@ jobs:
         if: ${{ github.event_name != 'workflow_dispatch' }}
         uses: dorny/paths-filter@v4
         with:
+          # push는 이번 push로 들어온 커밋만 비교한다(직전 커밋 github.event.before 기준).
+          # 비워 두면 기본 브랜치와의 누적 diff로 판정해 skip이 사실상 동작하지 않는다.
+          # 새 브랜치 첫 push(before가 0으로만 채워짐)나 PR은 빈 값 → 기본 동작(기본 브랜치·PR base 비교).
+          base: ${{ github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000' && github.event.before || '' }}
           filters: |
             project:
               - '${{ env.PROJECT_PATH == '.' && '**' || format('{0}/**', env.PROJECT_PATH) }}'
@@ -212,6 +219,7 @@ jobs:
               '| 검사 항목 | 상태 | 소요 시간 |',
               '|----------|------|----------|',
               '| 🔍 Analyze | ⏳ 진행 중... | - |',
+              '| 🧪 Test | ⏳ 진행 중... | - |',
               `| 🤖 Android 빌드 | ${androidStatus} | - |`,
               `| 🍎 iOS 빌드 | ${iosStatus} | - |`,
               '',
@@ -257,6 +265,7 @@ jobs:
 
     outputs:
       status: ${{ steps.result.outputs.status }}
+      test_status: ${{ steps.result.outputs.test_status }}
       duration: ${{ steps.result.outputs.duration }}
 
     steps:
@@ -288,6 +297,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -304,6 +314,7 @@ jobs:
           restore-keys: ${{ runner.os }}-flutter-pub-
 
       - name: Install dependencies
+        id: deps
         run: |
           flutter pub get
           if grep -q "build_runner" pubspec.yaml; then
@@ -318,6 +329,22 @@ jobs:
           flutter analyze --no-fatal-infos
           echo "✅ 코드 분석 완료"
 
+      # analyze가 실패해도 테스트 결과는 따로 보여 준다. 실패하면 job이 실패해 CI Gate도 실패한다.
+      - name: Run Flutter Test
+        id: test
+        if: ${{ !cancelled() && steps.deps.outcome == 'success' }}
+        run: |
+          # test/에 *_test.dart가 없으면 flutter test 자체가 실패하므로 건너뛴다
+          if [ -d test ] && [ -n "$(find test -name '*_test.dart' -print -quit)" ]; then
+            echo "🧪 Flutter 테스트 시작..."
+            flutter test ${DART_DEFINE_FILE:+--dart-define-from-file="$DART_DEFINE_FILE"}
+            echo "ran=true" >> "$GITHUB_OUTPUT"
+            echo "✅ 테스트 통과"
+          else
+            echo "::notice title=Flutter 테스트 건너뜀::test/ 폴더에 *_test.dart 파일이 없어 flutter test를 실행하지 않았습니다"
+            echo "ran=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: 분석 결과 기록
         id: result
         if: always()
@@ -332,10 +359,16 @@ jobs:
             const duration = minutes > 0 ? `${minutes}분 ${seconds}초` : `${seconds}초`;
 
             const status = '${{ steps.analyze.outcome }}' === 'success' ? 'success' : 'failure';
+            // none: 테스트 파일 없음, skipped: 의존성 설치 실패로 실행 못 함
+            const testOutcome = '${{ steps.test.outcome }}';
+            const testStatus = testOutcome === 'success'
+              ? ('${{ steps.test.outputs.ran }}' === 'true' ? 'success' : 'none')
+              : (testOutcome === 'failure' ? 'failure' : 'skipped');
 
             core.setOutput('status', status);
+            core.setOutput('test_status', testStatus);
             core.setOutput('duration', duration);
-            console.log(`📋 코드 분석 결과: ${status} (${duration})`);
+            console.log(`📋 코드 분석 결과: ${status}, 테스트: ${testStatus} (${duration})`);
 
   # Job 3: Android 빌드 (조건부, 병렬)
   build-android:
@@ -383,6 +416,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -430,8 +464,13 @@ jobs:
       - name: Setup Gradle
         working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
-          chmod +x gradlew
-          echo "✅ Gradle wrapper permissions set"
+          # flutter create 기본 .gitignore는 gradlew를 커밋하지 않는다 — 없으면 flutter build가 만든다
+          if [ -f gradlew ]; then
+            chmod +x gradlew
+            echo "✅ Gradle wrapper permissions set"
+          else
+            echo "ℹ️ gradlew가 저장소에 없습니다 — flutter build가 생성합니다"
+          fi
 
       # APK 빌드 (CI는 빌드 검증 목적이므로 서명 불필요한 debug 빌드 사용)
       - name: Build APK
@@ -527,6 +566,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -558,9 +598,14 @@ jobs:
 
       - name: Install CocoaPods
         run: |
-          gem install cocoapods
-          cd ios && pod install --repo-update || pod install
-          echo "✅ CocoaPods installed"
+          # 플러그인이 없는 기본 프로젝트는 Podfile이 없다 — 플러그인이 생기면 flutter build가 Podfile을 만든다
+          if [ -f ios/Podfile ]; then
+            gem install cocoapods
+            (cd ios && (pod install --repo-update || pod install))
+            echo "✅ CocoaPods installed"
+          else
+            echo "ℹ️ ios/Podfile이 없어 pod install을 건너뜁니다 (CocoaPods 플러그인 없음)"
+          fi
 
       - name: Build iOS
         id: build
@@ -614,6 +659,7 @@ jobs:
             // 결과 수집
             const analyzeStatus = '${{ needs.analyze.outputs.status }}';
             const analyzeDuration = '${{ needs.analyze.outputs.duration }}' || '-';
+            const testStatus = '${{ needs.analyze.outputs.test_status }}';
             const androidStatus = '${{ needs.build-android.outputs.status }}';
             const androidDuration = '${{ needs.build-android.outputs.duration }}' || '-';
             const iosStatus = '${{ needs.build-ios.outputs.status }}';
@@ -638,6 +684,17 @@ jobs:
               overallSuccess = false;
             }
 
+            // Test 상태 (테스트 파일이 없으면 실패로 보지 않는다)
+            let testDisplay;
+            if (testStatus === 'success') {
+              testDisplay = '✅ 성공';
+            } else if (testStatus === 'none') {
+              testDisplay = '⏸️ 테스트 없음';
+            } else {
+              testDisplay = testStatus === 'failure' ? '❌ 실패' : '⏸️ 실행 안 됨';
+              overallSuccess = false;
+            }
+
             // Android 상태
             if (analyzeOnly) {
               androidDisplay = '⏸️ 스킵';
@@ -681,6 +738,7 @@ jobs:
               '| 검사 항목 | 상태 | 소요 시간 |',
               '|----------|------|----------|',
               `| 🔍 Analyze | ${analyzeDisplay} | ${analyzeDuration} |`,
+              `| 🧪 Test | ${testDisplay} | - |`,
               `| 🤖 Android 빌드 | ${androidDisplay} | ${analyzeOnly || !enableAndroid ? '-' : androidDuration} |`,
               `| 🍎 iOS 빌드 | ${iosDisplay} | ${analyzeOnly || !enableIos ? '-' : iosDuration} |`,
               '',
@@ -712,6 +770,12 @@ jobs:
                 bodyParts.push('');
               }
 
+              if (testStatus === 'failure') {
+                bodyParts.push('**Test 실패 시:**');
+                bodyParts.push('- `flutter test` 로컬에서 실행하여 실패한 테스트 확인');
+                bodyParts.push('');
+              }
+
               if (!analyzeOnly && enableAndroid && androidStatus !== 'success') {
                 bodyParts.push('**Android 빌드 실패 시:**');
                 bodyParts.push('- Gradle 빌드 로그에서 에러 확인');