# 00. 프로젝트 컨텍스트 및 복구 (Project Context & Restore Point)

이 파일은 다른 개발 환경이나 새로운 AI 세션에서 프로젝트의 현재 상태를 빠르게 파악하고 작업을 이어가기 위해 작성되었습니다.

## 1. 프로젝트 개요

- **프로젝트명:** Colosseum's Choice
- **플랫폼:** Flutter (Android/iOS/Web/Desktop)
- **장르:** 텍스트 기반의 턴제 RPG + GUI (로그라이크 요소 포함)
- **상태:** 프로토타입 단계 (전투 시각화, 데이터 주도 시스템, 반응형 UI 구현 완료)

## 2. 현재 구현된 핵심 기능 (Feature Status)

### A. 게임 흐름 (Game Flow)

1.  **메인 메뉴 (`MainMenuScreen`):** 게임 시작 버튼.
2.  **캐릭터 선택 (`CharacterSelectionScreen`):** 'Warrior' 직업 구현.
3.  **메인 게임 (`MainWrapper`):** 하단 탭 네비게이션 (Battle / Inventory).
4.  **반응형 레이아웃 (Responsive UI):**
    - `ResponsiveContainer` 위젯을 통해 최대 너비(600px) 및 높이(1000px) 제한.
    - 웹/태블릿 환경에서도 모바일 앱처럼 중앙 정렬된 화면 제공.
    - **Battle UI Layout:** 플레이어(좌측 하단) vs 적(우측 상단) 대각선 구도 배치 및 캐릭터 임시 아이콘 적용.
    - **Widget Refactoring:** `BattleScreen`의 주요 UI 컴포넌트(`CharacterStatusCard`, `BattleLogOverlay` 등)를 `lib/widgets/battle/`로 분리하여 모듈화.

### B. 전투 시스템 (`BattleProvider`)

- **턴제 전투:** 플레이어 턴 -> 적 턴.
- **행동 선택:** 공격(Attack) / 방어(Defend).
- **리스크 시스템 (Risk System):** Safe(100%/50%), Normal(80%/100%), Risky(40%/200%) 선택.
- **적 인공지능 (Enemy AI & Intent):**
  - **Intent UI:** 적의 다음 행동(공격/방어, 리스크)을 미리 표시.
  - **선제 방어 (Pre-emptive Defense):** 적이 방어를 선택하면 턴 시작 전에 즉시 방어도가 적용됨.
  - **Defense Restriction:** `DefenseForbidden` 상태 시 방어 행동 선택 불가.
  - **Variance Removed:** 적의 공격/방어 수치 계산 시 랜덤 분산(Variance) 제거 (고정 수치).
- **적 장비 시스템 (Enemy Equipment):**
  - 적에게 아이템 장착 가능 (`enemies.json`의 `equipment` 필드).
  - 장착된 아이템의 스탯 및 특수 효과(상태이상 등)가 전투 시 적용됨.
- **시각 효과 (Visual Effects):**
  - **Floating Text:** 데미지 발생 시 캐릭터 위에 데미지 수치가 떠오름 (일반: 빨강, 출혈: 보라, 취약: 주황).
  - **Action Feedback:** 공격 빗나감(MISS - 적 위치/회색) 및 방어 실패(FAILED - 내 위치/빨강) 텍스트 오버레이.
  - **Effect Icons:** 공격/방어 및 리스크 레벨에 따른 아이콘 애니메이션 출력.
  - **Advanced Animations:**
    - **Risk-Based:** Safe(Wobble), Normal(Dash), Risky(Scale Up + Heavy Dash + Shake + Explosion).
    - **Icon-Only:** 공격 시 캐릭터 아이콘만 이동하며, 스탯 정보(HP/Armor)는 일시적으로 숨김 처리.
    - **Impact Sync:** 타격 이펙트와 데미지 텍스트가 애니메이션 타격 시점에 정확히 동기화됨.
- **상태이상:** `Stun`, `Bleed`, `Vulnerable`, `DefenseForbidden`.
- **행운 시스템 (Luck System):**
  - 아이템 옵션으로 `luck` 스탯 제공.
  - `totalLuck` 수치만큼 행동(공격/방어) 성공 확률 증가 (1 Luck = +1%).
  - 성공 확률은 최대 100%로 제한됨.
  - **UI:** 인벤토리에서 Luck 수치 확인 가능, 전투 시 Risk 선택 창에서 보정된 확률 표시.

### C. 데이터 주도 설계 (Data-Driven Design)

- **JSON 데이터:** `assets/data/items.json` (ID 포함), `assets/data/enemies.json` (장비 포함).
- **데이터 로더:** `ItemTable` (ID 조회 지원), `EnemyTable` (장비 장착 지원).

### D. 아이템 및 경제 (`Item`, `Inventory`)

- **장비:** 무기, 방어구, 방패, 장신구.
- **아이콘 및 색상 (`ItemUtils`):**
  - 무기: 빨강 삼각형 (`Icons.change_history`)
  - 방패: 파랑 방패 (`Icons.shield`)
  - 갑옷: 파랑 옷 (`Icons.checkroom`)
  - 장신구: 보라 다이아몬드 (`Icons.diamond`)
- **가격:** JSON 고정 가격 사용. 판매 시 60% (`GameMath.floor`) 획득.
- **인벤토리:** 장착 슬롯 및 가방(Bag) 그리드 UI 구현.
- **아이템 시스템 (Item System):**
  - **Rarity (희귀도):** Common, Rare, Epic, Legendary. (드랍 확률 관여)
  - **Tier (티어):** 1티어(초반), 2티어(중반), 3티어(후반). (라운드 진행도에 따라 등장 제한)
  - **획득 로직:** 현재 라운드(Tier)에 맞는 아이템 풀 내에서 Rarity 확률에 따라 결정.

### E. 스테이지 시스템 (`StageModel`)

- **타입:** Battle, Shop, Rest, Elite.
- **적 생성:** 스테이지 레벨에 따른 스탯 스케일링 적용.
- **적 등장 테이블 (Enemy Pull):** 적 조우 시, 현재 스테이지(라운드)에 따라 등장 가능한 적 목록(`enemy_table_pull`)을 설정하여 해당 범위 내에서 적을 랜덤 생성해야 함.
- **게임 구조 (Game Structure):**
  - **총 3라운드 (3 Rounds):** 각 라운드는 12개의 스테이지로 구성 (12/12/12).
  - **라운드 구성:**
    1.  **1라운드:** 지하 불법 투기장 (Underground Illegal Arena)
    2.  **2라운드:** 콜로세움 (Colosseum)
    3.  **3라운드:** 왕의 투기장 (King's Arena) - 최종 보스(Final Boss) 등장.

### F. 시스템 및 설정 (System & Settings)

- **설정 페이지 (Settings Screen):**
  - 게임 재시작 (Restart Game) 및 메인 메뉴로 돌아가기 (Return to Main Menu) 기능.
  - 하단 네비게이션 바(BottomNavigationBar)에 설정 탭 추가.
- **로컬 저장 (Local Storage):**
  - `shared_preferences`를 사용하여 스테이지 클리어 시 자동 저장.
  - 메인 메뉴에서 '이어하기 (CONTINUE)' 버튼을 통해 저장된 시점부터 게임 재개 가능.
  - 저장 데이터: 스테이지 진행도, 턴 수, 플레이어 상태(체력, 장비, 인벤토리 등).

## 3. 핵심 파일 및 아키텍처

- **`lib/providers/battle_provider.dart`:**
  - **Core Logic:** 상태 관리, 전투 루프.
  - **Streams:** `damageStream`, `effectStream`을 통해 UI(`BattleScreen`)에 비동기 이벤트 전달.
- **`lib/game/enums.dart`:** 프로젝트 전반의 Enum 통합 관리 (`ActionType`, `RiskLevel`, `StageType` 등).
- **`lib/utils/item_utils.dart`:** 아이템 타입별 아이콘 및 색상 로직 중앙화.
- **`lib/widgets/battle/`:** `BattleScreen`에서 분리된 재사용 가능한 위젯들.
  - **UI Components:** `CharacterStatusCard`, `BattleLogOverlay`, `FloatingBattleTexts`, `StageUI`.
  - **Effects:** `BattleAnimationWidget` (공격 애니메이션), `ExplosionWidget` (파티클), `ShakeWidget` (화면 흔들림).
- **`lib/widgets/responsive_container.dart`:** 반응형 레이아웃 컨테이너.
- **`lib/game/model/`:**
  - `damage_event.dart`, `effect_event.dart`: 이벤트 모델.
  - `entity.dart`: `Character` (Player/Enemy).
  - `item.dart`: `Item` (ID 필드 포함).
- **`lib/screens/battle_screen.dart`:**
  - `StreamSubscription`을 통해 이펙트 이벤트 수신 및 `Overlay` 애니메이션 렌더링.
  - `Stack` 및 `Positioned` 기반의 정교한 레이아웃.

## 4. 작업 컨벤션 (Working Conventions)

- **Prompt Driven Development:** `prompt/XX_description.md` 유지.
- **Language:** **모든 프롬프트 파일(prompt/XX_...)은 반드시 한국어(Korean)로 작성해야 합니다.**
- **State Management:** `Provider` + `Stream` (이벤트성 데이터).
- **Data:** JSON 기반.

## 5. 다음 단계 작업 (Next Steps)

1.  **아이템 시스템 고도화:** `items.json`에 `rarity`, `tier` 필드 추가 및 `ItemTable` 로직 수정.
2.  **[x] 상점 구매 기능:** `Shop` 스테이지 구매 UI 구현 (Tier/Rarity 기반 목록 생성).
3.  **적 등장 테이블 구현:** 스테이지별 등장 가능한 적 목록(`enemy_table_pool`) 설정 및 적용.
4.  **이미지 리소스 적용:** JSON 경로에 맞는 실제 이미지 파일 추가 및 UI 표시.
5.  **밸런싱 및 콘텐츠 확장:** 아이템/적 데이터 추가 및 밸런스 조정.

## 6. 장기 목표 (Future Roadmap / TODO)

- [ ] **출혈 상태 이상 조건 변경:** 공격 시 상대방의 방어도에 의해 공격이 완전히 막힐 경우, 출혈 상태 이상이 적용되지 않도록 로직 변경.
- [ ] **장비 분해 시스템 (적 장비):** 플레이어 장비의 옵션으로 상대방의 장비를 분해하여 '언암드' 상태로 만들 수 있는 시스템 구현.
- [ ] **플레이어 공격 데미지 분산(Variance) 적용 여부 검토:** 현재 적에게만 적용된 +/- 20% 데미지 분산을 플레이어에게도 적용할지 결정.
- [x] **애니메이션 및 타격감 고도화:**
  - 캐릭터별 이미지 추가 및 하스스톤 스타일의 공격 모션(대상에게 돌진 후 타격) 구현 완료 (Icon-Only Animation).
  - **Risky 공격:** 하스스톤의 7데미지 이상 타격감(화면 흔들림, 강렬한 파티클 및 임팩트) 구현 완료.
- [ ] **체력 조건부 특수 능력:** 캐릭터의 체력이 30% 미만일 때 발동 가능한 특수 능력 시스템 구현.
- [ ] **영구 스탯 수정자 로직 적용 (필수):**
  - 현재 `Character` 클래스에 `permanentModifiers` 필드만 선언되어 있음.
  - 추후 `totalAtk`, `totalDefense`, `totalMaxHp` 계산 시 이 수정자들을 반드시 반영해야 함.
- [ ] **Google OAuth 로그인 및 계정 연동:**
  - Firebase Auth 등을 활용한 구글 로그인 구현.
  - Firestore 또는 Realtime Database에 유저 계정 정보(진행 상황, 재화 등) 저장 및 불러오기 기능 추가.
  - _Note: 이 기능은 게임의 핵심 로직이 안정화된 후, 완전 나중에 진행할 예정입니다._
- [ ] **설정 페이지 (Settings Page) 구현 (Priority: Very Low):**
  - **이펙트 강도 조절 (Effect Intensity):** 1 ~ 999 범위로 설정 가능.
  - **Easter Egg:** 강도를 999로 설정하고 Risky 공격 성공 시, "심각한 오류로 프로세스가 종료되었습니다" 같은 페이크 시스템 팝업 출력.

---

**이 프롬프트를 읽은 AI 에이전트는 위 내용을 바탕으로 즉시 개발을 이어가십시오.**

## 7. 프롬프트 히스토리 (Prompt History)

- [x] 39_luck_system.md
- [x] 40_ui_update_summary.md
- [x] 41_refactoring_presets.md
- [x] 42_item_rarity_and_tier.md
- [x] 43_shop_system.md
- [x] 44_settings_and_local_storage.md