README · 빌드 안내 — 앱·서버 소스 구성 · 빌드 · 테스트 · 배포

2026-10-04 01:43:10 +09:00
parent 4f6e1eac61
commit 613798b863
4 changed files with 377 additions and 352 deletions
@@ -6,7 +6,7 @@ Gradle 이 조용히 실패하지 않고 명확히 죽으므로 아래를 그대
 | 구성 | 값 | 비고 |
 |---|---|---|
 | Flutter | **3.47.2** | `fvm` 으로 고정 — `app/.fvmrc` |
-| JDK | **Temurin 17** | `fvm flutter config --jdk-dir` 로 지정 |
+| JDK | **Temurin 17** | `~/.jdks/jdk-17.0.20.1+1/Contents/Home` |
 | Gradle | 8.14 | `android/gradle/wrapper/gradle-wrapper.properties` |
 | AGP | 8.11.1 | `android/settings.gradle.kts` |
 | Android SDK | `/opt/homebrew/share/android-commandlinetools` | `brew install --cask android-commandlinetools` |
@@ -21,11 +21,11 @@ Android Studio 번들 JBR 은 **JDK 25** 이고 **Gradle 8.14 와 비호환**이
 JDK 17 을 쓰는 쪽을 택했다.

 ```bash
-fvm flutter config --jdk-dir <JDK 17 설치 경로>
+fvm flutter config --jdk-dir ~/.jdks/jdk-17.0.20.1+1/Contents/Home
 ```

 `brew install --cask temurin@17` 은 sudo 를 요구한다. sudo 없이 쓰려면 Adoptium
-tar.gz 를 사용자 폴더에 풀고 그 경로를 지정하면 된다.
+tar.gz 를 `~/.jdks/` 에 풀면 된다.

 ## 테스트

@@ -33,8 +33,22 @@ tar.gz 를 사용자 폴더에 풀고 그 경로를 지정하면 된다.
 export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
 fvm flutter analyze
 fvm flutter test
+fvm flutter build apk --debug        # 플러그인 네이티브 결합까지 본다
+npm --prefix firebase/functions run build
 ```

+**`pubspec.lock` 의 `firebase_core` 는 4.13.0 이어야 한다.** 4.14.0 이 올라오면 Android
+컴파일이 깨진다. `pub get` 이 올려 버렸는지 게이트에서 함께 본다.
+
+```bash
+grep -A 6 '^  firebase_core:' pubspec.lock | grep version   # → 4.13.0
+```
+
+**`analyze` 와 `test` 는 Android 네이티브 컴파일을 하지 않는다.** 의존성을 추가하거나
+올리면 Dart 쪽은 멀쩡한데 Gradle 이 죽는 조합이 생긴다(실례 — `firebase_core` 가
+4.14.0 으로 올라가 `firebase_auth` 6.5.7 의 `customAuthDomain` 에서 깨졌다).
+그래서 의존성을 건드린 회차는 **디버그 APK 빌드까지 게이트에 넣는다.**
+
 스모크 테스트가 `craft-allowlist.yaml` 의 `APP_TABS` 를 직접 읽어 앱의 `appTabs` 와 정확 일치를
 검증한다(5탭 계약 대조). 파일은 아래 순서로 찾는다.

@@ -43,7 +57,8 @@ fvm flutter test
 3. 저장소 루트 `design/craft-allowlist.yaml`.

 하나도 못 찾으면 통과가 아니라 실패한다 — 계약 대조가 조용히 사라지면 안 된다.
-루트 파일을 고칠 때는 `app/design/` 사본도 함께 맞춘다.
+루트 파일을 고칠 때는 `app/design/` 사본도 함께 맞춘다. 두 파일이 함께 보이면 스모크 테스트가
+`APP_TABS` 줄을 서로 비교해 다르면 실패한다.

 ## 빌드

@@ -72,12 +87,89 @@ apksigner verify --print-certs build/app/outputs/flutter-apk/app-release.apk
 # Signer #1 certificate SHA-256 digest: 5e83f4c9cd35357b11561a5b82c47d300af8c31e33d80d94bc32a4f10f46dee7
 ```

-## 알려진 어긋남 — minSdk
+## Firebase 앱 등록 — 식별자 `kr.co.fanuzu.app`

-문서(`2주차_플러그인_선검증리포트` · 별첨 1)는 **Android 10(API 29)** 을 하한으로 적었으나
-현재 빌드는 **API 24** 로 나간다. 하한을 29 로 올리는 것은 위치 퀘스트의
-`geofence_foreground_service` 인데 아직 넣지 않았다. **6주차 위치 퀘스트 구현 시점에
-29 로 올라간다.** 그때 기준 단말 2종 충족을 다시 확인해 빌드 노트에 적는다.
+프로젝트는 `fanuzu-dev-b020d`(계정 `dev@sweech.io`). 2026-09-11 별첨 C 4번 확정으로
+아래 두 앱을 새로 등록했다. 잠정 식별자(`kr.co.sweech.fancake`) 앱은 지우지 않고
+남겨 두었다 — 그 식별자로 이미 설치된 테스트 빌드가 있고, Gradle 은
+`google-services.json` 안에서 **패키지명으로 골라 쓰므로** 섞이지 않는다.
+
+| 플랫폼 | App ID |
+|---|---|
+| Android | `1:959364197461:android:6f1b79847ba8c3ed08b8dc` |
+| iOS | `1:959364197461:ios:716771ae8ece67ee08b8dc` |
+
+설정 파일은 `firebase/setup-project.sh` 가 제자리에 내려받는다(둘 다 `.gitignore` 대상).
+
+### SHA-1 지문은 firebase CLI 로 등록할 수 없다
+
+firebase-tools 15 에 지문 명령이 없다. Firebase Management REST 로 넣었고, 등록된 값은
+디버그 키스토어와 업로드 키스토어 둘이다.
+
+지문을 다시 뽑으려면(JDK 17 의 keytool):
+
+```bash
+keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android | grep SHA
+keytool -list -v -keystore ~/.fanuzu-signing/fanuzu-upload.p12 -alias fanuzu-upload -storetype PKCS12 | grep SHA
+```
+
+등록값 4건(디버그·릴리스 × SHA-1·SHA-256):
+
+```
+SHA-1   debug   85:2B:1B:A8:93:4D:CB:AF:D0:B6:D6:56:AF:98:99:5D:02:FF:07:C1
+SHA-1   release 58:27:8E:F0:80:B8:DA:6E:0E:E8:C1:70:F4:90:74:AD:5A:54:94:E8
+SHA-256 debug   28:F1:75:B8:…:88:46:5E:AF
+SHA-256 release 5E:83:F4:C9:…:0F:46:DE:E7
+```
+
+### 설정 파일은 저장소에 없다 — 다시 받는 명령
+
+`google-services.json` · `GoogleService-Info.plist` · `ios/config/Google.xcconfig` 셋 다
+`.gitignore` 대상이다. 새 작업 폴더에서는 아래를 돌린다.
+
+```bash
+firebase login:use dev@sweech.io
+firebase apps:sdkconfig ANDROID 1:959364197461:android:6f1b79847ba8c3ed08b8dc \
+  --project fanuzu-dev-b020d --out android/app/google-services.json
+firebase apps:sdkconfig IOS 1:959364197461:ios:716771ae8ece67ee08b8dc \
+  --project fanuzu-dev-b020d --out ios/Runner/GoogleService-Info.plist
+python3 tools/ios/inject_url_scheme.py      # → ios/config/Google.xcconfig
+```
+
+> `apps:sdkconfig` 는 대상 파일이 이미 있으면 거부한다. 갱신하려면 먼저 지운다.
+
+Authentication 제공자는 이메일/비밀번호와 Google 둘 다 켜져 있다(2026-09-11). Google 을
+켜야 `oauth_client` 와 `REVERSED_CLIENT_ID` 가 채워지며, 콘솔에서만 켤 수 있다.
+
+
+> **테스터 안내(식별자 전환 이후):** 새 빌드(`kr.co.fanuzu.app`)는 기존 설치본(`kr.co.sweech.fancake`)과 **별개의 앱으로 나란히 설치**됩니다. 기존 앱의 SharedPreferences · iOS 키체인 · 캐시된 소셜 자격 증명은 넘어오지 않으므로 다시 로그인해야 합니다. Firebase Authentication 계정은 프로젝트 단위라 그대로 살아 있어 같은 계정으로 들어갑니다. "로그아웃됐다" 는 오인 신고를 막기 위해 빌드 노트에도 같은 문장을 넣습니다.
+
+## minSdk 는 29 — 문서와 일치한다
+
+`android/app/build.gradle.kts` 의 `minSdk = 29` 다. 문서(`2주차_플러그인_선검증리포트` ·
+별첨 1)가 적은 **Android 10(API 29)** 과 같다. (이 절은 하한이 24 이던 때의 기록을
+지운 것이다 — 값이 이미 29 이므로 「올려야 한다」는 서술이 사실과 달랐다.)
+
+## 퀘스트 플러그인 3종 — 선검증리포트를 그대로 따른다
+
+| 플러그인 | 버전 | 쓰는 곳 | 하한 |
+|---|---|---|---|
+| `pedometer` | 4.2.0 | 만보기 퀘스트(S-H-WALK) 걸음 수 | Android 16 · iOS 10 |
+| `geolocator` | **13.x 고정** | 위치 퀘스트(S-H-PLACE) 좌표·mock location | iOS 11 |
+| `permission_handler` | **12.x 고정** | 활동 인식 권한 | Android 24 · iOS 12 |
+| `shared_preferences` | 2.5.x | 걸음 기준선을 하루 단위로 보관 | 하한 영향 없음 |
+
+**두 버전을 올리지 않는 이유는 선검증리포트에 있다.** `geolocator 14.x` 는 `win32 6.x` 를
+끌어와 `health 13.3.1` 과 공존하지 못하고(§2.2), `permission_handler 13.0.0` 은 Gradle
+빌드가 깨진다(§2.3). 올리려면 그 두 항목을 다시 재고 리포트를 고쳐야 한다.
+
+`geofence_foreground_service` 는 **넣지 않았다.** 지오펜스 판정은 서버가 하고
+(`fn-quest-verify-place`), 앱은 인증 시점의 좌표 한 점만 보낸다 — 상시 추적을 하지 않는다는
+v1.6.1 13장을 지키려면 상주 서비스가 필요 없다.
+
+권한은 `android/app/src/main/AndroidManifest.xml` 에 `ACTIVITY_RECOGNITION` ·
+`ACCESS_FINE_LOCATION` · `ACCESS_COARSE_LOCATION` 셋이다. **`ACCESS_BACKGROUND_LOCATION`
+은 요청하지 않는다.** iOS 사용 문구는 `Info.plist` 에 이미 들어 있다.

 ---

@@ -100,32 +192,8 @@ export DEVELOPER_DIR=~/Downloads/Xcode-beta.app/Contents/Developer
 fvm flutter build ios --release --no-codesign
 ```

-### 제출 빌드 — App Store Connect
-
-서명 팀은 **Fancake Inc. `V28G543VK5`** 다(`Runner.xcodeproj` 의 `DEVELOPMENT_TEAM`,
-`ios/ExportOptions.plist` 의 `teamID`). 번들 ID `kr.co.fanuzu.app`.
-
-| 항목 | 파일 | 없으면 |
-|---|---|---|
-| Sign in with Apple · 푸시 환경 | `ios/Runner/Runner.entitlements` | Apple 로그인이 동작하지 않고 심사에서 반려된다 |
-| 암호화 사용 신고 | `Info.plist` `ITSAppUsesNonExemptEncryption` | 업로드마다 수동 응답을 요구한다 |
-| Google 콜백 스킴 | `Info.plist` + `ios/config/Google.xcconfig` | Google 로그인 콜백이 돌아오지 않는다 |
-| Firebase 설정 | `ios/Runner/GoogleService-Info.plist` (번들 리소스) | 목 모드로 뜨고 Google 로그인 client ID 를 못 읽는다 |
-| 내보내기 설정 | `ios/ExportOptions.plist` | `-exportArchive` 가 대화형으로 묻는다 |
-
-`GoogleService-Info.plist` 와 `ios/config/Google.xcconfig` 는 저장소에 넣지 않는다.
-Xcode 프로젝트가 `GoogleService-Info.plist` 를 리소스로 참조하므로 **파일이 없으면 iOS 빌드가 멈춘다.**
-
-```bash
-# 1. Firebase 콘솔에서 받은 iOS 설정 파일을 둔다
-cp <받은 파일> ios/Runner/GoogleService-Info.plist
-# 2. Google 콜백 스킴을 뽑는다 → ios/config/Google.xcconfig
-python3 tool/ios/inject_url_scheme.py
-# 3. 아카이브 · IPA
-fvm flutter build ipa --release --export-options-plist=ios/ExportOptions.plist
-```
-
-배포 프로파일이 없으면 `xcodebuild` 로 나눠 `-allowProvisioningUpdates` 를 붙인다.
+**서명은 Apple Developer 계정이 있어야 한다.** 계정 없이 여기까지는 확인되므로,
+TestFlight 제출에 남은 것은 **서명과 업로드뿐**이다.

 ### 정리해야 할 것 — CocoaPods / SwiftPM 이중 상태

@@ -139,22 +207,64 @@ iOS 플러그인이 전부 Swift Package 로 옮겨졌는데 프로젝트에 Coc
 `Debug.xcconfig` · `Release.xcconfig` 의 Pods include 제거가 필요하다.
 **11주차 최적화 구간에서 정리한다.**

-## 서버 없이 로그인을 돌려 보기
+## 서버 없이 로그인·원장을 돌려 보기

-실 Firebase 프로젝트는 계정 명의가 확정되어야 열 수 있다.
+실 Firebase 프로젝트는 계정 명의가 확정되어야 열 수 있다(계정·권한 이전 별첨 A-3).
 그 전까지는 **에뮬레이터를 물려 실제 왕복을 돈다.** 설정 파일 대신 에뮬레이터를 붙이는
 것이라, 이 절차가 통과하면 설정 파일이 들어오는 날 코드 수정 없이 동작한다.

 ### 1. 에뮬레이터 기동

 ```
-cd app/firebase
-firebase emulators:start --only auth --project demo-fanuzu
+cd firebase
+npm install                       # 최초 1회
+npm --prefix functions run build  # Functions 를 JS 로 빌드
+firebase emulators:start --only auth,firestore,functions --project demo-fanuzu
+```
+
+프로필 사진 업로드를 함께 돌려 보려면 `storage` 를 더한다(`firebase.json` 에
+규칙과 포트 9199 가 들어 있다).
+
+```
+firebase emulators:start --only auth,firestore,functions,storage --project demo-fanuzu
 ```

 **JDK 21 이상이 필요하다.** firebase-tools 15 가 그 아래를 거부한다. Gradle 은 Temurin 17 을
 쓰므로 둘이 다르며, 에뮬레이터를 띄울 때만 `JAVA_HOME` 을 21+ 로 바꾼다.

+```bash
+export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
+```
+
+### 전역 `firebase` 가 조용히 죽으면 저장소 로컬 firebase-tools 를 쓴다
+
+**증상** — `firebase emulators:exec` 가 출력을 한 줄도 남기지 않고 종료 코드 137(SIGKILL)로
+끝난다. `firebase --version` 은 정상이고 `JAVA_HOME` 을 21 로 맞춰도 같다. 포트도 비어 있다.
+에뮬레이터가 안 뜨는 것처럼 보이지만 원인은 CLI 래퍼다.
+
+**원인과 대처** — 전역 Homebrew `firebase`(15.29.0)에서만 나며, 저장소 devDependency 인
+firebase-tools 로는 정상 기동한다. `firebase/test` 는 자기 `node_modules/.bin` 이 PATH 에
+올라 이미 로컬 바이너리를 쓰고, `firebase/functions` 는 firebase-tools 를 직접 의존하지
+않으므로 스크립트가 형제 경로를 가리킨다.
+
+```bash
+cd firebase/functions && npm ci        # 최초 1회
+cd firebase/test && npm ci             # firebase-tools 가 여기 들어 있다
+npm --prefix firebase/functions run test:emulator   # 로컬 바이너리로 돈다
+cd firebase/test && npm run test:emulator
+```
+
+직접 부를 때도 같다.
+
+```bash
+../test/node_modules/.bin/firebase emulators:exec \
+  --config ../firebase.json --only firestore --project demo-fanuzu "npm test"
+```
+
+> 비상 대안 — 그마저 막히면 에뮬레이터 JAR 를 직접 띄우고
+> `FIRESTORE_EMULATOR_HOST=127.0.0.1:8080` 을 실어 테스트를 돌린다(규칙 적재는 회귀 테스트가
+> REST 로 따로 한다): `"$JAVA_HOME/bin/java" -jar ~/.cache/firebase/emulators/cloud-firestore-emulator-v1.22.0.jar --host=127.0.0.1 --port=8080`
+
 ### 2. 앱을 에뮬레이터에 붙이기

 ```
@@ -164,6 +274,82 @@ flutter run --dart-define=FANUZU_EMULATOR_HOST=127.0.0.1  # iOS 시뮬레이터

 `10.0.2.2` 는 Android 에뮬레이터가 보는 호스트 PC 주소다.

+### 2-1. 에뮬레이터는 **저장소 안의 firebase-tools** 로 띄운다
+
+전역 Homebrew `firebase`(15.29.0)는 일부 환경에서 시작 배너만 찍고 **SIGKILL(exit 137)**
+로 죽는다(`emulators:*` · `deploy`. `--version` 과 `projects:list` 는 정상). 저장소의
+devDependency 를 쓰면 그대로 뜬다.
+
+```bash
+npm --prefix firebase/test ci          # 최초 1회 — firebase-tools 15.28.2
+cd firebase
+JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
+test/node_modules/.bin/firebase emulators:exec \
+  --only auth,firestore,functions --project fanuzu-dev-b020d "<명령>"
+```
+
+**프로젝트 ID 를 앱과 맞춘다.** `firebase.json` 이 `singleProjectMode: true` 라 다른 ID 의
+요청은 서지 않는다. 설정 파일이 들어간 Android 빌드는 네이티브가 만든 `[DEFAULT]` 앱을
+그대로 쓰므로 **실 프로젝트 ID(`fanuzu-dev-b020d`)** 로 붙는다. 에뮬레이터도 같은 ID 로
+띄워야 앱이 넣은 값과 시드가 같은 칸에 들어간다.
+
+**시드는 `Authorization: Bearer owner` 로 넣는다.** 없으면 보안 규칙이 그대로 걸려
+`quests` 쓰기가 마스터 전용으로 막히고, 시드가 조용히 사라진다.
+
+### 2-2. Firestore 만 필요할 때 — CLI 없이
+
+서버 단위 검증만 할 때는 받아 둔 jar 를 직접 띄워도 된다.
+
+```bash
+java -Djava.net.preferIPv4Stack=true \
+  -jar ~/.cache/firebase/emulators/cloud-firestore-emulator-v1.22.0.jar \
+  --host=0.0.0.0 --port=8080 &
+CI=1 FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 GCLOUD_PROJECT=demo-fanuzu \
+  npm --prefix firebase/functions test
+```
+
+`CI=1` 이 필요하다. 없으면 vitest 가 대화형 모드로 남아 명령이 끝나지 않는다.
+**`-Djava.net.preferIPv4Stack=true` 를 빼지 마라.** 없으면 JVM 이 8080 을 IPv6 로만 열고,
+Android 에뮬레이터가 `10.0.2.2` 로 거는 연결이 **ECONNREFUSED** 로 떨어진다. 앱에서는
+`[cloud_firestore/unavailable] client is offline` 으로만 보여 원인이 네트워크 설정처럼 읽힌다.
+
+### 2-3. 앱을 붙여 한 바퀴 — 로그인 → 출석 → 원장 → 화면
+
+Callable 까지 도는 확인이다. 기기 포트를 호스트로 넘기고 한 명령으로 돌린다.
+
+```bash
+for p in 8080 9099 5001; do adb reverse tcp:$p tcp:$p; done
+cd firebase
+JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
+test/node_modules/.bin/firebase emulators:exec \
+  --only auth,firestore,functions --project fanuzu-dev-b020d \
+  "bash ../tool/emulator_quest_roundtrip.sh"
+```
+
+스크립트가 퀘스트 정의·운영값을 넣고 `integration_test/quest_callable_emulator_test.dart`
+를 돌린다. 확인하는 것은 **가입 → `fn-auth-oncreate` 계정·지갑 생성 → 출석 참여 →
+`fn-quest-attend` → 원장 1행 → 보유 POP → 목록 재조회 「보상완료」 → 2회차 E-POP-03 거부**다.
+
+### 2-4. 서버가 쓴 값을 앱이 읽는지만 볼 때
+
+```bash
+CI=1 FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 GCLOUD_PROJECT=demo-fanuzu \
+  npm --prefix firebase/functions test          # 서버가 상태를 만든다
+fvm flutter test integration_test/pop_loop_emulator_test.dart \
+  -d <device> --dart-define=FANUZU_EMULATOR_HOST=10.0.2.2
+```
+
+### 3. 자동 검증
+
+```
+flutter drive --driver=test_driver/perf_driver.dart \
+  --target=integration_test/auth_emulator_test.dart \
+  --dart-define=FANUZU_EMULATOR_HOST=10.0.2.2 --profile --no-dds -d <device>
+```
+
+가입 → 로그인 → 재로그인 → Auth 트리거의 계정·지갑 문서 생성 → 클라이언트 지갑 쓰기
+차단까지 6건을 확인한다.
+
 ### 평문 HTTP 예외에 대하여

 에뮬레이터는 평문 HTTP 로 뜨는데 Android 9 부터 평문이 기본 차단이다. 예외를
@@ -174,3 +360,45 @@ flutter run --dart-define=FANUZU_EMULATOR_HOST=127.0.0.1  # iOS 시뮬레이터
 unzip -p build/app/outputs/flutter-apk/app-release.apk AndroidManifest.xml \
  | strings | grep -c networkSecurityConfig    # 0 이어야 한다
 ```
+
+## iOS 스토어 제출 준비 — 계정 전에 할 수 있는 것을 다 해 두었다
+
+Apple Developer 계정은 발주사 명의 회신 대상이라(계정 이전 별첨 A-1) 서명과
+업로드는 그날부터다. **그 외의 것을 미리 두지 않으면 계정이 열린 날 하루를
+설정에 쓴다.** 아래는 이미 들어가 있다.
+
+| 항목 | 파일 | 없으면 어떻게 되는가 |
+|---|---|---|
+| Sign in with Apple Capability | `ios/Runner/Runner.entitlements` | Apple 로그인 코드가 있어도 동작하지 않고 심사에서 반려된다 |
+| 푸시 환경 선언 | 같은 파일 `aps-environment` | FCM 토큰이 발급되지 않는다 |
+| 암호화 사용 신고 | `Info.plist` `ITSAppUsesNonExemptEncryption` | 업로드마다 수동 응답을 요구하고 그동안 배포가 멈춘다 |
+| 권한 사용 문구 6종 | `Info.plist` `NS*UsageDescription` | **권한을 요청하는 순간 앱이 종료된다.** 크래시로 보이지만 원인은 이 파일이다 |
+| Google 콜백 스킴 | `Info.plist` + `ios/config/Google.xcconfig` | Google 로그인 콜백이 조용히 돌아오지 않는다 |
+| 내보내기 설정 | `ios/ExportOptions.plist` | `xcodebuild -exportArchive` 가 대화형으로 물어 자동 배포가 불가능하다 |
+| 업로드 절차 | `tools/ios/upload_testflight.sh` | 계정이 열린 날 명령을 처음부터 찾게 된다 |
+
+### 업로드 절차
+
+서명 팀은 발주사 Fancake Inc.(`V28G543VK5`)다. `ios/Runner.xcodeproj` 의 `DEVELOPMENT_TEAM`
+과 `ios/ExportOptions.plist` 의 `teamID` 가 모두 이 값이어야 하고, `store_readiness_test`
+가 지킨다. 다른 팀으로 서명하면 업로드가 그 팀의 App Store Connect 로 가 버린다.
+
+```
+# 1. Firebase 설정 파일(ios/Runner/GoogleService-Info.plist)을 둔다 — 없으면 빌드가 멈춘다
+# 2. Google 콜백 스킴을 뽑는다
+python3 tools/ios/inject_url_scheme.py
+
+# 3. 올린다 (Xcode 정식판 필요 — 베타 SDK 빌드는 App Store Connect 가 거부한다)
+export ASC_KEY_ID=... ASC_ISSUER_ID=... ASC_KEY_PATH=...
+bash tools/ios/upload_testflight.sh
+```
+
+API 키가 없으면 Xcode 에 로그인된 계정으로 올린다:
+`xcodebuild -exportArchive -archivePath build/ios/archive/Runner.xcarchive -exportOptionsPlist ios/ExportOptions.plist -exportPath build/ios/ipa -allowProvisioningUpdates`
+(`ExportOptions.plist` 에 `destination` = `upload` 를 임시로 넣거나 생성된 IPA 를 Transporter 로 올린다.)
+
+### 화면 회전을 막지 않은 이유
+
+별첨 1 ① 예외 처리가 「백그라운드 복귀·**화면 회전** 시 렌더링 정상 재개」를
+요구한다. Figma 는 세로 프레임만 있으나 계약 문서가 회전을 판정 항목으로
+두었으므로 가로를 닫지 않는다.