client/FRONTEND_STRUCTURE.md

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

📁 디렉토리 구조

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

# 사용 예시
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 구조:

<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 추가
• 색상 테마 변경
• 반응형 디자인 추가

사용 방법:

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() 함수에서 반환값에 포함

---

🧪 테스트 방법

개별 컴포넌트 테스트

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

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

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

통합 테스트

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 연결

변경이 필요한 부분:

# 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. 환경 설정

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

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

2. 앱 실행

# 새로운 컴포넌트 분리 버전
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() 컨텍스트 내부에서 호출해야 합니다.

문제 상황:

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

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

해결 방법:

# ✅ 올바른 방법
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