폴더	내용
`lib/`	앱 소스 (화면 · 데이터 저장소 · 다국어)
`lib/l10n/`	다국어 리소스 5종(ko · en · ja · zh · es)
`test/` · `integration_test/`	앱 테스트
`firebase/functions/`	Cloud Functions (TypeScript, Node.js 22) · 서버 테스트 `firebase/functions/test/`
`firebase/firestore.rules` · `firebase/storage.rules` · `firebase/firestore.indexes.json`	보안 규칙 · 인덱스
`firebase/test/`	보안 규칙 테스트
`android/` · `ios/`	플랫폼 설정

1. 개발 환경

항목	버전
Flutter	3.47.2 (`.fvmrc` 로 고정 — fvm 사용 권장)
Dart	3.11.5 이상
JDK (Android 빌드)	17 (Temurin 17 권장. Android Studio 번들 JDK 25 는 현재 Gradle 8.14 와 호환되지 않아 빌드가 실패합니다)
JDK (Firebase 에뮬레이터)	21 이상 (firebase-tools 요구)
Android	minSdk 29 (Android 10) · Android SDK build-tools 35
iOS	15.0 이상 · Xcode 26
Node.js	22 (Cloud Functions 런타임과 동일)
Firebase CLI	최신 (`npm i -g firebase-tools`)

fvm 을 쓰지 않는 경우 아래 명령의 fvm flutter 를 flutter 로 바꾸고, Flutter 3.47.2 를 직접 설치해 주십시오.

JDK 17 을 Flutter 에 지정합니다.

fvm flutter config --jdk-dir <JDK 17 경로>

2. 저장소에 포함하지 않은 파일

아래 파일은 보안상 저장소에 넣지 않았습니다. 빌드 전에 준비해 주십시오.

파일	받는 곳
`android/app/google-services.json`	Firebase 콘솔 → 프로젝트 `fanuzu-dev-b020d` → 프로젝트 설정 → Android 앱(`kr.co.fanuzu.app`)
`ios/Runner/GoogleService-Info.plist`	같은 화면의 iOS 앱
`android/key.properties` · 업로드 서명 키	릴리스(서명) 빌드에만 필요합니다. 요청하시면 별도 보안 경로로 전달합니다. 디버그 빌드에는 필요 없습니다

설정 파일이 없으면 앱은 표본 데이터로 동작하는 목(mock) 모드로 뜹니다(디버그 빌드에서만 진입 가능).

3. 앱 빌드 · 실행

cd app
fvm flutter pub get
fvm flutter run                        # 연결된 실기기 · 에뮬레이터에서 실행
fvm flutter build apk --debug          # 디버그 APK → build/app/outputs/flutter-apk/app-debug.apk
fvm flutter build apk --release        # 서명 릴리스 APK (key.properties 필요)
fvm flutter build ios --no-codesign    # iOS 빌드 확인

선택 빌드 설정(--dart-define):

키	용도	없을 때
`FANUZU_SHARE_BASE_URL`	공유 링크 주소(웹 브릿지)	공유 시 링크 없이 카드 · 문구만 보냅니다
`FANUZU_APPLE_SERVICE_ID` · `FANUZU_APPLE_REDIRECT_URI`	Android 에서 Apple 로그인	Android 의 Apple 로그인 버튼이 비활성입니다
`FANUZU_EMULATOR_HOST`	로컬 Firebase 에뮬레이터 연결(개발용)	실서버에 연결합니다

4. 테스트

cd app
fvm flutter analyze                    # 정적 분석 — 0건이어야 합니다
fvm flutter test                       # 앱 테스트

cd firebase/test
npm ci                                 # 에뮬레이터용 Firebase CLI 포함 — 서버 테스트도 이것을 씁니다
npm run test:emulator                  # 보안 규칙 테스트 (JDK 21 필요)

cd ../functions
npm ci
npm run typecheck                      # 서버 타입 검사
npm run test:emulator                  # 서버 테스트 (Firestore 에뮬레이터 · JDK 21 필요)

의존성을 바꾼 경우 analyze · test 만으로는 Android 네이티브 컴파일 오류를 잡지 못하므로 fvm flutter build apk --debug 까지 확인해 주십시오. pubspec.lock 의 firebase_core 는 4.13.0 이어야 합니다(4.14.0 에서 Android 컴파일이 실패합니다).

5. 서버 배포

cd app/firebase
npm --prefix functions ci
npm --prefix functions run build
firebase deploy --only firestore,storage,functions --project fanuzu-dev-b020d

Storage 규칙 배포는 Firebase 콘솔에서 Storage 를 먼저 활성화해야 합니다.

6. 테스트 계정 · 권한

릴리스 빌드의 로그인은 Google 계정으로 합니다. 각자의 Google 계정으로 가입하시면 됩니다. Apple 은 iOS(TestFlight) 준비 후, Kakao · LINE 은 제공자 앱 키 수령 후 연결합니다.
운영 기능(퀘스트 · 캠페인 검수, 타임어택 발동, 결과보고 등록 등)은 운영자 권한이 있는 계정만 호출할 수 있습니다. 권한을 드릴 Google 계정을 알려 주시면 운영자 권한을 부여합니다.

7. 실기기에서만 확인 가능한 기능

기능	이유
만보기 퀘스트	걸음 수 센서 · 건강 데이터 권한
위치 퀘스트	GPS 반경 인증
이클립스 방어 · Music Shake	흔들기(가속도 센서)
푸시 알림(이클립스 사전 알림 · 타임어택 · 브리핑)	FCM 수신
보상형 광고	Google 테스트 광고 단위로 동작
인앱 결제 · Focus 구독	스토어 결제 창 — 스토어 상품 등록 전에는 「스토어 상품 준비 중」으로 표시
공유(카드 이미지)	시스템 공유 시트

에뮬레이터에서는 위 기능의 화면은 뜨지만 센서 · 결제 · 푸시가 동작하지 않습니다.