Sync from GitHub f8e98d3f03952efd3d7c1b217df60c77c3992aec

.env.example

@@ -1,12 +1,23 @@
-DATABASE_URL=postgresql+pg8000://cert_study:cert_study@localhost:5432/cert_study
-CERT_STUDY_DB_FALLBACK=0
+POSTGRES_DB=cert_study
+POSTGRES_USER=cert_study
+POSTGRES_PASSWORD=change-me
 
-OLLAMA_BASE_URL=http://localhost:11434
+DATABASE_URL=postgresql+pg8000://cert_study:change-me@postgres:5432/cert_study
+
+CERT_STUDY_LLM_PROVIDER=ollama
 OLLAMA_MODEL=qwen2.5:14b
 OLLAMA_FAST_MODEL=qwen3.5:9b
 OLLAMA_VISUAL_MODEL=qwen3-vl:8b-instruct-q4_K_M
+OLLAMA_BASE_URL=http://host.docker.internal:11434
 EMBEDDING_MODEL=BAAI/bge-m3
 
-AIRFLOW_API_BASE_URL=http://localhost:8080
+AIRFLOW_API_BASE_URL=http://host.docker.internal:8080
 AIRFLOW_API_USERNAME=admin
-AIRFLOW_API_PASSWORD=admin
+AIRFLOW_API_PASSWORD=change-me
+AIRFLOW_ADMIN_USERNAME=admin
+AIRFLOW_ADMIN_PASSWORD=change-me
+AIRFLOW_ADMIN_EMAIL=admin@example.com
+
+CERT_STUDY_SEED_DEMO=1
+CERT_STUDY_REFRESH_SEED=1
+CERT_STUDY_OVERWRITE_REVIEWED_SEED=0

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 2026-06-07
+
+- Added deployable Hugging Face seed data and static question assets.
+- Restored common passages and parent images for case-study questions.
+- Improved seed refresh so deployed databases can receive updated questions.
+- Added Yes/No matrix handling for true/false hotspot questions.
+- Added grouped row selection for `1-A / 1-B / 2-A / 2-B` style questions.
+- Added centralized answer normalization for single choice, multi-select, ordered answers, and Yes/No matrices.
+- Added centralized question type normalization for aliases such as `Hotspot (True/False)` and `Hotspot (Drag and Drop)`.
+- Reduced mobile home screen noise by prioritizing study actions and grouping upload/admin actions.
+- Added lightweight tests for answer normalization, question type aliases, and seed export reports.
+- Added GitHub Actions quality check workflow.
+- Added `.env.example` and Docker Compose environment variable defaults.
+- Updated README and docs for the current deployment and troubleshooting flow.

README.md

@@ -26,6 +26,7 @@ pinned: false
 - 문제, 정답, 해설, 풀이 기록 저장
 - Streamlit 기반 문제풀이 화면
 - 공통 지문, 원문 이미지, Yes/No 진술형 문제풀이 UI
+- 문제 유형 표준화 및 정답 정규화 로직
 - 오답/복습 화면
 - 개념 정리 화면
 - Chroma 기반 유사 문제 검색 구조
@@ -57,12 +58,14 @@ pinned: false
 8. [GitHub / Hugging Face 배포 자동화](docs/08_publish_automation.md)
 9. [모바일 앱처럼 사용하기](docs/09_mobile_pwa.md)
 10. [개발일지](docs/devlog/2026-06-07.md)
+11. [변경 이력](CHANGELOG.md)
 
 ## 실행 방법
 
 Docker가 설치되어 있다면 아래 명령으로 실행합니다.
 
 ```bash
+cp .env.example .env
 docker compose up --build
 ```
 
@@ -83,7 +86,7 @@ DATABASE_URL=sqlite:////tmp/cert-study-local-check.db \
 
 Hugging Face Space에는 로컬 DB나 PDF 원본을 올리지 않고, `cert_study_app/demo_data/questions_seed.json`과 `static/question_assets/`의 참조 이미지를 사용합니다.
 
-현재 배포용 seed는 321문항, 공통 지문 포함 문항, 원문 이미지, Yes/No 진술형 문제 UI에 필요한 구조를 포함합니다. seed는 아래 명령으로 다시 만들 수 있습니다.
+현재 배포용 seed는 321문항, 공통 지문 포함 36문항, 원문 이미지, Yes/No 진술형 문제 UI에 필요한 구조를 포함합니다. seed는 아래 명령으로 다시 만들 수 있습니다.
 
 ```bash
 python scripts/export_hf_seed.py
@@ -97,6 +100,28 @@ Git 커밋은 날짜와 함께 남기 때문에 일자별 변경 내용을 확
 scripts/git_daily_changes.sh 2026-06-07
 ```
 
+## 테스트
+
+문제 유형이 다양하기 때문에 정답 처리 로직은 별도 테스트로 확인합니다.
+
+```bash
+python -m pip install -r requirements-dev.txt
+python -m pytest tests
+```
+
+배포 전에 핵심 품질 검사를 한 번에 실행할 수도 있습니다.
+
+```bash
+python scripts/check_quality.py
+```
+
+현재 우선 확인하는 범위:
+
+- Yes/No 진술형 정답 정규화
+- 복수 선택 정답 정렬
+- 순서가 중요한 답안 보존
+- `Hotspot (True/False)`, `Hotspot (Drag and Drop)` 같은 문제 유형 alias 표준화
+
 ## 환경 변수
 
 기본 데이터베이스는 PostgreSQL입니다.
@@ -123,4 +148,4 @@ CERT_STUDY_DB_FALLBACK=1
 - 문제 중복 감지 및 재업로드 처리
 - Oracle Cloud Ubuntu 서버 배포
 - 배포용 환경 변수와 비밀값 관리 정리
-- 테스트와 CI/CD 추가
+- 테스트 범위 확대와 CI/CD 추가

cert_study_app/demo_data/questions_seed.report.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": 1,
+  "seed_path": "cert_study_app/demo_data/questions_seed.json",
+  "question_count": 321,
+  "first_question_number": 1,
+  "last_question_number": 321,
+  "common_passage_count": 36,
+  "type_counts": {
+    "Drag and Drop (Auth)": 1,
+    "Drag and Drop (Roles)": 1,
+    "Drag and Drop (Steps)": 9,
+    "Hotspot (Drag and Drop)": 88,
+    "Hotspot (Select Two)": 2,
+    "Hotspot (Select options in sequence)": 1,
+    "Hotspot (True/False)": 50,
+    "Multiple Choice": 121,
+    "Multiple Choice (Select Three)": 2,
+    "Multiple Choice (Select Two)": 15,
+    "True/False": 2,
+    "True/False (In-Context)": 29
+  },
+  "duplicate_numbers": [],
+  "missing_answers": [],
+  "missing_options": [],
+  "missing_images": [],
+  "ready": true
+}

cert_study_app/services/answer_normalizer.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from cert_study_app.services.text_cleanup_service import clean_inline_text
+
+
+YES_WORDS = {"yes", "y", "예", "true", "selected"}
+NO_WORDS = {"no", "n", "아니오", "아니요", "false", "not selected"}
+
+
+@dataclass(frozen=True)
+class AnswerEvaluation:
+    chosen: str
+    answer: str
+    normalized_chosen: str
+    normalized_answer: str
+    correct: bool
+    ordered: bool = False
+
+
+def normalize_options(raw: Any) -> list[str]:
+    if not raw:
+        return []
+    try:
+        if isinstance(raw, str):
+            parsed = json.loads(raw)
+            if isinstance(parsed, (list, dict)):
+                raw = parsed
+        if isinstance(raw, dict):
+            keyed = []
+            for key, value in sorted(raw.items(), key=lambda kv: str(kv[0])):
+                text = clean_inline_text(value)
+                if re.match(r"^[A-Za-z1-9][\.\)]\s+", text):
+                    keyed.append(text)
+                else:
+                    keyed.append(f"{key}. {text}")
+            return split_embedded_options(keyed)
+        if isinstance(raw, list):
+            return split_embedded_options(raw)
+    except Exception:
+        return []
+    return []
+
+
+def split_embedded_options(options: list[str]) -> list[str]:
+    split = []
+    expected = "A"
+    for option in options:
+        text = clean_inline_text(option)
+        if not text:
+            continue
+        parts = list(re.finditer(r"(?<![A-Za-z0-9])([A-Z])[\.\)]\s+", text))
+        if len(parts) <= 1:
+            split.append(text)
+            continue
+        for index, match in enumerate(parts):
+            end = parts[index + 1].start() if index + 1 < len(parts) else len(text)
+            part = text[match.start() : end].strip()
+            label = match.group(1).upper()
+            if label >= expected:
+                split.append(part)
+                expected = chr(ord(label) + 1)
+    return split
+
+
+def extract_options_from_stem(stem: str) -> list[str]:
+    lines = [line.strip() for line in (stem or "").splitlines() if line.strip()]
+    options = []
+    current_key = None
+    current_parts = []
+    expected = "A"
+
+    def flush():
+        if current_key and current_parts:
+            text = " ".join(current_parts).strip()
+            if text:
+                options.append(f"{current_key}. {text}")
+
+    for line in lines:
+        if re.match(r"^(answer|정답|explanation|reference)\b", line, re.I):
+            flush()
+            current_key = None
+            current_parts = []
+            break
+
+        marker = None
+        body = ""
+        exact = re.match(r"^([A-Z])[\.\)]?$", line, re.I)
+        inline = re.match(r"^([A-Z])[\.\)]?\s+(.+)$", line, re.I)
+        if exact:
+            marker = exact.group(1).upper()
+        elif inline:
+            marker = inline.group(1).upper()
+            body = inline.group(2).strip()
+
+        if marker and marker >= expected:
+            flush()
+            current_key = marker
+            current_parts = [body] if body else []
+            expected = chr(ord(marker) + 1)
+        elif current_key:
+            current_parts.append(line)
+
+    flush()
+    return options if len(options) >= 2 else []
+
+
+def extract_answer_from_stem(stem: str) -> str:
+    match = re.search(r"(?:Answer|정답)\s*:?\s*([A-Z1-9])", stem or "", re.I)
+    if not match:
+        return ""
+    value = match.group(1).upper()
+    if value.isdigit():
+        return chr(ord("A") + int(value) - 1)
+    return value
+
+
+def option_label(value: Any) -> str:
+    text = str(value or "").strip().upper()
+    if text.isdigit():
+        return chr(ord("A") + int(text) - 1)
+    match = re.match(r"^([A-Z])(?:[\s\.,\)]|$)", text)
+    return match.group(1) if match else text
+
+
+def choice_labels(value: Any) -> list[str]:
+    text = str(value or "").strip().upper()
+    if not text:
+        return []
+    if re.fullmatch(r"[A-Z]{2,26}", text):
+        return list(text)
+    tokens = re.findall(r"\b[A-Z]\b|\b[1-9]\b", text)
+    return [option_label(token) for token in tokens]
+
+
+def yes_no_labels(value: Any) -> list[str]:
+    raw_value = _parse_jsonish(value)
+
+    if isinstance(raw_value, list):
+        values = [
+            item.get("value") or item.get("answer") or item.get("selected_answer")
+            for item in raw_value
+            if isinstance(item, dict)
+        ]
+        labels = yes_no_labels(",".join(str(item) for item in values if item))
+        if labels:
+            return labels
+    elif isinstance(raw_value, dict):
+        labels = yes_no_labels(",".join(str(item) for item in raw_value.values()))
+        if labels:
+            return labels
+
+    text = str(value or "").strip().lower()
+    if not text:
+        return []
+    if re.fullmatch(r"[yn](?:\s*,\s*[yn])+", text, re.I):
+        return [token.upper() for token in re.findall(r"[yn]", text, re.I)]
+
+    tokens = re.findall(
+        r"(?<![가-힣])예(?![가-힣])|아니오|아니요|\byes\b|\bno\b|\bselected\b|\bnot selected\b|\btrue\b|\bfalse\b",
+        text,
+        re.I,
+    )
+    labels = []
+    for token in tokens:
+        lowered = token.lower()
+        labels.append("Y" if token == "예" or lowered in YES_WORDS else "N")
+    return labels if len(labels) >= 2 else []
+
+
+def structured_answer_values(value: Any) -> list[str]:
+    raw_value = _parse_jsonish(value)
+    if isinstance(raw_value, list):
+        values = [
+            item.get("value") or item.get("answer") or item.get("selected_answer")
+            for item in raw_value
+            if isinstance(item, dict)
+        ]
+    elif isinstance(raw_value, dict):
+        values = list(raw_value.values())
+    else:
+        return []
+    return [str(item).strip() for item in values if str(item).strip()]
+
+
+def option_text(options: list[str], label: str) -> str:
+    label = option_label(label)
+    for index, option in enumerate(options, 1):
+        text = str(option).strip()
+        keys = {str(index), chr(ord("A") + index - 1)}
+        match = re.match(r"^([A-Z1-9])[\.\)]\s+(.+)$", text, re.I)
+        if match:
+            keys.add(option_label(match.group(1)))
+            if match.group(1).isdigit():
+                keys.add(match.group(1))
+        if label in keys:
+            return text
+    return ""
+
+
+def option_labels_from_texts(options: list[str], values: Any, allow_duplicates: bool = False) -> list[str]:
+    if not values:
+        return []
+    if isinstance(values, str):
+        values = [values]
+    labels = []
+    for value in values:
+        target = re.sub(r"\s+", " ", str(value or "").strip()).lower()
+        if not target:
+            continue
+        for index, option in enumerate(options, 1):
+            body = re.sub(r"\s+", " ", _option_body(option)).lower()
+            if body and (target == body or target in body or body in target):
+                label = chr(ord("A") + index - 1)
+                if allow_duplicates or label not in labels:
+                    labels.append(label)
+                break
+    return labels
+
+
+def normalize_answer(value: Any, *, ordered: bool = False) -> str:
+    yn = yes_no_labels(value)
+    if yn:
+        return ",".join(yn)
+    labels = choice_labels(value)
+    if not labels:
+        return option_label(value)
+    if ordered:
+        return ",".join(labels)
+    return ",".join(sorted(set(labels)))
+
+
+def evaluate_answer(chosen: Any, answer: Any, *, ordered: bool = False) -> AnswerEvaluation:
+    normalized_chosen = normalize_answer(chosen, ordered=ordered)
+    normalized_answer = normalize_answer(answer, ordered=ordered)
+    return AnswerEvaluation(
+        chosen=str(chosen or ""),
+        answer=str(answer or ""),
+        normalized_chosen=normalized_chosen,
+        normalized_answer=normalized_answer,
+        correct=normalized_chosen == normalized_answer,
+        ordered=ordered,
+    )
+
+
+def _option_body(option: str) -> str:
+    text = str(option or "").strip()
+    match = re.match(r"^([A-Z1-9])[\.\)]\s+(.+)$", text, re.I)
+    return (match.group(2) if match and match.group(2) else text).strip()
+
+
+def _parse_jsonish(value: Any) -> Any:
+    if isinstance(value, (list, dict)):
+        return value
+    try:
+        return json.loads(value) if isinstance(value, str) else None
+    except Exception:
+        return None

cert_study_app/services/demo_seed_service.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import hashlib
 from pathlib import Path
 
 from sqlalchemy import func
@@ -13,6 +14,9 @@ DEMO_SOURCE = "Demo Certification Sample"
 DEMO_DATA_DIR = Path(__file__).resolve().parent.parent / "demo_data"
 FULL_SEED_DATA_PATH = DEMO_DATA_DIR / "questions_seed.json"
 DEMO_DATA_PATH = DEMO_DATA_DIR / "demo_questions.json"
+SEED_VERSION = "seed-v2"
+SEED_QUALITY_STATUS = "seed"
+SEED_SOURCES = {DEMO_SOURCE, "AZ-104 imported seed"}
 
 
 def _seed_data_path() -> Path:
@@ -30,7 +34,15 @@ def _json_text(value, fallback):
         return fallback
 
 
+def _seed_hash(row: dict) -> str:
+    payload = json.dumps(row, ensure_ascii=False, sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
 def _apply_seed_row(question: Question, row: dict) -> None:
+    row_with_meta = dict(row)
+    row_with_meta["_seed_version"] = SEED_VERSION
+    row_with_meta["_seed_hash"] = _seed_hash(row)
     question.stem = row["stem"]
     question.answer = _json_text(row.get("answer"), None)
     question.explanation = row.get("explanation")
@@ -45,14 +57,14 @@ def _apply_seed_row(question: Question, row: dict) -> None:
     question.source = row.get("source") or DEMO_SOURCE
     question.image_path = row.get("image_path")
     question.raw_text = row.get("raw_text") or row.get("stem")
-    question.structured_data_json = json.dumps(row, ensure_ascii=False)
+    question.structured_data_json = json.dumps(row_with_meta, ensure_ascii=False)
     question.parse_status = row.get("parse_status") or "approved"
     question.quality_score = row.get("quality_score") or 100
-    question.quality_status = row.get("quality_status") or "seed"
+    question.quality_status = row.get("quality_status") or SEED_QUALITY_STATUS
     question.quality_issues = _json_text(row.get("quality_issues"), "[]")
     question.chunk_key = row.get("chunk_key")
     question.chunk_index = row.get("chunk_index")
-    question.parser_version = row.get("parser_version") or "seed-v1"
+    question.parser_version = row.get("parser_version") or SEED_VERSION
     question.code = row.get("code")
     question.pairs = _json_text(row.get("pairs"), None)
     question.sequence = _json_text(row.get("sequence"), None)
@@ -64,21 +76,38 @@ def _refresh_seed_questions(db, rows: list[dict]) -> int:
     if os.getenv("CERT_STUDY_REFRESH_SEED", "1") == "0":
         return 0
 
+    overwrite_reviewed = os.getenv("CERT_STUDY_OVERWRITE_REVIEWED_SEED", "0") == "1"
     changed = 0
     for row in rows:
         question_number = row.get("question_number")
         if not question_number:
             continue
 
+        source = row.get("source") or DEMO_SOURCE
         question = (
             db.query(Question)
             .filter(Question.question_number == question_number)
+            .filter(Question.source == source)
             .order_by(Question.id.asc())
             .first()
         )
+        if not question:
+            question = (
+                db.query(Question)
+                .filter(Question.question_number == question_number)
+                .filter(Question.quality_status == SEED_QUALITY_STATUS)
+                .order_by(Question.id.asc())
+                .first()
+            )
         if not question:
             question = Question()
             db.add(question)
+        elif (
+            not overwrite_reviewed
+            and question.quality_status != SEED_QUALITY_STATUS
+            and question.source not in SEED_SOURCES
+        ):
+            continue
 
         _apply_seed_row(question, row)
         changed += 1

cert_study_app/services/parse_quality_service.py

@@ -7,8 +7,8 @@ from pathlib import Path
 from statistics import median
 from typing import Any
 
+from cert_study_app.services.question_type_metadata_service import is_visual_question_type, normalize_question_type
 
-VISUAL_TYPES = {"hotspot", "yes_no", "ordering", "table_choice", "matching"}
 ISSUE_WEIGHTS = {
     "missing_stem": 18,
     "short_stem": 8,
@@ -62,7 +62,7 @@ def build_parse_quality_report(
         stem = _text(item.get("stem") or item.get("question") or item.get("q_text"))
         answer = item.get("answer")
         options = _normal_options(item.get("options"))
-        question_type = _text(item.get("question_type") or "mcq").lower()
+        question_type = normalize_question_type(item.get("question_type") or "mcq")
         raw_fingerprints[_fingerprint(raw_text)].append(index)
         chunk_lengths.append(len(raw_text))
 
@@ -72,7 +72,7 @@ def build_parse_quality_report(
             _add_issue(issues_by_index, index, "short_stem", "문제 본문이 너무 짧습니다.", length=len(stem))
         if not _has_answer(answer):
             _add_issue(issues_by_index, index, "missing_answer", "정답이 비어 있습니다.")
-        if question_type not in VISUAL_TYPES and len(options) < 2:
+        if not is_visual_question_type(question_type) and len(options) < 2:
             _add_issue(issues_by_index, index, "missing_options", "객관식/선택형으로 보이지만 보기가 2개 미만입니다.", option_count=len(options))
         if len(options) >= 2:
             expected_labels = [chr(ord("A") + offset) for offset in range(len(options))]
@@ -99,7 +99,7 @@ def build_parse_quality_report(
             _add_issue(issues_by_index, index, "answer_leaked_to_stem", "본문에 정답 라인이 섞여 있습니다.")
         if re.search(r"(?m)\n\s*\d{1,3}\s*[.)]\s+\S+", stem):
             _add_issue(issues_by_index, index, "embedded_next_question", "청크 안에 다음 문제 시작처럼 보이는 줄이 있습니다.")
-        if question_type in VISUAL_TYPES and item.get("image_path") and not Path(str(item.get("image_path"))).exists():
+        if is_visual_question_type(question_type) and item.get("image_path") and not Path(str(item.get("image_path"))).exists():
             _add_issue(issues_by_index, index, "image_missing", "이미지 기반 문제의 원문 이미지 파일을 찾을 수 없습니다.")
 
     nonzero_numbers = [number for number in numbers if number is not None]

cert_study_app/services/question_review_service.py

@@ -13,12 +13,15 @@ from cert_study_app.services.quiz_service import (
     yes_no_labels,
 )
 from cert_study_app.services.text_cleanup_service import clean_question_text
-from cert_study_app.services.question_type_metadata_service import type_metadata
+from cert_study_app.services.question_type_metadata_service import (
+    is_visual_question_type,
+    normalize_question_type,
+    type_metadata,
+)
 from cert_study_app.services.question_concept_service import apply_question_concept
 
 
 AUTO_APPROVE_THRESHOLD = 85
-VISUAL_TYPES = {"hotspot", "ordering", "matching", "table_choice"}
 
 
 def _answer_labels(answer: str) -> set[str]:
@@ -62,7 +65,7 @@ def _clean_options(options: list[str]) -> list[str]:
 
 
 def _looks_like_yes_no_hotspot(question_type: str, stem: str, answer: str, explanation: str, options: list[str]) -> bool:
-    if (question_type or "").lower() not in {"hotspot", "table_choice"}:
+    if normalize_question_type(question_type) not in {"hotspot", "table_choice", "yes_no"}:
         return False
     text = " ".join([stem or "", answer or "", explanation or "", " ".join(str(option) for option in options or [])])
     return bool(
@@ -81,13 +84,14 @@ def _visual_analysis(question: Question) -> dict:
 
 
 def _looks_like_box_dropdown(question_type: str, stem: str) -> bool:
-    if (question_type or "").lower() not in {"hotspot", "table_choice"}:
+    if normalize_question_type(question_type) not in {"hotspot", "table_choice", "matching"}:
         return False
     return bool(re.search(r"(답변\s*영역|드롭다운|적절한\s*옵션|답변하려면)", stem or ""))
 
 
 def _detect_answer_mode(question_type: str, stem: str, answer: str, explanation: str, options: list[str]) -> str:
-    if _looks_like_yes_no_hotspot(question_type, stem, answer, explanation, options):
+    normalized_type = normalize_question_type(question_type)
+    if normalized_type == "yes_no" or _looks_like_yes_no_hotspot(question_type, stem, answer, explanation, options):
         return "yes_no_matrix"
     labels = choice_labels(answer or "")
     if len(labels) > 1:
@@ -101,7 +105,7 @@ def _detect_answer_mode(question_type: str, stem: str, answer: str, explanation:
         )
         if (
             not looks_like_standard_multi
-            and (question_type or "").lower() in {"hotspot", "table_choice"}
+            and normalized_type in {"hotspot", "table_choice", "matching"}
             and re.search(r"(각\s*리소스|각\s*항목|각\s*행|답변\s*영역|드롭다운|적절한\s*옵션|(?:상자|Box)\s*1)", text, re.I)
         ):
             return "per_row_choice"
@@ -151,8 +155,8 @@ def analyze_question(question: Question) -> dict:
     else:
         issues.append("정답을 찾지 못했습니다.")
 
-    question_type = (question.question_type or "").strip()
-    if question_type.lower() in {"unparsed", "unknown", ""} and re.search(r"(드래그|끌어|drag|drop)", stem, re.I):
+    question_type = normalize_question_type(question.question_type)
+    if question_type in {"unparsed", "unknown", ""} and re.search(r"(드래그|끌어|drag|drop)", stem, re.I):
         question_type = "matching"
     answer_mode = _detect_answer_mode(question_type, stem, answer, question.explanation or "", options)
     yn_labels = yes_no_labels(answer) or yes_no_labels(question.explanation or "")
@@ -160,7 +164,7 @@ def analyze_question(question: Question) -> dict:
     has_answer_areas = bool(visual.get("answer_areas"))
     has_statements = bool(visual.get("statements"))
     needs_answer_areas = _looks_like_box_dropdown(question_type, stem)
-    needs_statements = answer_mode == "yes_no_matrix" or (question_type or "").lower() == "yes_no"
+    needs_statements = answer_mode == "yes_no_matrix" or question_type == "yes_no"
     if has_answer_areas:
         answer_mode = "per_row_choice"
     if has_statements:
@@ -205,7 +209,7 @@ def analyze_question(question: Question) -> dict:
     if needs_answer_areas and not has_answer_areas:
         issues.append("상자/드롭다운형 문제로 보이지만 answer_areas 구조가 없습니다. qwen 이미지 분석이 필요합니다.")
 
-    if question_type and question_type.lower() not in {"unparsed", "unknown"}:
+    if question_type and question_type not in {"unparsed", "unknown"}:
         score += 5
     else:
         issues.append("문제 유형을 확정하지 못했습니다.")
@@ -215,11 +219,11 @@ def analyze_question(question: Question) -> dict:
         or (answer_mode == "yes_no_matrix" and bool(yn_labels) and (has_statements or not needs_statements))
         or (needs_answer_areas and has_answer_areas)
     )
-    if (question_type.lower() in VISUAL_TYPES or answer_mode == "yes_no_matrix") and image_ok and not playable_input_ready:
+    if (is_visual_question_type(question_type) or answer_mode == "yes_no_matrix") and image_ok and not playable_input_ready:
         issues.append("풀이 화면에서 사용할 보기/상자/진술 구조가 없습니다. 주관식 입력으로 처리하면 안 됩니다.")
 
     visual_playable = (
-        (question_type.lower() in VISUAL_TYPES or answer_mode == "yes_no_matrix")
+        (is_visual_question_type(question_type) or answer_mode == "yes_no_matrix")
         and image_ok
         and has_answer_text
         and len(stem) >= 20
@@ -232,7 +236,7 @@ def analyze_question(question: Question) -> dict:
         image_ok
         and len(stem) >= 20
         and (
-            question_type.lower() in VISUAL_TYPES
+            is_visual_question_type(question_type)
             or answer_mode in {"yes_no_matrix", "per_row_choice"}
         )
         and not playable_input_ready

cert_study_app/services/question_type_metadata_service.py

@@ -8,6 +8,41 @@ from sqlalchemy import func
 from cert_study_app.models import Question
 
 
+TYPE_ALIASES = {
+    "single_choice": "mcq",
+    "single select": "mcq",
+    "single-select": "mcq",
+    "multiple choice": "mcq",
+    "mcq": "mcq",
+    "multi": "multi_select",
+    "multiple_response": "multi_select",
+    "multiple-response": "multi_select",
+    "multiple select": "multi_select",
+    "multi_select": "multi_select",
+    "yes/no": "yes_no",
+    "yes no": "yes_no",
+    "yes_no": "yes_no",
+    "true_false": "yes_no",
+    "true/false": "yes_no",
+    "true/false (in-context)": "yes_no",
+    "hotspot (true/false)": "yes_no",
+    "hotspot true/false": "yes_no",
+    "hotspot": "hotspot",
+    "hotspot (drag and drop)": "matching",
+    "drag and drop": "matching",
+    "drag-and-drop": "matching",
+    "matching": "matching",
+    "ordering": "ordering",
+    "order": "ordering",
+    "sequence": "ordering",
+    "table": "table_choice",
+    "table_choice": "table_choice",
+    "table choice": "table_choice",
+    "case_study": "case_study",
+    "case study": "case_study",
+}
+
+
 TYPE_METADATA = {
     "mcq": {
         "label": "단일 선택",
@@ -87,7 +122,7 @@ STATUS_LABELS = {
 
 
 def type_metadata(question_type: Optional[str], answer_mode: Optional[str] = None) -> dict:
-    key = (question_type or "unparsed").lower()
+    key = normalize_question_type(question_type)
     metadata = dict(TYPE_METADATA.get(key, TYPE_METADATA["unparsed"]))
     metadata["type"] = key
     metadata["answer_mode"] = answer_mode or "single_choice"
@@ -106,6 +141,43 @@ def type_metadata(question_type: Optional[str], answer_mode: Optional[str] = Non
     return metadata
 
 
+def normalize_question_type(question_type: Optional[str]) -> str:
+    raw = str(question_type or "").strip().lower()
+    if not raw:
+        return "unparsed"
+    compact = raw.replace("-", " ").replace("_", " ")
+    compact = " ".join(compact.split())
+    if raw in TYPE_ALIASES:
+        return TYPE_ALIASES[raw]
+    if compact in TYPE_ALIASES:
+        return TYPE_ALIASES[compact]
+    if "true/false" in raw or "yes/no" in raw or "yes no" in compact:
+        return "yes_no"
+    if "drag" in raw or "matching" in raw:
+        return "matching"
+    if "hotspot" in raw:
+        return "hotspot"
+    if "table" in raw:
+        return "table_choice"
+    if "order" in raw or "sequence" in raw:
+        return "ordering"
+    if "multi" in raw:
+        return "multi_select"
+    if "case" in raw:
+        return "case_study"
+    if "mcq" in raw or "choice" in raw:
+        return "mcq"
+    return raw if raw in TYPE_METADATA else "unparsed"
+
+
+def is_visual_question_type(question_type: Optional[str]) -> bool:
+    return normalize_question_type(question_type) in {"yes_no", "hotspot", "table_choice", "matching", "ordering"}
+
+
+def is_ordered_answer_type(question_type: Optional[str]) -> bool:
+    return normalize_question_type(question_type) in {"ordering", "table_choice", "hotspot", "matching", "yes_no"}
+
+
 def status_label(status: Optional[str]) -> str:
     return STATUS_LABELS.get(status or "none", status or "미정")
 

cert_study_app/services/quiz_service.py

@@ -1,236 +1,25 @@
 from cert_study_app.config import DEFAULT_USER
 from cert_study_app.models import Question
 from cert_study_app.repositories.question_repository import QuestionRepository
-from cert_study_app.services.text_cleanup_service import clean_inline_text
 from cert_study_app.services.question_concept_service import concept_label
+from cert_study_app.services.answer_normalizer import (
+    choice_labels,
+    evaluate_answer,
+    extract_answer_from_stem,
+    extract_options_from_stem,
+    normalize_options,
+    option_label,
+    option_labels_from_texts,
+    option_text,
+    structured_answer_values,
+    yes_no_labels,
+)
+from cert_study_app.services.question_type_metadata_service import is_ordered_answer_type, normalize_question_type
 from typing import Optional
 import json
 import re
 
 
-def normalize_options(raw):
-    if not raw:
-        return []
-    try:
-        if isinstance(raw, dict):
-            keyed = []
-            for k, v in sorted(raw.items(), key=lambda kv: kv[0]):
-                value = clean_inline_text(v)
-                if re.match(r"^[A-Za-z1-9][\.\)]\s+", value):
-                    keyed.append(value)
-                else:
-                    keyed.append(f"{k}. {value}")
-            return split_embedded_options(keyed)
-        if isinstance(raw, list):
-            return split_embedded_options(raw)
-    except Exception:
-        pass
-    return []
-
-
-def split_embedded_options(options: list[str]) -> list[str]:
-    split = []
-    expected = "A"
-    for option in options:
-        text = clean_inline_text(option)
-        if not text:
-            continue
-        parts = list(re.finditer(r"(?<![A-Za-z0-9])([A-Z])[\.\)]\s+", text))
-        if len(parts) <= 1:
-            split.append(text)
-            continue
-        for index, match in enumerate(parts):
-            end = parts[index + 1].start() if index + 1 < len(parts) else len(text)
-            part = text[match.start() : end].strip()
-            label = match.group(1).upper()
-            if label >= expected:
-                split.append(part)
-                expected = chr(ord(label) + 1)
-    return split
-
-
-def extract_options_from_stem(stem: str) -> list[str]:
-    lines = [line.strip() for line in (stem or "").splitlines() if line.strip()]
-    options = []
-    current_key = None
-    current_parts = []
-    expected = "A"
-
-    def flush():
-        if current_key and current_parts:
-            text = " ".join(current_parts).strip()
-            if text:
-                options.append(f"{current_key}. {text}")
-
-    for line in lines:
-        if re.match(r"^(answer|정답|explanation|reference)\b", line, re.I):
-            flush()
-            current_key = None
-            current_parts = []
-            break
-
-        marker = None
-        body = ""
-        exact = re.match(r"^([A-Z])[\.\)]?$", line, re.I)
-        inline = re.match(r"^([A-Z])[\.\)]?\s+(.+)$", line, re.I)
-        if exact:
-            marker = exact.group(1).upper()
-        elif inline:
-            marker = inline.group(1).upper()
-            body = inline.group(2).strip()
-
-        if marker and marker >= expected:
-            flush()
-            current_key = marker
-            current_parts = [body] if body else []
-            expected = chr(ord(marker) + 1)
-        elif current_key:
-            current_parts.append(line)
-
-    flush()
-    return options if len(options) >= 2 else []
-
-
-def extract_answer_from_stem(stem: str) -> str:
-    match = re.search(r"(?:Answer|정답)\s*:?\s*([A-Z1-9])", stem or "", re.I)
-    if not match:
-        return ""
-    value = match.group(1).upper()
-    if value.isdigit():
-        return chr(ord("A") + int(value) - 1)
-    return value
-
-
-def option_label(value: str) -> str:
-    value = str(value or "").strip().upper()
-    if value.isdigit():
-        return chr(ord("A") + int(value) - 1)
-    match = re.match(r"^([A-Z])(?:[\s\.,\)]|$)", value)
-    return match.group(1) if match else value
-
-
-def choice_labels(value: str) -> list[str]:
-    text = str(value or "").strip().upper()
-    if not text:
-        return []
-    if re.fullmatch(r"[A-Z]{2,26}", text):
-        return list(text)
-    tokens = re.findall(r"\b[A-Z]\b|\b[1-9]\b", text)
-    return [option_label(token) for token in tokens]
-
-
-def normalize_choice_answer(value: str, ordered: bool = False) -> str:
-    yn = yes_no_labels(value)
-    if yn:
-        return ",".join(yn)
-    labels = choice_labels(value)
-    if not labels:
-        return option_label(value)
-    if ordered:
-        return ",".join(labels)
-    return ",".join(sorted(set(labels)))
-
-
-def yes_no_labels(value: str) -> list[str]:
-    if isinstance(value, (list, dict)):
-        raw_value = value
-    else:
-        raw_value = None
-        try:
-            raw_value = json.loads(value) if isinstance(value, str) else None
-        except Exception:
-            raw_value = None
-
-    if isinstance(raw_value, list):
-        values = [
-            item.get("value") or item.get("answer") or item.get("selected_answer")
-            for item in raw_value
-            if isinstance(item, dict)
-        ]
-        labels = yes_no_labels(",".join(str(item) for item in values if item))
-        if labels:
-            return labels
-    elif isinstance(raw_value, dict):
-        labels = yes_no_labels(",".join(str(item) for item in raw_value.values()))
-        if labels:
-            return labels
-
-    text = str(value or "").strip().lower()
-    if not text:
-        return []
-    if re.fullmatch(r"[yn](?:\s*,\s*[yn])+", text, re.I):
-        return [token.upper() for token in re.findall(r"[yn]", text, re.I)]
-    tokens = re.findall(r"(?<![가-힣])예(?![가-힣])|아니오|아니요|\byes\b|\bno\b", text, re.I)
-    labels = []
-    for token in tokens:
-        lowered = token.lower()
-        labels.append("Y" if token == "예" or lowered == "yes" else "N")
-    return labels if len(labels) >= 2 else []
-
-
-def structured_answer_values(value) -> list[str]:
-    if isinstance(value, (list, dict)):
-        raw_value = value
-    else:
-        try:
-            raw_value = json.loads(value) if isinstance(value, str) else None
-        except Exception:
-            raw_value = None
-
-    if isinstance(raw_value, list):
-        values = [
-            item.get("value") or item.get("answer") or item.get("selected_answer")
-            for item in raw_value
-            if isinstance(item, dict)
-        ]
-    elif isinstance(raw_value, dict):
-        values = list(raw_value.values())
-    else:
-        return []
-    return [str(item).strip() for item in values if str(item).strip()]
-
-
-def option_text(options: list[str], label: str) -> str:
-    label = option_label(label)
-    for index, option in enumerate(options, 1):
-        text = str(option).strip()
-        keys = {str(index), chr(ord("A") + index - 1)}
-        match = re.match(r"^([A-Z1-9])[\.\)]\s+(.+)$", text, re.I)
-        if match:
-            keys.add(option_label(match.group(1)))
-            if match.group(1).isdigit():
-                keys.add(match.group(1))
-        if label in keys:
-            return text
-    return ""
-
-
-def _option_body(option: str) -> str:
-    text = str(option or "").strip()
-    match = re.match(r"^([A-Z1-9])[\.\)]\s+(.+)$", text, re.I)
-    return (match.group(2) if match and match.group(2) else text).strip()
-
-
-def option_labels_from_texts(options: list[str], values, allow_duplicates: bool = False) -> list[str]:
-    if not values:
-        return []
-    if isinstance(values, str):
-        values = [values]
-    labels = []
-    for value in values:
-        target = re.sub(r"\s+", " ", str(value or "").strip()).lower()
-        if not target:
-            continue
-        for index, option in enumerate(options, 1):
-            body = re.sub(r"\s+", " ", _option_body(option)).lower()
-            if body and (target == body or target in body or body in target):
-                label = chr(ord("A") + index - 1)
-                if allow_duplicates or label not in labels:
-                    labels.append(label)
-                break
-    return labels
-
-
 def visual_analysis(question) -> dict:
     try:
         return json.loads(question.visual_analysis_json) if question.visual_analysis_json else {}
@@ -246,20 +35,17 @@ def clean_explanation(raw: str) -> str:
 
 def effective_answer(question) -> str:
     answer = question.answer or ""
-    question_type = (question.question_type or "").lower()
+    question_type = normalize_question_type(question.question_type)
     options = normalize_options(question.get_options()) or extract_options_from_stem(question.stem)
     structured_values = structured_answer_values(answer)
     if structured_values:
         structured_yn = yes_no_labels(",".join(structured_values))
         return ",".join(structured_yn or structured_values)
 
-    is_structured_visual = any(
-        keyword in question_type
-        for keyword in ["hotspot", "table_choice", "matching", "ordering", "yes_no", "true/false"]
-    ) and "in-context" not in question_type
+    is_structured_visual = question_type in {"hotspot", "table_choice", "matching", "ordering", "yes_no"}
     if is_structured_visual:
         answer_labels = yes_no_labels(answer)
-        if answer_labels and "true/false" in question_type:
+        if answer_labels and question_type == "yes_no":
             return ",".join(answer_labels)
         analysis = visual_analysis(question)
         statements = analysis.get("statements")
@@ -294,7 +80,7 @@ def effective_answer(question) -> str:
 
 def build_tutor_explanation(question, chosen: str, answer: str) -> str:
     options = normalize_options(question.get_options()) or extract_options_from_stem(question.stem)
-    ordered = (question.question_type or "").lower() in {"ordering", "table_choice", "hotspot"}
+    ordered = is_ordered_answer_type(question.question_type)
     answer_yn = yes_no_labels(answer)
     chosen_yn = yes_no_labels(chosen)
     answer_labels = choice_labels(answer)
@@ -306,7 +92,7 @@ def build_tutor_explanation(question, chosen: str, answer: str) -> str:
     answer_option_lines = [line for line in answer_option_lines if line]
     chosen_option_lines = [option_text(options, label) for label in chosen_labels]
     chosen_option_lines = [line for line in chosen_option_lines if line]
-    correct = normalize_choice_answer(chosen, ordered=ordered) == normalize_choice_answer(answer, ordered=ordered)
+    correct = evaluate_answer(chosen, answer, ordered=ordered).correct
 
     lines = [f"#### 정답", f"**{answer_label}**"]
     for answer_option in answer_option_lines:
@@ -470,8 +256,8 @@ class QuizService:
         answer = effective_answer(question)
         if not answer or answer in {"[]", "{}", "None"}:
             answer = extract_answer_from_stem(question.stem)
-        ordered = (question.question_type or "").lower() in {"ordering", "table_choice", "hotspot"}
-        correct = normalize_choice_answer(chosen, ordered=ordered) == normalize_choice_answer(answer, ordered=ordered)
+        evaluation = evaluate_answer(chosen, answer, ordered=is_ordered_answer_type(question.question_type))
+        correct = evaluation.correct
         self.repo.add_attempt(
             user_id=user_id,
             question_id=question.id,

docker-compose.yml

@@ -3,15 +3,15 @@ services:
     image: postgres:16-alpine
     container_name: cert-study-postgres
     environment:
-      POSTGRES_DB: cert_study
-      POSTGRES_USER: cert_study
-      POSTGRES_PASSWORD: cert_study
+      POSTGRES_DB: ${POSTGRES_DB:-cert_study}
+      POSTGRES_USER: ${POSTGRES_USER:-cert_study}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-cert_study}
     ports:
       - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U cert_study -d cert_study"]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-cert_study} -d ${POSTGRES_DB:-cert_study}"]
       interval: 5s
       timeout: 5s
       retries: 20
@@ -30,16 +30,16 @@ services:
       STREAMLIT_SERVER_ADDRESS: 0.0.0.0
       STREAMLIT_SERVER_PORT: 8501
       STREAMLIT_BROWSER_GATHER_USAGE_STATS: "false"
-      CERT_STUDY_LLM_PROVIDER: ollama
-      OLLAMA_MODEL: qwen2.5:14b
-      OLLAMA_FAST_MODEL: qwen3.5:9b
-      OLLAMA_VISUAL_MODEL: qwen3-vl:8b-instruct-q4_K_M
-      EMBEDDING_MODEL: BAAI/bge-m3
-      OLLAMA_BASE_URL: http://host.docker.internal:11434
-      DATABASE_URL: postgresql+pg8000://cert_study:cert_study@postgres:5432/cert_study
-      AIRFLOW_API_BASE_URL: http://host.docker.internal:8080
-      AIRFLOW_API_USERNAME: admin
-      AIRFLOW_API_PASSWORD: admin
+      CERT_STUDY_LLM_PROVIDER: ${CERT_STUDY_LLM_PROVIDER:-ollama}
+      OLLAMA_MODEL: ${OLLAMA_MODEL:-qwen2.5:14b}
+      OLLAMA_FAST_MODEL: ${OLLAMA_FAST_MODEL:-qwen3.5:9b}
+      OLLAMA_VISUAL_MODEL: ${OLLAMA_VISUAL_MODEL:-qwen3-vl:8b-instruct-q4_K_M}
+      EMBEDDING_MODEL: ${EMBEDDING_MODEL:-BAAI/bge-m3}
+      OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://host.docker.internal:11434}
+      DATABASE_URL: ${DATABASE_URL:-postgresql+pg8000://cert_study:cert_study@postgres:5432/cert_study}
+      AIRFLOW_API_BASE_URL: ${AIRFLOW_API_BASE_URL:-http://host.docker.internal:8080}
+      AIRFLOW_API_USERNAME: ${AIRFLOW_API_USERNAME:-admin}
+      AIRFLOW_API_PASSWORD: ${AIRFLOW_API_PASSWORD:-admin}
     volumes:
       - ./data:/app/data
       - ./chroma_db:/app/chroma_db
@@ -57,20 +57,23 @@ services:
     entrypoint: /bin/bash
     command:
       - -c
-      - airflow db migrate && airflow users create --username admin --password admin --firstname Cert --lastname Study --role Admin --email admin@example.com || true
+      - airflow db migrate && airflow users create --username "$${AIRFLOW_ADMIN_USERNAME:-admin}" --password "$${AIRFLOW_ADMIN_PASSWORD:-admin}" --firstname Cert --lastname Study --role Admin --email "$${AIRFLOW_ADMIN_EMAIL:-admin@example.com}" || true
     environment: &airflow-env
       AIRFLOW__CORE__EXECUTOR: SequentialExecutor
       AIRFLOW__CORE__LOAD_EXAMPLES: "false"
       AIRFLOW__CORE__DAGS_ARE_PAUSED_AT_CREATION: "false"
       AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: sqlite:////opt/airflow_db/airflow.db
       AIRFLOW__API__AUTH_BACKENDS: airflow.api.auth.backend.basic_auth
-      CERT_STUDY_LLM_PROVIDER: ollama
-      OLLAMA_MODEL: qwen2.5:14b
-      OLLAMA_FAST_MODEL: qwen3.5:9b
-      OLLAMA_VISUAL_MODEL: qwen3-vl:8b-instruct-q4_K_M
-      EMBEDDING_MODEL: BAAI/bge-m3
-      OLLAMA_BASE_URL: http://host.docker.internal:11434
-      DATABASE_URL: postgresql+pg8000://cert_study:cert_study@postgres:5432/cert_study
+      CERT_STUDY_LLM_PROVIDER: ${CERT_STUDY_LLM_PROVIDER:-ollama}
+      OLLAMA_MODEL: ${OLLAMA_MODEL:-qwen2.5:14b}
+      OLLAMA_FAST_MODEL: ${OLLAMA_FAST_MODEL:-qwen3.5:9b}
+      OLLAMA_VISUAL_MODEL: ${OLLAMA_VISUAL_MODEL:-qwen3-vl:8b-instruct-q4_K_M}
+      EMBEDDING_MODEL: ${EMBEDDING_MODEL:-BAAI/bge-m3}
+      OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://host.docker.internal:11434}
+      DATABASE_URL: ${DATABASE_URL:-postgresql+pg8000://cert_study:cert_study@postgres:5432/cert_study}
+      AIRFLOW_ADMIN_USERNAME: ${AIRFLOW_ADMIN_USERNAME:-admin}
+      AIRFLOW_ADMIN_PASSWORD: ${AIRFLOW_ADMIN_PASSWORD:-admin}
+      AIRFLOW_ADMIN_EMAIL: ${AIRFLOW_ADMIN_EMAIL:-admin@example.com}
       PYTHONPATH: /opt/airflow
     volumes: &airflow-volumes
       - ./dags:/opt/airflow/dags

docs/02_architecture.md

@@ -15,6 +15,8 @@
 | Streamlit | 사용자 화면 제공, PDF 업로드, 문제풀이 UI |
 | PostgreSQL | 문제, 보기, 정답, 해설, 사용자 풀이 기록 저장 |
 | Chroma | 문제 임베딩 저장, 유사 문제 검색 |
+| Question Type Metadata | 다양한 문제 유형 이름을 내부 표준 유형으로 정리 |
+| Answer Normalizer | 객관식, 복수 선택, Yes/No, 순서형 답안을 비교 가능한 형태로 정규화 |
 | Airflow | PDF 처리, 파싱, 임베딩, 저장 작업의 파이프라인 관리 |
 | Docker / Docker Compose | 개발 및 실행 환경 표준화 |
 | Oracle Cloud Ubuntu | 향후 서비스 배포 대상 서버 |
@@ -51,6 +53,10 @@
 
 현재 코드 기준으로는 Streamlit 화면이 `QuizService`, `IngestionJobService`, `QuestionVectorStore` 같은 서비스 계층을 호출하고, PDF 처리처럼 시간이 오래 걸리는 작업은 Airflow DAG와 PDF Ingestion Graph를 통해 단계별로 실행됩니다.
 
+문제풀이 흐름에서는 문제 유형이 여러 이름으로 들어올 수 있기 때문에 `question_type_metadata_service.py`에서 먼저 표준 유형으로 정리합니다. 예를 들어 `Hotspot (True/False)`는 내부적으로 Yes/No 진술형으로, `Hotspot (Drag and Drop)`은 매칭형으로 다룹니다.
+
+정답 비교는 `answer_normalizer.py`를 통해 처리합니다. 이 계층은 `Y,N,Y`, `예/아니오`, 복수 선택, 순서가 중요한 답안을 비교 가능한 문자열로 정리합니다. 이렇게 해 두면 화면 UI와 채점 로직이 서로 다른 기준으로 동작하는 문제를 줄일 수 있습니다.
+
 ## 6. PDF 처리 흐름
 
 PDF 업로드 이후에는 파싱 과정을 통해 문제를 추출하고, 문제/보기/정답/해설 형태로 구조화합니다.
@@ -73,6 +79,8 @@ PDF 업로드 이후에는 파싱 과정을 통해 문제를 추출하고, 문
 8. 최종 검증
 9. 처리 완료
 
+파싱 품질 검증에서도 문제 유형 표준화 결과를 사용합니다. 시각형 문제를 일반 객관식으로 잘못 보고 `보기가 부족하다`고 판단하는 일을 줄이기 위한 구조입니다.
+
 ## 7. 데이터 저장 구조
 
 이 시스템에서는 PostgreSQL과 Chroma를 함께 사용합니다.
@@ -136,6 +144,7 @@ Chroma는 별도 컨테이너라기보다 현재 프로젝트의 `chroma_db` 디
 현재 프로젝트는 개발 중이며, 다음 기능을 중심으로 구현하고 있습니다.
 
 - Streamlit 기반 문제풀이 화면
+- 문제 유형 표준화 및 정답 정규화 구조
 - PDF 업로드 및 파싱 구조
 - PostgreSQL 기반 문제 데이터 저장
 - Chroma 기반 유사 문제 검색 구조
@@ -152,6 +161,7 @@ Chroma는 별도 컨테이너라기보다 현재 프로젝트의 `chroma_db` 디
 - 오답노트 자동 생성
 - 북마크 기능
 - 카테고리별 문제 분류
+- 문제 유형별 테스트 범위 확대
 - LLM 기반 해설 보조 생성
 - 유사 문제 추천
 - PDF 파싱 실패 케이스 관리

docs/05_deployment.md

@@ -15,6 +15,7 @@
 ## 로컬 실행
 
 ```bash
+cp .env.example .env
 docker compose up --build
 ```
 
@@ -73,7 +74,20 @@ Space에는 아래 런타임 데이터는 올리지 않습니다.
 
 대신 `cert_study_app/demo_data/questions_seed.json`과 `static/question_assets/`를 포함합니다. 앱 시작 시 DB가 비어 있거나 기존 seed가 오래된 경우 seed 기준으로 문제를 추가/갱신합니다.
 
-현재 seed에는 321문항, 공통 지문, 원문 이미지, Yes/No 진술형 문제 구조가 포함됩니다.
+현재 seed에는 321문항, 공통 지문 포함 36문항, 원문 이미지, Yes/No 진술형 문제 구조가 포함됩니다.
+
+seed를 다시 만들면 검증 리포트도 함께 생성됩니다.
+
+```bash
+python scripts/export_hf_seed.py
+```
+
+생성 파일:
+
+- `cert_study_app/demo_data/questions_seed.json`
+- `cert_study_app/demo_data/questions_seed.report.json`
+
+리포트에서는 전체 문항 수, 공통 지문 포함 문항 수, 유형별 개수, 중복 번호, 정답 누락, 이미지 누락 여부를 확인할 수 있습니다.
 
 ## 환경 변수
 
@@ -96,6 +110,19 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
 
 운영 배포에서는 비밀번호와 API 정보가 코드에 직접 들어가지 않도록 `.env` 또는 서버 비밀값 관리 방식을 사용해야 합니다.
 
+처음 실행할 때는 예시 파일을 복사해서 시작합니다.
+
+```bash
+cp .env.example .env
+```
+
+운영 환경에서는 최소한 아래 값은 기본값에서 바꾸는 것이 좋습니다.
+
+- `POSTGRES_PASSWORD`
+- `DATABASE_URL`
+- `AIRFLOW_API_PASSWORD`
+- `AIRFLOW_ADMIN_PASSWORD`
+
 ## Oracle Cloud Ubuntu에 배포하려는 이유
 
 향후 배포 대상은 Oracle Cloud Ubuntu 서버를 계획하고 있습니다.
@@ -120,14 +147,14 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
 
 ## 배포 전에 정리할 것
 
-- 운영용 비밀번호 분리
-- `.env.example` 정리
+- 운영용 비밀번호를 `.env`로 분리
 - PostgreSQL 데이터 백업 방식
 - Chroma 인덱스 재생성 방식
 - Airflow 관리자 계정 설정
 - 업로드 파일 저장 위치
 - 로그 관리
 - HTTPS 적용 여부
+- `python scripts/check_quality.py` 통과 여부
 
 ## 현재 상태
 

docs/06_decision_log.md

@@ -170,3 +170,49 @@ PDF 파싱 후 바로 저장하지 않고, 파싱 품질 검증과 Quality Gate
 ### 결과
 
 파이프라인 단계는 늘어나지만, 문제 데이터의 신뢰도를 높일 수 있습니다. 앞으로는 품질 리포트를 UI에서 더 보기 쉽게 만드는 작업이 필요합니다.
+
+## ADR-008. 문제 유형과 정답 비교는 별도 계층에서 표준화한다
+
+- 상태: 채택
+- 날짜: 2026-06-07
+
+### 배경
+
+자격증 문제에는 단일 선택, 복수 선택, Yes/No 진술형, 핫스팟, 드래그 앤 드롭, 공통 지문 문제가 섞여 있습니다. 원본 데이터의 `question_type`도 `Hotspot (True/False)`처럼 다양한 문자열로 들어올 수 있습니다.
+
+### 결정
+
+문제 유형은 `question_type_metadata_service.py`에서 내부 표준 유형으로 변환하고, 정답 비교는 `answer_normalizer.py`에서 처리한다.
+
+### 이유
+
+- 화면, 검수, 채점 로직이 서로 다른 기준을 쓰는 문제를 줄일 수 있다.
+- 새 문제 유형 alias가 들어와도 한 곳에서 추가할 수 있다.
+- Yes/No와 순서형 답안처럼 일반 객관식과 다른 채점 방식을 분리할 수 있다.
+
+### 결과
+
+문제풀이 화면과 자동 검수 서비스가 같은 문제 유형 기준을 공유합니다. 앞으로 새 유형을 추가할 때는 먼저 표준 유형 변환과 테스트를 추가해야 합니다.
+
+## ADR-009. 배포 전 품질 검사는 스크립트와 GitHub Actions로 자동화한다
+
+- 상태: 채택
+- 날짜: 2026-06-07
+
+### 배경
+
+Hugging Face Space에는 DB 전체가 아니라 seed 파일과 정적 이미지를 올립니다. 따라서 seed 구조, 문제 유형 alias, 정답 정규화가 깨지면 배포 후 문제풀이가 바로 영향을 받습니다.
+
+### 결정
+
+`scripts/check_quality.py`를 추가하고, GitHub Actions에서 핵심 테스트와 문법 검사를 실행한다.
+
+### 이유
+
+- push 전에 로컬에서 같은 검사를 실행할 수 있다.
+- GitHub에서도 최소 품질 검사를 자동으로 남길 수 있다.
+- 무거운 OCR/LLM 의존성을 설치하지 않고 핵심 도메인 로직만 빠르게 검증할 수 있다.
+
+### 결과
+
+현재 자동 검사는 문제 유형/정답/seed 리포트 중심입니다. 이후 PDF 파싱과 DB 저장 테스트까지 점진적으로 넓힐 수 있습니다.

docs/07_troubleshooting.md

@@ -212,6 +212,33 @@ Yes/No 진술형 문제는 일반 객관식과 다르게 진술별 `예 / 아니
 - 정답이 `Y,N,Y` 또는 `[{key, value}]` 형태로 정규화되는지 확인한다.
 - `1-A / 1-B / 2-A / 2-B` 형식은 항목별 선택 UI로 표시되어야 한다.
 
+### 확인 명령
+
+문제 유형 alias와 정답 정규화 테스트를 먼저 실행한다.
+
+```bash
+python -m pytest tests/test_answer_normalizer.py tests/test_question_type_metadata_service.py
+```
+
+### 해결 방향
+
+- 새 문제 유형 문자열이 추가되면 `question_type_metadata_service.py`의 alias에 먼저 등록한다.
+- 채점이 이상하면 화면 코드보다 `answer_normalizer.py`에서 `chosen`과 `answer`가 같은 기준으로 정규화되는지 확인한다.
+- Yes/No는 일반 객관식 A/B/C가 아니라 `Y,N,Y`처럼 행별 답안으로 비교하는 것이 기준이다.
+
+## 모바일 화면이 복잡하게 보일 때
+
+### 증상
+
+휴대폰에서 메뉴가 너무 많거나, 답안 선택 영역이 작아 보입니다.
+
+### 해결 방향
+
+- 홈 화면은 문제풀이, 오답/복습, 개념 정리 같은 학습 기능을 먼저 보여준다.
+- PDF 업로드, 처리 현황, AI 색인은 `업로드/관리` 영역으로 묶는다.
+- 답안 선택 UI는 최소 44px 이상의 터치 영역을 유지한다.
+- 문제 유형별로 radio, checkbox, selectbox, Yes/No matrix를 구분해서 사용한다.
+
 ## Chroma 검색 결과가 이상할 때
 
 ### 증상

docs/08_publish_automation.md

@@ -71,10 +71,19 @@ python scripts/export_hf_seed.py
 생성 결과:
 
 - `cert_study_app/demo_data/questions_seed.json`
+- `cert_study_app/demo_data/questions_seed.report.json`
 - `static/question_assets/`
 
 `dump.pdf` 전체나 `data/images/` 전체를 올리지 않고, 문제풀이와 원문 확인에 필요한 참조 이미지만 복사합니다. 현재 seed에는 321문항, 공통 지문, 원문 이미지, Yes/No 진술형 문제 구조가 포함됩니다.
 
+push 전에 핵심 검사를 실행하면 유형 처리나 seed 리포트 오류를 먼저 잡을 수 있습니다.
+
+```bash
+python scripts/check_quality.py
+```
+
+`main` 브랜치에 push하면 `Quality Check` GitHub Actions가 먼저 실행되고, 같은 push 이벤트에서 Hugging Face 동기화 workflow도 실행됩니다.
+
 실제 기출/덤프 성격의 문제를 포함하는 경우 Hugging Face Space는 private로 운영하는 것을 권장합니다.
 
 데모 seed를 끄고 싶다면 실행 환경에 아래 값을 설정합니다.
@@ -158,6 +167,7 @@ git push hf main
 평소에는 아래 방식이 가장 단순합니다.
 
 ```bash
+python scripts/check_quality.py
 git push origin main
 ```
 

docs/devlog/2026-06-07.md

@@ -129,3 +129,28 @@ GitHub와 Hugging Face Space 배포 자동화를 정리했다. Hugging Face에
 ```bash
 scripts/git_daily_changes.sh 2026-06-07
 ```
+
+## 문제 유형/모바일 UI 개선
+
+문제 유형이 여러 형태로 들어오면서 화면 표시와 채점 기준이 어긋날 수 있는 문제가 있었다. 예를 들어 `Hotspot (True/False)`, `True/False (In-Context)`, `Hotspot (Drag and Drop)`처럼 원문에서 온 유형명이 내부 로직과 정확히 맞지 않으면 Yes/No 문제가 객관식처럼 보이거나, 순서가 중요한 답안이 일반 복수 선택처럼 비교될 수 있었다.
+
+이를 줄이기 위해 다음 구조를 추가했다.
+
+- `answer_normalizer.py`: Yes/No, 객관식, 복수 선택, 순서형 답안을 비교 가능한 형태로 정규화
+- `question_type_metadata_service.py`: 다양한 문제 유형명을 내부 표준 유형으로 변환
+- `tests/test_answer_normalizer.py`: 정답 정규화 테스트
+- `tests/test_question_type_metadata_service.py`: 문제 유형 alias 테스트
+
+모바일 화면은 문제풀이를 첫 번째 동선으로 두고, 업로드/처리 현황/AI 색인은 관리 영역으로 묶었다. 답안 선택 UI는 터치하기 쉽도록 버튼과 radio 영역의 높이와 간격을 조정했다.
+
+## 배포/품질 보완
+
+추가로 배포 전에 놓치기 쉬운 부분을 정리했다.
+
+- seed 갱신 시 사람이 검수한 문제를 기본적으로 덮어쓰지 않도록 보호
+- seed export 결과를 `questions_seed.report.json`으로 저장
+- `scripts/check_quality.py`로 문법 검사와 핵심 테스트를 한 번에 실행
+- GitHub Actions `quality-check.yml` 추가
+- `.env.example` 추가
+- Docker Compose에서 비밀번호와 모델 설정을 환경 변수로 분리
+- `CHANGELOG.md` 추가

requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest==8.4.1

scripts/check_quality.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+PYTHON_FILES = [
+    "streamlit_app.py",
+    "cert_study_app/services/answer_normalizer.py",
+    "cert_study_app/services/demo_seed_service.py",
+    "cert_study_app/services/parse_quality_service.py",
+    "cert_study_app/services/question_review_service.py",
+    "cert_study_app/services/question_type_metadata_service.py",
+    "cert_study_app/services/quiz_service.py",
+    "scripts/export_hf_seed.py",
+]
+
+TEST_FILES = [
+    "tests/test_answer_normalizer.py",
+    "tests/test_question_type_metadata_service.py",
+    "tests/test_export_hf_seed.py",
+]
+
+
+def run(command: list[str]) -> None:
+    print("+", " ".join(command))
+    subprocess.run(command, check=True)
+
+
+def main() -> int:
+    run([sys.executable, "-m", "py_compile", *PYTHON_FILES])
+    run([sys.executable, "-m", "pytest", *TEST_FILES])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/export_hf_seed.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import shutil
 from pathlib import Path
 from typing import Any
@@ -13,6 +14,7 @@ DEFAULT_PARENT_SOURCE_JSON = ROOT / "data" / "parsed_json" / "reparsed_multipage
 DEFAULT_IMAGE_ROOT = ROOT / "data" / "images"
 DEFAULT_SEED_PATH = ROOT / "cert_study_app" / "demo_data" / "questions_seed.json"
 DEFAULT_ASSET_ROOT = ROOT / "static" / "question_assets"
+DEFAULT_REPORT_PATH = ROOT / "cert_study_app" / "demo_data" / "questions_seed.report.json"
 
 
 def _load_rows(path: Path) -> list[dict[str, Any]]:
@@ -75,6 +77,15 @@ def _copy_image_reference(image_path: Any, asset_root: Path) -> str | None:
     return _copy_image(source_path, asset_root)
 
 
+def _asset_exists(path: Any) -> bool:
+    if not path:
+        return False
+    asset_path = Path(str(path))
+    if not asset_path.is_absolute():
+        asset_path = ROOT / asset_path
+    return asset_path.exists()
+
+
 def _question_number(row: dict[str, Any]) -> Any:
     return row.get("question_number") or row.get("question_id") or row.get("number")
 
@@ -111,6 +122,15 @@ def _parent_context_by_scenario(
     return contexts
 
 
+def _meaningful_parent_stem(value: Any) -> str | None:
+    text = str(value or "").strip()
+    if not text or text == "단일문제":
+        return None
+    if len(text) < 40 and not re.search(r"[\n:]", text):
+        return None
+    return text
+
+
 def _export_row(
     row: dict[str, Any],
     image_root: Path,
@@ -143,6 +163,11 @@ def _export_row(
         if copied_path:
             parent_image_paths.append(copied_path)
 
+    parent_stem = (
+        _meaningful_parent_stem(parent_context.get("parent_stem"))
+        or _meaningful_parent_stem(row.get("parent_stem"))
+    )
+
     return {
         "question_number": question_number,
         "stem": row.get("stem") or row.get("question") or "",
@@ -157,7 +182,7 @@ def _export_row(
         "image_path": image_path,
         "raw_text": row.get("raw_text") or row.get("stem") or row.get("question") or "",
         "group_id": parent_context.get("group_id") or row.get("group_id"),
-        "parent_stem": parent_context.get("parent_stem") or row.get("parent_stem") or row.get("scenario"),
+        "parent_stem": parent_stem,
         "parent_image_paths": parent_image_paths,
         "concept_tags": row.get("concept_tags") or [],
         "parse_status": row.get("parse_status") or "approved",
@@ -177,6 +202,7 @@ def export_seed(
     image_root: Path,
     seed_path: Path,
     asset_root: Path,
+    report_path: Path | None = DEFAULT_REPORT_PATH,
 ) -> int:
     rows = _load_rows(source_json)
     parent_rows = _load_rows(parent_source_json) if parent_source_json.exists() else []
@@ -192,9 +218,74 @@ def export_seed(
     with seed_path.open("w", encoding="utf-8") as file:
         json.dump(exported, file, ensure_ascii=False, indent=2)
         file.write("\n")
+    if report_path:
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        with report_path.open("w", encoding="utf-8") as file:
+            json.dump(build_seed_report(exported, seed_path), file, ensure_ascii=False, indent=2)
+            file.write("\n")
     return len(exported)
 
 
+def build_seed_report(rows: list[dict[str, Any]], seed_path: Path) -> dict[str, Any]:
+    numbers = []
+    duplicate_numbers = []
+    seen_numbers = set()
+    type_counts: dict[str, int] = {}
+    missing_images = []
+    missing_answers = []
+    missing_options = []
+    common_passage_count = 0
+
+    for row in rows:
+        number = row.get("question_number")
+        if number in seen_numbers:
+            duplicate_numbers.append(number)
+        seen_numbers.add(number)
+        numbers.append(number)
+        question_type = str(row.get("question_type") or "unparsed")
+        type_counts[question_type] = type_counts.get(question_type, 0) + 1
+        if row.get("parent_stem"):
+            common_passage_count += 1
+        if not row.get("answer"):
+            missing_answers.append(number)
+        if not row.get("options"):
+            missing_options.append(number)
+        image_paths = [row.get("image_path")] + list(row.get("parent_image_paths") or [])
+        for image_path in image_paths:
+            if image_path and not _asset_exists(image_path):
+                missing_images.append({"question_number": number, "image_path": image_path})
+
+    numeric_numbers = []
+    for number in numbers:
+        try:
+            numeric_numbers.append(int(number))
+        except Exception:
+            continue
+
+    return {
+        "schema_version": 1,
+        "seed_path": _display_path(seed_path),
+        "question_count": len(rows),
+        "first_question_number": min(numeric_numbers) if numeric_numbers else None,
+        "last_question_number": max(numeric_numbers) if numeric_numbers else None,
+        "common_passage_count": common_passage_count,
+        "type_counts": dict(sorted(type_counts.items())),
+        "duplicate_numbers": duplicate_numbers,
+        "missing_answers": missing_answers,
+        "missing_options": missing_options,
+        "missing_images": missing_images,
+        "ready": not duplicate_numbers and not missing_answers and not missing_images,
+    }
+
+
+def _display_path(path: Path) -> str:
+    try:
+        resolved = path.resolve()
+        return resolved.relative_to(ROOT).as_posix()
+    except Exception:
+        return path.as_posix()
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Export deployable question seed data for Hugging Face Space.")
     parser.add_argument("--source-json", type=Path, default=DEFAULT_SOURCE_JSON)
@@ -202,6 +293,7 @@ def main() -> None:
     parser.add_argument("--image-root", type=Path, default=DEFAULT_IMAGE_ROOT)
     parser.add_argument("--seed-path", type=Path, default=DEFAULT_SEED_PATH)
     parser.add_argument("--asset-root", type=Path, default=DEFAULT_ASSET_ROOT)
+    parser.add_argument("--report-path", type=Path, default=DEFAULT_REPORT_PATH)
     args = parser.parse_args()
 
     count = export_seed(
@@ -210,8 +302,10 @@ def main() -> None:
         image_root=args.image_root,
         seed_path=args.seed_path,
         asset_root=args.asset_root,
+        report_path=args.report_path,
     )
     print(f"Exported {count} questions to {args.seed_path}")
+    print(f"Wrote seed report to {args.report_path}")
 
 
 if __name__ == "__main__":

streamlit_app.py

@@ -20,7 +20,12 @@ from cert_study_app.services.concept_note_service import ConceptNoteService
 from cert_study_app.services.demo_seed_service import seed_demo_questions_if_empty
 from cert_study_app.services.ingestion_job_service import IngestionJobService
 from cert_study_app.services.parse_quality_service import default_quality_report_path
-from cert_study_app.services.question_type_metadata_service import automation_summary, status_label, type_metadata
+from cert_study_app.services.question_type_metadata_service import (
+    automation_summary,
+    normalize_question_type,
+    status_label,
+    type_metadata,
+)
 from cert_study_app.services.question_concept_service import classify_question_batch, concept_label
 from cert_study_app.services.quiz_service import QuizService, yes_no_labels
 from cert_study_app.services.study_assistant_service import StudyAssistantService
@@ -112,8 +117,13 @@ def apply_mobile_styles():
     st.markdown(
         """
         <style>
+        :root {
+            --cert-primary: #2563eb;
+            --cert-border: rgba(15, 23, 42, 0.12);
+            --cert-soft: rgba(37, 99, 235, 0.08);
+        }
         .block-container {
-            padding-top: 1rem;
+            padding-top: 0.75rem;
             padding-left: 1rem;
             padding-right: 1rem;
             max-width: 760px;
@@ -123,6 +133,36 @@ def apply_mobile_styles():
         }
         div[data-testid="stButton"] > button {
             min-height: 44px;
+            border-radius: 8px;
+            white-space: normal;
+            line-height: 1.25;
+        }
+        div[data-testid="stRadio"] label,
+        div[data-testid="stCheckbox"] label {
+            min-height: 40px;
+            align-items: flex-start;
+        }
+        div[role="radiogroup"] > label {
+            border: 1px solid var(--cert-border);
+            border-radius: 8px;
+            padding: 0.55rem 0.7rem;
+            margin-bottom: 0.35rem;
+        }
+        div[role="radiogroup"] > label:has(input:checked) {
+            border-color: var(--cert-primary);
+            background: var(--cert-soft);
+        }
+        .cert-quick-actions {
+            display: grid;
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+            gap: 0.5rem;
+            margin: 0.35rem 0 0.75rem;
+        }
+        .cert-section-title {
+            margin: 1.2rem 0 0.35rem;
+            font-size: 0.95rem;
+            font-weight: 700;
+            color: rgba(15, 23, 42, 0.72);
         }
         div[role="radiogroup"] {
             gap: 0.35rem;
@@ -147,6 +187,10 @@ def apply_mobile_styles():
             margin-top: 0.8rem;
         }
         @media (max-width: 640px) {
+            .block-container {
+                padding-left: 0.7rem;
+                padding-right: 0.7rem;
+            }
             h1 {
                 font-size: 1.6rem;
             }
@@ -159,6 +203,15 @@ def apply_mobile_styles():
             div[data-testid="stMetric"] {
                 padding: 0.25rem 0;
             }
+            div[data-testid="stHorizontalBlock"] {
+                flex-wrap: wrap;
+            }
+            div[data-testid="column"] {
+                min-width: 100%;
+            }
+            div[data-testid="column"] div[data-testid="stMetric"] {
+                border-bottom: 1px solid var(--cert-border);
+            }
         }
         </style>
         """,
@@ -210,21 +263,21 @@ def render_home(exams):
     total_questions = sum(exam["count"] for exam in exams)
     st.caption(f"등록된 시험 {len(exams)}개 · 전체 문항 {total_questions}개")
 
-    col1, col2 = st.columns(2)
-    if col1.button("문제 풀이", type="primary", use_container_width=True):
+    if st.button("문제 풀이 시작", type="primary", use_container_width=True):
         go_to("문제 풀이")
-    if col2.button("PDF 업로드", use_container_width=True):
-        go_to("PDF 업로드")
-
-    with st.expander("학습 메뉴", expanded=True):
-        if st.button("취약 개념 학습", use_container_width=True):
-            go_to("취약 개념 학습")
-        if st.button("오답/복습", use_container_width=True):
-            go_to("오답/복습")
-        if st.button("개념 정리", use_container_width=True):
-            go_to("개념 정리")
-
-    with st.expander("관리 메뉴", expanded=False):
+
+    st.markdown('<div class="cert-section-title">학습</div>', unsafe_allow_html=True)
+    col1, col2 = st.columns(2)
+    if col1.button("오답/복습", use_container_width=True):
+        go_to("오답/복습")
+    if col2.button("개념 정리", use_container_width=True):
+        go_to("개념 정리")
+    if st.button("취약 개념 학습", use_container_width=True):
+        go_to("취약 개념 학습")
+
+    with st.expander("업로드/관리", expanded=False):
+        if st.button("PDF 업로드", use_container_width=True):
+            go_to("PDF 업로드")
         if st.button("처리 현황", use_container_width=True):
             go_to("처리 현황")
         if st.button("시험 현황", use_container_width=True):
@@ -539,8 +592,8 @@ def is_multi_answer(question) -> bool:
 
 
 def is_per_row_choice(question) -> bool:
-    question_type = (question.get("question_type") or "").lower()
-    if question_type not in {"table_choice", "hotspot"}:
+    question_type = normalize_question_type(question.get("question_type"))
+    if question_type not in {"table_choice", "hotspot", "matching"}:
         return False
     if visual_answer_areas(question):
         return True
@@ -684,12 +737,10 @@ def yes_no_answer_labels(value: str) -> list[str]:
 
 
 def is_yes_no_hotspot(question) -> bool:
-    question_type = (question.get("question_type") or "").lower()
-    if "in-context" in question_type:
-        return False
-    if not any(keyword in question_type for keyword in ["hotspot", "table_choice", "yes_no", "true/false"]):
+    question_type = normalize_question_type(question.get("question_type"))
+    if question_type not in {"yes_no", "hotspot", "table_choice"}:
         return False
-    if "true/false" in question_type:
+    if question_type == "yes_no":
         return True
     text = " ".join(
         [
@@ -809,7 +860,7 @@ def render_yes_no_matrix(question, key_prefix, rows, caption="진술별 답안")
 
 def render_answer_input(question, key_prefix):
     options = question["options"]
-    question_type = (question.get("question_type") or "").lower()
+    question_type = normalize_question_type(question.get("question_type"))
     statement_rows = [
         str(statement.get("text") or "").strip()
         for statement in visual_statements(question)
@@ -836,7 +887,7 @@ def render_answer_input(question, key_prefix):
 
     if not options:
         answer = str(question.get("answer") or "").upper()
-        if question_type in {"yes_no", "table_choice", "hotspot"} and re.search(r"(예|아니오|아니요|YES|NO)", answer, re.I):
+        if question_type in {"yes_no", "table_choice", "hotspot"} and re.search(r"(예|아니오|아니요|YES|NO|Y|N)", answer, re.I):
             rows = yes_no_lines(question.get("question") or "") or ["진술 1", "진술 2", "진술 3"]
             return render_yes_no_matrix(question, key_prefix, rows)
 

tests/test_answer_normalizer.py

@@ -0,0 +1,36 @@
+from cert_study_app.services.answer_normalizer import evaluate_answer, normalize_answer, yes_no_labels
+
+
+def test_yes_no_labels_from_letters():
+    assert yes_no_labels("Y,N,Y") == ["Y", "N", "Y"]
+
+
+def test_yes_no_labels_from_words():
+    assert yes_no_labels("Yes, No, Selected") == ["Y", "N", "Y"]
+
+
+def test_yes_no_labels_from_structured_list():
+    raw = [
+        {"statement": "A", "selected_answer": "Yes"},
+        {"statement": "B", "selected_answer": "No"},
+        {"statement": "C", "selected_answer": "Yes"},
+    ]
+    assert yes_no_labels(raw) == ["Y", "N", "Y"]
+
+
+def test_multi_choice_answer_is_sorted_when_unordered():
+    assert normalize_answer("C,A") == "A,C"
+
+
+def test_ordered_answer_preserves_order():
+    assert normalize_answer("C,A", ordered=True) == "C,A"
+
+
+def test_evaluate_answer_handles_yes_no_matrix():
+    result = evaluate_answer("예, 아니오, 예", "Y,N,Y", ordered=True)
+    assert result.correct is True
+    assert result.normalized_chosen == "Y,N,Y"
+
+
+def test_evaluate_answer_handles_unordered_multi_select():
+    assert evaluate_answer("C,A", "A,C").correct is True

tests/test_export_hf_seed.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from scripts.export_hf_seed import build_seed_report
+
+
+def test_build_seed_report_flags_duplicates_and_missing_answer():
+    rows = [
+        {
+            "question_number": 1,
+            "question_type": "MCQ",
+            "answer": "A",
+            "options": ["A. One", "B. Two"],
+            "parent_stem": "Common passage",
+        },
+        {
+            "question_number": 1,
+            "question_type": "Hotspot (True/False)",
+            "answer": "",
+            "options": [],
+        },
+    ]
+
+    report = build_seed_report(rows, Path("cert_study_app/demo_data/questions_seed.json"))
+
+    assert report["question_count"] == 2
+    assert report["common_passage_count"] == 1
+    assert report["duplicate_numbers"] == [1]
+    assert report["missing_answers"] == [1]
+    assert report["ready"] is False

tests/test_question_type_metadata_service.py

@@ -0,0 +1,22 @@
+from cert_study_app.services.question_type_metadata_service import (
+    is_ordered_answer_type,
+    is_visual_question_type,
+    normalize_question_type,
+)
+
+
+def test_normalize_question_type_aliases():
+    assert normalize_question_type("Hotspot (True/False)") == "yes_no"
+    assert normalize_question_type("True/False (In-Context)") == "yes_no"
+    assert normalize_question_type("Hotspot (Drag and Drop)") == "matching"
+    assert normalize_question_type("Multiple Select") == "multi_select"
+
+
+def test_visual_question_type_detection_uses_normalized_type():
+    assert is_visual_question_type("Hotspot (True/False)") is True
+    assert is_visual_question_type("MCQ") is False
+
+
+def test_ordered_answer_type_detection_uses_normalized_type():
+    assert is_ordered_answer_type("Hotspot (Drag and Drop)") is True
+    assert is_ordered_answer_type("Multiple Select") is False