# 앱 스토어 배포 자동화 가이드

## 개요

Zellyy Finance 앱의 Google Play Store와 Apple App Store 자동 배포 시스템 설정 가이드입니다. GitHub Actions를 통해 빌드부터 스토어 업로드까지 완전 자동화됩니다.

## 지원 플랫폼

### Android - Google Play Store
- **트랙**: Internal Testing (내부 테스트)
- **파일 형식**: AAB (Android App Bundle)
- **자동 업로드**: main 브랜치 빌드 시
- **API**: Google Play Console API

### iOS - App Store Connect
- **트랙**: TestFlight (베타 테스트)
- **파일 형식**: IPA
- **자동 업로드**: main 브랜치 빌드 시
- **API**: App Store Connect API

## 사전 준비 사항

### 1. Google Play Store 설정

#### 1.1 Google Cloud Console 설정
1. [Google Cloud Console](https://console.cloud.google.com/)에 접속
2. 새 프로젝트 생성 또는 기존 프로젝트 선택
3. Google Play Developer Reporting API 활성화
4. 서비스 계정 생성:
   - IAM & Admin > 서비스 계정
   - "서비스 계정 만들기" 클릭
   - 이름: `zellyy-finance-ci`
   - 역할: 없음 (Google Play Console에서 설정)

#### 1.2 Google Play Console 설정
1. [Google Play Console](https://play.google.com/console/)에 접속
2. 새 앱 생성:
   - 앱 이름: `Zellyy Finance`
   - 패키지명: `com.zellyy.finance`
   - 언어: 한국어
3. API 액세스 설정:
   - 설정 > API 액세스
   - 서비스 계정 연결
   - 위에서 생성한 서비스 계정 선택
   - 권한: 앱 정보 보기 및 편집, 릴리즈 관리

#### 1.3 서비스 계정 키 생성
```bash
# Google Cloud Console에서
1. IAM & Admin > 서비스 계정
2. 생성한 서비스 계정 클릭
3. "키" 탭 > "키 추가" > "새 키 만들기"
4. JSON 형식 선택
5. 다운로드된 JSON 파일 내용을 GitHub Secrets에 저장
```

### 2. Apple App Store 설정

#### 2.1 Apple Developer Account 준비
1. [Apple Developer](https://developer.apple.com/) 계정 필요
2. App Store Connect 접근 권한
3. 연간 개발자 등록비 $99 납부

#### 2.2 App Store Connect 앱 생성
1. [App Store Connect](https://appstoreconnect.apple.com/)에 접속
2. 새 앱 생성:
   - 이름: `Zellyy Finance`
   - Bundle ID: `com.zellyy.finance`
   - SKU: `zellyy-finance`
   - 언어: 한국어

#### 2.3 API 키 생성
1. App Store Connect > 사용자 및 액세스
2. 키 탭 > "+" 버튼
3. 키 이름: `Zellyy Finance CI/CD`
4. 액세스: Developer (또는 App Manager)
5. 생성 후 다음 정보 저장:
   - Issuer ID
   - Key ID
   - Private Key (.p8 파일)

#### 2.4 인증서 및 프로비저닝 프로파일
```bash
# iOS 배포 인증서 생성
1. Apple Developer > Certificates
2. "+" > iOS Distribution (App Store and Ad Hoc)
3. CSR 파일 업로드
4. 인증서 다운로드 (.cer)

# 프로비저닝 프로파일 생성
1. Apple Developer > Profiles
2. "+" > iOS App Store
3. App ID 선택: com.zellyy.finance
4. 인증서 선택: 위에서 생성한 배포 인증서
5. 프로파일 다운로드 (.mobileprovision)
```

## GitHub Secrets 설정

### 1. Repository Settings
```bash
GitHub Repository > Settings > Secrets and Variables > Actions
```

### 2. Android 관련 Secrets

| Secret 이름 | 설명 | 값 |
|-------------|------|-----|
| `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` | Google Play API 서비스 계정 JSON | Google Cloud Console에서 다운로드한 JSON 파일 전체 내용 |

### 3. iOS 관련 Secrets

| Secret 이름 | 설명 | 값 |
|-------------|------|-----|
| `APPSTORE_ISSUER_ID` | App Store Connect API Issuer ID | App Store Connect API 키 생성 시 표시된 Issuer ID |
| `APPSTORE_KEY_ID` | App Store Connect API Key ID | API 키 생성 시 표시된 Key ID |
| `APPSTORE_PRIVATE_KEY` | App Store Connect API Private Key | .p8 파일의 전체 내용 (헤더/푸터 포함) |

### 4. 코드 서명 Secrets (기존 문서 참조)

| Secret 이름 | 설명 |
|-------------|------|
| `ANDROID_KEYSTORE_BASE64` | Android 키스토어 파일 (base64) |
| `ANDROID_KEYSTORE_PASSWORD` | 키스토어 비밀번호 |
| `ANDROID_KEY_PASSWORD` | 키 비밀번호 |
| `ANDROID_KEY_ALIAS` | 키 별칭 |
| `IOS_CERTIFICATES_P12_BASE64` | iOS 배포 인증서 P12 (base64) |
| `IOS_CERTIFICATES_P12_PASSWORD` | P12 파일 비밀번호 |

## 배포 트랙 설정

### 1. Google Play Store 트랙

#### Internal Testing (내부 테스트)
- **목적**: 개발팀 내부 테스트
- **승인**: 즉시 (Google 승인 불필요)
- **테스터**: 최대 100명
- **자동 업로드**: ✅ 활성화됨

#### Alpha/Beta Testing (미래 계획)
```yaml
# 향후 Alpha/Beta 트랙 추가 시
track: alpha  # 또는 beta
```

#### Production (프로덕션)
```yaml
# 안정성 검증 후 수동으로 프로덕션 배포
track: production
inAppUpdatePriority: 3
userFraction: 1.0
```

### 2. App Store Connect 트랙

#### TestFlight (베타 테스트)
- **목적**: 베타 테스터 배포
- **승인**: Apple 자동 승인 (보통 24시간 이내)
- **테스터**: 최대 10,000명
- **자동 업로드**: ✅ 활성화됨

#### App Store (프로덕션)
- **목적**: 일반 사용자 배포
- **승인**: Apple 수동 심사 (2-7일)
- **배포**: 수동 릴리즈 필요

## 자동 배포 워크플로우

### 1. 트리거 조건
```yaml
# 자동 배포가 실행되는 조건
on:
  push:
    branches: [main]        # main 브랜치 푸시
    tags: ['v*']           # 버전 태그 푸시
  workflow_dispatch:       # 수동 실행
```

### 2. 배포 흐름
```
코드 푸시 → 테스트 → 빌드 → 버전 태그 → 스토어 업로드 → 알림
```

### 3. 배포 단계별 상세

#### Stage 1: 빌드 및 서명
```yaml
- Android AAB 생성 (서명 포함)
- iOS IPA 생성 (서명 포함)
- 아티팩트 저장
```

#### Stage 2: 스토어 업로드
```yaml
- Google Play: Internal Testing 트랙 업로드
- TestFlight: 베타 테스트 업로드
```

#### Stage 3: 결과 알림
```yaml
- Slack 알림 (성공/실패)
- GitHub 이슈 생성 (실패 시)
- 이메일 알림 (선택사항)
```

## 릴리즈 노트 자동 생성

### 1. 커밋 메시지 기반 생성
```bash
# Conventional Commits 사용
feat: 새로운 거래 필터링 기능 추가
fix: 로그인 세션 만료 문제 수정
perf: 차트 렌더링 성능 50% 개선
```

### 2. 릴리즈 노트 형식
```markdown
# Zellyy Finance v1.2.0

## ✨ 새로운 기능
- 거래 내역 고급 필터링
- 다크 모드 지원

## 🐛 버그 수정
- 로그인 세션 안정성 개선
- 차트 데이터 로딩 오류 수정

## ⚡ 성능 개선
- 앱 시작 시간 30% 단축
- 메모리 사용량 최적화
```

### 3. 스토어별 릴리즈 노트

#### Google Play Store
- **최대 길이**: 500자
- **언어**: 한국어
- **자동 적용**: ✅

#### App Store Connect
- **최대 길이**: 4000자
- **언어**: 한국어
- **자동 적용**: ✅

## 배포 후 검증

### 1. 자동 검증
```bash
# GitHub Actions에서 자동 실행
- 스토어 업로드 성공 확인
- 버전 번호 일치 확인
- 릴리즈 노트 적용 확인
```

### 2. 수동 검증
```bash
# 개발팀에서 수행
1. Google Play Console에서 Internal Testing 트랙 확인
2. TestFlight에서 베타 빌드 확인
3. 실제 디바이스에서 앱 설치 테스트
4. 주요 기능 동작 확인
```

## 트러블슈팅

### 1. Google Play Store 업로드 실패

#### 오류: "Package name already exists"
```bash
해결: 
1. 기존 앱이 있는지 Google Play Console 확인
2. 패키지명 중복 확인 (com.zellyy.finance)
3. 다른 개발자 계정에서 사용 중인지 확인
```

#### 오류: "Version code too low"
```bash
해결:
1. android/app/build.gradle의 versionCode 확인
2. semantic-release로 자동 증가하는지 확인
3. 수동으로 버전 코드 증가
```

#### 오류: "API access denied"
```bash
해결:
1. Google Play Console에서 API 액세스 확인
2. 서비스 계정 권한 확인
3. JSON 키 파일 재생성
```

### 2. App Store Connect 업로드 실패

#### 오류: "Invalid provisioning profile"
```bash
해결:
1. Apple Developer에서 프로비저닝 프로파일 재생성
2. 인증서 유효성 확인
3. Bundle ID 일치 확인 (com.zellyy.finance)
```

#### 오류: "API key invalid"
```bash
해결:
1. App Store Connect에서 API 키 재생성
2. Issuer ID, Key ID 재확인
3. P8 파일 전체 내용 확인 (헤더/푸터 포함)
```

#### 오류: "Build processing timeout"
```bash
해결:
1. Apple 서버 상태 확인
2. 15-30분 후 재시도
3. 빌드 크기 최적화
```

### 3. 일반적인 배포 문제

#### 빌드 아티팩트 누락
```bash
해결:
1. GitHub Actions 아티팩트 저장 확인
2. 빌드 단계 성공 여부 확인
3. 파일 경로 올바른지 확인
```

#### 버전 동기화 오류
```bash
해결:
1. npm run version:sync 실행
2. semantic-release 설정 확인
3. package.json 버전 확인
```

## 모니터링 및 알림

### 1. 배포 상태 모니터링
```bash
# GitHub Actions에서 제공
- 실시간 배포 진행 상황
- 각 단계별 성공/실패 상태
- 상세 로그 및 오류 메시지
```

### 2. 스토어 상태 확인
```bash
# Google Play Console
- Internal Testing 트랙 상태
- 리뷰 진행 상황
- 다운로드 통계

# App Store Connect
- TestFlight 베타 상태
- 리뷰 진행 상황
- 크래시 리포트
```

### 3. 알림 채널
```bash
# 즉시 알림
- Slack #deployments 채널
- 이메일 (선택사항)
- GitHub 이슈 (실패 시)

# 정기 리포트
- 주간 배포 요약
- 월간 스토어 통계
- 분기별 성과 분석
```

## 보안 고려사항

### 1. API 키 관리
- GitHub Secrets에 안전하게 저장
- 정기적인 키 로테이션 (6개월마다)
- 최소 권한 원칙 적용

### 2. 코드 서명 인증서
- P12 파일 안전한 저장
- 인증서 만료일 추적 (Apple: 1년, Android: 25년)
- 백업 및 복구 계획

### 3. 접근 권한 관리
- 배포 권한은 핵심 개발자만
- API 키 접근 로그 모니터링
- 의심스러운 활동 알림

## 확장 계획

### 1. 추가 트랙 지원
```bash
# Google Play Store
- Alpha Testing 트랙
- Beta Testing 트랙
- Production 자동 배포

# App Store
- App Store 자동 배포
- 단계적 출시 (Phased Release)
```

### 2. 고급 기능
```bash
- A/B 테스트 자동화
- 스토어 메타데이터 관리
- 스크린샷 자동 업로드
- 다국어 릴리즈 노트
```

---

이 가이드는 Zellyy Finance 앱의 완전 자동화된 스토어 배포 시스템 구축을 위한 종합 참조 문서입니다.