# 수익화 시스템 설계

## 메타 정보

- **문서 버전**: 1.0
- **최종 수정**: 2026-01-16
- **상태**: 계획 단계
- **플랫폼**: Android/iOS (모바일 전용)
- **광고 SDK**: AdMob

---

## Task 리스트

### Phase 1: 데이터 구조 (선행 작업)

- [ ] `MonetizationState` 모델 생성
- [ ] `DeathInfo.lostItem: EquipmentItem?` 필드 추가
- [ ] `GameSave` v3 → v4 마이그레이션
- [ ] 장비 손실 확률 공식 변경: `20% + (level-1) * 8.89%`
- [ ] `ItemService.determineRarity()` 확률 수정: 34/40/20/5/1

### Phase 2: AdMob 연동

- [ ] `google_mobile_ads` 패키지 추가
- [ ] `AdService` 클래스 생성
- [ ] 리워드 광고 로드/표시/콜백 구현
- [ ] 인터스티셜 광고 로드/표시/콜백 구현
- [ ] 디버그 빌드 광고 ON/OFF 토글 구현

### Phase 3: IAP 연동

- [ ] `in_app_purchase` 패키지 추가
- [ ] 광고 제거 상품 등록 (Google Play / App Store)
- [ ] `IAPService` 클래스 생성
- [ ] 구매 처리 로직 구현
- [ ] 구매 복원 로직 구현
- [ ] 구매 상태 영구 저장

### Phase 4: 캐릭터 생성 광고

- [ ] 굴리기 횟수 상태 관리 (rollsRemaining)
- [ ] 굴리기 횟수 저장/로드 구현
- [ ] 되돌리기 히스토리 관리
- [ ] 되돌리기 횟수 상태 관리 (undoRemaining)
- [ ] 캐릭터 생성 UI 수정: 굴리기 버튼
- [ ] 캐릭터 생성 UI 수정: 되돌리기 버튼

### Phase 5: 부활 시스템

- [ ] 사망 시 `DeathInfo.lostItem` 저장 로직
- [ ] `reviveWithAdReward()` 함수 구현
- [ ] `reviveWithoutAd()` 함수 구현
- [ ] 자동부활 버프 상태 관리 (autoReviveEndMs)
- [ ] 자동부활 버프 중 사망 처리 로직
- [ ] 사망 화면 UI: 광고 부활 버튼
- [ ] 사망 화면 UI: 일반 부활 버튼

### Phase 6: 속도업

- [ ] 속도 상태 관리 (1x/2x/5x)
- [ ] 명예의 전당 캐릭터 존재 여부 확인 로직
- [ ] 5배속 버프 상태 관리 (speedBoostEndMs)
- [ ] 속도 UI: 버튼 표시 로직
- [ ] 속도 UI: 남은 시간 표시

### Phase 7: 복귀 보상

- [ ] `lastPlayTime` 저장/로드 구현
- [ ] 오프라인 시간 계산 로직
- [ ] 오프라인 진행 시뮬레이션 (1배/2배)
- [ ] 보물 상자 축적 로직
- [ ] 보물 상자 내용물 생성 로직
- [ ] 행운의 부적 버프 발동 로직
- [ ] 복귀 보상 UI: 환영 다이얼로그
- [ ] 복귀 보상 UI: 상자 오픈

### Phase 8: 디버그 기능

- [ ] 메인 메뉴: 디버그 옵션 섹션 (kDebugMode)
- [ ] 스타트 화면: 디버그 옵션 섹션
- [ ] 광고 ON/OFF 토글
- [ ] IAP 구매 시뮬레이션 토글
- [ ] 오프라인 시간 시뮬레이션

---

## 스펙 요약

### 광고 유형

| ID | 유형 | 길이 | 사용처 |
| -- | ---- | ---- | ------ |
| AD_REWARD_REVIVE | 리워드 | 30초 | 부활 |
| AD_REWARD_UNDO | 리워드 | 30초 | 캐릭터 생성 되돌리기 |
| AD_INTERSTITIAL_ROLL | 인터스티셜 | 6초 | 굴리기 횟수 충전 |
| AD_INTERSTITIAL_SPEED | 인터스티셜 | 6초 | 게임 속도업 |

### IAP 상품

| ID | 가격 | 유형 |
| -- | ---- | ---- |
| remove_ads | $9.99 | 비소모성 (1회 구매) |

### 무료 vs 구매 유저 비교

| 기능 | 무료 유저 | 구매 유저 |
| ---- | --------- | --------- |
| 광고 | 표시 | 제거 (버튼 클릭 시 바로 활성화) |
| 복귀 상자 최대 | 5개 | 10개 |
| 오프라인 진행 속도 | 1배 | 2배 |
| 행운 버프 발동 | 1시간당 5분 | 30분당 5분 |
| 캐릭터 되돌리기 | 1회 (광고) | 3회 (무료) |
| 굴리기 충전 | 광고 필요 | 무제한 |
| 속도업 | 광고 필요 | 무제한 |

---

## 상세 스펙

### 1. 캐릭터 생성 - 굴리기

```yaml
rollsRemaining:
  default: 5
  min: 0
  max: 5
  recharge: +5 (인터스티셜 광고 시청 후)
  persistence: 저장됨 (0회로 종료 시 재시작해도 0회)
```

### 2. 캐릭터 생성 - 되돌리기

```yaml
undoRemaining:
  free_user: 1
  paid_user: 3
  ad_required:
    free_user: true (30초 리워드)
    paid_user: false
  range: 1단계 전만
  reset: 새로 굴리기 시작 시 초기화
  constraint: min(undoRemaining, rollHistory.length)
```

### 3. 장비 손실 확률

```yaml
formula: 20 + (level - 1) * 80 / 9
level_1: 20%
level_5: 56%
level_10_plus: 100%
code: |
  int calculateEquipmentLossChance(int level) {
    if (level >= 10) return 100;
    return 20 + ((level - 1) * 80 ~/ 9);
  }
```

### 4. 부활 시스템

```yaml
normal_revive:
  ad: false
  hp_recovery: 50%
  equipment_loss: confirmed
  sacrifice: required

ad_revive:
  ad: true (30초 리워드)
  hp_recovery: 100%
  equipment_loss: cancelled (lostItem 복구)
  sacrifice: none
  auto_revive_buff:
    duration: 600000ms (10분)
    effect: 버프 중 사망 시 자동부활 + 장비 손실 없음
```

### 5. 게임 속도

```yaml
speed_levels:
  - 1x: 기본
  - 2x: 명예의 전당 캐릭터 1명 이상 시 해금
  - 5x: 광고 시청 (5분간) 또는 IAP 구매 시 무제한

speed_boost:
  duration: 300000ms (5분)
  ad: 인터스티셜 6초
  paid_user: 광고 없이 무제한
```

### 6. 복귀 보상

```yaml
offline_progress:
  free_user: 1x
  paid_user: 2x

treasure_chest:
  rate: 1개/시간
  max_free: 5개
  max_paid: 10개
  contents:
    equipment: 50%
    gold: 30%
    potion: 15%
    bonus_equipment: 5%

lucky_charm_buff:
  free_user: 5분/오프라인1시간
  paid_user: 5분/오프라인30분
  max_duration: 30분
  effect:
    common: 34% → 28%
    uncommon: 40% → 40%
    rare: 20% → 20%
    epic: 5% → 10%
    legendary: 1% → 2%
```

### 7. 아이템 희귀도 (목표)

```yaml
rarity_distribution:
  common: 34%
  uncommon: 40%
  rare: 20%
  epic: 5%
  legendary: 1%
note: 현재 코드와 다름. ItemService.determineRarity() 수정 필요
```

---

## 데이터 모델

### MonetizationState

```dart
class MonetizationState {
  final bool adRemovalPurchased;      // IAP 구매 여부
  final int rollsRemaining;           // 굴리기 남은 횟수 (0-5)
  final int undoRemaining;            // 되돌리기 남은 횟수
  final List<Stats>? rollHistory;     // 되돌리기용 히스토리
  final int? autoReviveEndMs;         // 자동부활 버프 종료 시점
  final int? speedBoostEndMs;         // 5배속 종료 시점
  final DateTime? lastPlayTime;       // 마지막 플레이 시각
  final int pendingChests;            // 미개봉 상자 개수
  final int? luckyCharmEndMs;         // 행운 버프 종료 시점
}
```

### DeathInfo 확장

```dart
class DeathInfo {
  // 기존 필드
  final String? lostItemName;
  final EquipmentSlot? lostItemSlot;
  final ItemRarity? lostItemRarity;

  // 신규 필드
  final EquipmentItem? lostItem;      // 복구용 전체 장비 정보
}
```

### GameSave 버전

```yaml
current_version: 3
next_version: 4
migration:
  - add: MonetizationState monetization
  - add: DeathInfo.lostItem
```

---

## 엣지 케이스

| 케이스 | 조건 | 처리 |
| ------ | ---- | ---- |
| 광고 로드 실패 | 네트워크 오류 | 재시도 버튼 표시 |
| 오프라인 상태 | 네트워크 없음 | 광고 버튼 비활성화 |
| 광고 중 앱 종료 | 광고 미완료 | 보상 미지급 |
| IAP 복원 | 앱 재설치 | 구글/애플 구매기록 확인 |
| 자동부활 중 종료 | 버프 활성 중 | 남은 시간 저장 |
| 시간 조작 | lastPlayTime > now | 복귀 보상 없음 |
| 굴리기 0회 종료 | rollsRemaining == 0 | 0회 유지 |
| 되돌리기 초과 | undoRemaining > historyLength | min 적용 |

---

## 디버그 옵션 (kDebugMode 전용)

```yaml
debug_options:
  ad_enabled:
    type: bool
    default: true
    off_behavior: 광고 버튼 클릭 시 바로 보상
    on_behavior: 실제 광고 재생

  iap_simulated:
    type: bool
    default: false
    off_behavior: 무료 유저로 동작
    on_behavior: 구매 유저로 동작

  offline_hours:
    type: int
    options: [0, 1, 5, 10]
    default: 0
    purpose: 복귀 보상 테스트

locations:
  - 메인 메뉴 (광고 제거 버튼 아래)
  - 스타트 화면
```

---

## UI 요약

### 메인 메뉴

```
[ 새 게임 ]
[ 불러오기 ]
[ 설정 ]
[ 명예의 전당 ]
────────────
[ 광고 제거 - $9.99 ]    ← 구매 후 비활성화
── Debug Only ──
[ 광고: ON/OFF ]
[ IAP: 미구매/구매 ]
```

### 캐릭터 생성

```
STR: 14  CON: 12  DEX: 10
INT: 16  WIS: 8   CHA: 11
Total: 71

[ 굴리기 (N/5) ]         ← 0회 시 🎬 표시
[ 🎬 이전으로 (N/M) ]    ← 무료:1회, 구매:3회
```

### 게임 화면 - 속도

```
명예의 전당 없음: [ 1x ] [ 🎬 5x ]
명예의 전당 있음: [ 1x ] [ 2x ] [ 🎬 5x ]
5배속 중: [ 5x ⏱️ 4:32 ]
```

### 사망 화면

```
☠️ You Died
Killed by: {monster}
Lost: {item}

[ 🎬 광고 부활 (30초) ]
  - 장비 복구
  - 제물 없음
  - HP 100%
  - 10분 자동부활

[ 일반 부활 ]
  - 장비 손실
  - 제물 소모
  - HP 50%
```

---

## 참고

### 관련 파일

- `lib/src/core/model/game_state.dart`: GameState 모델
- `lib/src/core/engine/progress_service.dart`: 사망 처리 로직
- `lib/src/core/storage/`: 저장/로드 시스템
- `lib/src/core/engine/item_service.dart`: 아이템 희귀도 결정

### 의존성 패키지

```yaml
dependencies:
  google_mobile_ads: ^5.0.0  # AdMob
  in_app_purchase: ^3.1.0    # IAP
```
