# 로컬 TRPG 메이커 프로젝트 구조

이제까지 작성된 코드를 기반으로 전체 프로젝트의 구조를 정리하겠습니다. 각 파일과 함수들의 관계와 역할을 체계적으로 설명하겠습니다.

## 프로젝트 폴더 구조

```
📂 src/
├── config/                       # 환경 설정
│   ├── constants.py              # 상수 정의
│   └── styles.py                 # UI 스타일 정의
├── modules/                      # 기능 모듈
│   ├── ai_service.py             # AI 서비스 연동
│   ├── character_creation.py     # 캐릭터 생성 기능
│   ├── character_utils.py        # 캐릭터 관련 유틸리티
│   ├── game_play.py              # 게임 플레이 기능
│   ├── item_manager.py           # 아이템 관리 기능
│   └── world_description.py      # 세계관 설명 기능
├── utils/                        # 유틸리티 함수
│   ├── dice_roller.py            # 주사위 굴림 기능
│   ├── location_manager.py       # 위치 관리 기능
│   ├── session_manager.py        # 세션 상태 관리
│   └── theme_manager.py          # 테마 관리 기능
└── main.py                       # 메인 애플리케이션
```

## 파일별 주요 기능

### main.py
- 애플리케이션의 진입점
- 전체 UI 레이아웃 구성 및 단계 흐름 제어
- 세션 상태 초기화 및 관리
- 현재 단계(stage)에 따른 UI 표시 로직

### config/constants.py
- 애플리케이션 전반에서 사용되는 상수 정의
- 통합된 상수 관리로 일관성 유지
- 주요 상수: 스텟 이름, 테마 유형, AI 서비스 설정 등

### config/styles.py
- UI 스타일 관련 CSS 정의
- 일관된 디자인 시스템 유지
- 주요 스타일: 카드, 버튼, 패널, 알림 등의 스타일 정의

### modules/ai_service.py
- AI 서비스 연동 기능
- 주요 함수:
  - `setup_gemini()`: AI 모델 초기화
  - `generate_gemini_text()`: AI 모델로 텍스트 생성
  - `generate_world_description()`: 세계관 생성
  - `generate_character_options()`: 캐릭터 배경 옵션 생성
  - `generate_story_response()`: 주사위 결과에 따른 스토리 생성
  - `get_ability_suggestion()`: 행동에 적합한 능력치 제안
  - `master_answer_game_question()`: 마스터 질문 응답 생성

### modules/character_creation.py
- 캐릭터 생성 관련 기능
- 주요 함수:
  - `initialize_character_creation_state()`: 캐릭터 생성 상태 초기화
  - `display_character_creation_page()`: 캐릭터 생성 페이지 표시
  - `display_race_selection()`: 종족 선택 UI 표시
  - `display_profession_selection()`: 직업 선택 UI 표시
  - `display_background_selection()`: 배경 선택 UI 표시
  - `display_abilities_selection()`: 능력치 설정 UI 표시
  - `ability_roll_section()`: 주사위 굴림 기반 능력치 생성
  - `base_abilities_section()`: 기본 능력치 설정
  - `display_character_review()`: 캐릭터 최종 확인

### modules/character_utils.py
- 캐릭터 관련 유틸리티 함수
- 주요 함수:
  - `generate_races()`: 테마별 종족 목록 생성
  - `generate_professions()`: 테마별 직업 목록 생성
  - `extract_background_tags()`: 배경 스토리에서 태그 추출
  - `get_stat_info()`: 능력치 정보 및 시각적 표현 제공
  - `generate_special_trait()`: 캐릭터 특별 특성 생성

### modules/game_play.py
- 게임 플레이 핵심 기능
- 주요 함수:
  - `initialize_game_state()`: 게임 상태 초기화
  - `display_game_play_page()`: 게임 플레이 페이지 표시
  - `display_character_panel()`: 캐릭터 정보 패널 표시
  - `display_story_and_actions()`: 스토리 및 행동 UI 표시
  - `handle_action_phase()`: 행동 단계 관리
  - `handle_movement()`: 위치 이동 처리
  - `handle_ability_check()`: 능력치 판정 처리
  - `handle_action_suggestions()`: 행동 제안 관리
  - `handle_story_progression()`: 스토리 진행 처리
  - `display_game_tools()`: 게임 도구 패널 표시
  - `display_master_question_ui()`: 마스터 질문 UI 표시

### modules/item_manager.py
- 아이템 관리 기능
- 주요 함수 및 클래스:
  - `Item` 클래스: 아이템 데이터 및 메서드 정의
  - `initialize_inventory()`: 테마별 기본 인벤토리 초기화
  - `display_inventory()`: 인벤토리 아이템 표시
  - `display_inventory_for_review()`: 캐릭터 검토용 인벤토리 표시
  - `extract_items_from_story()`: 스토리에서 아이템 추출
  - `extract_used_items_from_story()`: 사용된 아이템 추출
  - `update_inventory()`: 인벤토리 아이템 추가/제거/사용

### modules/world_description.py
- 세계관 설명 관련 기능
- 주요 함수:
  - `world_description_page()`: 세계관 설명 페이지 표시
  - `process_question()`: 세계관 질문 처리
  - `handle_world_expansion()`: 세계관 확장 처리

### utils/dice_roller.py
- 주사위 관련 유틸리티
- 주요 함수:
  - `roll_dice()`: 기본 주사위 굴림
  - `calculate_dice_result()`: 주사위 표현식 계산
  - `display_dice_animation()`: 주사위 굴림 애니메이션

### utils/location_manager.py
- 위치 관련 유틸리티
- 주요 함수:
  - `generate_locations()`: 테마별 위치 생성
  - `generate_movement_story()`: 이동 스토리 생성
  - `get_location_image()`: 위치 이미지 생성

### utils/session_manager.py
- 세션 상태 관리 유틸리티
- 주요 함수:
  - `reset_game_session()`: 게임 세션 초기화
  - `initialize_session_state()`: 세션 상태 초기화

### utils/theme_manager.py
- 테마 관련 유틸리티
- 주요 함수:
  - `create_theme_image()`: 테마별 이미지 생성
  - `get_theme_description()`: 테마 설명 제공

## 주요 기능 흐름

1. **초기화 및 메인 UI**: `main.py`에서 시작하여 각 모듈 초기화
2. **테마 선택**: 사용자가 테마 선택 → `theme_manager.py`의 함수 활용
3. **세계관 생성**: `ai_service.py`를 통해 세계관 생성
4. **세계관 탐색**: `world_description.py`를 통해 세계관 확장 및 질문 처리
5. **캐릭터 생성**: `character_creation.py`의 단계별 함수를 통해 캐릭터 생성
6. **게임 플레이**: `game_play.py`를 통해 스토리 진행, 행동 처리, 능력치 판정 등

## 개선된 설계 특징

1. **모듈화**: 기능별로 명확히 분리된 모듈로 유지보수성 향상
2. **단일 책임 원칙**: 각 모듈과 함수가 명확한 하나의 책임을 가짐
3. **상태 관리**: 세션 상태를 효율적으로 관리하여 일관된 사용자 경험 제공
4. **UI/비즈니스 로직 분리**: 표시 로직과 비즈니스 로직을 분리
5. **확장성**: 새로운 기능, 테마, 아이템 등을 쉽게 추가할 수 있는 구조
6. **재사용성**: 공통 유틸리티 함수를 통해 코드 중복 제거

이 구조는 기존의 단일 파일 애플리케이션(app.py)에 비해 훨씬 더 체계적이고 유지보수하기 쉬운 코드베이스를 제공합니다. 각 모듈은 독립적으로 테스트하고 개발할 수 있으며, 전체 시스템의 복잡성을 관리하기 쉽게 합니다.