feat: 초기 커밋

- Progress Quest 6.4 Flutter 포팅 프로젝트 - 게임 루프, 상태 관리, UI 구현 - 캐릭터 생성, 인벤토리, 장비, 주문 시스템 - 시장/판매/구매 메커니즘
2025-12-09 17:24:04 +09:00
commit 08054d97c1
168 changed files with 12876 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 프로젝트 개요
+
+Askii Never Die는 Progress Quest 6.4 (Delphi 원본)를 Flutter로 100% 동일하게 복제하는 오프라인 싱글플레이어 RPG입니다. 네트워크 기능은 모두 제외되며, 원본 알고리즘과 데이터를 그대로 유지해야 합니다.
+
+## 빌드 및 실행
+
+```bash
+# 의존성 설치
+flutter pub get
+
+# 실행 (플랫폼 지정 가능: -d macos, -d chrome 등)
+flutter run
+
+# 핸드오프 전 필수 검증
+dart format --set-exit-if-changed .
+flutter analyze
+flutter test
+```
+
+## 아키텍처
+
+### 디렉토리 구조
+
+```
+lib/
+├── main.dart                      # 앱 진입점
+├── data/pq_config_data.dart       # PQ 정적 데이터 (Config.dfm 추출)
+└── src/
+    ├── app.dart                   # MaterialApp 설정
+    ├── core/
+    │   ├── engine/                # 게임 루프 및 진행 로직
+    │   │   ├── progress_loop.dart     # 타이머 기반 메인 루프 (원본 200ms)
+    │   │   ├── progress_service.dart  # 틱 처리, 경험치/레벨업 로직
+    │   │   ├── game_mutations.dart    # 상태 변경 함수
+    │   │   └── reward_service.dart    # 보상 처리
+    │   ├── model/
+    │   │   ├── game_state.dart        # 핵심 상태: Traits, Stats, Inventory, Equipment, SpellBook, ProgressState, QueueState
+    │   │   ├── pq_config.dart         # Config 데이터 접근
+    │   │   ├── equipment_slot.dart    # 장비 슬롯 정의
+    │   │   └── save_data.dart         # 저장 데이터 구조
+    │   ├── storage/                   # 세이브 파일 처리
+    │   └── util/
+    │       ├── deterministic_random.dart  # 결정론적 RNG (재현 가능)
+    │       ├── pq_logic.dart              # 원본 로직 포팅 (odds, randSign 등)
+    │       └── roman.dart                 # 로마 숫자 변환
+    └── features/
+        ├── front/front_screen.dart        # 임시 프론트 화면
+        └── game/game_session_controller.dart  # 게임 세션 관리
+
+example/pq/     # Delphi 원본 소스 (참조용, 빌드 대상 아님)
+test/           # 단위/위젯 테스트
+```
+
+### 레이어 구조 (Clean Architecture)
+
+- **Presentation** (`features/`) → **Domain** (`core/model/`, `core/engine/`) → **Data** (`data/`, `core/storage/`)
+- 역방향 의존 금지: Domain은 Flutter/UI import 불가
+
+### 핵심 데이터 흐름
+
+1. `ProgressLoop`가 타이머로 `tickOnce()` 호출
+2. `ProgressService.tick()`이 GameState 업데이트
+3. GameState 스트림으로 UI 갱신
+4. 레벨업/퀘스트 완료 시 `SaveManager` 자동 저장
+
+## 핵심 규칙
+
+### 원본 충실도
+- `example/pq/` 내 Delphi 소스의 알고리즘/데이터를 100% 동일하게 포팅
+- 원본 로직 변경 필요 시 반드시 사용자 승인 필요
+- 새로운 기능, 값, 처리 로직 추가 금지 (디버깅 로그 예외)
+
+### 데이터 관리
+- 정적 데이터(몬스터, 아이템, 주문 등)는 `Config.dfm`에서 추출하여 JSON/Dart const로 관리
+- 영문 원문 기준 작성, UI 텍스트는 i18n 구조로 분리
+- 이미지 파일 미사용
+
+### 코딩 표준
+- 2-space 인덴트, `dart format` 준수
+- 타입 명시적 선언, `any`/`dynamic` 지양
+- 파일명: snake_case, 클래스: PascalCase, 변수/함수: camelCase
+- 파일당 200 LOC 이하, 함수 20 라인 이하 권장
+- SRP(Single Responsibility Principle) 준수
+
+### 화면 구성
+- 2개 화면만 사용: 캐릭터 생성 화면, 게임 진행 화면
+- 화면 내 요소는 위젯 단위로 분리
+
+## 원본 소스 참조 (example/pq/)
+
+| 파일 | 핵심 함수/라인 | 역할 |
+|------|----------------|------|
+| `Main.pas:523-1040` | `MonsterTask` | 전투/전리품/레벨업 |
+| `Main.pas:267-424` | `StartTimer` | 메인 게임 루프 |
+| `Main.pas:456-521` | `InterplotCinematic`, `NamedMonster` | 시네마틱/명명 |
+| `NewGuy.pas:55-68` | `RerollClick` | 캐릭터 생성 (3d6) |
+| `Config.dfm` | TMemo 데이터 | 주문, 몬스터, 아이템, 종족, 직업 등 |
+
+## 승인 필요 사항
+
+- `pubspec.yaml` 의존성 변경
+- 플랫폼 빌드 설정 (Android/iOS/desktop)
+- 네트워크 접근 도입
+- 원본 데이터/알고리즘 수정
+- 대규모 파일 삭제 또는 구조 변경
+
+## 커밋 규칙
+
+```
+type(scope): 한국어 설명
+
+- 변경 상세 내용
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `style`, `chore`, `perf`