Instruction file imported from michaeldslim/gomoku-game (.cursor/rules/gomoku-ios-ipa-build-plan.mdc). Copyright stays with the author.

Gomoku iOS IPA Build Plan

Last reviewed: 2026-09-07.

프로젝트: Expo SDK 57 + React Native 0.86.3 (gomoku-game) · expo-audio
빌드 방식: Xcode 로컬 빌드 (EAS Apple ID 로그인 스킵)
현재 상태: ios/ 생성됨 · CocoaPods 설치됨 · Xcode 26.6 · Keychain 서명 인증서 없음 (Xcode에서 Team 설정 필요)
UI 개편: UI-0~2 완료 · UI-14(홈) 완료 — Career·아바타 미리보기 · QA(UI-15~16) 잔여

Notation: P0 = Phase 0, P1 = Phase 1, … P5 = Phase 5.
UI: UI-0 … UI-3 = UI 개편 단계 (IPA 전 권장).

Progress summary

Apple ID가 꼭 필요한가?

물리 iPhone에 설치 가능한 .ipa는 코드 서명이 필수이므로, 어떤 형태로든 Apple 계정이 필요합니다. 다만 유료 Developer Program($99)과 무료 Apple ID는 다릅니다.

서명 없는 .ipa는 iPhone에 설치 불가 (탈옥 기기 제외). Xcode만으로 우회할 수 없습니다.

추천: 목적별 최단 경로

① 본인 폰에서만 테스트 (IPA 파일 불필요, 가장 쉬움)

# iPhone USB 연결 후
npx expo run:ios --device

Xcode Settings → Accounts에 무료 Apple ID만 추가하면 됩니다.

② 본인 폰용 .ipa 파일이 필요

1. Xcode → Settings → Accounts → 무료 Apple ID 추가
2. iPhone USB 연결 (Xcode가 기기 등록)
3. open ios/Gomoku.xcworkspace → Signing Team 선택
4. Product → Archive → Distribute → Development → .ipa export

③ 다른 테스터에게 IPA 배포

유료 Apple Developer Program + Ad Hoc (테스터 UDID 등록) 필요.

왜 Xcode인가?

현재 프로젝트 스냅샷

Phase 0 (P0) — Mac 환경

• #1 Xcode — 26.6 설치됨 (/Applications/Xcode.app)
• #2 CocoaPods — brew install cocoapods (1.17.0)
• #3 Node.js · npm — npm install 완료
• #4 Apple Developer Program — 가입됨 (Team 설정은 P2에서)

Phase 1 (P1) — 네이티브 iOS 프로젝트 생성

• #5 app.json iOS 설정 — bundleIdentifier, buildNumber, ITSAppUsesNonExemptEncryption
• #6 prebuild 실행

cd /Users/mikelim/Github/gomoku-game
npx expo prebuild --platform ios --clean

• #7 CocoaPods — prebuild 중 pod install 완료

ios/는 .gitignore에 포함. 재생성 시 npx expo prebuild --platform ios --clean.

Phase 2 (P2) — Xcode Signing 설정 ← 현재

무료 Apple ID만으로 본인 기기 테스트 가능. 유료 Developer Program은 Ad Hoc·TestFlight 배포 시에만 필요.

Keychain에 서명 인증서가 없으면 (0 valid identities found) 아래 순서로 진행.

• #8 Apple ID를 Xcode에 추가 (무료 Apple ID로 충분 — 본인 폰 테스트 시)

  1. Xcode → Settings (⌘,) → Accounts 탭
  2. + → Apple ID → 로그인
  3. Team이 목록에 표시되는지 확인

• #9 프로젝트 Signing 설정

  1. 워크스페이스 열기:

open /Users/mikelim/Github/gomoku-game/ios/Gomoku.xcworkspace

2. 왼쪽 Gomoku 프로젝트 선택 → TARGETS → Gomoku
3. Signing & Capabilities 탭
4. Automatically manage signing ✅
5. Team → 본인 Apple Developer Team 선택
6. Bundle Identifier → com.mike008.gomokugame 확인
7. 에러 없이 녹색 체크가 뜨는지 확인

• #10 (Ad Hoc IPA 시) 테스트 기기 등록
  • developer.apple.com → Devices → iPhone UDID 등록
  • Ad Hoc 프로비저닝 프로파일에 해당 기기 포함 필요

Phase 3 (P3) — Archive → IPA export

• #11 빌드 대상 설정

  1. Xcode 상단 Scheme: Gomoku
  2. Destination: Any iOS Device (arm64) (시뮬레이터 선택 시 Archive 비활성화)

• #12 Archive

Product → Archive

• 첫 빌드는 수 분 소요

• 완료 시 Organizer 창 자동 열림

• #13 IPA Export

Organizer에서 방금 Archive 선택 → Distribute App:

Phase 4 (P4) — 배포 · 설치

• #14 TestFlight (권장) — Distribute → App Store Connect → App Store Connect에서 테스터 초대
• #15 Ad Hoc 설치 — Xcode Window → Devices and Simulators에서 기기에 드래그, 또는 Apple Configurator 2

Phase 5 (P5) — 트러블슈팅

UI 개편 로드맵 ← 설계 확정

상세 백로그: .cursor/rules/gomoku-improvement-plan.mdc Phase 5 (P5)
현재 gomoku 상태: 점수 0→100 마스터 런 · Expert 80 전환 · 2-segment progress bar · 태블릿 가로는 3-column HUD
태블릿 QA 기준: 갤럭시 탭(Android) 우선 · iPad는 부가 회귀

설계 결정 (확정 · 2026-09-07)

옵션 A 상세

• 점수 런(0→100): useScoreProgression 그대로 — AI 난이도·리더보드·Master 축하
• Career: 직급 ladder (인턴→CEO) — AI 승리 누적, 패배해도 진행 유지, 차장+ Expert pool 조건
• UI: 사이드 HUD careerBadge + 설정 careerModeEnabled 토글
• 연출 큐: 일반 승리 popup → Career 승진 / Master(100) → PromotionOverlay (밝은 톤 변형)

밝은 톤 가이드

• PromotionOverlay·PhoneLandscapeWarning — 밝은 gomoku 팔레트 (colors.ts)
• 승진 accent gold: #D4A853 (리더보드 버튼 border와 통일)
• LandscapeSideArt: 나무 보드 #C4A574 톤 + 흑백 돌 SVG (다크 wood gradient 사용 안 함)

아바타 에셋 계획 (assets/avatars/)

오목 전용 PNG 중 placeholder는 추후 교체 가능. 범용 10종만으로도 MVP 동작.

UI 구현 요약

Phase UI-0 — 공통 기반

• #UI-1 src/constants/colors.ts — 밝은 톤 디자인 토큰 (background, accent, gold, textPrimary …)
• #UI-2 src/constants/avatars.ts + assets/avatars/ — 14종 PNG (범용 10 + 오목 전용 4)
• #UI-3 PlayerAvatar.tsx · AvatarPicker.tsx
• #UI-4 UserSettings — playerAvatarId · aiAvatarId · careerModeEnabled (토글 UI는 UI-8)

Phase UI-1 — 승진 · 아바타 UX

• #UI-5 src/career/* — rules · storage · provider · AI tier mapping
• #UI-6 PromotionOverlay.tsx — 승진 연출 (밝은 골드 배너)
• #UI-7 CareerScreen.tsx — 직급 사다리 · 현황
• #UI-8 SettingsScreen — Career 토글 · 승진 현황 링크 · i18n (careerI18n.ts)

Phase UI-2 — 태블릿 가로 레이아웃

• #UI-9 useScreenLayout.ts — isTabletWideLayout · sidePanelWidth · orientation guide
• #UI-10 PhoneLandscapeWarning.tsx — App.tsx 루트에 마운트
• #UI-11 GameSideHud.tsx (gomoku용) — 아바타 · 턴 · 점수/Career · Undo/Restart/New
• #UI-12 LandscapeSideArt.tsx (gomoku용) — 흑/백 돌 SVG 장식 (react-native-svg)
• #UI-13 Game.tsx wide layout — 3-column [player HUD | board | opponent HUD]

Phase UI-3 — 홈 · QA (IPA 전)

• #UI-14 홈 화면 — HomePlayerPreview.tsx · Career badge · 아바타 미리보기
• #UI-15 갤럭시 탭 가로/세로 · iPhone 세로 회귀 · iPad 부가 확인
• #UI-16 Play Store용 갤럭시 탭 가로 스크린샷 · (선택) iPad/TestFlight 캡처

태블릿 QA 체크리스트 — 갤럭시 탭 우선 (Archive/APK 전)

권장 기기: Tab S9 / Tab A · 에뮬: Pixel Tablet 또는 10" API 34+ landscape

Android 재빌드 필수: orientation / AndroidManifest 변경 후 npx expo run:android (또는 release APK).

권장 실행 순서

1. ✅ P0  Xcode · CocoaPods 준비
2. ✅ P1  expo prebuild → ios/Gomoku.xcworkspace 생성
3. ▶  P2  Xcode Accounts + Signing & Capabilities   ← 빌드: 지금 여기
4.     UI-0…2  UI 개편 (아바타 → Career → 태블릿 가로)   ← UI: 병행 권장
5.     UI-3  갤럭시 탭 QA (+ iPhone 세로)
6.     P3  Product → Archive → Distribute App → .ipa
7.     P4  TestFlight 또는 Ad Hoc 설치

Tip: UI-2(태블릿 가로)까지 완료한 뒤 갤럭시 탭 실기 QA → Play Store 스크린샷. iPad IPA는 부가(Ad Hoc/TestFlight).

관련 파일

EAS Build (참고 — 현재 미사용)

EAS를 다시 쓰려면 Apple ID 대신 App Store Connect API Key (.p8)로도 가능:

EXPO_ASC_API_KEY_PATH="/path/to/AuthKey_XXX.p8" \
EXPO_ASC_KEY_ID="XXX" \
EXPO_ASC_ISSUER_ID="xxx-xxx-xxx" \
EXPO_APPLE_TEAM_ID="XXX" \
EXPO_APPLE_TEAM_TYPE="INDIVIDUAL" \
eas build --platform ios --profile production

현재는 Xcode 로컬 빌드가 더 단순한 경로.