update

2025-12-07 17:58:00 +09:00
parent d5609aff0f
commit dcfb8ab9de
22 changed files with 612 additions and 165 deletions
@@ -73,8 +73,7 @@
 ### E. 스테이지 시스템 (`StageModel`)

 - **타입:** Battle, Shop, Rest, Elite.
- **적 생성:** 스테이지 레벨에 따른 스탯 스케일링 적용.
- **적 등장 테이블 (Enemy Pull):** 적 조우 시, 현재 스테이지(라운드)에 따라 등장 가능한 적 목록(`enemy_table_pull`)을 설정하여 해당 범위 내에서 적을 랜덤 생성해야 함.
+- **적 등장 테이블 (Enemy Pool):** 적 조우 시, 현재 스테이지(라운드)에 따라 등장 가능한 적 목록(`enemy_table_pool`)을 설정하여 해당 범위 내에서 적을 랜덤 생성해야 함.
 - **게임 구조 (Game Structure):**
  - **총 3라운드 (3 Rounds):** 각 라운드는 12개의 스테이지로 구성 (12/12/12).
  - **라운드 구성:**
@@ -115,7 +114,7 @@

 - **Prompt Driven Development:** `prompt/XX_description.md` 유지.
  - **유사 작업 통합:** 작업 내용이 이전 프롬프트와 유사한 경우 새로운 프롬프트를 생성하지 않고 기존 프롬프트에 내용을 추가합니다.
- **Language:** **모든 프롬프트 파일(prompt/XX_...)은 반드시 한국어(Korean)로 작성해야 합니다.**
+- **Language:** **모든 프롬프트 파일(prompt/XX\_...)은 반드시 한국어(Korean)로 작성해야 합니다.**
 - **Config Management:** 하드코딩되는 값들은 `config` 폴더 내 파일들(`lib/game/config/` 등)에서 통합 관리할 수 있도록 작성해야 합니다.
 - **State Management:** `Provider` + `Stream` (이벤트성 데이터).
 - **Data:** JSON 기반.
@@ -159,4 +158,10 @@
 - [x] 47_inventory_full_handling.md
 - [x] 48_refactor_stage_ui.md
 - [x] 49_implement_item_icons.md
-
+- [x] 50_expand_item_pool.md
+- [x] 51_refactor_prefix_table.md
+- [x] 52_round_based_enemy_pool.md
+- [x] 53_refine_stage_rewards.md
+- [x] 54_fix_shop_logic.md
+- [x] 55_fix_shop_ui_sync.md
+- [x] 56_permadeath_implementation.md
@@ -25,6 +25,7 @@
 - **`BattleScreen` (`lib/screens/battle_screen.dart`):**
  - 스테이지 클리어 보상 팝업의 아이템 아이콘 교체.
  - **플로팅 액션 버튼(FAB):** ATK/DEF 버튼의 아이콘을 `icon_weapon.png`와 `icon_shield.png`로 교체하고 흰색 틴트 적용.
+- **고해상도 이미지 처리:** 모든 `Image.asset` 위젯에 `filterQuality: FilterQuality.high`를 적용하여 이미지 축소 시 발생하는 앨리어싱(깨짐) 현상 완화.

 ## 3. 결과 (Result)
 - 게임 내 아이템 표현이 단순 기호에서 구체적인 이미지로 변경되어 시각적 몰입도가 향상되었습니다.
@@ -0,0 +1,31 @@
+# 53. 아이템 풀 확장 및 접두사 시스템 (Item Pool Expansion & Prefix System)
+
+## 1. 목표 (Goal)
+- 아이템 풀을 다양화하기 위해 `ItemRarity.normal`(일반 등급)을 추가합니다.
+- 일반 등급 아이템의 드랍 확률을 가장 높게 설정하고, 새로운 무기 데이터(Short Bow, Long Sword)를 추가합니다.
+- 일반 등급 아이템 생성 시 확률적으로 접두사(Crude, Old, High-quality)를 부여하여 스탯이 변동되는 시스템을 구현합니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### Enum 및 설정 업데이트
+- **`ItemRarity`:** `normal` 등급 추가 (가장 낮은 등급).
+- **`ThemeConfig` & `ItemUtils`:** `normal` 등급의 색상(흰색) 매핑 추가.
+- **`ItemConfig`:** `defaultRarityWeights`를 수정하여 Normal 등급이 가장 높은 확률(50%)을 가지도록 조정.
+
+### 데이터 추가 (`items.json`)
+- **신규 무기:**
+  - `short_bow` (Tier 1, Normal)
+  - `long_sword` (Tier 2, Normal)
+
+### 로직 구현 (`ItemTemplate`)
+- **`createItem` 메서드 수정:**
+  - **Normal 등급 로직:** 0~100 주사위를 굴려 접두사 부여.
+    - **0-25 (Crude/조잡한):** 이름에 "Crude " 추가, 모든 스탯 -10%.
+    - **26-50 (Old/낡은):** 이름에 "Old " 추가, 모든 스탯 -5%.
+    - **51-75 (Base):** 변동 없음.
+    - **76-100 (High-quality/상급):** 이름에 "High-quality " 추가, 모든 스탯 +10%.
+  - 스탯 계산 시 `GameMath` 또는 `floor`를 사용하여 정수형 유지.
+
+## 3. 결과 (Result)
+- 초반부 아이템 획득의 다양성이 증가하고, 같은 아이템이라도 접두사에 따라 성능 차이가 발생하여 파밍의 재미가 추가되었습니다.
+- `normal` 등급 아이템이 자주 등장하여 기본적인 장비 수급이 원활해졌습니다.
@@ -0,0 +1,27 @@
+# 54. 접두사 테이블 리팩토링 (Prefix Table Refactoring)
+
+## 1. 목표 (Goal)
+- `ItemTable`에 하드코딩되어 있던 Normal 등급 접두사 로직(이름, 배율, 확률)을 `ItemPrefixTable`로 이동하여 데이터 기반으로 관리합니다.
+- `ItemModifier` 클래스를 확장하여 스탯 배율(`multiplier`)과 가중치(`weight`)를 지원하도록 개선합니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### `ItemPrefixTable` 개선
+- **`ItemModifier` 구조 변경:**
+  - `multiplier`: 퍼센트 기반 스탯 변경을 위한 필드 추가 (기본값 1.0).
+  - `weight`: 랜덤 선택 가중치를 위한 필드 추가 (기본값 1).
+- **`normalPrefixes` 데이터 추가:**
+  - Crude (0.9, weight 25)
+  - Old (0.95, weight 25)
+  - Standard (1.0, weight 25, empty prefix)
+  - High-quality (1.1, weight 25)
+
+### `ItemTable` 로직 수정
+- **`createItem` 메서드:**
+  - 하드코딩된 `if-else` 확률 로직을 제거.
+  - `ItemPrefixTable.normalPrefixes`를 사용하여 가중치 기반 랜덤 선택(Weighted Random Selection) 알고리즘 구현.
+  - 선택된 Modifier의 `multiplier`를 적용하여 스탯 계산.
+
+## 3. 결과 (Result)
+- 접두사 데이터 추가 및 밸런스 조정이 `ItemPrefixTable` 수정만으로 가능해졌습니다.
+- 코드 중복이 줄어들고 확장성이 향상되었습니다.
@@ -0,0 +1,27 @@
+# 52. 라운드별 적 등장 시스템 (Round-based Enemy Pool)
+
+## 1. 목표 (Goal)
+- 게임 진행도(라운드)에 따라 등장하는 적들을 다르게 설정하여 난이도 곡선을 구현합니다.
+- `enemies.json` 데이터에 `tier` 필드를 추가하고, 스테이지에 맞는 적을 소환하는 로직을 `EnemyTable`에 구현합니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### 데이터 구조 변경 (`enemies.json` & `EnemyTemplate`)
+- **JSON:** `tier` 필드 추가 (1, 2, 3).
+  - **Tier 1:** Goblin, Slime, Wolf, Orc Warrior(Elite).
+  - **Tier 2:** Bandit, Skeleton, Giant Spider(Elite).
+  - **Tier 3:** Shadow Assassin, Armored Bear, Dark Knight(Elite).
+- **Template:** `tier` 필드를 파싱하고 저장하도록 클래스 업데이트.
+
+### 로직 구현 (`EnemyTable`)
+- **`getRandomEnemy(int stage)` 메서드 추가:**
+  - 현재 스테이지에 따라 목표 Tier를 결정 (1: 1~12, 2: 13~24, 3: 25+).
+  - 해당 Tier의 적 목록에서 랜덤 선택.
+  - 해당 Tier의 적이 없을 경우 하위 Tier 또는 전체 풀에서 선택하는 폴백 로직 포함.
+
+### 전투 연동 (`BattleProvider`)
+- `_prepareNextStage`에서 적 생성 시 `EnemyTable.getRandomEnemy`를 호출하여 스테이지에 적합한 적이 등장하도록 변경.
+
+## 3. 결과 (Result)
+- 게임 초반에는 약한 적, 후반에는 강한 적이 등장하여 단계적인 난이도 상승을 경험할 수 있습니다.
+- 데이터 주도적으로 적의 등장 시기를 제어할 수 있게 되었습니다.
@@ -0,0 +1,24 @@
+# 55. 스테이지 보상 로직 개선 (Refine Stage Reward Logic)
+
+## 1. 목표 (Goal)
+- 스테이지 티어(1~3) 및 타입(일반/엘리트)에 따라 아이템 보상의 희귀도(`Rarity`)를 조정하여 밸런스를 맞춥니다.
+- **Tier 1:** 일반 전투에서는 Rare 등급 이상 등장 불가 (최대 Magic). 엘리트 전투 승리 시 첫 번째 보상으로 Rare 등급 확정.
+- **Tier 2/3:** 엘리트 전투 승리 시 첫 번째 보상으로 Legendary 등급 확정.
+
+## 2. 구현 상세 (Implementation Details)
+
+### `ItemTable` 개선
+- **`getRandomItem` 메서드 확장:**
+  - `minRarity`, `maxRarity` 선택적 매개변수 추가.
+  - 가중치 랜덤 선택 전에 희귀도 범위를 기반으로 후보군 및 가중치를 필터링하는 로직 구현.
+
+### `BattleProvider` 수정
+- **`_onVictory` 메서드 로직 변경:**
+  - 현재 스테이지의 `Tier`와 `isElite` 여부를 확인.
+  - **Tier 1 Normal:** `maxRarity`를 `Magic`으로 제한.
+  - **Tier 1 Elite:** 첫 번째 보상 생성 시 `minRarity`와 `maxRarity`를 `Rare`로 고정 (확정 Rare).
+  - **Tier 2/3 Elite:** 첫 번째 보상 생성 시 `minRarity`를 `Legendary`로 설정 (확정 Legendary).
+  - 나머지 보상 슬롯(2, 3번)은 해당 티어의 일반적인 규칙(Tier 1은 Magic 제한)을 따름.
+
+## 3. 결과 (Result)
+- 초반(Tier 1)에 지나치게 강력한 아이템이 나오는 것을 방지하고, 엘리트 몬스터 처치에 대한 확실한 보상(확정 Rare/Legendary)을 제공하여 도전 욕구를 고취시켰습니다.
@@ -0,0 +1,22 @@
+# 56. 상점 UI 및 로직 디버깅 (Shop UI & Logic Debugging)
+
+## 1. 목표 (Goal)
+- 상점 구매 기능이 정상적으로 작동하지 않는 문제(성공 시에도 빨간색 에러 메시지 표시 등)를 해결합니다.
+- `ShopUI`에서 `ShopProvider`와의 연동 로직을 개선하여 사용자 피드백(SnackBar)을 명확하게 만듭니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### `ShopUI` 수정
+- **구매 확인 다이얼로그 (`_showBuyConfirmation`):**
+  - 기존: `buyItem` 호출 후 결과 확인 없이 다이얼로그 닫음 + `ShopProvider`의 메시지 상태에 의존하여 `build` 메서드에서 스낵바 출력 (타이밍 이슈 및 색상 고정 문제 발생).
+  - **변경:** `shopProvider.buyItem(item, player)`의 `bool` 반환값을 직접 확인.
+    - **성공 (`true`):** 다이얼로그 닫고 **초록색** "Bought [Item Name]" 스낵바 출력.
+    - **실패 (`false`):** 다이얼로그 닫고 **빨간색** 에러 메시지(Provider의 `lastShopMessage`) 스낵바 출력.
+- **불필요한 코드 제거:** `build` 메서드 내의 `WidgetsBinding.instance.addPostFrameCallback` 블록 삭제.
+
+### `ShopProvider` 확인
+- `buyItem` 메서드는 이미 성공/실패 여부를 `bool`로 반환하고, 실패 시 `_lastShopMessage`를 설정하도록 잘 구현되어 있음. (수정 불필요)
+
+## 3. 결과 (Result)
+- 상점 아이템 구매 성공 시 정상적으로 초록색 메시지가 뜨고, 골드 부족이나 인벤토리 가득 참 등의 실패 시에는 빨간색 에러 메시지가 뜹니다.
+- 구매 로직과 UI 피드백이 동기화되어 사용자 혼란을 방지했습니다.
@@ -0,0 +1,18 @@
+# 57. 상점 구매 UI 동기화 버그 수정 (Fix Shop Purchase UI Sync Bug)
+
+## 1. 목표 (Goal)
+- 상점에서 아이템 구매 성공 시, 인벤토리 및 골드 상태 변화가 UI에 즉시 반영되지 않는 문제를 해결합니다.
+- `ShopProvider`가 `BattleProvider` 소유의 `player` 객체를 수정했을 때, `BattleProvider`를 구독하는 위젯들이 갱신되도록 강제합니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### `BattleProvider`
+- `refreshUI()` 메서드 추가: 단순히 `notifyListeners()`를 호출하여 `BattleProvider`의 상태 변경을 알리는 public 메서드.
+
+### `ShopUI`
+- **`_showBuyConfirmation` 수정:**
+  - `shopProvider.buyItem` 호출 후 성공(`true`) 시, `battleProvider.refreshUI()`를 호출.
+  - 이를 통해 `InventoryScreen`이나 상단 바의 골드 표시 등 `BattleProvider`를 구독하는 모든 UI가 재빌드되어, 변경된 인벤토리와 골드 상태를 즉시 반영.
+
+## 3. 결과 (Result)
+- 상점 구매 직후 인벤토리에 아이템이 정상적으로 표시되고, 소모된 골드가 UI에 즉시 업데이트됩니다.
@@ -0,0 +1,21 @@
+# 58. 패배 시 저장 데이터 삭제 (Permadeath Implementation)
+
+## 1. 목표 (Goal)
+- 로그라이크 장르 특성에 맞춰 플레이어 패배(사망) 시 저장된 진행 데이터를 즉시 삭제하여 영구적인 죽음(Permadeath)을 구현합니다.
+
+## 2. 구현 상세 (Implementation Details)
+
+### `BattleProvider`
+- **`_onDefeat` 메서드 추가:**
+  - 비동기(`async`) 메서드.
+  - "Player defeated! Enemy wins!" 로그 추가.
+  - `SaveManager.clearSaveData()` 호출하여 저장 파일 삭제.
+  - `notifyListeners()` 호출하여 UI 갱신.
+- **패배 조건 체크 추가:**
+  - `playerAction`: 턴 시작 시 상태이상(출혈 등)으로 인한 사망 체크.
+  - `_enemyTurn`: 적 공격 후 및 턴 종료 시 사망 체크.
+  - 사망 확인 시 `_onDefeat` 호출.
+
+## 3. 결과 (Result)
+- 플레이어가 게임에서 패배하면 메인 메뉴로 돌아가더라도 '이어하기' 버튼이 활성화되지 않습니다(저장 데이터 삭제됨).
+- 긴장감 있는 게임 플레이 환경이 조성되었습니다.