docs: CHANGELOG 및 아키텍처 문서 추가

- CHANGELOG.md: 리팩토링 내역 기록 - docs/ARCHITECTURE.md: ASCII 다이어그램으로 구조 시각화
2026-01-21 17:34:11 +09:00
parent 97b40ccb1f
commit 742b0d1773
2 changed files with 254 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,46 @@
+# Changelog
+
+프로젝트의 주요 변경 사항을 기록합니다.
+
+## [Unreleased]
+
+### Refactored (리팩토링)
+
+#### GameSessionController 분할 (SRP 개선)
+- 920 LOC → 526 LOC (43% 감소)
+- 5개 매니저로 책임 분리:
+  - `GameStatisticsManager` - 세션/누적 통계 추적
+  - `SpeedBoostManager` - 광고 배속 부스트 기능
+  - `ReturnRewardsManager` - 복귀 보상 기능
+  - `ResurrectionManager` - 사망/부활 처리
+  - `HallOfFameManager` - 명예의 전당 관리
+
+#### ProgressService 메서드 분할
+- `tick()`: 350 LOC → 80 LOC (8개 헬퍼 메서드)
+- `_generateNextTask()`: 200 LOC → 35 LOC (6개 헬퍼 메서드)
+
+#### GamePlayScreen 메서드 분할
+- `build()`: 300 LOC → 15 LOC (5개 헬퍼 메서드)
+
+#### Clean Architecture 개선
+- `MonsterGrade.displayColor` (Color) → `displayColorCode` (int)
+- Domain 레이어에서 Flutter 의존성 제거
+
+### Fixed (버그 수정)
+
+#### Analyzer 경고 정리
+- 미사용 import 제거 (`panel_header.dart`)
+- 미사용 필드 제거 (`new_character_screen.dart`)
+- JsonKey 경고 억제 (`equipment_item.dart`, `monetization_state.dart`)
+
+---
+
+## 버전 표기 규칙
+
+- `Added`: 새로운 기능 추가
+- `Changed`: 기존 기능 변경
+- `Deprecated`: 곧 제거될 기능
+- `Removed`: 제거된 기능
+- `Fixed`: 버그 수정
+- `Security`: 보안 관련 수정
+- `Refactored`: 코드 구조 개선 (기능 변화 없음)
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,208 @@
+# 아키텍처 문서
+
+## 디렉토리 구조
+
+```
+lib/
+├── main.dart                 # 앱 진입점
+├── data/                     # 정적 데이터 (Config.dfm 추출)
+│   ├── pq_config_data.dart
+│   ├── race_data.dart
+│   ├── class_data.dart
+│   └── skill_data.dart
+├── l10n/                     # i18n 생성 파일
+└── src/
+    ├── app.dart              # MaterialApp 설정
+    ├── core/                 # 도메인 레이어
+    │   ├── animation/        # ASCII 애니메이션
+    │   ├── audio/            # 오디오 서비스
+    │   ├── engine/           # 게임 로직
+    │   ├── model/            # 데이터 모델
+    │   ├── storage/          # 저장/로드
+    │   └── util/             # 유틸리티
+    ├── features/             # 프레젠테이션 레이어
+    │   ├── arena/            # 아레나 화면
+    │   ├── front/            # 프론트 화면
+    │   ├── game/             # 게임 화면
+    │   ├── hall_of_fame/     # 명예의 전당
+    │   ├── new_character/    # 캐릭터 생성
+    │   └── settings/         # 설정
+    └── shared/               # 공통 위젯/스타일
+```
+
+## 레이어 구조 (Clean Architecture)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Presentation Layer                        │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Screens   │  │   Widgets   │  │     Controllers     │  │
+│  │  (features/)│  │  (widgets/) │  │  (game_session_     │  │
+│  │             │  │             │  │   controller.dart)  │  │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
+└─────────┼────────────────┼───────────────────┼──────────────┘
+          │                │                   │
+          ▼                ▼                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Domain Layer                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Models    │  │   Services  │  │      Managers       │  │
+│  │  (model/)   │  │  (engine/)  │  │  (game/managers/)   │  │
+│  │             │  │             │  │                     │  │
+│  │ - GameState │  │ - Progress  │  │ - Statistics        │  │
+│  │ - Equipment │  │ - Combat    │  │ - SpeedBoost        │  │
+│  │ - Skills    │  │ - Item      │  │ - ReturnRewards     │  │
+│  └─────────────┘  └─────────────┘  │ - Resurrection      │  │
+│                                    │ - HallOfFame        │  │
+│                                    └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+          │                │                   │
+          ▼                ▼                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       Data Layer                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │  Static     │  │   Storage   │  │     External        │  │
+│  │  Data       │  │             │  │     Services        │  │
+│  │  (data/)    │  │  (storage/) │  │                     │  │
+│  │             │  │             │  │ - AdService         │  │
+│  │ - Config    │  │ - SaveMgr   │  │ - IAPService        │  │
+│  │ - Races     │  │ - HallOfFame│  │ - AudioService      │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## GameSessionController 매니저 구조
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                   GameSessionController                       │
+│                        (526 LOC)                             │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  핵심 책임:                                              │  │
+│  │  - 게임 루프 관리 (startNew, pause, resume)             │  │
+│  │  - 콜백 처리 (_onPlayerDied, _onGameComplete)          │  │
+│  │  - 상태 관리 (GameState, MonetizationState)            │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                           │                                  │
+│           ┌───────────────┼───────────────┐                  │
+│           ▼               ▼               ▼                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │ Statistics  │  │ SpeedBoost  │  │  Return     │          │
+│  │  Manager    │  │  Manager    │  │  Rewards    │          │
+│  │  (140 LOC)  │  │  (190 LOC)  │  │  (180 LOC)  │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+│           │               │               │                  │
+│           ▼               ▼               ▼                  │
+│  ┌─────────────┐  ┌─────────────┐                           │
+│  │Resurrection │  │ HallOfFame  │                           │
+│  │  Manager    │  │  Manager    │                           │
+│  │  (160 LOC)  │  │  (130 LOC)  │                           │
+│  └─────────────┘  └─────────────┘                           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 매니저별 책임
+
+| 매니저 | 파일 | 책임 |
+|--------|------|------|
+| `GameStatisticsManager` | `game_statistics_manager.dart` | 세션/누적 통계, 레벨업/골드/처치 추적 |
+| `SpeedBoostManager` | `speed_boost_manager.dart` | 광고 배속, 버프 만료 체크 |
+| `ReturnRewardsManager` | `return_rewards_manager.dart` | 복귀 보상 계산, 상자 보상 적용 |
+| `ResurrectionManager` | `resurrection_manager.dart` | 일반/광고 부활, 자동부활 조건 |
+| `HallOfFameManager` | `hall_of_fame_manager.dart` | 명예의 전당 등록, 테스트 캐릭터 |
+
+## 게임 루프 흐름
+
+```
+┌─────────────┐
+│  startNew() │
+└──────┬──────┘
+       │
+       ▼
+┌──────────────────┐
+│   ProgressLoop   │◄──────┐
+│    (50ms tick)   │       │
+└────────┬─────────┘       │
+         │                 │
+         ▼                 │
+┌──────────────────┐       │
+│ ProgressService  │       │
+│    .tick()       │       │
+└────────┬─────────┘       │
+         │                 │
+    ┌────┴────┐            │
+    │         │            │
+    ▼         ▼            │
+┌───────┐ ┌───────┐        │
+│ Task  │ │ Quest │        │
+│Process│ │/Plot  │        │
+└───┬───┘ └───┬───┘        │
+    │         │            │
+    └────┬────┘            │
+         │                 │
+         ▼                 │
+┌──────────────────┐       │
+│  State Stream    │───────┘
+│  → UI Update     │
+└──────────────────┘
+         │
+         ▼
+┌──────────────────┐
+│   AutoSave       │
+│   (30초 간격)     │
+└──────────────────┘
+```
+
+## 데이터 흐름
+
+```
+User Action
+     │
+     ▼
+┌─────────────────┐
+│ GamePlayScreen  │
+│   (UI Layer)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ GameSession     │
+│ Controller      │
+└────────┬────────┘
+         │
+    ┌────┴────┬────────┬────────┐
+    │         │        │        │
+    ▼         ▼        ▼        ▼
+┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
+│Progres│ │Stats  │ │Resurre│ │HallOf │
+│sLoop  │ │Manager│ │ction  │ │Fame   │
+└───┬───┘ └───────┘ │Manager│ │Manager│
+    │               └───────┘ └───────┘
+    ▼
+┌─────────────────┐
+│ProgressService  │
+│ (Game Logic)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   GameState     │
+│  (Immutable)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   SaveManager   │
+│  (Persistence)  │
+└─────────────────┘
+```
+
+## 원본 PQ 알고리즘 매핑
+
+| PQ 원본 (Delphi) | 포팅 위치 |
+|-----------------|----------|
+| `Main.pas:MonsterTask` | `progress_service.dart:_createMonsterTask()` |
+| `Main.pas:StartTimer` | `progress_loop.dart:tick()` |
+| `NewGuy.pas:RerollClick` | `character_roll_service.dart` |
+| `Config.dfm` 데이터 | `data/pq_config_data.dart` |