# 🎨 프론트엔드 파일 구조 문서

## 📁 디렉토리 구조

```
audio_validation_app/
├── app.py                    # 기존 파일 (백업용)
├── app_new.py               # 새로운 메인 앱 (컴포넌트 분리 버전)
│
├── frontend/                # 🆕 프론트엔드 디렉토리
│   ├── __init__.py
│   │
│   ├── app_ui.py           # UI 조립 메인 파일
│   │
│   ├── components/          # UI 컴포넌트
│   │   ├── __init__.py
│   │   ├── header.py           # 👨‍💻 개발자 A
│   │   ├── audio_input.py      # 👨‍💻 개발자 A
│   │   ├── history_display.py  # 👨‍💻 개발자 B
│   │   ├── failure_modal.py    # 👨‍💻 개발자 B
│   │   └── success_screen.py   # 👨‍💻 개발자 A
│   │
│   └── styles/              # CSS 스타일
│       └── custom_css.py
│
├── components/              # 백엔드 로직 (기존)
│   ├── audio_validator.py
│   └── ui_renderer.py
│
├── utils/                   # 유틸리티 (기존)
│   ├── stt_handler.py
│   └── state_manager.py
│
└── config/                  # 설정 (기존)
    └── settings.py
```

---

## 👥 팀 분담

### 👨‍💻 개발자 A: 입력 관련 컴포넌트

- `frontend/components/header.py` - 헤더 및 난이도 설정
- `frontend/components/audio_input.py` - 오디오 입력 및 검증 버튼
- `frontend/components/success_screen.py` - 성공 화면

### 👨‍💻 개발자 B: 피드백 관련 컴포넌트

- `frontend/components/history_display.py` - 실패 기록 표시
- `frontend/components/failure_modal.py` - 실패 팝업 모달

### 🤝 공통 작업

- `frontend/styles/custom_css.py` - CSS 스타일 (필요 시 각자 추가)
- `frontend/app_ui.py` - UI 조립 (최종 통합 시 수정)

---

## 📄 파일별 상세 설명

### 1. `frontend/app_ui.py` (UI 조립 메인)

**역할**: 모든 컴포넌트를 import하고 연결
**주요 클래스**: `AppUI`

```python
# 사용 예시
ui_builder = AppUI(validator, ui_renderer)
components = ui_builder.build()  # UI 빌드
ui_builder.setup_events(components, handlers)  # 이벤트 연결
```

**주요 메서드**:

- `build()`: 전체 UI 구성
- `setup_events()`: 이벤트 바인딩

---

### 2. `frontend/components/header.py` (👨‍💻 개발자 A)

**역할**: 앱 타이틀, 난이도 슬라이더, 목표 문장 표시

**주요 클래스**: `HeaderComponent`

**렌더링 컴포넌트**:

- 타이틀: "🎙️ 음성 검증 시스템"
- 난이도 슬라이더 (1-5)
- 현재 목표 문장 텍스트박스

**이벤트**:

- 난이도 변경 시 → 목표 문장 업데이트

**수정 가능 영역**:

- 타이틀 스타일 변경
- 슬라이더 범위/레이블 수정
- 설정 Accordion 내부에 추가 옵션 추가

---

### 3. `frontend/components/audio_input.py` (👨‍💻 개발자 A)

**역할**: 음성 녹음/업로드 및 검증 버튼

**주요 클래스**: `AudioInputComponent`

**렌더링 컴포넌트**:

- 목표 문장 표시 (Markdown)
- 오디오 입력 위젯 (녹음 + 업로드)
- 검증 버튼

**이벤트**:

- 검증 버튼 클릭 → `validate_audio_handler` 호출

**수정 가능 영역**:

- 버튼 텍스트/스타일
- 오디오 입력 설정 (샘플레이트 등)
- 목표 문장 표시 스타일

---

### 4. `frontend/components/history_display.py` (👨‍💻 개발자 B)

**역할**: 실패 기록을 HTML로 표시

**주요 클래스**: `HistoryDisplayComponent`

**렌더링 컴포넌트**:

- 실패 기록 HTML 영역

**데이터 흐름**:

- `ui_renderer.render_failure_history()` → HTML 생성
- 검증 실패 시 자동 업데이트

**수정 가능 영역**:

- 기록 표시 레이아웃
- 섹션 타이틀 변경
- 추가 통계 정보 표시

---

### 5. `frontend/components/failure_modal.py` (👨‍💻 개발자 B)

**역할**: 실패 시 팝업 모달로 결과 표시

**주요 클래스**: `FailureModalComponent`

**렌더링 컴포넌트**:

- Modal 컨테이너
- HTML 콘텐츠 영역
- 닫기 버튼

**정적 메서드**:

- `create_modal_content(recognized_text, score, hint)`: 모달 HTML 생성

**이벤트**:

- 닫기 버튼 클릭 → 모달 숨김

**수정 가능 영역**:

- 모달 HTML 템플릿 (색상, 레이아웃)
- 버튼 스타일
- 애니메이션 효과 추가

**모달 HTML 구조**:

```html
<div style="padding: 20px; text-align: center;">
  <h2>❌ 실패!</h2>
  <div><strong>인식된 텍스트:</strong> ...</div>
  <div><strong>점수:</strong> ...점</div>
  <div><strong>💡 힌트:</strong> ...</div>
</div>
```

---

### 6. `frontend/components/success_screen.py` (👨‍💻 개발자 B)

**역할**: 성공 시 전체 화면 전환

**주요 클래스**: `SuccessScreenComponent`

**렌더링 컴포넌트**:

- 성공 화면 컨테이너 (`elem_id="success-screen"`)
- 축하 메시지 (Markdown)
- 처음부터 다시 버튼

**이벤트**:

- 처음부터 다시 버튼 → `window.location.reload()` (JavaScript)

**수정 가능 영역**:

- 축하 메시지 텍스트/스타일
- 버튼 디자인
- 애니메이션 효과 추가

**CSS 연결**:
`frontend/styles/custom_css.py`의 `SUCCESS_SCREEN_CSS` 참조

---

### 7. `frontend/styles/custom_css.py` (공통)

**역할**: 전체 앱의 CSS 스타일 정의

**현재 CSS**:

- `#success-screen`: 성공 화면 전체 오버레이 스타일
  - 고정 위치 (position: fixed)
  - 보라색 그라데이션 배경
  - 중앙 정렬

**수정 가능**:

- 새로운 CSS 추가
- 색상 테마 변경
- 반응형 디자인 추가

**사용 방법**:

```python
from frontend.styles.custom_css import get_all_css

gr.Blocks(css=get_all_css())
```

---

## 🔄 데이터 흐름

### 검증 프로세스

1. **사용자 액션**: 오디오 업로드 → 검증 버튼 클릭
2. **핸들러 호출**: `validate_audio_handler(audio, difficulty, history, storage)`
3. **더미 로직 실행**:
   - 5번까지 실패 → 모달 표시 + 기록 추가
   - 6번째 성공 → 성공 화면 전환
4. **UI 업데이트**:
   - 실패: `failure_modal` 표시, `history_html` 업데이트
   - 성공: `main_screen` 숨김, `success_screen` 표시

### 상태 관리

- `gr.State`: 세션 상태 (새로고침 시 초기화)

  - `difficulty`: 현재 난이도
  - `failure_history`: 실패 기록 리스트

- `gr.BrowserState`: localStorage 영구 저장
  - `storage_key="audio_validation_history"`
  - 구조: `{"date": "YYYY-MM-DD", "failures": [...], "successes": [...]}`
  - 날짜 변경 시 자동 초기화

---

## 🛠️ 개발 가이드

### 컴포넌트 수정 시

1. 해당 컴포넌트 파일만 수정
2. 클래스의 `render()` 메서드에서 UI 구성
3. 필요 시 `setup_events()` 메서드에서 이벤트 연결

### 새 컴포넌트 추가 시

1. `frontend/components/` 에 새 파일 생성
2. 클래스 작성 (`render()`, `setup_events()` 메서드 구현)
3. `frontend/app_ui.py`에서 import 및 연결

### CSS 스타일 추가 시

1. `frontend/styles/custom_css.py`에 CSS 문자열 추가
2. `get_all_css()` 함수에서 반환값에 포함

---

## 🧪 테스트 방법

### 개별 컴포넌트 테스트

각 컴포넌트는 독립적으로 테스트 가능:

```python
# header.py 테스트
from frontend.components.header import HeaderComponent
from components.audio_validator import AudioValidator

validator = AudioValidator(config)
header = HeaderComponent(validator)
# Gradio 앱에서 header.render() 호출
```

### 통합 테스트

```bash
python app_new.py
```

---

## 📝 커밋 컨벤션 (권장)

```
[개발자A] header: 난이도 슬라이더 범위 수정
[개발자B] modal: 실패 모달 스타일 개선
[공통] css: 반응형 디자인 추가
```

---

## 🔧 백엔드 연결 (추후 작업)

현재 더미 데이터로 동작하며, 실제 백엔드 연결 시:

1. `app_new.py`의 `validate_audio_handler()` 수정
2. `components/audio_validator.py` 로직 활성화
3. `utils/stt_handler.py` 실제 STT API 연결

**변경이 필요한 부분**:

```python
# app_new.py:72-90 (더미 데이터 부분)
# 실제 검증 로직으로 교체
result = self.validator.validate(audio_path, expected_text)
recognized_text = result['text']
score = result['score']
```

---

## 📚 참고 문서

- **Gradio 공식 문서**: `docs/GRADIO_BASICS.md`
- **Gradio Modal 컴포넌트**: https://huggingface.co/spaces/aliabid94/gradio_modal
- **기존 앱 구조**: `app.py` (백업)

---

## 🚀 시작하기

### 1. 환경 설정

```bash
# 가상환경 활성화
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# 의존성 설치 (gradio_modal 추가)
pip install gradio_modal
```

### 2. 앱 실행

```bash
# 새로운 컴포넌트 분리 버전
python app_new.py

# 기존 버전 (백업)
python app.py
```

### 3. 브라우저 접속

```
http://localhost:7860
```

---

## ❓ FAQ

### Q1: 개발자 A와 B가 동시에 작업하면 충돌이 나지 않나요?

**A**: 각자 다른 파일을 수정하므로 Git 충돌이 거의 없습니다. `app_ui.py`만 최종 통합 시 조심히 병합하면 됩니다.

### Q2: 컴포넌트 간 통신은 어떻게 하나요?

**A**: `app_ui.py`의 `setup_events()`에서 이벤트를 연결합니다. 각 컴포넌트는 독립적이며, 상태는 `gr.State`를 통해 공유됩니다.

### Q3: CSS를 컴포넌트별로 분리할 수 있나요?

**A**: 네, `frontend/styles/` 에 여러 파일을 만들고 `get_all_css()`에서 합칠 수 있습니다.

### Q4: 기존 app.py는 삭제해야 하나요?

**A**: 아니요, 백업용으로 남겨두세요. `app_new.py`가 안정화되면 교체하면 됩니다.

### Q5: "Cannot call change outside of a gradio.Blocks context" 에러가 발생합니다!

**A**: Gradio 이벤트(`.click()`, `.change()` 등)는 반드시 `gr.Blocks()` 컨텍스트 내부에서 호출해야 합니다.

**문제 상황**:

```python
# ❌ 잘못된 방법
with gr.Blocks() as demo:
    components = build()  # UI만 빌드
    return components

# gr.Blocks 컨텍스트 밖에서 이벤트 바인딩 (에러 발생!)
setup_events(components)
```

**해결 방법**:

```python
# ✅ 올바른 방법
with gr.Blocks() as demo:
    components = build()  # UI 빌드
    setup_events(components)  # 이벤트 바인딩도 여기서!
    return components
```

**현재 구조에서의 구현**:

- `frontend/app_ui.py`의 `build(handlers)` 메서드 안에서 UI 렌더링과 이벤트 바인딩을 모두 수행
- 각 컴포넌트의 `setup_events()` 메서드는 `gr.Blocks()` 컨텍스트 내부에서 호출됨

---

## 📞 연락처

문제가 발생하면:

1. 해당 컴포넌트 파일의 docstring 확인
2. `GRADIO_BASICS.md` 참고
3. 팀 채널에 질문

---

## 📝 변경 이력

### v1.1 (2024-11-25)

- FAQ Q5 추가: Gradio 이벤트 바인딩 컨텍스트 이슈 해결 방법
- `app_ui.py` 구조 개선: `build()` 메서드에서 이벤트 바인딩 통합

### v1.0 (2024-11-24)

- 초기 문서 작성
- 프론트엔드 컴포넌트 분리 구조 설계

---

**최종 수정일**: 2024-11-25
**버전**: 1.1
**작성자**: Claude Code Assistant