# 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`