# 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](https://fvm.app) 사용 권장) |
| 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 에 지정합니다.

```bash
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. 앱 빌드 · 실행

```bash
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. 테스트

```bash
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. 서버 배포

```bash
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 구독 | 스토어 결제 창 — 스토어 상품 등록 전에는 「스토어 상품 준비 중」으로 표시 |
| 공유(카드 이미지) | 시스템 공유 시트 |

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