shinalok/youlbot-webui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e08b43c7851e0f97a172cf19c97adfa0df9d111c
youlbot-webui/ROADMAP.md
T
shinalok e08b43c785 UI/UX D0: fix Textbox label, hide audio accordion, hide footer, hide ingest result box 
- app.py: show_label=False on msg_box to remove "Textbox" label
- app.py: wrap audio input in gr.Accordion(open=False) to hide microphone error on load
- app.py: add CSS to hide Gradio footer branding
- app.py: ingest_status starts visible=False; ingest_files returns gr.update(visible=True)
- ROADMAP.md: add UI/UX design improvement section (D0–D3) and mark D0 complete

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-02 14:25:54 +09:00

382 lines
18 KiB
Markdown
Raw Blame History

# youlbot-webui 개선 로드맵
## 현황 요약
| 항목 | 현재 상태 | 심각도 |
|------|---------|--------|
| 아키텍처 모듈화 | ~~2파일 혼재~~ → config / api_client / services/ / container / app 5모듈 분리 | ✅ 완료 |
| Windows 호환성 | ~~TTS `say` 명령어 — macOS 전용~~ → 크로스플랫폼 구현 완료 | ✅ 완료 |
| Gradio Chatbot 타입 | ~~`type="messages"` 누락~~ → Gradio 6.x 기본 포맷 사용 | ✅ 완료 |
| JSON yield 타입 불일치 | ~~`JSONDecodeError` 시 타입 혼용~~ → `str()` 변환 적용 | ✅ 완료 |
| run_id 인덱싱 버그 | ~~`history` / `run_ids` 동기화 취약~~ → 방어 로직 추가 | ✅ 완료 |
| RAG 출처 표시 | ~~thinking 박스에 혼재~~ → 답변 하단 `📄 출처` 전용 박스로 분리 | ✅ 완료 |
| async/sync 혼용 | ~~`asyncio.run()` 5곳~~ → 모든 콜백 async 전환 완료 | ✅ 완료 |
| 코드 중복 | ~~`asyncio.run()` 5회 반복~~ → container 위임으로 제거 | ✅ 완료 |
| 결합도 | ~~`api_client` 직접 임포트~~ → DI container + Protocol 추상화 | ✅ 완료 |
| 테스트 가능성 | ~~모킹 불가능~~ → pytest-asyncio 단위 테스트 10개 작성 | ✅ 완료 |
| 로깅 | ~~`print()` 만 사용~~ → `logging` 모듈, `LOG_LEVEL` 환경변수 | ✅ 완료 |
---
## IoC / 의존성 주입 전략
전용 IoC 프레임워크(`dependency-injector` 등)는 현재 규모에 **과도한 복잡도**를 유발합니다.
대신 **수동 DI 패턴**을 적용합니다.
- `Protocol` 기반 인터페이스로 `api_client` 추상화 → 테스트 모킹 가능
- `Container` 클래스가 서비스 인스턴스 생성·생명주기 관리
- 향후 규모가 커질 경우 프레임워크로 전환 용이
---
## 목표 아키텍처
```
┌──────────────────────────────────────────┐
│ app.py (Gradio UI) │
│ 콜백 함수는 service 메서드만 호출 │
└──────────────┬───────────────────────────┘
│ 주입받음
┌──────────────▼───────────────────────────┐
│ container.py (Container) │
│ chat_service, document_service 제공 │
└──────────────┬───────────────────────────┘
│ 생성
┌──────────────▼───────────────────────────┐
│ services/ │
│ chat.py / document.py / tts.py │
└──────────────┬───────────────────────────┘
│ 사용
┌──────────────▼───────────────────────────┐
│ api_client.py (APIClientProtocol) │
│ HTTPAPIClient (실구현) │
└──────────────┬───────────────────────────┘
│ 설정 읽음
┌──────────────▼───────────────────────────┐
│ config.py (AppConfig / APIConfig) │
│ 환경변수 일원화 │
└──────────────────────────────────────────┘
```
---
## P0 — 즉시 수정 (버그·호환성)
> 현재 Windows 환경에서 실행 불가 또는 런타임 오류 유발 항목
### 1. 크로스플랫폼 TTS 구현 (`app.py:47-61`)
- **문제**: `subprocess.run(["say", ...])` 는 macOS 전용 → Windows에서 동작 불가.
- **플랫폼별 우선순위**:
- **macOS**: `say`(오프라인, 내장) → `edge-tts`(온라인 폴백) → `pyttsx3`(최종 폴백)
- **Windows**: `edge-tts`(온라인) → `pyttsx3`(오프라인 폴백)
| 우선순위 | 라이브러리 | 방식 | 품질 | Windows | macOS |
|---------|-----------|------|------|---------|-------|
| macOS 1순위 | `say` | 오프라인(내장) | ⭐⭐⭐⭐ | ❌ | ✅ |
| macOS 2순위 / Windows 1순위 | `edge-tts` | 온라인(MS Edge) | ⭐⭐⭐⭐⭐ | ✅ | ✅ |
| 최종 폴백 | `pyttsx3` | 오프라인(SAPI5/NSSpeech) | ⭐⭐⭐ | ✅ | ✅ |
```python
async def tts_speak(text: str) -> str | None:
"""크로스플랫폼 TTS — 플랫폼별 우선순위 적용."""
if not text:
return None
# macOS: say 우선 (오프라인, 자연스러운 한국어)
if platform.system() == "Darwin":
try:
tmp = tempfile.NamedTemporaryFile(suffix=".aiff", delete=False)
tmp.close()
await asyncio.to_thread(
subprocess.run,
["say", "-v", _TTS_VOICE, "-o", tmp.name, text],
check=True, capture_output=True,
)
return tmp.name
except Exception:
pass
# Windows 1순위 / macOS say 실패 시: edge-tts (온라인)
try:
import edge_tts
tmp = tempfile.NamedTemporaryFile(suffix=".mp3", delete=False)
tmp.close()
await edge_tts.Communicate(text, _TTS_EDGE_VOICE).save(tmp.name)
return tmp.name
except Exception:
pass
# 최종 폴백: pyttsx3 (오프라인)
try:
import pyttsx3
tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
tmp.close()
def _save():
engine = pyttsx3.init()
engine.save_to_file(text, tmp.name)
engine.runAndWait()
await asyncio.to_thread(_save)
return tmp.name
except Exception:
return None
```
- **전역 변수** (`app.py` 상단 추가):
```python
_TTS_VOICE = os.getenv("TTS_VOICE", "Yuna") # macOS say
_TTS_EDGE_VOICE = os.getenv("TTS_EDGE_VOICE", "ko-KR-SunHiNeural") # edge-tts
```
- **출력 포맷**: macOS say → `.aiff` (기존 유지), edge-tts → `.mp3`, pyttsx3 → `.wav`
- **requirements.txt 추가**: `edge-tts>=6.1.9`, `pyttsx3>=2.90`
- **주요 edge-tts 한국어 보이스**: `ko-KR-SunHiNeural`(여성), `ko-KR-InJoonNeural`(남성)
### 2. Gradio Chatbot `type="messages"` 누락 (`app.py:186`)
- **문제**: Gradio 4.x에서 `{"role": ..., "content": ...}` 딕셔너리 포맷 사용 시
`type="messages"` 를 명시하지 않으면 경고 또는 오류 발생.
- **수정**: `gr.Chatbot(type="messages", ...)` 추가.
### 3. JSON yield 타입 불일치 (`api_client.py:45-46`)
- **문제**: `JSONDecodeError` 발생 시 `raw`(bytes 또는 str)를 그대로 yield →
반환 타입 `tuple[str, str | None]` 불일치.
- **수정**: `yield str(raw), None` 으로 명시적 변환.
### 4. run_id 인덱싱 방어 로직 (`app.py:107-108`)
- **문제**: `history` 길이와 `run_ids` 길이가 어긋나면 인덱스 오류 발생 가능.
- **수정**: `asst_turn` 계산 후 범위 초과 시 `None` 반환하는 방어 코드 보강.
---
## P1 — 1주일 내 (구조 개선)
### 1. 설정 분리 → `config.py` 신규 생성
```python
# config.py
from dataclasses import dataclass, field
import os
@dataclass
class APIConfig:
url: str = field(default_factory=lambda: os.getenv("YOULBOT_API_URL", "http://localhost:8000"))
token: str = field(default_factory=lambda: os.getenv("YOULBOT_API_TOKEN", ""))
timeout: int = 180
@dataclass
class AppConfig:
api: APIConfig = field(default_factory=APIConfig)
whisper_model_size: str = field(default_factory=lambda: os.getenv("WHISPER_MODEL_SIZE", "small"))
tts_voice: str = field(default_factory=lambda: os.getenv("TTS_VOICE", "Yuna"))
server_host: str = "0.0.0.0"
server_port: int = 7860
```
### 2. Protocol 인터페이스 + HTTPAPIClient 분리 (`api_client.py` 리팩터링)
```python
# api_client.py
from typing import Protocol, AsyncIterator, runtime_checkable
@runtime_checkable
class APIClientProtocol(Protocol):
async def chat(self, message: str, user_id: str, show_thinking: bool) -> AsyncIterator[tuple[str, str | None]]: ...
async def reset(self, user_id: str) -> None: ...
async def ingest(self, file_path: str) -> dict: ...
async def list_documents(self) -> list[str]: ...
async def delete_document(self, source: str) -> None: ...
async def save_feedback(self, user_id: str, user_msg: str, asst_msg: str, rating: int, run_id: str | None) -> None: ...
class HTTPAPIClient:
def __init__(self, config: APIConfig): ...
# 기존 함수들을 메서드로 이전
```
### 3. 서비스 레이어 분리 → `services/` 패키지 신규 생성
```
services/
├── __init__.py — ChatService, DocumentService, TTSService 재익스포트
├── chat.py — ChatService: chat, reset, save_feedback
├── document.py — DocumentService: ingest, list_documents, delete_document
└── tts.py — TTSService: speak (플랫폼 분기)
```
### 4. 수동 DI 컨테이너 → `container.py` 신규 생성
```python
# container.py
class Container:
def __init__(self, config: AppConfig):
self._config = config
self._api_client: HTTPAPIClient | None = None
self._chat_service: ChatService | None = None
self._document_service: DocumentService | None = None
@property
def api_client(self) -> HTTPAPIClient: ...
@property
def chat_service(self) -> ChatService: ...
@property
def document_service(self) -> DocumentService: ...
```
### 5. Async 콜백 통일 (`app.py`)
- `handle_feedback`, `reset_chat`, `ingest_files`, `list_docs`, `delete_doc` →
모두 `async def` 로 전환
- `asyncio.get_event_loop().run_until_complete()` 패턴 완전 제거
- Gradio 4.x async 콜백 지원 활용
---
## P2 — 2주일 내 (품질 개선)
| # | 항목 | 설명 |
|---|------|------|
| 1 | 로깅 시스템 | `print()` → `logging` 모듈, 구조적 로그 포맷 |
| 2 | httpx 연결 풀 공유 | `HTTPAPIClient`에서 `AsyncClient` 인스턴스 재사용 |
| 3 | 입력 검증 | 파일 경로 sanitize, URL path parameter 검증 |
| 4 | 단위 테스트 | `tests/` 폴더 생성, `ChatService` / `DocumentService` Mock 테스트 |
---
## P3 — 선택 사항 (장기)
| # | 항목 | 설명 |
|---|------|------|
| 1 | 재시도 로직 | `tenacity` 라이브러리 또는 수동 exponential backoff |
| 2 | Pydantic Settings | `pydantic-settings` 로 타입 안전 환경변수 관리 |
| 3 | IoC 프레임워크 전환 | 규모 확장 시 `dependency-injector` 도입 검토 |
---
## 최종 파일 구조 (목표)
```
youlbot-webui/
├── app.py # Gradio UI 전용 — 콜백만 존재, 비즈니스 로직 없음
├── container.py # 수동 DI 컨테이너
├── services/
│ ├── __init__.py # 재익스포트
│ ├── chat.py # ChatService
│ ├── document.py # DocumentService
│ └── tts.py # TTSService
├── api_client.py # APIClientProtocol + HTTPAPIClient
├── config.py # AppConfig, APIConfig dataclass
├── tests/
│ ├── test_chat_service.py
│ └── test_document_service.py
├── requirements.txt
├── .env.example
└── ROADMAP.md
```
---
## UI/UX 디자인 개선
> 실제 UI 스크린샷 분석(2026-06-02) 기반 — 우선순위 순 정렬
### D0 — 즉시 수정 (노출 결함)
| # | 위치 | 문제 | 개선 방안 |
|---|------|------|-----------|
| 1 | 대화 탭 · 입력창 | `"Textbox"` 레이블이 입력창 위에 그대로 노출 | `gr.Textbox(label="", show_label=False, ...)` 또는 `label=None` |
| 2 | 대화 탭 · 음성 영역 | `"마이크를 찾을 수 ..."` 오류 메시지가 항상 노출 | 마이크 미사용 시 해당 텍스트 숨김 처리, 또는 `visible=False` 기본값 |
| 3 | 전체 탭 · 푸터 | `"Gradio로 제작됨 🎉"` Gradio 브랜딩 노출 | `css="footer { display: none; }"` 추가 또는 `gr.Blocks(show_footer=False)` |
| 4 | 문서 등록 탭 · 결과 박스 | 업로드 전에도 빈 `결과` 박스가 항상 노출 | 초기 `visible=False`, 수집 완료 시에만 `visible=True` 반환 |
### D1 — 1주일 내 (레이아웃 개선)
| # | 위치 | 문제 | 개선 방안 |
|---|------|------|-----------|
| 5 | 대화 탭 · 채팅 영역 | 초기 화면이 빈 흰 공간으로 시작 — 어색한 첫 인상 | 웰컴 메시지 또는 예시 질문 버블(`gr.Examples`) 추가 |
| 6 | 대화 탭 · 이미지 첨부 | 이미지 업로드 영역이 항상 전체 크기로 펼쳐짐 | `gr.Accordion("이미지 첨부 (선택)", open=False)` 로 접이식 변경 |
| 7 | 대화 탭 · 하단 컨트롤 | `사고 과정 표시`, `TTS`, `대화 초기화` 배치가 불규칙 | `gr.Row`로 균등 3분할, `대화 초기화`는 오른쪽 정렬 |
| 8 | 대화 탭 · 입력 영역 | 텍스트 입력창과 `전송` 버튼이 시각적으로 분리됨 | 입력창 높이를 `lines=2`로 통일, 버튼 높이 CSS로 맞춤 |
| 9 | 문서 관리 탭 · 삭제 UX | 경로를 테이블에서 복사해 입력 필드에 붙여넣기 해야 함 | 테이블 행 클릭 → 입력 필드 자동 채움 (`select` 이벤트 활용) |
| 10 | 문서 등록 탭 · 버튼 | `문서 수집` 버튼이 전체 너비를 차지해 무게감 과도 | `scale=0` 또는 `min_width=200` 으로 적정 크기 조절 |
### D2 — 2주일 내 (시각 품질)
| # | 항목 | 설명 |
|---|------|------|
| 11 | 헤더 브랜딩 | 텍스트 전용 헤더 → 아이콘/로고 이미지 + 서브타이틀 레이아웃으로 개선 |
| 12 | 커스텀 테마 | Gradio 기본 보라색 → `gr.themes.Soft()` 또는 커스텀 `primary_hue` 색상 지정 |
| 13 | 사용자 선택 위치 | `사용자` 드롭다운이 채팅 위에 있어 흐름 방해 → 헤더 우측 또는 사이드바로 이동 |
| 14 | 채팅 버블 스타일 | Gradio 기본 스타일 → CSS로 사용자/봇 버블 배경색·radius 차별화 |
| 15 | 응답 로딩 표시 | 스트리밍 중 시각적 피드백 없음 → 입력 비활성화 + 스피너 CSS 추가 |
| 16 | 반응형 레이아웃 | 좁은 뷰포트에서 요소 겹침 → `gr.Column`/`gr.Row` 비율 재조정 |
### D3 — 선택 사항 (장기)
| # | 항목 | 설명 |
|---|------|------|
| 17 | 다크 모드 | `gr.themes.Base()` + CSS 변수로 다크/라이트 토글 지원 |
| 18 | 채팅 내보내기 | 대화 내용을 `.txt`/`.md`로 다운로드하는 버튼 추가 |
| 19 | 접근성 | `aria-label` 속성 추가, 키보드 포커스 표시 개선 |
| 20 | 온보딩 투어 | 첫 방문 사용자 대상 단계별 기능 안내 (JS 오버레이) |
### D 체크리스트
#### D0
- [x] `gr.Textbox(show_label=False)` — `"Textbox"` 레이블 제거
- [x] 음성 오류 메시지 기본 숨김 처리 — `gr.Accordion("🎤 음성으로 질문하기", open=False)` 로 기본 접힘
- [x] Gradio 푸터 CSS 숨김 — `footer { display: none !important; }` 추가
- [x] `결과` 박스 초기 `visible=False` — `ingest_files`에서 `gr.update(visible=True)` 반환
#### D1
- [ ] 웰컴 메시지 또는 예시 질문 버블 추가
- [ ] 이미지 첨부 영역 `gr.Accordion`으로 접이식 변경
- [ ] 하단 컨트롤 `gr.Row` 균등 배치
- [ ] 문서 관리 탭 — 테이블 행 클릭 → 삭제 경로 자동 채움
- [ ] `문서 수집` 버튼 크기 적정화
#### D2
- [ ] 헤더 아이콘/로고 추가
- [ ] `gr.themes.Soft()` 또는 커스텀 테마 적용
- [ ] 사용자 드롭다운 위치 이동
- [ ] 채팅 버블 커스텀 CSS
- [ ] 스트리밍 로딩 표시
#### D3
- [ ] 다크 모드 토글
- [ ] 채팅 내보내기 버튼
- [ ] 접근성 개선
---
## 진행 체크리스트
### P0
- [x] `tts_speak()` 크로스플랫폼 구현 (macOS: say→edge-tts→pyttsx3 / Windows: edge-tts→pyttsx3)
- [x] `requirements.txt` — `edge-tts>=6.1.9`, `pyttsx3>=2.90` 추가
- [x] `.env.example` — `TTS_EDGE_VOICE=ko-KR-SunHiNeural` 항목 추가 (`TTS_VOICE=Yuna` 유지)
- [x] `gr.Chatbot` — Gradio 6.x 기본 dict 포맷 사용 (`type` 파라미터 불필요, 제거)
- [x] `api_client.py` JSON yield 타입 수정
- [x] `run_id` 인덱싱 방어 로직 추가
- [x] RAG 출처 전용 박스 분리 — `source_box` gr.HTML + `_sources_html()` + `__sources` 토큰 처리
### P1
- [x] `config.py` 작성 (APIConfig, AppConfig)
- [x] `api_client.py` — `APIClientProtocol` + `HTTPAPIClient` 분리
- [x] `services/` 패키지 작성 (chat.py, document.py, tts.py + __init__.py 재익스포트)
- [x] `container.py` 작성 (lazy singleton 프로퍼티)
- [x] `app.py` — 모든 콜백 async 전환 및 container 사용 (`asyncio.run()` 완전 제거)
### P2
- [x] `logging` 모듈 도입 — `basicConfig` + `LOG_LEVEL` 환경변수, `print()` 제거
- [x] httpx `AsyncClient` 재사용 — `HTTPAPIClient.__init__`에서 공유 클라이언트 생성, `aclose()` 추가
- [x] 입력 검증 추가 — `DocumentService.ingest` 파일 존재·확장자 검증, `delete_document` URL 인코딩
- [x] `tests/` 단위 테스트 작성 — `pytest-asyncio`, `ChatService` 4개 / `DocumentService` 6개 (10/10 통과)
### P3
- [x] 재시도 로직 — `tenacity` / 5xx·TransportError에만 최대 3회, 지수 백오프(1→8s) / `chat` 제외 5개 메서드 적용
- [x] Pydantic Settings — `config.py` dataclass → `BaseSettings` (flat `AppConfig`), `.env` 자동 로드
- [x] IoC 프레임워크 전환 — 수동 DI → `dependency-injector` `DeclarativeContainer` + `providers.Singleton`
Reference in New Issue View Git Blame Copy Permalink