docs/devlog/2026-07-04.md

개발일지: 2026-07-04

이번 세션에서 한 일

크게 두 가지였다.

1. 앱 실행 중 발생하는 API 에러 처리 강화
2. 학생 시각으로 본 UX 개선 6종

---

1. API 에러 처리 강화

문제

앱이 켜져 있는 상태에서 특정 기능을 쓸 때 화면 전체가 에러로 깨지는 현상이 있었다.
원인은 세 곳이었다.

① ChromaDB 빈 컬렉션 crash

QuestionVectorStore.search(k=5)를 호출할 때, 컬렉션에 문서가 0개이면 ChromaDB가 n_results > n_documents 에러를 던진다.
문제 색인을 한 번도 안 한 상태에서 AI 검색 버튼을 누르면 페이지 전체가 깨졌다.

# 수정 전 — 그냥 query 호출
result = collection.query(query_texts=[query], n_results=k)

# 수정 후 — count 체크 후 min(k, count) 사용
count = collection.count()
if count == 0:
    return []
kwargs["n_results"] = min(k, count)
result = collection.query(**kwargs)

cert_study_app/services/vector_service.py의 search() 메서드에서 수정했다.

② Ollama 스트리밍 에러 전파

study_assistant_service.py의 stream_chunks() 제너레이터가 Ollama API 오류를 그냥 올려보냈다.
UI(notes.py, streamlit_app.py)에서 for chunk in result["stream"] 루프를 돌다가 예외가 터지면 페이지가 깨졌다.

# 수정 후 — 제너레이터 내부에서 catch
def stream_chunks():
    try:
        for chunk in chain.stream(...):
            yield chunk
    except Exception as exc:
        yield f"\n\n*(Ollama 응답 오류: {exc})*"

③ render_quiz_assistant 에러 전파

StudyAssistantService 초기화(임베딩 모델 로드)나 ask_stream 중 오류가 나도 사용자에게 아무 안내 없이 페이지가 깨졌다.

# 수정 후 — 초기화 실패는 조기 반환, ask_stream 실패는 st.error()
try:
    service = StudyAssistantService(...)
except Exception as exc:
    st.error(f"AI 검색 서비스 초기화 실패: {exc}")
    return

try:
    result = service.ask_stream(...)
    for chunk in result["stream"]:
        ...
except Exception as exc:
    st.error(f"AI 질문 처리 중 오류: {exc}")
    st.caption(f"Ollama URL이 실행 중인지, 모델이 설치되어 있는지 확인하세요.")

수정 파일 요약

파일	수정 내용
cert_study_app/services/vector_service.py	search() — 빈 컬렉션 안전 처리, n_results = min(k, count)
cert_study_app/services/study_assistant_service.py	stream_chunks() — Ollama 오류 yield로 처리
cert_study_app/services/concept_note_service.py	requests.post — ConnectionError를 RuntimeError로 래핑
cert_study_app/services/visual_question_service.py	동일 패턴
streamlit_app.py	render_quiz_assistant() — 초기화·스트리밍 에러 표시
cert_study_app/ui/notes.py	동일 패턴 (모듈 분리본)

---

2. UX 개선 6종

학생 시각으로 앱을 쓰면서 불편한 점 6개를 찾고 바로 수정했다.

문제 1: "다음에 뭘 해야 하는지 모른다"

홈의 Smart CTA(파란 버튼)가 "개념공부" 랜딩 페이지로 가서 또 버튼을 눌러야 했다.

수정: 단계별 직접 이동으로 변경

• 이론 카드 안 본 경우 → "이론 카드 시작하기 →" → 이론 학습 직행
• 이론 카드는 봤고 퀴즈가 남은 경우 → "확인 퀴즈 이어가기 →" → 확인 퀴즈 직행

문제 2: "오늘 몇 단계인지 숫자만 보인다"

Hero 카드에 "오늘 1/3 단계" 텍스트만 있어서 구체적으로 뭘 해야 하는지 몰랐다.

수정: Hero 카드 아래에 3단계 표시기 추가

①개념 → ②실습 → ③복습
(완료 시 ✓ 표시)

문제 3: "→ 버튼이 너무 작다"

모드 카드(개념공부 / 실습 / 시험준비) 오른쪽에 작은 "→" 버튼만 있어서 모바일에서 누르기 어려웠다.

수정: 카드 전체를 full-width 버튼으로 교체. 제목·설명·상태를 한 줄에 담고 전체 영역 클릭 가능.

문제 4: "이론 카드 완료 후 다음을 모른다"

"학습 완료" 버튼을 누르면 성공 메시지가 잠깐 나왔다가 사라지고, 다음 단계 안내가 없었다.

수정: 완료 직후 "이 레슨 확인 퀴즈 N개 바로 풀기 →" 버튼 표시. 관련 퀴즈가 없으면 "확인 퀴즈 전체 이어가기 →" 표시.

문제 5: "퀴즈 정답 후 다음 문제까지 스크롤해야 한다"

설명이 길면 "다음 퀴즈" 버튼이 화면 밖으로 내려가 있었다.

수정: 설명 바로 아래 "다음 퀴즈 →" 버튼 추가. 마지막 문제면 안내 메시지 표시.

문제 6: "실습 완료 후 다음을 모른다"

실습 채점 정답 후 "다음 실습" 버튼이 아래에만 있었다.

수정: 채점 결과 바로 아래 "다음 실습 →" 버튼 추가. 모든 실습 완료 시 "홈에서 다음 단계로" 안내.

---

배운 것

ChromaDB count check 패턴

count = collection.count()
if count == 0:
    return []
n_results = min(k, count)  # k가 count보다 크면 에러

ChromaDB는 n_results > n_documents이면 예외를 던진다. 빈 컬렉션에서 search를 호출하는 것은 실제로 자주 발생하는 상황(첫 실행, 색인 전)이므로 반드시 방어해야 한다.

Streamlit에서 제너레이터 에러 처리

Streamlit 스트리밍은 for chunk in generator: 루프에서 예외가 발생하면 그 시점에 페이지가 깨진다. 제너레이터 내부에서 try/except로 처리하고, 에러를 yield하는 방식이 가장 안전하다.

UX: "다음 단계 안내"가 학습 흐름의 핵심

공부 앱에서 학생이 가장 자주 겪는 불편은 "지금 뭘 해야 하는지 모른다"이다. 각 화면의 끝에 "다음에 할 것 →" 버튼 하나가 있으면 이탈률이 줄어든다. 완료 후 안내, 채점 후 다음 이동은 모두 이 원칙에서 나온다.

---

다음 작업 후보

• Alembic 마이그레이션 도입 — 현재 db.py는 앱 시작마다 ALTER TABLE을 실행한다. Alembic으로 교체하면 안전하다.
• Progress 저장 atomic write — save_progress()가 JSON 파일을 통째로 덮어쓴다. tempfile + os.replace()로 교체하면 crash 시 데이터 손실을 막을 수 있다.
• Spaced Repetition 통합 — spaced_review(int ID)와 lab_spaced_review(str ID) 두 구현이 거의 동일하다. 제네릭 클래스 하나로 통합할 수 있다.
• cert_study_app/ui/ 모듈화 완성 — quiz.py, admin.py 생성 후 streamlit_app.py를 라우팅만 남기기