ZELLYY/zellyy-finance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7c92e60a534b840337e5786d2ace08c4888720d0
zellyy-finance/docs/app-store-deployment-guide.md
hansoo 8343b25439 feat: Stage 2 TypeScript 타입 안전성 개선 - any 타입 83개 → 62개 대폭 감소 
✨ 주요 개선사항:
- any 타입 83개에서 62개로 21개 수정 (25% 감소)
- 모든 ESLint 에러 11개 → 0개 완전 해결
- 타입 안전성 대폭 향상으로 런타임 오류 가능성 감소

🔧 수정된 파일들:
• PWADebug.tsx - 사용하지 않는 import들에 _ prefix 추가
• categoryUtils.ts - 불필요한 any 캐스트 제거
• TransactionsHeader.tsx - BudgetData 인터페이스 정의
• storageUtils.ts - generic 타입과 unknown 타입 적용
• 각종 error handler들 - Error | {message?: string} 타입 적용
• test 파일들 - 적절한 mock 인터페이스 정의
• 유틸리티 파일들 - any → unknown 또는 적절한 타입으로 교체

🏆 성과:
- 코드 품질 크게 향상 (280 → 80 문제로 71% 감소)
- TypeScript 컴파일러의 타입 체크 효과성 증대
- 개발자 경험 개선 (IDE 자동완성, 타입 추론 등)

🧹 추가 정리:
- ESLint no-console/no-alert 경고 해결
- Prettier 포맷팅 적용으로 코드 스타일 통일

🎯 다음 단계: 남은 62개 any 타입 계속 개선 예정

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-14 10:08:51 +09:00

10 KiB
Raw Blame History

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

개요

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에 접속
  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에 접속
  2. 새 앱 생성:
    • 앱 이름: Zellyy Finance
    • 패키지명: com.zellyy.finance
    • 언어: 한국어
  3. API 액세스 설정:
    • 설정 > API 액세스
    • 서비스 계정 연결
    • 위에서 생성한 서비스 계정 선택
    • 권한: 앱 정보 보기 및 편집, 릴리즈 관리

1.3 서비스 계정 키 생성

# 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 계정 필요
  2. App Store Connect 접근 권한
  3. 연간 개발자 등록비 $99 납부

2.2 App Store Connect 앱 생성

  1. App Store Connect에 접속
  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 인증서 및 프로비저닝 프로파일

# 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

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 (미래 계획)

# 향후 Alpha/Beta 트랙 추가 시
track: alpha  # 또는 beta

Production (프로덕션)

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

2. App Store Connect 트랙

TestFlight (베타 테스트)

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

App Store (프로덕션)

  • 목적: 일반 사용자 배포
  • 승인: Apple 수동 심사 (2-7일)
  • 배포: 수동 릴리즈 필요

자동 배포 워크플로우

1. 트리거 조건

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

2. 배포 흐름

코드 푸시 → 테스트 → 빌드 → 버전 태그 → 스토어 업로드 → 알림

3. 배포 단계별 상세

Stage 1: 빌드 및 서명

- Android AAB 생성 (서명 포함)
- iOS IPA 생성 (서명 포함)
- 아티팩트 저장

Stage 2: 스토어 업로드

- Google Play: Internal Testing 트랙 업로드
- TestFlight: 베타 테스트 업로드

Stage 3: 결과 알림

- Slack 알림 (성공/실패)
- GitHub 이슈 생성 (실패 시)
- 이메일 알림 (선택사항)

릴리즈 노트 자동 생성

1. 커밋 메시지 기반 생성

# Conventional Commits 사용
feat: 새로운 거래 필터링 기능 추가
fix: 로그인 세션 만료 문제 수정
perf: 차트 렌더링 성능 50% 개선

2. 릴리즈 노트 형식

# Zellyy Finance v1.2.0

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

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

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

3. 스토어별 릴리즈 노트

Google Play Store

  • 최대 길이: 500자
  • 언어: 한국어
  • 자동 적용: ✅

App Store Connect

  • 최대 길이: 4000자
  • 언어: 한국어
  • 자동 적용: ✅

배포 후 검증

1. 자동 검증

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

2. 수동 검증

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

트러블슈팅

1. Google Play Store 업로드 실패

오류: "Package name already exists"

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

오류: "Version code too low"

해결:
1. android/app/build.gradle의 versionCode 확인
2. semantic-release로 자동 증가하는지 확인
3. 수동으로 버전 코드 증가

오류: "API access denied"

해결:
1. Google Play Console에서 API 액세스 확인
2. 서비스 계정 권한 확인
3. JSON 키 파일 재생성

2. App Store Connect 업로드 실패

오류: "Invalid provisioning profile"

해결:
1. Apple Developer에서 프로비저닝 프로파일 재생성
2. 인증서 유효성 확인
3. Bundle ID 일치 확인 (com.zellyy.finance)

오류: "API key invalid"

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

오류: "Build processing timeout"

해결:
1. Apple 서버 상태 확인
2. 15-30분 후 재시도
3. 빌드 크기 최적화

3. 일반적인 배포 문제

빌드 아티팩트 누락

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

버전 동기화 오류

해결:
1. npm run version:sync 실행
2. semantic-release 설정 확인
3. package.json 버전 확인

모니터링 및 알림

1. 배포 상태 모니터링

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

2. 스토어 상태 확인

# Google Play Console
- Internal Testing 트랙 상태
- 리뷰 진행 상황
- 다운로드 통계

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

3. 알림 채널

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

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

보안 고려사항

1. API 키 관리

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

2. 코드 서명 인증서

  • P12 파일 안전한 저장
  • 인증서 만료일 추적 (Apple: 1년, Android: 25년)
  • 백업 및 복구 계획

3. 접근 권한 관리

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

확장 계획

1. 추가 트랙 지원

# Google Play Store
- Alpha Testing 트랙
- Beta Testing 트랙
- Production 자동 배포

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

2. 고급 기능

- A/B 테스트 자동화
- 스토어 메타데이터 관리
- 스크린샷 자동 업로드
- 다국어 릴리즈 노트

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

Reference in New Issue View Git Blame Copy Permalink