fanuzu/app/README.md

FANUZU 앱 · 서버 소스

발주사 (주)팬케이크 / 수행사 스위치 주식회사(Sweech)

이 저장소는 FANUZU 모바일 앱(Flutter)과 서버(Firebase — Cloud Functions · Firestore 보안 규칙 · 인덱스 · Storage 규칙)의 전체 소스입니다.

폴더	내용
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. 이 브랜치 · 태그와 제출 빌드

브랜치 · 태그	커밋	대응 제출 빌드	산출물 SHA-256
project-1 · 태그 v0.1.1+14	0d2394c	1차 보완 빌드 0.1.1(14) — Android APK · iOS TestFlight 같은 소스	APK 7d2ebadc624666c7992ac92ac3aa5d2c5e7b4bd0c602efeabc194ec73c99eb52 · IPA d00870facdb27d38b458cdadc5723190b9fb18bfba06c64f578e0705a28627c8
태그 v0.2.0+10	be99511	2차 제출 빌드 0.2.0(10)	APK 856e15781d002aff066a02da0d53f9d8eeada9e1fc6b6fc139c0705c77342c2c(릴리스 「2차 제출 빌드 v0.2.0+10」 첨부)
project-2	4236d75	제출 빌드 없음 — 태그 v0.2.0+10 에 1차 보완(0.1.1+14) 내용을 합친 최신 코드	—

재빌드 확인. 태그를 체크아웃한 뒤 아래 3절 명령으로 빌드하면 같은 버전 · 빌드 번호의 APK 가 나옵니다. 서명 키가 달라 서명 블록은 다르므로, 비교는 unzip -l 로 본 파일 목록과 classes*.dex · lib/*/libapp.so 의 SHA-256 으로 합니다. 제출본과 같은 서명으로 다시 만들어야 하면 서명 키를 별도 보안 경로로 요청해 주십시오.

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

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

파일	받는 곳
android/app/google-services.json	Firebase 콘솔 → 프로젝트 fanuzu-dev-b020d → 프로젝트 설정 → Android 앱(kr.co.fanuzu.app)
ios/Runner/GoogleService-Info.plist	같은 화면의 iOS 앱
config/kakao.env	config/kakao.env.example 을 복사해 FANUZU_KAKAO_NATIVE_APP_KEY(카카오 네이티브 앱 키) · FANUZU_LINE_CHANNEL_ID(LINE Login 채널 ID)를 적습니다. 없으면 카카오 · LINE 로그인만 「설정 전」으로 막힙니다
firebase/functions/.env.<프로젝트>	서버 fnAuthKakao 의 KAKAO_APP_ID(카카오 앱 ID) · fnAuthLine 의 LINE_CHANNEL_ID 를 적습니다
android/key.properties · 업로드 서명 키	릴리스(서명) 빌드에만 필요합니다. 요청하시면 별도 보안 경로로 전달합니다. 디버그 빌드에는 필요 없습니다

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

4. 앱 빌드 · 실행

cd app
fvm flutter pub get
fvm flutter run --dart-define-from-file=config/kakao.env   # 연결된 실기기 · 에뮬레이터에서 실행
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_EMULATOR_HOST	로컬 Firebase 에뮬레이터 연결(개발용)	실서버에 연결합니다

5. 테스트

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 컴파일이 실패합니다).

6. 서버 배포

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 를 먼저 활성화해야 합니다.

7. 로그인 구성

1차 로그인은 Google · Apple · Kakao · LINE 4종입니다(별첨 B). 이메일 · 비밀번호 가입과 X 로그인은 없습니다.

제공자	앱 쪽	서버 쪽	Firebase 사용자 식별
Google	Google 로그인 SDK	Firebase Authentication	google.com
Apple	iOS 는 Apple 로그인 SDK, Android 는 Firebase 웹 흐름	Firebase Authentication	apple.com
Kakao	카카오 SDK 로그인	fnAuthKakao 가 카카오 토큰을 확인하고 Firebase 커스텀 토큰 발급	oidc.kakao 제공자 ID 로 기록
LINE	LINE SDK 로그인(앱 설치 시 LINE 앱, 없으면 웹 로그인)	fnAuthLine 이 LINE 토큰을 확인하고 Firebase 커스텀 토큰 발급	oidc.line 제공자 ID 로 기록

• Kakao · LINE 은 Firebase OIDC 웹 흐름이 아니라 각 SDK 와 서버 커스텀 토큰으로 로그인합니다. 제공자 ID oidc.kakao · oidc.line 은 이전 가입자의 UID 를 유지하려고 그대로 씁니다.
• Kakao · LINE 이메일은 선택 동의 항목입니다. 이메일이 없어도 제공자 고유 식별값으로 가입 · 로그인합니다.
• SNS 연결(MY › 설정) 은 서버가 현재 로그인과 새 제공자의 인증 자격을 확인해 붙입니다. 이메일이 같은지는 보지 않으며, 다른 FANUZU 계정에 이미 붙은 제공자는 거부합니다. 마지막 남은 제공자는 뗄 수 없습니다.

8. 폰트

pubspec.yaml 에 등록되어 앱에 들어가 있습니다.

패밀리	파일	쓰임
42dot Sans	assets/fonts/42dotSans[wght].ttf	본문(디자인 토큰 font-body)
ABeeZee	assets/fonts/ABeeZee-Regular.ttf	제목 · 수치(디자인 토큰 font-display · font-mono)
Pretendard(Black, 라틴 부분집합)	assets/fonts/Pretendard-Black-Latin.otf	홈 헤더 워드마크 · 이클립스 숫자

9. 테스트 계정 · 권한

• 로그인은 위 4종 가운데 각자의 계정으로 가입하시면 됩니다.
• 운영 기능(퀘스트 · 캠페인 검수, 타임어택 발동, 결과보고 등록 등)은 운영자 권한이 있는 계정만 호출할 수 있습니다. 권한을 드릴 Google 계정을 알려 주시면 운영자 권한을 부여합니다.

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

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

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