zellyy-finance/docs/ios-signing-setup.md

# iOS 코드 서명 설정 가이드

## 1. Apple Developer 계정 설정

### 필수 준비사항
- Apple Developer Program 계정 (연간 $99)
- Xcode 15.0 이상
- macOS 빌드 환경

### App Store Connect 설정
1. [App Store Connect](https://appstoreconnect.apple.com) 로그인
2. "My Apps" > "+" > "New App" 클릭
3. 앱 정보 입력:
   - Platform: iOS
   - Name: Zellyy Finance
   - Primary Language: Korean
   - Bundle ID: com.zellyy.finance
   - SKU: zellyy-finance-ios

## 2. 인증서 및 프로비저닝 프로파일 생성

### Developer 계정에서 생성 (수동)
1. [Apple Developer Portal](https://developer.apple.com/account) 접속
2. Certificates, Identifiers & Profiles 섹션으로 이동

#### 인증서 생성
```bash
# 1. CSR(Certificate Signing Request) 생성
# 키체인 접근 > 인증서 지원 > 인증 기관에서 인증서 요청

# 2. Apple Developer Portal에서 인증서 생성
# - iOS Distribution (App Store and Ad Hoc)
# - CSR 파일 업로드
# - 생성된 인증서(.cer) 다운로드 및 키체인에 설치
```

#### App ID 생성/확인
```
- Identifier: com.zellyy.finance
- Description: Zellyy Finance
- Capabilities: 필요한 기능들 활성화 (Push Notifications 등)
```

#### 프로비저닝 프로파일 생성
```
- Type: App Store
- App ID: com.zellyy.finance
- Certificate: 위에서 생성한 Distribution 인증서
- Profile Name: Zellyy Finance App Store
```

### API 키를 통한 자동화 (권장)
```bash
# App Store Connect API 키 생성
# App Store Connect > 사용자 및 액세스 > 키 > API 키 > "+" 클릭
# - 이름: Zellyy Finance CI/CD
# - 액세스: App Manager 또는 Developer
# - 키 다운로드 (.p8 파일)
```

## 3. Xcode 프로젝트 설정

### Team 및 Bundle Identifier 설정
```bash
# ios/App/App.xcodeproj 열기
# 프로젝트 설정 > Signing & Capabilities
# - Team: Apple Developer 팀 선택
# - Bundle Identifier: com.zellyy.finance
# - Signing Certificate: iOS Distribution
```

### 빌드 설정 확인
```bash
# ios/App/App/Info.plist 확인
CFBundleIdentifier: com.zellyy.finance
CFBundleDisplayName: Zellyy Finance
CFBundleShortVersionString: 1.0.0
CFBundleVersion: 10000
```

## 4. GitHub Actions용 인증서 내보내기

### 인증서를 P12로 내보내기
```bash
# 키체인 접근에서:
# 1. iOS Distribution 인증서 선택
# 2. 개인키와 함께 내보내기 선택
# 3. .p12 파일로 저장
# 4. 내보내기 비밀번호 설정
```

### Base64로 인코딩
```bash
# P12 파일을 base64로 인코딩
base64 -i ios-distribution.p12 | pbcopy
# 결과를 IOS_CERTIFICATES_P12_BASE64 시크릿에 저장
```

### 프로비저닝 프로파일 내보내기
```bash
# ~/Library/MobileDevice/Provisioning Profiles/ 에서 찾거나
# Apple Developer Portal에서 다운로드
base64 -i ZellyyFinance_AppStore.mobileprovision | pbcopy
```

## 5. GitHub Secrets 설정

### iOS 관련 시크릿들
- `IOS_CERTIFICATES_P12_BASE64`: P12 인증서 파일의 base64 인코딩
- `IOS_CERTIFICATES_P12_PASSWORD`: P12 파일 내보내기 시 설정한 비밀번호
- `IOS_PROVISIONING_PROFILE_BASE64`: 프로비저닝 프로파일의 base64 인코딩

### App Store Connect API 시크릿들
- `APPSTORE_ISSUER_ID`: App Store Connect API 발급자 ID
- `APPSTORE_KEY_ID`: App Store Connect API 키 ID
- `APPSTORE_PRIVATE_KEY`: App Store Connect API 개인 키 (.p8 파일 내용)

## 6. ExportOptions.plist 설정 확인

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.zellyy.finance</key>
        <string>Zellyy Finance App Store</string>
    </dict>
    <key>signingCertificate</key>
    <string>iPhone Distribution</string>
    <key>signingStyle</key>
    <string>manual</string>
</dict>
</plist>
```

## 7. 로컬 빌드 테스트

### 릴리즈 빌드 테스트
```bash
# 웹 앱 빌드
npm run build:prod

# Capacitor 동기화
npm run mobile:sync

# iOS 프로젝트 열기
npm run ios:open

# Xcode에서 Archive 빌드
# Product > Archive 선택
# Archive 성공 시 Organizer에서 확인
```

### 명령어로 빌드 테스트
```bash
cd ios/App

# CocoaPods 의존성 설치
pod install

# 릴리즈 빌드
xcodebuild -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath App.xcarchive \
  archive

# IPA 내보내기
xcodebuild -exportArchive \
  -archivePath App.xcarchive \
  -exportPath ./build \
  -exportOptionsPlist ExportOptions.plist
```

## 8. TestFlight 배포 설정

### 자동 업로드 설정
```bash
# fastlane 설치 (옵션)
gem install fastlane

# TestFlight 업로드
xcrun altool --upload-app \
  --type ios \
  --file "App.ipa" \
  --username "your-apple-id@example.com" \
  --password "app-specific-password"
```

### GitHub Actions 통합
```yaml
# .github/workflows/mobile-build.yml에서 사용
- name: Upload to TestFlight
  uses: Apple-Actions/upload-testflight-build@v1
  with:
    app-path: ios/App/build/App.ipa
    issuer-id: ${{ secrets.APPSTORE_ISSUER_ID }}
    api-key-id: ${{ secrets.APPSTORE_KEY_ID }}
    api-private-key: ${{ secrets.APPSTORE_PRIVATE_KEY }}
```

## 9. 보안 고려사항

### 인증서 관리
- P12 파일 및 프로비저닝 프로파일은 git에 커밋하지 않음
- Apple Developer 계정의 2단계 인증 활성화
- App Store Connect API 키는 최소 권한으로 설정

### CI/CD 보안
- GitHub Secrets로 모든 민감 정보 보호
- 릴리즈 브랜치에서만 서명된 빌드 생성
- 빌드 로그에서 민감 정보 노출 방지

## 10. 문제 해결

### 일반적인 오류들
- `Code signing error`: 인증서 또는 프로비저닝 프로파일 문제
- `Bundle ID mismatch`: Bundle Identifier 불일치
- `Provisioning profile expired`: 프로비저닝 프로파일 만료
- `Team ID not found`: Apple Developer 팀 설정 오류

### 디버깅 명령어
```bash
# 코드 서명 정보 확인
security find-identity -v -p codesigning

# 프로비저닝 프로파일 확인
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Xcode 빌드 로그 확인
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release build | xcpretty
```

### 유용한 도구들
- [iOS App Signer](https://github.com/DanTheMan827/ios-app-signer): GUI 코드 서명 도구
- [fastlane](https://fastlane.tools): iOS 배포 자동화 도구
- [xcpretty](https://github.com/xcpretty/xcpretty): Xcode 빌드 로그 포맷터