docs: 개발 계획 및 감사 보고서 추가

- PLAN.md: 개발 계획 문서 - doc/audit-report-2026-02-13.md: 코드 감사 보고서
2026-02-13 16:08:18 +09:00
parent 6994f4fc9b
commit bccb5cb188
2 changed files with 790 additions and 0 deletions
--- a/PLAN.md
+++ b/PLAN.md
@@ -0,0 +1,250 @@
+# 종족/클래스 패시브 미반영 수정 계획
+
+## 1. 현황 분석
+
+### 반영되는 패시브 (전투 스탯 계산에 적용됨)
+- HP/MP 보너스, 물리/마법 데미지 보너스, 방어력/회피율/크리티컬 보너스
+
+### 미반영 패시브 (정의만 있고 실제 로직에서 미사용)
+
+| 패시브 | 영향받는 종족/클래스 | 수정 위치 |
+|--------|---------------------|-----------|
+| `expMultiplier` | Byte Human (+5%), Callback Seraph (+3%) | `progress_service.dart:387` |
+| `firstStrikeBonus` | Pointer Assassin (1.5배) | `combat_tick_service.dart` |
+| `multiAttack` | Refactor Monk | `combat_tick_service.dart` |
+| `postCombatHeal` | Garbage Collector (+5%) | `progress_service.dart:279` |
+| `healingBonus` | Debugger Paladin, Exception Handler, Null Checker | `potion_service.dart`, `skill_service.dart` |
+| `deathEquipmentPreserve` | Coredump Undead | **특성 변경 필요** |
+
+---
+
+## 2. 수정 내용
+
+### 2.1 경험치 배율 (`expMultiplier`)
+
+**파일**: `lib/src/core/engine/progress_service.dart`
+
+**위치**: 384-387줄
+
+**현재 코드**:
+```dart
+if (gain && nextState.traits.level < 100 && monsterExpReward > 0) {
+  final newExpPos = progress.exp.position + monsterExpReward;
+```
+
+**수정 후**:
+```dart
+if (gain && nextState.traits.level < 100 && monsterExpReward > 0) {
+  // 종족 경험치 배율 적용 (예: Byte Human +5%)
+  final race = RaceData.findById(nextState.traits.raceId);
+  final expMultiplier = race?.expMultiplier ?? 1.0;
+  final adjustedExp = (monsterExpReward * expMultiplier).round();
+  final newExpPos = progress.exp.position + adjustedExp;
+```
+
+---
+
+### 2.2 첫 공격 배율 (`firstStrikeBonus`)
+
+**파일**: `lib/src/core/engine/combat_tick_service.dart`
+
+**설계**:
+- 전투 시작 시 첫 공격인지 추적하는 플래그 필요
+- 첫 공격 시 `firstStrikeBonus` 배율 적용
+
+**수정 방안**:
+1. `CombatState`에 `isFirstAttack` 플래그 추가
+2. `CombatTickService`에서 첫 플레이어 공격 시 배율 적용:
+```dart
+var damage = result.damage;
+if (isFirstPlayerAttack && firstStrikeBonus > 1.0) {
+  damage = (damage * firstStrikeBonus).round();
+  isFirstPlayerAttack = false;
+}
+```
+
+---
+
+### 2.3 연속 공격 (`multiAttack`)
+
+**파일**: `lib/src/core/engine/combat_tick_service.dart`
+
+**설계**:
+- `hasMultiAttack` 패시브가 있으면 일정 확률로 추가 공격
+- 예: 30% 확률로 연속 공격 (2타)
+
+**수정 방안**:
+```dart
+// 플레이어 공격 후
+if (hasMultiAttack && rng.nextDouble() < 0.3) {
+  // 추가 공격 실행
+  final extraAttack = calculator.playerAttackMonster(...);
+  // 결과 합산
+}
+```
+
+---
+
+### 2.4 전투 후 HP 회복 (`postCombatHeal`)
+
+**파일**: `lib/src/core/engine/progress_service.dart`
+
+**위치**: 276-280줄
+
+**현재 코드**:
+```dart
+// 전투 승리 시 HP 회복 (50% + CON/2)
+final conBonus = nextState.stats.con ~/ 2;
+final healAmount = (maxHp * 0.5).round() + conBonus;
+```
+
+**수정 후**:
+```dart
+// 전투 승리 시 HP 회복 (50% + CON/2 + 클래스 패시브)
+final conBonus = nextState.stats.con ~/ 2;
+var healAmount = (maxHp * 0.5).round() + conBonus;
+
+// 클래스 패시브: 전투 후 HP 회복 (Garbage Collector +5%)
+final klass = ClassData.findById(nextState.traits.classId);
+if (klass != null) {
+  final postCombatHealRate = klass.getPassiveValue(ClassPassiveType.postCombatHeal);
+  if (postCombatHealRate > 0) {
+    healAmount += (maxHp * postCombatHealRate).round();
+  }
+}
+```
+
+---
+
+### 2.5 회복력 보너스 (`healingBonus`)
+
+물약/스킬 사용 시 추가 회복 적용
+
+#### 2.5.1 물약 회복
+
+**파일**: `lib/src/core/engine/potion_service.dart`
+
+**수정 위치**: `usePotion()` 메서드 (73-81줄)
+
+**현재 코드**:
+```dart
+if (potion.isHpPotion) {
+  healedAmount = potion.calculateHeal(maxHp);
+  newHp = (currentHp + healedAmount).clamp(0, maxHp);
+```
+
+**수정 후**:
+```dart
+if (potion.isHpPotion) {
+  var baseHeal = potion.calculateHeal(maxHp);
+  // 회복력 보너스 적용 (클래스 패시브)
+  baseHeal = (baseHeal * healingMultiplier).round();
+  newHp = (currentHp + baseHeal).clamp(0, maxHp);
+  healedAmount = newHp - currentHp;
+```
+
+**참고**: `PotionService`에 `healingMultiplier` 파라미터 추가 필요
+
+#### 2.5.2 스킬 회복
+
+**파일**: `lib/src/core/engine/skill_service.dart`
+
+**수정 위치**: `useHealSkill()` 메서드 (125-132줄)
+
+**현재 코드**:
+```dart
+int healAmount = skill.healAmount;
+if (skill.healPercent > 0) {
+  healAmount += (player.hpMax * skill.healPercent).round();
+}
+```
+
+**수정 후**:
+```dart
+int healAmount = skill.healAmount;
+if (skill.healPercent > 0) {
+  healAmount += (player.hpMax * skill.healPercent).round();
+}
+// 회복력 보너스 적용 (클래스 패시브)
+healAmount = (healAmount * healingMultiplier).round();
+```
+
+**참고**: `SkillService`에 `healingMultiplier` 파라미터 추가 필요
+
+---
+
+### 2.6 Coredump Undead 특성 변경
+
+**현재 특성**: `deathEquipmentPreserve` (사망 시 장비 1개 유지) - BM 침해
+
+**대체 특성 제안** (언데드 콘셉트에 어울리는 것):
+
+| 옵션 | 설명 | 장점 |
+|------|------|------|
+| **방어력 +10%** | 언데드는 고통을 느끼지 않아 피해 감소 | 구현 간단, CON+2와 시너지 |
+| **HP +8%** | 불사의 육체 | 구현 간단, 생존형 콘셉트 유지 |
+| **HP +5% + 방어력 +5%** | 복합 생존 특화 | 다른 종족과 차별화 |
+
+**추천**: `defenseBonus: 0.10` (방어력 +10%)
+- 이유: 언데드의 "고통을 느끼지 않는" 콘셉트와 어울림
+- 기존 CON+2, STR+1 스탯과 탱커형 시너지
+
+**파일**: `lib/data/race_data.dart`
+
+**수정**:
+```dart
+static const coredumpUndead = RaceTraits(
+  raceId: 'coredump_undead',
+  name: 'Coredump Undead',
+  statModifiers: {
+    StatType.con: 2,
+    StatType.str: 1,
+    StatType.cha: -2,
+    StatType.dex: -1,
+  },
+  passives: [
+    PassiveAbility(
+      type: PassiveType.defenseBonus,  // 변경
+      value: 0.10,                      // 변경
+      description: '방어력 +10%',       // 변경
+    ),
+  ],
+);
+```
+
+---
+
+## 3. 수정 순서
+
+1. **Coredump Undead 특성 변경** - 단순 데이터 수정
+2. **경험치 배율** - 간단한 로직 추가
+3. **전투 후 HP 회복** - 간단한 로직 추가
+4. **회복력 보너스** - 서비스 파라미터 수정 필요
+5. **첫 공격 배율** - 전투 상태 추적 필요
+6. **연속 공격** - 전투 로직 수정 필요
+
+---
+
+## 4. 검증 방법
+
+1. `flutter analyze` 통과
+2. 각 패시브가 적용된 종족/클래스로 캐릭터 생성
+3. 실제 게임 플레이로 효과 확인:
+   - Byte Human: 경험치 +5% (레벨업 속도)
+   - Pointer Assassin: 첫 공격 1.5배 (전투 시작 데미지)
+   - Refactor Monk: 연속 공격 (추가 타격)
+   - Garbage Collector: 전투 후 +5% HP 회복
+   - Debugger Paladin: 물약/스킬 회복량 +10%
+   - Coredump Undead: 방어력 +10%
+
+---
+
+## 5. 삭제할 코드
+
+**파일**: `lib/src/core/model/race_traits.dart`
+
+`PassiveType.deathEquipmentPreserve` enum 삭제 (사용되지 않음)
+
+**파일**: `lib/src/core/engine/stat_calculator.dart`
+
+`calculateDeathEquipmentPreserve()` 메서드 삭제 (사용되지 않음)