# 볼링 매니저 구독 및 인앱 결제 통합 문서

## 개요

볼링 매니저 앱은 구독 기반 비즈니스 모델을 채택하여 다양한 기능을 제공합니다. 이 문서는 Flutter 모바일 앱에서 구독 및 인앱 결제 기능의 구현과 통합에 대한 상세 정보를 제공합니다.

## 아키텍처 개요

구독 및 인앱 결제 시스템은 다음 주요 구성 요소로 이루어져 있습니다:

1. **모델 (Models)**
   - `Subscription`: 사용자의 구독 정보를 나타냅니다.
   - `SubscriptionPlan`: 사용 가능한 구독 플랜의 세부 정보를 포함합니다.

2. **서비스 (Services)**
   - `SubscriptionService`: 구독 상태 관리 및 백엔드 API와의 통신을 담당합니다.
   - `InAppPurchaseService`: 플랫폼별 인앱 결제 처리를 담당합니다.

3. **백엔드 API**
   - 구독 검증, 상태 관리, 영수증 검증 등의 서버 측 로직을 제공합니다.

## 데이터 흐름

### 구독 구매 프로세스

1. 사용자가 구독 구매 버튼을 클릭합니다.
2. `SubscriptionService.createSubscription()`이 호출됩니다.
3. `InAppPurchaseService.purchaseSubscription()`이 호출되어 플랫폼별 결제 프로세스를 시작합니다.
4. 결제가 완료되면 `InAppPurchaseService`의 `purchaseStream`이 업데이트됩니다.
5. 결제 상태가 `PurchaseStatus.purchased`로 변경되면 `_verifyAndSavePurchase()` 메서드가 호출됩니다.
6. `_verifyAndSavePurchase()`는 플랫폼별 영수증 데이터를 추출하고 서버에 전송하여 검증합니다.
7. 서버는 영수증을 검증하고 구독 정보를 데이터베이스에 저장합니다.
8. 검증이 성공하면 `SubscriptionService`는 서버에서 최신 구독 정보를 가져와 로컬 상태를 업데이트합니다.

### 구독 상태 확인 및 기능 접근 제어

1. 앱이 시작되면 `SubscriptionService.loadCurrentSubscription()`이 호출되어 현재 구독 상태를 로드합니다.
2. 사용자가 특정 기능에 접근하려고 할 때 `SubscriptionService.canAccessFeature()`가 호출됩니다.
3. 현재 구독 상태에 따라 기능 접근 권한이 결정됩니다.
4. 접근 권한이 없는 경우 업그레이드 안내 대화상자가 표시됩니다.

## 주요 클래스 및 메서드

### SubscriptionService

```dart
class SubscriptionService extends ChangeNotifier {
  // 주요 속성
  Subscription? _currentSubscription;
  List<SubscriptionPlan> _availablePlans;
  InAppPurchaseService _purchaseService;
  
  // 주요 메서드
  Future<void> loadCurrentSubscription();
  Future<bool> createSubscription(SubscriptionPlanType planType, bool isYearly);
  Future<bool> restoreSubscriptions();
  Future<bool> changePlan(SubscriptionPlanType newPlanType, bool isYearly);
  Future<bool> toggleAutoRenew();
  bool canAccessFeature(SubscriptionFeature feature);
  Future<bool> checkFeatureAccess(SubscriptionFeature feature, BuildContext context);
  int getMaxMembersAllowed();
  int getMaxEventsAllowed();
}
```

### InAppPurchaseService

```dart
class InAppPurchaseService extends ChangeNotifier {
  // 주요 속성
  List<ProductDetails> _products;
  List<PurchaseDetails> _purchases;
  bool _purchaseVerified;
  Map<String, dynamic>? _verifiedPurchase;
  
  // 주요 메서드
  Future<void> initialize();
  Future<bool> purchaseSubscription(SubscriptionPlanType planType);
  Future<bool> restorePurchases();
  Future<bool> _verifyAndSavePurchase(PurchaseDetails purchaseDetails);
}
```

## 구독 플랜 및 기능

볼링 매니저는 다음과 같은 구독 플랜을 제공합니다:

1. **무료 (Free)**
   - 기본 볼링 점수 추적
   - 최대 10명의 회원 관리
   - 최대 5개의 이벤트 관리

2. **기본 (Basic)**
   - 모든 무료 기능
   - 최대 30명의 회원 관리
   - 최대 10개의 이벤트 관리
   - 기본 통계 분석

3. **프리미엄 (Premium)**
   - 모든 기본 기능
   - 최대 100명의 회원 관리
   - 최대 50개의 이벤트 관리
   - 고급 통계 분석
   - 커스터마이징 옵션

4. **프로 (Pro)**
   - 모든 프리미엄 기능
   - 최대 500명의 회원 관리
   - 최대 200개의 이벤트 관리
   - 우선 지원
   - 모든 고급 기능 접근

## 영수증 검증 프로세스

1. **iOS 영수증 검증**
   - App Store 영수증 데이터 추출
   - 서버에 영수증 데이터 전송
   - 서버는 Apple 서버에 영수증 검증 요청
   - 검증 결과에 따라 구독 상태 업데이트

2. **Android 영수증 검증**
   - Google Play 영수증 데이터(JSON) 추출
   - 서버에 영수증 데이터 전송
   - 서버는 Google Play API를 통해 영수증 검증
   - 검증 결과에 따라 구독 상태 업데이트

## 오류 처리

- 결제 프로세스 중 발생하는 오류는 `_error` 속성에 저장되고 UI에 표시됩니다.
- 네트워크 오류, 서버 오류, 검증 오류 등 다양한 오류 상황에 대한 처리가 구현되어 있습니다.
- 오류 발생 시 사용자에게 적절한 피드백을 제공하고 필요한 경우 재시도 옵션을 제공합니다.

## 테스트 및 QA

구독 및 인앱 결제 기능을 테스트하려면:

1. **샌드박스 환경 설정**
   - iOS: App Store Connect에서 샌드박스 테스터 계정 설정
   - Android: Google Play Console에서 테스트 트랙 설정

2. **테스트 시나리오**
   - 구독 구매
   - 구독 복원
   - 플랜 변경
   - 자동 갱신 설정 변경
   - 구독 만료 처리
   - 다양한 오류 상황 테스트

## 백엔드 API 엔드포인트

- `/subscriptions/current`: 현재 구독 정보 조회
- `/subscriptions/plans`: 사용 가능한 구독 플랜 목록 조회
- `/subscriptions/subscribe`: 새 구독 생성
- `/subscriptions/verify-receipt`: 인앱 결제 영수증 검증
- `/subscriptions/change-with-features`: 구독 플랜 변경
- `/subscriptions/autorenew`: 자동 갱신 설정 변경

## 결론

볼링 매니저의 구독 및 인앱 결제 시스템은 Flutter의 `in_app_purchase` 패키지와 커스텀 백엔드 API를 통합하여 안전하고 사용자 친화적인 결제 경험을 제공합니다. 이 문서는 시스템의 주요 구성 요소와 데이터 흐름을 설명하여 개발자들이 시스템을 이해하고 유지보수할 수 있도록 돕습니다.