From 742b0d17731b28a466b480ac2a67b495724ae377 Mon Sep 17 00:00:00 2001 From: JiWoong Sul Date: Wed, 21 Jan 2026 17:34:11 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CHANGELOG=20=EB=B0=8F=20=EC=95=84?= =?UTF-8?q?=ED=82=A4=ED=85=8D=EC=B2=98=20=EB=AC=B8=EC=84=9C=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CHANGELOG.md: 리팩토링 내역 기록 - docs/ARCHITECTURE.md: ASCII 다이어그램으로 구조 시각화 --- CHANGELOG.md | 46 ++++++++++ docs/ARCHITECTURE.md | 208 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 254 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 docs/ARCHITECTURE.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..05d61f8 --- /dev/null +++ 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`: 코드 구조 개선 (기능 변화 없음) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..44bcdcd --- /dev/null +++ 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` |