feat: schoolbridge spaces deploy (extract-text endpoint added)

.dockerignore

@@ -0,0 +1,54 @@
+# HF Spaces Docker 빌드 컨텍스트에서 제외 — 이미지 크기·빌드 시간 최소화
+
+# 안드는 백엔드와 무관
+android/
+
+# git/빌드 메타
+.git/
+.github/
+.gitignore
+.dockerignore
+
+# 가상환경
+.venv/
+venv/
+env/
+
+# 컴파일 캐시
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+**/*.pyd
+.pytest_cache/
+
+# 노트북 (서빙엔 불필요, 큼)
+**/*.ipynb
+**/.ipynb_checkpoints/
+
+# 학습 데이터 / 큰 csv·jsonl (서빙엔 불필요)
+data/
+backend/data/
+backend/external_data/
+external_data/
+model/classification/data/
+model/extraction/data/
+model/translation_tts/data/
+
+# 로컬 체크포인트 (HF Hub에서 다운로드되니 image에 포함 안 함)
+model/classification/checkpoints/
+model/extraction/checkpoints/
+
+# 시각화 png·문서 (서빙엔 불필요)
+**/*.png
+**/*.jpg
+docs/
+**/docs/
+
+# 로그·임시
+*.log
+*.tmp
+*.bak
+
+# 백엔드 자체 .env (Spaces secrets 사용)
+backend/.env
+.env

.github/workflows/backend-tests.yml

@@ -0,0 +1,50 @@
+name: backend-tests
+
+on:
+  pull_request:
+    paths:
+      - "backend/**"
+      - "model/translation_tts/**"
+      - ".github/workflows/backend-tests.yml"
+  push:
+    branches: [main, dev]
+    paths:
+      - "backend/**"
+      - "model/translation_tts/**"
+
+# 강사 피드백(2026-04-28): "단위테스트 끝나고 통합테스트 할 때 합의된 기준/절차에 의해 merge"
+# → PR 시 자동 실행되는 권한 검증 + 다국어 사전 로딩 게이트.
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install backend deps (CPU torch + dev)
+        working-directory: backend
+        run: |
+          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
+
+      - name: Symlink external_model (도커 마운트 경로 모사)
+        run: |
+          sudo mkdir -p /app
+          sudo ln -s "$GITHUB_WORKSPACE/backend/app" /app/app
+          sudo ln -s "$GITHUB_WORKSPACE/model" /app/external_model
+          sudo ln -s "$GITHUB_WORKSPACE/backend/static" /app/static
+          sudo mkdir -p /app/static/tts
+
+      - name: Run pytest
+        working-directory: backend
+        env:
+          PYTHONPATH: /app
+        run: |
+          pytest tests -v --tb=short

.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+*.egg
+
+# 환경변수
+.env
+.env.*
+!.env.example
+*.env.local
+
+# ML 체크포인트 / 대용량 파일
+ml/*/checkpoints/
+ml/*/best_model/
+*.pt
+*.bin
+*.onnx
+
+# 경이 simple 분류기 자동 학습 결과 (random seed에 따라 달라져 git 충돌 유발)
+# 학습 코드 + 데이터(csv)는 git에 있어 컨테이너 첫 호출 시 재현 가능
+model/classification/checkpoints/*.pkl
+
+# 컨테이너 작업 영역 (학습 데이터·OCR·임시 변환물)
+backend/data/
+
+# Android build outputs and local settings
+android/.gradle/
+android/.idea/
+android/build/
+android/app/build/
+android/local.properties
+*.apk
+*.aab
+*.keystore
+
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# TTS 출력물
+tts/*.mp3
+tts/*.wav
+
+# 런타임 업로드 (가통문 원본 PDF/이미지) + TTS mp3 — 폴더는 git에 유지
+backend/static/notices/*
+!backend/static/notices/.gitkeep
+backend/static/tts/*
+!backend/static/tts/.gitkeep
+
+#클로드
+.claude
+
+# nested repo 방지
+multicultural-ai/
+multicultural-school-ai/
+
+# 미팅 자료 (디코로만 공유, 깃에는 안 올림)
+docs/meetings/
+
+# 학습 데이터 draft (대용량, 미완성)
+data/processed/
+data/raw/

Dockerfile

@@ -0,0 +1,46 @@
+# HF Spaces Docker SDK — schoolbridge 백엔드
+# build context = repo root (backend/ + model/ 전부 포함)
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# 파일 변환 의존 (HWP → 텍스트, PDF, 이미지 OCR)
+# H2Orestart는 latest 채널 사용 — 버전별 asset 파일명 안전성 확보
+ARG H2O_URL=https://github.com/ebandal/H2Orestart/releases/latest/download/H2Orestart.oxt
+
+RUN apt-get update -qq && apt-get install -y --no-install-recommends \
+        libreoffice-core \
+        libreoffice-writer \
+        libreoffice-java-common \
+        default-jre-headless \
+        fonts-nanum \
+        fonts-noto-cjk \
+        wget \
+        ca-certificates \
+        tesseract-ocr \
+        tesseract-ocr-kor \
+        libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN wget -O /tmp/h2orestart.oxt "${H2O_URL}" \
+    && unopkg add --shared /tmp/h2orestart.oxt \
+    && rm -f /tmp/h2orestart.oxt
+
+# Python 의존 설치 (CPU torch + transformers + edge-tts 등)
+COPY backend/requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# 백엔드 코드
+COPY backend/app /app/app
+
+# 외부 모델 코드 (분류기·추출기 src/) — 가중치는 HF Hub에서 자동 다운로드
+COPY model /app/external_model
+
+# 정적 디렉토리 (TTS mp3, 가통문 원본 PDF/이미지)
+RUN mkdir -p /app/static/tts /app/static/notices \
+    && chmod -R 777 /app/static
+
+# HF Spaces 기본 포트 7860 — 도메인 https://{user}-{space}.hf.space 로 자동 매핑
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,36 @@
+---
+title: SchoolBridge
+emoji: 🏫
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+license: mit
+short_description: 가정통신문 AI 도우미 — 다문화 학부모용
+---
+
+# SchoolBridge
+
+가정통신문 AI 도우미 — 다문화 가정 학부모용 백엔드.
+
+## 엔드포인트
+
+- `GET /health`
+- `POST /notice/extract-text` — 파일 텍스트 추출 (미리보기, 저장 X)
+- `POST /notice/upload` — 파일 발송 (Notice 저장 + 원본 보존)
+- `POST /notice/upload-self` — 학부모 자가 업로드
+- `POST /notice/send` — 텍스트 직송
+- `GET /notice/inbox/{parent_id}`
+- `POST /notice/analyze/{notice_id}`
+- `GET /static/notices/{id}{ext}` — 원본 PDF/이미지
+
+## 모델
+
+- 추출: 윤정님 KoELECTRA (`yunjeong116/koelectra-extractor`)
+- 분류: 경이님 KcELECTRA v3 (`kysophia/kcelectra-category`)
+- 번역: NLLB-200-distilled-600M
+- TTS: Microsoft Edge-TTS
+
+## 라이센스
+
+MIT

backend/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# 파일 변환 의존: LibreOffice headless + H2Orestart 확장 + 한글 폰트.
+# 학습 데이터 가공과 런타임 [1] 텍스트 변환 모두 사용.
+# H2Orestart는 latest 채널 사용 — 버전별 asset 파일명이 일관되지 않아 latest/download 안전.
+ARG H2O_URL=https://github.com/ebandal/H2Orestart/releases/latest/download/H2Orestart.oxt
+
+RUN apt-get update -qq && apt-get install -y --no-install-recommends \
+        libreoffice-core \
+        libreoffice-writer \
+        libreoffice-java-common \
+        default-jre-headless \
+        fonts-nanum \
+        fonts-noto-cjk \
+        wget \
+        ca-certificates \
+        tesseract-ocr \
+        tesseract-ocr-kor \
+        libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN wget -O /tmp/h2orestart.oxt "${H2O_URL}" \
+    && unopkg add --shared /tmp/h2orestart.oxt \
+    && rm -f /tmp/h2orestart.oxt
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/app/auth.py

@@ -0,0 +1,71 @@
+"""사용자 식별 + 역할 검증.
+
+X-User-Id 헤더로 사용자를 식별하고, 역할(teacher/parent)에 따른 권한을 검증한다.
+시연 단계라 별도 비밀번호/토큰 없이 헤더 한 줄로 처리. 실제 운영 시 JWT/세션 도입 예정.
+"""
+from fastapi import Depends, Header, HTTPException, status
+
+from app.models.schemas import UserProfile
+
+# 모듈 레벨 인메모리 사용자 저장소. user.py 라우터와 공유.
+_user_store: dict[str, UserProfile] = {}
+
+
+def get_user(user_id: str) -> UserProfile | None:
+    return _user_store.get(user_id)
+
+
+def upsert_user(profile: UserProfile) -> UserProfile:
+    _user_store[profile.user_id] = profile
+    return profile
+
+
+def list_users() -> list[UserProfile]:
+    return list(_user_store.values())
+
+
+def seed_demo_users() -> None:
+    """시연용 기본 계정 시드. 이미 존재하면 덮어쓰지 않음."""
+    demos = [
+        UserProfile(user_id="teacher_001", role="teacher"),
+        UserProfile(user_id="teacher_002", role="teacher"),
+        UserProfile(user_id="parent_001", role="parent"),
+        UserProfile(user_id="parent_002", role="parent"),
+        UserProfile(user_id="parent_003", role="parent"),
+    ]
+    for profile in demos:
+        _user_store.setdefault(profile.user_id, profile)
+
+
+def require_user(x_user_id: str = Header(..., description="요청자 사용자 ID")) -> UserProfile:
+    """X-User-Id 헤더 필수. 등록되지 않은 ID면 401."""
+    if not x_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="X-User-Id 헤더가 필요합니다",
+        )
+    profile = _user_store.get(x_user_id)
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"등록되지 않은 사용자: {x_user_id}",
+        )
+    return profile
+
+
+def require_teacher(user: UserProfile = Depends(require_user)) -> UserProfile:
+    if user.role != "teacher":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="선생님 권한이 필요합니다",
+        )
+    return user
+
+
+def require_parent(user: UserProfile = Depends(require_user)) -> UserProfile:
+    if user.role != "parent":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="학부모 권한이 필요합니다",
+        )
+    return user

backend/app/main.py

@@ -0,0 +1,46 @@
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from app.auth import seed_demo_users
+from app.routers import notice, tts, user
+
+STATIC_DIR = Path("/app/static")
+STATIC_DIR.mkdir(parents=True, exist_ok=True)
+(STATIC_DIR / "tts").mkdir(parents=True, exist_ok=True)
+(STATIC_DIR / "notices").mkdir(parents=True, exist_ok=True)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    seed_demo_users()
+    yield
+
+
+app = FastAPI(
+    title="가정통신문 AI 도우미 API",
+    description="베트남 결혼이민 학부모를 위한 가정통신문 할 일 요약 + TTS 서비스",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+app.include_router(notice.router, prefix="/notice", tags=["notice"])
+app.include_router(tts.router, prefix="/tts", tags=["tts"])
+app.include_router(user.router, prefix="/user", tags=["user"])
+
+
+@app.get("/health", tags=["health"])
+def health_check():
+    return {"status": "ok"}

backend/app/models/schemas.py

@@ -0,0 +1,164 @@
+from enum import Enum
+from typing import Any
+from pydantic import BaseModel
+
+
+class KoreanLevel(str, Enum):
+    beginner = "beginner"          # 초급: 베트남어 TTS
+    intermediate = "intermediate"  # 중급: 한국어 TTS + 용어 설명
+
+
+class Category(str, Enum):
+    schedule = "일정"
+    supplies = "준비물"
+    submission = "제출"
+    cost = "비용"
+    health = "건강·안전"
+    other = "기타"
+
+
+class TodoItem(BaseModel):
+    category: Category
+    text_ko: str
+    text_vi: str
+    importance: float  # 0.0 ~ 1.0
+    due_date: str | None = None
+
+
+class YunjeongTodo(BaseModel):
+    """윤정님 v2 추출 모델 출력 — 통신문 1개에서 문장 단위로 뽑힌 할일.
+
+    내부에 정규식 due_date/amount 추출 + binary 분류(BINARY_THRESHOLD=0.5) 포함.
+    confidence < 0.5 항목은 모델이 자동 필터링해 출력에 포함 안 됨.
+    """
+    text: str                       # 원문 문장
+    source: str | None = None       # 파일명 (같은 통신문 묶음용)
+    due_date: str | None = None     # YYYY-MM-DD 또는 상대표현 ("다음 주 금요일")
+    amount: int | None = None       # 원 단위
+    confidence: float               # binary 확률 (0.0 ~ 1.0)
+    action_hint: str | None = None  # 신청 / 제출 / 납부 / 준비 / 참여 / 확인
+
+
+class Notice(BaseModel):
+    notice_id: str
+    teacher_id: str
+    parent_id: str
+    text: str
+    todos: list[TodoItem] = []
+    # 원본 파일 (선생님/학부모가 업로드한 PDF/이미지). text 직송이면 None.
+    original_file_url: str | None = None       # 예: "/static/notices/abc123.pdf"
+    original_filename: str | None = None       # 예: "5월 가정통신문.pdf"
+    mime_type: str | None = None               # 예: "application/pdf"
+
+
+class NoticeSendRequest(BaseModel):
+    teacher_id: str
+    parent_id: str
+    text: str
+
+
+class NoticeAnalyzeRequest(BaseModel):
+    target_language: str   # vi/en/ru/ms/mn/zh/th/ja/ko_easy — 필수, default 없음
+
+
+# ── 슬롯 기반 응답 (강사 처방 1·3 대응) ──────────────────────────
+# source: "regex" | "model" | "model+regex" — 신뢰도 추적용
+# 정규식이 잡은 항목은 LLM 의존 없이 확보됐음을 안드/검수에서 표시 가능.
+class SlotEntry(BaseModel):
+    ko: str
+    translated: str = ""
+    source: str = "model"
+    conditional: bool = False  # "흐릴 경우 우산" 같은 조건부 항목
+
+
+class SummarySlots(BaseModel):
+    dates: list[SlotEntry] = []
+    times: list[SlotEntry] = []
+    places: list[SlotEntry] = []
+    supplies: list[SlotEntry] = []   # ⚠️ 강사 강조: 누락 금지
+    amounts: list[SlotEntry] = []    # ⚠️ 강사 강조: 누락 금지
+    deadlines: list[SlotEntry] = []
+    urls: list[SlotEntry] = []       # NLLB가 깨먹지 않게 ko 그대로 노출
+    phones: list[SlotEntry] = []     # 같은 이유
+
+
+class AnalyzeItem(BaseModel):
+    """카테고리별 할 일 — YunjeongTodo + 경이님 카테고리 결합 결과.
+
+    deprecated — SlotCard로 대체 예정 (안드 마이그레이션 완료 후 폐기).
+    """
+    category: Category                  # 경이님 (주제: 일정/준비물/제출/비용/건강·안전/기타)
+    action_hint: str | None = None      # 윤정님 (행동: 신청/제출/납부/준비/참여/확인)
+    title_ko: str
+    title_translated: str = ""
+    when: str | None = None
+    where: str | None = None
+    what: list[str] = []
+    amount: str | None = None
+    deadline: str | None = None
+    importance: float = 0.5
+    note_ko: str | None = None          # 조건부 메모 (예: "날씨가 흐릴 경우")
+    note_translated: str | None = None
+
+
+class SlotCard(BaseModel):
+    """슬롯 카드 — 헤더 + 값 + 카테고리 칩.
+
+    강사님 처방 "지저분한 줄글 X, 슬롯 위주로 가공" 대응.
+    한 카드 = 한 의미 단위 (운영시간 / 신청기간 / 운영방법 ...).
+    todos 헤더 분해 + regex 슬롯 컨텍스트 매칭 둘 다 카드로 통합.
+    """
+    header_ko: str                       # 예: "운영시간"
+    header_translated: str = ""          # 예: "Thời gian hoạt động"
+    value_ko: str                        # 예: "오전 10:00 ~ 12:00 (2시간)"
+    value_easy_ko: str = ""              # 세종님 to_easy_korean() 결과 — 미구현 시 value_ko 그대로
+    value_translated: str = ""           # NLLB 번역 결과
+    chip: str | None = None              # category 값 — None이면 칩 미표시
+    importance: float = 0.5              # 정렬용 (높은 순)
+
+
+class NoticeAnalyzeResponse(BaseModel):
+    notice_id: str
+    raw_text: str
+    target_language: str
+    # 통신문 제목 (윤정님 PR #90 extract_title heuristic) — 못 찾으면 ""
+    title: str = ""
+    title_translated: str = ""
+    # 신규 — 안드 슬롯 카드 UI 대상 (단계적 마이그레이션, 본 필드가 메인)
+    cards: list[SlotCard] = []
+    # deprecated — 안드 마이그레이션 완료 후 다음 PR에서 폐기 예정
+    summary: SummarySlots
+    items: list[AnalyzeItem] = []
+    tts_text: str = ""                   # 음성 변환 직전 텍스트 — 시연·디버그용 가시화
+    tts_url: str = ""                    # 번역 합본 TTS (안드 기존 버튼)
+    tts_url_easy_ko: str = ""            # 쉬운 한국어 합본 TTS (세종님 별도 버튼 요청)
+    quality_note: str = ""
+    review_needed: str = ""
+
+
+class TTSRequest(BaseModel):
+    user_id: str
+    todo_items: list[TodoItem]
+    level: KoreanLevel
+
+
+class UserProfile(BaseModel):
+    user_id: str
+    role: str = "parent"   # "teacher" | "parent"
+    child_grade: int = 1   # 1~6학년 (부모만 해당)
+    level: KoreanLevel = KoreanLevel.beginner
+    tts_speed: float = 1.0
+
+
+class ApiResponse(BaseModel):
+    status: str   # "success" | "error"
+    data: Any = None
+    message: str = ""
+
+    @classmethod
+    def success(cls, data: Any = None, message: str = "") -> "ApiResponse":
+        return cls(status="success", data=data, message=message)
+
+    @classmethod
+    def error(cls, message: str) -> "ApiResponse":
+        return cls(status="error", data=None, message=message)

backend/app/routers/notice.py

@@ -0,0 +1,490 @@
+import mimetypes
+import os
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile, status
+from app.auth import get_user, require_teacher, require_user
+from app.models.schemas import (
+    AnalyzeItem, ApiResponse, Category, Notice, NoticeAnalyzeRequest,
+    NoticeSendRequest, SlotCard, SlotEntry, SummarySlots, UserProfile,
+    YunjeongTodo,
+)
+from app.services.extractor import extract_todos, extract_title
+from app.services.parser import ParserError, parse_bytes_to_text
+from app.services.translator import translate_short_sentence, translate_term
+from app.services.classifier import classify_category
+from app.services.tts import generate_tts_file
+from app.services.slot_extractor import (
+    extract_summary_regex_slots, find_when_in_text,
+    split_supply_tokens, strip_markers,
+)
+from app.services.card_builder import build_cards
+from app.services.mock import MOCK_TODOS
+
+router = APIRouter()
+
+_notices: dict[str, Notice] = {}
+MAX_CARDS = 8
+
+NOTICES_DIR = Path("/app/static/notices")
+
+
+def _save_original(notice_id: str, raw_bytes: bytes, filename: str) -> tuple[str, str | None]:
+    """업로드된 원본 파일을 static/notices/{notice_id}{ext}로 저장.
+    Returns (url, mime_type). 실패 시 mime_type=None."""
+    ext = os.path.splitext(filename or "")[1].lower()
+    if not ext:
+        # 시그니처로 추정
+        if raw_bytes.startswith(b"%PDF"):
+            ext = ".pdf"
+        elif raw_bytes[:3] == b"\xff\xd8\xff":
+            ext = ".jpg"
+        elif raw_bytes.startswith(b"\x89PNG"):
+            ext = ".png"
+    safe_name = f"{notice_id}{ext}"
+    NOTICES_DIR.mkdir(parents=True, exist_ok=True)
+    (NOTICES_DIR / safe_name).write_bytes(raw_bytes)
+    mime_type, _ = mimetypes.guess_type(safe_name)
+    return f"/static/notices/{safe_name}", mime_type
+
+
+@router.post("/send", response_model=ApiResponse)
+async def send_notice(
+    req: NoticeSendRequest,
+    user: UserProfile = Depends(require_teacher),
+):
+    """선생님이 가정통신문 발송 → 부모 수신함에 저장."""
+    if user.user_id != req.teacher_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인 선생님 ID로만 발송 가능합니다",
+        )
+    parent = get_user(req.parent_id)
+    if parent is None or parent.role != "parent":
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"학부모 계정을 찾을 수 없습니다: {req.parent_id}",
+        )
+    notice_id = str(uuid.uuid4())
+    notice = Notice(
+        notice_id=notice_id,
+        teacher_id=req.teacher_id,
+        parent_id=req.parent_id,
+        text=req.text,
+        todos=[],
+    )
+    _notices[notice_id] = notice
+    return ApiResponse.success(data={"notice_id": notice_id}, message="발송 완료")
+
+
+@router.post("/extract-text", response_model=ApiResponse)
+async def extract_text(
+    file: UploadFile = File(...),
+    user: UserProfile = Depends(require_user),
+):
+    """파일 → 텍스트 추출만 (Notice 저장·발송 X). 선생님 발송 전 미리보기용.
+
+    실제 발송은 사용자가 발송 버튼을 누를 때 /notice/upload (파일 동봉) 또는
+    /notice/send (텍스트만)로 호출됨.
+    """
+    raw_bytes = await file.read()
+    try:
+        text = parse_bytes_to_text(raw_bytes, file.filename or "")
+    except ParserError as error:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"파일 변환 실패: {error}",
+        )
+    if not text:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="파일에서 추출된 텍스트가 비어있습니다",
+        )
+    return ApiResponse.success(
+        data={"text": text, "char_count": len(text), "filename": file.filename},
+        message=f"텍스트 추출 완료 ({file.filename})",
+    )
+
+
+@router.post("/upload", response_model=ApiResponse)
+async def upload_notice(
+    teacher_id: str = Form(...),
+    parent_id: str = Form(...),
+    file: UploadFile = File(...),
+    user: UserProfile = Depends(require_teacher),
+):
+    """선생님이 HWP/PDF 파일로 가정통신문 발송. 파일 → 텍스트 변환 후 send와 동일 흐름."""
+    if user.user_id != teacher_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인 선생님 ID로만 발송 가능합니다",
+        )
+    parent = get_user(parent_id)
+    if parent is None or parent.role != "parent":
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"학부모 계정을 찾을 수 없습니다: {parent_id}",
+        )
+
+    raw_bytes = await file.read()
+    try:
+        text = parse_bytes_to_text(raw_bytes, file.filename or "")
+    except ParserError as error:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"파일 변환 실패: {error}",
+        )
+    if not text:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="파일에서 추출된 텍스트가 비어있습니다",
+        )
+
+    notice_id = str(uuid.uuid4())
+    original_url, mime_type = _save_original(notice_id, raw_bytes, file.filename or "")
+    notice = Notice(
+        notice_id=notice_id,
+        teacher_id=teacher_id,
+        parent_id=parent_id,
+        text=text,
+        todos=[],
+        original_file_url=original_url,
+        original_filename=file.filename,
+        mime_type=mime_type,
+    )
+    _notices[notice_id] = notice
+    return ApiResponse.success(
+        data={"notice_id": notice_id, "char_count": len(text), "text": text},
+        message=f"파일 업로드 완료 ({file.filename})",
+    )
+
+
+@router.post("/upload-self", response_model=ApiResponse)
+async def upload_notice_self(
+    parent_id: str = Form(...),
+    file: UploadFile = File(...),
+    user: UserProfile = Depends(require_user),
+):
+    """학부모가 종이 통신문 사진/파일을 직접 업로드 → 수신함에 self-send 형태로 저장.
+
+    teacher_id = parent_id (자기 자신이 발신자)로 저장되며
+    이후 /analyze/{notice_id} 흐름은 동일.
+    """
+    if user.role != "parent" or user.user_id != parent_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인 학부모 ID로만 업로드 가능합니다",
+        )
+
+    raw_bytes = await file.read()
+    try:
+        text = parse_bytes_to_text(raw_bytes, file.filename or "")
+    except ParserError as error:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"파일 변환 실패: {error}",
+        )
+    if not text:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="파일에서 추출된 텍스트가 비어있습니다",
+        )
+
+    notice_id = str(uuid.uuid4())
+    original_url, mime_type = _save_original(notice_id, raw_bytes, file.filename or "")
+    _notices[notice_id] = Notice(
+        notice_id=notice_id,
+        teacher_id=parent_id,
+        parent_id=parent_id,
+        text=text,
+        todos=[],
+        original_file_url=original_url,
+        original_filename=file.filename,
+        mime_type=mime_type,
+    )
+    return ApiResponse.success(
+        data={"notice_id": notice_id, "char_count": len(text), "text": text},
+        message=f"업로드 완료 ({file.filename})",
+    )
+
+
+@router.get("/inbox/{parent_id}", response_model=ApiResponse)
+async def get_inbox(
+    parent_id: str,
+    user: UserProfile = Depends(require_user),
+):
+    """부모가 수신된 가정통신문 목록 조회. 본인 ID만 허용."""
+    if user.role != "parent" or user.user_id != parent_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인 수신함만 조회할 수 있습니다",
+        )
+    inbox = [n for n in _notices.values() if n.parent_id == parent_id]
+    return ApiResponse.success(data=inbox)
+
+
+@router.delete("/inbox/{parent_id}", response_model=ApiResponse)
+async def clear_inbox(
+    parent_id: str,
+    user: UserProfile = Depends(require_user),
+):
+    """parent_id 수신함 초기화 (시연용). 본인 ID만 허용."""
+    if user.role != "parent" or user.user_id != parent_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인 수신함만 삭제할 수 있습니다",
+        )
+    targets = [nid for nid, n in _notices.items() if n.parent_id == parent_id]
+    for nid in targets:
+        del _notices[nid]
+    return ApiResponse.success(
+        data={"deleted": len(targets)},
+        message=f"{parent_id} 수신함 {len(targets)}개 삭제",
+    )
+
+
+# ── 슬롯 기반 응답 빌더 ───────────────────────────────────────────
+# 강사 처방(2026-04-28):
+#   1. 템플릿 슬롯 출력 (summary)
+#   2. 정규식 + 모델 하이브리드 (regex source 표시)
+#   3. 핵심 명사(준비물·금액) 누락 가시화 (빈 슬롯 즉시 노출)
+def _amount_to_ko(amount: int | None) -> str | None:
+    if amount is None:
+        return None
+    return f"{amount:,}원"
+
+
+def _build_item(todo: YunjeongTodo, target_lang: str) -> AnalyzeItem:
+    """YunjeongTodo + 경이님 카테고리 → AnalyzeItem.
+
+    - category : 경이님 6-class 분류 (주제)
+    - action_hint : 윤정님 추출 결과 (행동: 신청/제출/...)
+    - due_date / amount : 윤정님 모델 결과 신뢰 (정규식 [2]는 summary 전체 단위 담당)
+    - when : 자유텍스트의 일시 표현은 정규식으로 추가 추출
+    - what : 준비물 카테고리일 때만 토큰 분해
+    - 마크업(■)은 보존, TTS 빌더에서만 strip.
+    """
+    text = todo.text
+    category = classify_category(text)
+
+    when = find_when_in_text(text, target_lang)
+
+    what: list[str] = []
+    if category == Category.supplies:
+        what = split_supply_tokens(text)
+
+    title_translated = translate_short_sentence(text, target_lang) or text
+
+    return AnalyzeItem(
+        category=category,
+        action_hint=todo.action_hint,
+        title_ko=text,
+        title_translated=title_translated,
+        when=when,
+        where=None,
+        what=what,
+        amount=_amount_to_ko(todo.amount),
+        deadline=todo.due_date,
+        importance=todo.confidence,
+    )
+
+
+def _slot_entry(ko: str, target_lang: str, source: str = "model") -> SlotEntry:
+    return SlotEntry(ko=ko, translated=translate_term(ko, target_lang), source=source)
+
+
+def _build_summary(
+    regex_slots: dict[str, list[dict]],
+    items: list[AnalyzeItem],
+    target_lang: str,
+) -> SummarySlots:
+    """정규식 슬롯(dates/times/amounts/urls/phones) + items에서 모델 슬롯(supplies/deadlines) 집계."""
+    summary = SummarySlots(
+        dates=[SlotEntry(**s) for s in regex_slots["dates"]],
+        times=[SlotEntry(**s) for s in regex_slots["times"]],
+        amounts=[SlotEntry(**s) for s in regex_slots["amounts"]],
+        urls=[SlotEntry(**s) for s in regex_slots.get("urls", [])],
+        phones=[SlotEntry(**s) for s in regex_slots.get("phones", [])],
+    )
+
+    # supplies: category=supplies items의 what 토큰 집계 (중복 제거, 순서 보존)
+    supplies: list[SlotEntry] = []
+    seen_supplies: set[str] = set()
+    for item in items:
+        if item.category != Category.supplies:
+            continue
+        for token in item.what:
+            if token in seen_supplies:
+                continue
+            seen_supplies.add(token)
+            supplies.append(_slot_entry(token, target_lang, source="model"))
+    summary.supplies = supplies
+
+    # deadlines: items의 deadline 집계
+    deadlines: list[SlotEntry] = []
+    seen_deadlines: set[str] = set()
+    for item in items:
+        if not item.deadline or item.deadline in seen_deadlines:
+            continue
+        seen_deadlines.add(item.deadline)
+        deadlines.append(_slot_entry(item.deadline, target_lang, source="model+regex"))
+    summary.deadlines = deadlines
+
+    return summary
+
+
+@router.post("/analyze/{notice_id}", response_model=ApiResponse)
+async def analyze_notice(
+    notice_id: str,
+    req: NoticeAnalyzeRequest,
+    user: UserProfile = Depends(require_user),
+):
+    """수신된 가정통신문 → 슬롯 기반 분석 응답.
+
+    파이프라인:
+      [3] 윤정 추출 (binary + 정규식, list[YunjeongTodo])
+      [2] 정규식 슬롯 (전체 통신문 단위)
+      [4] 경이 6-class 분류 (각 todo.text)
+      [5] 슬롯/짧은 문장 번역 (세종)
+      [6] AnalyzeItem 결합 + summary 집계
+      [7] TTS
+
+    학부모 본인의 가정통신문만 분석 가능. target_language 필수.
+    """
+    if notice_id not in _notices:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="가정통신문을 찾을 수 없습니다",
+        )
+
+    notice = _notices[notice_id]
+    if user.role != "parent" or user.user_id != notice.parent_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="본인의 가정통신문만 분석할 수 있습니다",
+        )
+    target_lang = req.target_language
+
+    # [3] 윤정 추출 → list[YunjeongTodo] (할일 없으면 [])
+    try:
+        todos = extract_todos(notice.text)
+        if not todos:
+            todos = MOCK_TODOS
+    except Exception as error:
+        print(f"[analyze] extractor failed: {error}")
+        todos = MOCK_TODOS
+
+    # [3'] 제목 추출 (윤정님 PR #90 heuristic) — split_sentences 이전, 원문 직접 스캔
+    title_ko = extract_title(notice.text) or ""
+    title_translated = (
+        translate_short_sentence(title_ko, target_lang) if title_ko else ""
+    )
+
+    # [2] 정규식 슬롯 (전체 통신문 단위, summary 재료)
+    regex_slots = extract_summary_regex_slots(notice.text, target_lang)
+
+    # [4]+[6] items: 각 todo에 경이님 카테고리 + 슬롯 결합 (deprecated, 다음 PR 폐기)
+    items = [_build_item(t, target_lang) for t in todos]
+
+    # [6] summary 집계: 정규식 + items 모델 슬롯 통합 (deprecated, 다음 PR 폐기)
+    summary = _build_summary(regex_slots, items, target_lang)
+
+    # [6'] cards: 신규 슬롯 카드 응답 — 시연 안정성을 위해 상위 N개만 번역/TTS 대상으로 사용.
+    top_todos = sorted(todos, key=lambda t: -t.confidence)[:MAX_CARDS]
+    cards = build_cards(top_todos, regex_slots, target_lang)[:MAX_CARDS]
+
+    # [7] TTS: 두 갈래 — 번역 합본 + 쉬운 한국어 합본 (세종님 별도 버튼 요청)
+    tts_text_translated = _build_tts_text_from_cards(cards, "translated")
+    tts_text_easy_ko = _build_tts_text_from_cards(cards, "easy_ko")
+    try:
+        tts_url = await generate_tts_file(tts_text_translated, target_lang=target_lang) if tts_text_translated else ""
+    except Exception as error:
+        print(f"[analyze] TTS (translated) failed: {error}")
+        tts_url = ""
+    try:
+        tts_url_easy_ko = await generate_tts_file(tts_text_easy_ko, target_lang="ko_easy") if tts_text_easy_ko else ""
+    except Exception as error:
+        print(f"[analyze] TTS (easy_ko) failed: {error}")
+        tts_url_easy_ko = ""
+
+    response = {
+        "notice_id": notice_id,
+        "raw_text": notice.text,
+        "target_language": target_lang,
+        "title": title_ko,
+        "title_translated": title_translated,
+        "cards": [c.model_dump() for c in cards],
+        "summary": summary.model_dump(),
+        "items": [item.model_dump() for item in items],
+        "tts_text": tts_text_translated,
+        "tts_url": tts_url,
+        "tts_url_easy_ko": tts_url_easy_ko,
+        "quality_note": "",
+        "review_needed": "",
+    }
+    return ApiResponse.success(data=response)
+
+
+def _build_tts_text_from_cards(cards: list[SlotCard], mode: str) -> str:
+    """슬롯 카드 → TTS 텍스트 (헤더 + 값 한 줄씩 합본).
+
+    mode="translated": 대상 언어 TTS용 — value_translated + header_translated
+    mode="easy_ko":    쉬운 한국어 TTS용 — value_easy_ko + header_ko
+    """
+    if not cards:
+        return ""
+    lines: list[str] = []
+    for c in cards:
+        if mode == "translated":
+            header = c.header_translated or c.header_ko
+            value = c.value_translated or c.value_ko
+        else:  # easy_ko
+            header = c.header_ko
+            value = c.value_easy_ko or c.value_ko
+        if not value:
+            continue
+        value = strip_markers(value)
+        line = f"{header}. {value}" if header else value
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _build_tts_text(
+    summary: SummarySlots,
+    items: list[AnalyzeItem],
+    target_lang: str,
+) -> str:
+    """items 한 건씩 title + 슬롯 정보를 합쳐 한 문장으로 — 음성 정보량 최대화.
+
+    슬롯 한국어 값(amount/deadline/what)은 summary의 translated 매핑으로 대상 언어 변환.
+    정렬은 importance 내림차순. 경이 분리 후엔 action_required="Y" 우선으로 교체 예정.
+    """
+    if not items:
+        return ""
+
+    # 한국어 슬롯 → 대상 언어 매핑 (summary가 이미 translated 보유)
+    supply_map = {s.ko: s.translated or s.ko for s in summary.supplies}
+    amount_map = {s.ko: s.translated or s.ko for s in summary.amounts}
+    deadline_map = {s.ko: s.translated or s.ko for s in summary.deadlines}
+
+    sorted_items = sorted(items, key=lambda i: -i.importance)
+    lines: list[str] = []
+    for item in sorted_items:
+        title = item.title_ko if target_lang == "ko_easy" else item.title_translated
+        if not title:
+            continue
+        # 음성에서 ■ 등 장식 마크업은 노이즈 — TTS 직전 strip
+        title = strip_markers(title)
+        extras: list[str] = []
+        if item.when:        # 이미 target_lang 포맷
+            extras.append(item.when)
+        if item.what:
+            extras.append(", ".join(supply_map.get(w, w) for w in item.what))
+        if item.amount:
+            extras.append(amount_map.get(item.amount, item.amount))
+        if item.deadline:
+            extras.append(strip_markers(deadline_map.get(item.deadline, item.deadline)))
+        line = title + (". " + ". ".join(extras) if extras else "")
+        lines.append(line)
+    return "\n".join(lines)

backend/app/routers/tts.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+
+from app.models.schemas import ApiResponse, TTSRequest
+from app.services.tts import generate_tts_file
+
+router = APIRouter()
+
+
+@router.post("/generate", response_model=ApiResponse)
+async def generate_tts(req: TTSRequest):
+    """할 일 목록 → 베트남어 음성 파일 생성. 안드는 응답 url을 BASE_URL과 합쳐 재생."""
+    text = "\n".join(item.text_vi for item in req.todo_items if item.text_vi)
+    if not text.strip():
+        return ApiResponse.error(message="베트남어 텍스트가 비어 있습니다")
+    try:
+        url = await generate_tts_file(text)
+    except Exception as error:
+        return ApiResponse.error(message=f"TTS 생성 실패: {error}")
+    return ApiResponse.success(data={"tts_url": url})

backend/app/routers/user.py

@@ -0,0 +1,28 @@
+from fastapi import APIRouter
+
+from app.auth import get_user as _get_user, list_users, upsert_user
+from app.models.schemas import ApiResponse, UserProfile
+
+router = APIRouter()
+
+
+@router.get("/", response_model=ApiResponse)
+def list_all_users():
+    """등록된 사용자 전체 목록 (시연용)."""
+    return ApiResponse.success(data=list_users())
+
+
+@router.get("/{user_id}", response_model=ApiResponse)
+def get_user(user_id: str):
+    """사용자 프로파일 조회 (한국어 수준, 학년, TTS 속도)."""
+    profile = _get_user(user_id)
+    if profile is None:
+        return ApiResponse.error(message="사용자 없음")
+    return ApiResponse.success(data=profile)
+
+
+@router.post("/", response_model=ApiResponse)
+def save_user(profile: UserProfile):
+    """사용자 프로파일 저장/수정. 시연 시 학부모/선생님 계정 등록에도 사용."""
+    saved = upsert_user(profile)
+    return ApiResponse.success(data=saved)

backend/app/services/card_builder.py

@@ -0,0 +1,166 @@
+"""슬롯 카드 빌더 — todos + regex_slots → list[SlotCard].
+
+강사님 처방 "지저분한 줄글 X, 슬롯 위주 가공" 대응:
+  한 카드 = 한 의미 단위 (운영시간 / 신청기간 / 운영방법 ...).
+
+흐름:
+  1. todos → 헤더 분해 + 분류 + 번역 + 쉬운 한국어
+  2. regex 슬롯 (URL/시간/날짜/전화/금액) → 보강 카드 (todo로 못 잡은 정보)
+  3. importance 내림차순 정렬
+
+윤정님 모델이 임계값에서 컷한 정보(운영시간/신청기간 등)를 regex 슬롯이
+보완 — 강사님 의견 "슬롯 위주 표시" 본질과 정합.
+"""
+from __future__ import annotations
+
+import re
+
+from app.models.schemas import Category, SlotCard, YunjeongTodo
+from app.services.classifier import classify_category
+from app.services.easy_korean import to_easy_korean
+from app.services.header_split import split_header_value
+from app.services.translator import translate_short_sentence, translate_term
+
+# 헤더 추정 실패 시 fallback
+_FALLBACK_HEADER = "기타"
+
+# regex 슬롯별 기본 헤더 (todo에서 못 잡은 정보 보강용 카드)
+# todo로 헤더가 추정된 경우엔 이 카드를 만들지 않음 (중복 방지).
+_SLOT_HEADERS: dict[str, str] = {
+    "dates": "일시",
+    "times": "시간",
+    "urls": "신청 URL",
+    "phones": "연락처",
+    "amounts": "비용",
+}
+
+# regex 슬롯이 todo로 이미 흡수됐는지 판단할 헤더 매핑.
+# 예: todo가 "운영시간" 헤더로 이미 추출됐으면 regex times 카드는 만들지 않음.
+_TODO_HEADER_COVERS: dict[str, set[str]] = {
+    "times": {"운영시간", "신청시간", "시간"},
+    "dates": {"운영날짜", "일시", "기간", "운영기간"},
+    "urls": {"신청 URL", "신청경로", "신청방법"},
+    "phones": {"연락처", "문의", "문의처"},
+    "amounts": {"비용", "회비", "참가비", "수강료", "급식비"},
+}
+
+
+def _build_card_from_todo(todo: YunjeongTodo, target_lang: str) -> SlotCard:
+    """YunjeongTodo → SlotCard."""
+    header, value = split_header_value(todo.text)
+    if header is None:
+        header = _FALLBACK_HEADER
+
+    category = classify_category(value)
+    chip = category.value if category != Category.other else None
+
+    return SlotCard(
+        header_ko=header,
+        header_translated=translate_term(header, target_lang),
+        value_ko=value,
+        value_easy_ko=to_easy_korean(value),
+        value_translated=translate_short_sentence(value, target_lang) or value,
+        chip=chip,
+        importance=todo.confidence,
+    )
+
+
+def _slot_entry_ko(entry: dict | str) -> str:
+    if isinstance(entry, dict):
+        return entry.get("ko", "")
+    return entry
+
+
+def _slot_entry_translated(entry: dict | str) -> str:
+    if isinstance(entry, dict):
+        return entry.get("translated") or entry.get("ko", "")
+    return entry
+
+
+def _build_cards_from_regex_slots(
+    regex_slots: dict[str, list[dict]],
+    target_lang: str,
+    todo_headers: set[str],
+) -> list[SlotCard]:
+    """regex 슬롯 → 보강 SlotCard. todo 헤더가 이미 커버한 슬롯은 스킵."""
+    cards: list[SlotCard] = []
+
+    for slot_name, default_header in _SLOT_HEADERS.items():
+        entries = regex_slots.get(slot_name, [])
+        if not entries:
+            continue
+        # todo가 이미 이 슬롯을 커버하면 스킵 (중복 카드 방지)
+        if todo_headers & _TODO_HEADER_COVERS.get(slot_name, set()):
+            continue
+
+        # 슬롯당 한 카드 — 여러 값은 콤마 구분
+        values_ko = [_slot_entry_ko(e) for e in entries]
+        values_translated = [_slot_entry_translated(e) for e in entries]
+        value_ko = ", ".join(v for v in values_ko if v)
+        value_translated = ", ".join(v for v in values_translated if v)
+        if not value_ko:
+            continue
+
+        cards.append(SlotCard(
+            header_ko=default_header,
+            header_translated=translate_term(default_header, target_lang),
+            value_ko=value_ko,
+            value_easy_ko=to_easy_korean(value_ko),
+            value_translated=value_translated or value_ko,
+            chip=None,  # regex 슬롯은 칩 없음 — todo가 아니므로 카테고리 모호
+            importance=0.7,  # todo 평균 confidence보다 살짝 낮음
+        ))
+
+    return cards
+
+
+# dedup 비교용 — 표 구분자/콜론/연속 공백 정규화 (`|`/`:`/`：` 등 차이로 substring 놓치는 것 방지)
+_DEDUP_NORMALIZE = re.compile(r"[\s|｜:：]+")
+
+
+def _normalize_for_dedup(text: str) -> str:
+    """value 비교용 정규화 — 공백/구분자 차이 무시."""
+    return _DEDUP_NORMALIZE.sub(" ", text).strip()
+
+
+def _dedup_cards(cards: list[SlotCard]) -> list[SlotCard]:
+    """같은 헤더 안에서 substring 카드 제거.
+
+    pdfplumber가 본문 + [표] 양쪽에서 같은 정보를 추출해 두 카드로 들어오는 경우
+    (예: 서대구초 운영방법 156자 본문 카드 + 38자 표 영역 카드) 짧은 쪽이 긴
+    쪽 안에 substring으로 들어있으면 짧은 쪽 제거. 정보 손실 0.
+
+    헤더가 다르면 손대지 않음 — 운영방법/일시/시간/URL 등 다른 슬롯은 별개.
+    """
+    by_header: dict[str, list[SlotCard]] = {}
+    for c in cards:
+        by_header.setdefault(c.header_ko, []).append(c)
+
+    keep: list[SlotCard] = []
+    for group in by_header.values():
+        # 긴 value 우선 — 짧은 게 긴 것 substring이면 제거 가능
+        group.sort(key=lambda c: -len(c.value_ko))
+        kept_norms: list[str] = []
+        for card in group:
+            norm = _normalize_for_dedup(card.value_ko)
+            if any(norm in k for k in kept_norms):
+                continue
+            kept_norms.append(norm)
+            keep.append(card)
+    return keep
+
+
+def build_cards(
+    todos: list[YunjeongTodo],
+    regex_slots: dict[str, list[dict]],
+    target_lang: str,
+) -> list[SlotCard]:
+    """todos + regex_slots → list[SlotCard]. dedup + importance 내림차순 정렬."""
+    cards = [_build_card_from_todo(t, target_lang) for t in todos]
+
+    todo_headers = {c.header_ko for c in cards}
+    cards.extend(_build_cards_from_regex_slots(regex_slots, target_lang, todo_headers))
+
+    cards = _dedup_cards(cards)
+    cards.sort(key=lambda c: -c.importance)
+    return cards

backend/app/services/classifier.py

@@ -0,0 +1,48 @@
+"""경이님 6-class 분류 모델 wrapper.
+
+문장 → Category (일정/준비물/제출/비용/건강·안전/기타).
+파이프라인 [4] 단계 — 윤정님 todo 각각에 대해 호출되어 AnalyzeItem.category로 들어감.
+
+모델 모드: "auto" — KcELECTRA 체크포인트 있으면 그쪽, 없으면 simple(TF-IDF+LogReg) 폴백.
+경이님 v2 KcELECTRA 학습이 끝나면 자동으로 더 정확한 모델로 업그레이드됨.
+"""
+import sys
+from datetime import date
+from pathlib import Path
+
+from app.models.schemas import Category
+
+_CLF_DIR = Path("/app/external_model/classification")
+if str(_CLF_DIR) not in sys.path:
+    sys.path.insert(0, str(_CLF_DIR))
+
+# 외부 마운트가 없는 환경(CI/테스트)에선 import 가드 — 모듈 로드만큼은 안전하게.
+try:
+    from src.predict import predict_one  # noqa: E402
+except ImportError as error:
+    print(f"[classifier] predict_one unavailable: {error}")
+    predict_one = None
+
+
+def classify_category(text: str, today: date | None = None) -> Category:
+    """문장 → 6-class 카테고리. 실패/미정 시 Category.other.
+
+    model="auto"로 호출 — 경이님 predict_one이 KcELECTRA 체크포인트 존재 여부를
+    감지해 자동 선택. simple은 첫 호출 시 학습 데이터로 자가 학습 (~3초).
+    """
+    if not text or not text.strip():
+        return Category.other
+    if predict_one is None:
+        return Category.other  # 모델 부재 (CI 등) — 안전한 기본값
+
+    try:
+        result = predict_one(text, model="auto", today=today, explain=False)
+    except Exception as error:
+        print(f"[classifier] predict_one failed: {error}")
+        return Category.other
+
+    label = result.get("category", "")
+    try:
+        return Category(label)
+    except ValueError:
+        return Category.other

backend/app/services/easy_korean.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import re
+
+
+EASY_KO_DICT = {
+    "제출": "제출(내기)",
+    "납부": "납부(지불)",
+    "준비물": "준비할 것",
+    "방역지침": "마스크 착용 등 방역 규칙",
+    "신청": "신청",
+    "개인": "각자",
+    "해당": "관련",
+}
+
+_PROTECTED_PATTERN = re.compile(
+    r"("
+    r"\d{4}\s*년\s*\d{1,2}\s*월\s*\d{1,2}\s*일"
+    r"|"
+    r"\d{1,2}\s*월\s*\d{1,2}\s*일"
+    r"|"
+    r"\d{1,2}\s*/\s*\d{1,2}"
+    r"|"
+    r"\d{1,3}(?:,\d{3})+원"
+    r"|"
+    r"\d+원"
+    r")"
+)
+_PLACEHOLDER_PATTERN = re.compile(r"__EASY_KO_PROTECTED_(\d+)__")
+_WORD_CHARS = r"가-힣A-Za-z0-9_"
+_POLITE_ENDING_PATTERN = re.compile(r"(합니다|세요|입니다)[.!?]?$")
+
+
+def _protect_patterns(text: str) -> tuple[str, list[str]]:
+    protected: list[str] = []
+
+    def stash(match: re.Match[str]) -> str:
+        protected.append(match.group(0))
+        return f"__EASY_KO_PROTECTED_{len(protected) - 1}__"
+
+    return _PROTECTED_PATTERN.sub(stash, text), protected
+
+
+def _restore_patterns(text: str, protected: list[str]) -> str:
+    def restore(match: re.Match[str]) -> str:
+        index = int(match.group(1))
+        return protected[index] if index < len(protected) else match.group(0)
+
+    return _PLACEHOLDER_PATTERN.sub(restore, text)
+
+
+def _replace_terms(text: str) -> str:
+    for source, target in EASY_KO_DICT.items():
+        pattern = re.compile(rf"(?<![{_WORD_CHARS}]){re.escape(source)}(?![{_WORD_CHARS}])")
+        text = pattern.sub(target, text)
+    return text
+
+
+def _make_ending_natural(text: str) -> str:
+    stripped = text.strip()
+    if not stripped or _POLITE_ENDING_PATTERN.search(stripped):
+        return text
+
+    suffix_map = {
+        "신청": "신청해야 합니다",
+        "제출(내기)": "제출해야 합니다",
+        "준비": "준비해야 합니다",
+        "참가": "참가해야 합니다",
+    }
+
+    trailing_punctuation = ""
+    if stripped[-1] in ".!?":
+        trailing_punctuation = stripped[-1]
+        stripped = stripped[:-1].rstrip()
+
+    for suffix, replacement in suffix_map.items():
+        if stripped.endswith(suffix):
+            return stripped[: -len(suffix)] + replacement + trailing_punctuation
+    return text
+
+
+def to_easy_korean(value_ko: str) -> str:
+    try:
+        if not value_ko:
+            return value_ko
+        masked, protected = _protect_patterns(value_ko)
+        converted = _replace_terms(masked)
+        converted = _make_ending_natural(converted)
+        return _restore_patterns(converted, protected)
+    except Exception:
+        return value_ko
+
+
+if __name__ == "__main__":
+    samples = [
+        "3월 17일까지 신청",
+        "5,000원 납부",
+        "개인 준비물 지참",
+        "온라인 사전예약 후 방문 바랍니다",
+        "방역지침 준수",
+    ]
+    for sample in samples:
+        print(f"{sample} -> {to_easy_korean(sample)}")

backend/app/services/extractor.py

@@ -0,0 +1,92 @@
+"""윤정님 추출 모델 wrapper.
+
+가정통신문 텍스트 → list[YunjeongTodo].
+v2 모델 (model/extraction/file/predict.py): binary 분류(BINARY_THRESHOLD=0.5) +
+정규식 due_date/amount/action_hint. 출력 스키마가 YunjeongTodo와 1:1.
+
+v1 (구버전 model/extraction/predict.py)은 윤정님이 v2 머지하면서 삭제.
+v1 adapter 경로는 호환성을 위해 남겨두지만 실제로는 v2 진입점이 사용됨.
+"""
+import re
+import sys
+from pathlib import Path
+
+from app.models.schemas import YunjeongTodo
+
+# v2 진입점은 model/extraction/file/predict.py.
+# CI/테스트 환경에선 외부 마운트 부재 → 가드로 빈 결과 반환.
+_EXTRACTION_DIR = Path("/app/external_model/extraction/file")
+if str(_EXTRACTION_DIR) not in sys.path:
+    sys.path.insert(0, str(_EXTRACTION_DIR))
+
+try:
+    import predict as _yunjeong  # noqa: E402
+except ImportError as error:
+    print(f"[extractor] predict module unavailable: {error}")
+    _yunjeong = None
+
+_AMOUNT_RE = re.compile(r"(\d{1,3}(?:,\d{3})+|\d+)\s*원")
+
+
+def extract_title(notice_text: str) -> str | None:
+    """가정통신문 원문 → 제목 한 줄. 못 찾으면 None.
+
+    윤정님 PR #90 (predict.py:extract_title) — split_sentences()의
+    _HEADER_ONLY 필터가 제목을 차단하기 전에 원문 줄을 직접 스캔.
+    predict()와 별도 호출.
+    """
+    if not notice_text or not notice_text.strip():
+        return None
+    if _yunjeong is None or not hasattr(_yunjeong, "extract_title"):
+        return None
+    try:
+        return _yunjeong.extract_title(notice_text)
+    except Exception as error:
+        print(f"[extractor] extract_title failed: {error}")
+        return None
+
+
+def extract_todos(notice_text: str, source: str | None = None) -> list[YunjeongTodo]:
+    """가정통신문 원문 → list[YunjeongTodo]. 할일 없으면 []."""
+    if not notice_text or not notice_text.strip():
+        return []
+    if _yunjeong is None:
+        return []  # 모델 모듈 없음 (CI 등) — 빈 결과로 후속 단계 정상 동작
+
+    # v2 진입점: predict(text, source) → list[dict]
+    if hasattr(_yunjeong, "predict"):
+        try:
+            raw_items = _yunjeong.predict(notice_text, source=source)
+        except TypeError:
+            # source kwarg 미지원 버전 호환
+            raw_items = _yunjeong.predict(notice_text)
+        return [YunjeongTodo(**raw) for raw in raw_items]
+
+    # v1 fallback (구버전 predict.py가 마운트되어 있을 경우)
+    if hasattr(_yunjeong, "extract_todos_dict"):
+        raw_items = _yunjeong.extract_todos_dict(notice_text)
+        return [_adapt_v1(item) for item in raw_items]
+
+    return []
+
+
+def _adapt_v1(v1_item: dict) -> YunjeongTodo:
+    text = v1_item.get("text_ko", "")
+    return YunjeongTodo(
+        text=text,
+        source=None,
+        due_date=v1_item.get("due_date"),
+        amount=_extract_amount_value(text),
+        confidence=float(v1_item.get("importance", 0.5)),
+        action_hint=None,
+    )
+
+
+def _extract_amount_value(text: str) -> int | None:
+    m = _AMOUNT_RE.search(text)
+    if not m:
+        return None
+    try:
+        return int(m.group(1).replace(",", ""))
+    except ValueError:
+        return None

backend/app/services/header_split.py

@@ -0,0 +1,65 @@
+"""슬롯 카드 헤더 분해 — todo.text → (헤더, 값) 페어.
+
+강사님 처방 "슬롯 위주 가공" 대응:
+  슬롯 카드 = 헤더(라벨) 굵게 + 값 행. 본 모듈이 헤더 추출 책임.
+
+윤정님 split_sentences가 이미 헤더 단위로 todo를 분리해서 반환하므로
+보통 todo.text 시작에 헤더 키워드가 옴. 또한 윤정님이 한글 프로 기호 +
+표 구분자(`|`)를 정제하기로 합의됨 — 매칭 시 구분자는 옵셔널 처리.
+
+매칭 실패 시 (None, 원문)을 반환해 호출부가 fallback("기타") 헤더로 처리.
+"""
+from __future__ import annotations
+
+import re
+
+# 가정통신문 표준 헤더 키워드.
+# 윤정님 split_sentences 분리 룰의 키워드 + 갈산초/서대구초 케이스 보강.
+# 긴 표현이 짧은 것에 흡수되지 않게 정렬은 길이 내림차순 (예: "기타 안내사항" 우선, "기타" 후순위).
+HEADER_KEYWORDS: list[str] = [
+    # 운영 계열
+    "운영시간", "운영방법", "운영날짜", "운영기간", "운영장소",
+    # 신청 계열
+    "신청방법", "신청기간", "신청경로", "신청대상", "신청자격",
+    # 접수/제출
+    "접수기간", "접수방법", "접수처",
+    "제출방법", "제출기한", "제출처",
+    # 일정/장소
+    "일시", "기간", "장소", "위치", "주소",
+    # 대상/자격
+    "대상", "자격", "참가대상",
+    # 준비물/비용
+    "준비물", "지참물", "준비사항",
+    "비용", "회비", "참가비", "수강료", "급식비",
+    # 안내/유의
+    "기타 안내사항", "기타안내사항", "안내사항",
+    "유의사항", "참고사항", "주의사항",
+    # 문의
+    "문의", "연락처", "문의처",
+    # 기타 (가장 짧음, 마지막)
+    "기타",
+]
+
+_HEADER_KEYWORDS_SORTED = sorted(HEADER_KEYWORDS, key=len, reverse=True)
+
+# 줄 시작 + 헤더 키워드 + (선택적 `|`/`:`/`：` 구분자) + 값
+# `|`는 윤정님이 정제하기 전엔 살아있을 수 있어 옵셔널 처리.
+_HEADER_RE = re.compile(
+    r"^\s*(?P<header>" + "|".join(re.escape(k) for k in _HEADER_KEYWORDS_SORTED) + r")"
+    r"\s*[|:：]?\s*"
+    r"(?P<value>.+)$",
+    re.DOTALL,
+)
+
+
+def split_header_value(text: str) -> tuple[str | None, str]:
+    """todo.text → (헤더, 값) 페어.
+
+    매칭 실패 시 (None, text.strip()) 반환 — 호출부에서 "기타" 같은 fallback 헤더 처리.
+    """
+    if not text or not text.strip():
+        return None, ""
+    m = _HEADER_RE.match(text.strip())
+    if m:
+        return m.group("header"), m.group("value").strip()
+    return None, text.strip()

backend/app/services/mock.py

@@ -0,0 +1,44 @@
+"""모델 연결 전 mock 응답 데이터.
+
+extract_todos 실패/빈결과 시 fallback. 슬롯 파이프라인에서는 이 mock 도
+[3] YunjeongTodo → [4] 경이님 분류 → [6] AnalyzeItem 흐름을 그대로 통과한다.
+"""
+from app.models.schemas import YunjeongTodo
+
+MOCK_TODOS: list[YunjeongTodo] = [
+    YunjeongTodo(
+        text="현장체험학습 동의서를 내일까지 제출해주세요",
+        due_date="내일",
+        amount=None,
+        confidence=0.95,
+        action_hint="제출",
+    ),
+    YunjeongTodo(
+        text="도시락, 개인 물병, 돗자리를 준비해주세요",
+        due_date=None,
+        amount=None,
+        confidence=0.9,
+        action_hint="준비",
+    ),
+    YunjeongTodo(
+        text="체험학습비 15,000원을 4월 22일까지 납부해주세요",
+        due_date="2026-04-22",
+        amount=15000,
+        confidence=0.92,
+        action_hint="납부",
+    ),
+    YunjeongTodo(
+        text="4월 25일(금) 봄 소풍이 있습니다",
+        due_date="2026-04-25",
+        amount=None,
+        confidence=0.78,
+        action_hint="참여",
+    ),
+    YunjeongTodo(
+        text="미세먼지 심한 날에는 마스크를 착용해주세요",
+        due_date=None,
+        amount=None,
+        confidence=0.7,
+        action_hint="확인",
+    ),
+]

backend/app/services/parser.py

@@ -0,0 +1,290 @@
+"""HWP/PDF/text 입력 → clean_text 변환.
+
+파이프라인 [1] 단계. 호스트 앱이 어떤 양식으로 보내든 백엔드가 텍스트로 흡수.
+
+지원:
+  - text (text/plain) → 그대로
+  - PDF (application/pdf) → pdfplumber 본문 + 표 [표] 섹션
+  - HWP/HWPX → LibreOffice + H2Orestart로 ODT 변환 → content.xml 직접 파싱
+
+이미지(.jpg/.png) OCR은 별도 단계 (세종님 OCR 합류 시 추가).
+
+ODT 경로 채택 이유 (vs 이전 HWP→PDF):
+  HWP→PDF→pdfplumber는 LibreOffice가 텍스트를 두 번 그려 글자가 중복
+  추출되는 문제 ("22002266학학년년도도"). ODT(zip+content.xml)는 구조화된
+  단일 출력이라 중복 0. 검증: hwp5txt 28b 실패, docx 0c 실패, odt 1899c
+  키워드 6/6 보존.
+
+보안 모델:
+  - 원본 filename은 .suffix 추출에만 사용. 추출된 suffix는 화이트리스트 검사
+    (TEXT_EXTS / PDF_EXTS / HWP_EXTS) 통과 못 하면 ParserError로 즉시 거부.
+  - 디스크 저장 경로는 tempfile.TemporaryDirectory + 고정 이름 input{suffix}.
+    원본 filename은 어떤 경로/명령에도 사용되지 않음.
+  - subprocess 호출은 list 인자 형태(쉘 미사용) → 명령 주입 표면 없음.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+import zipfile
+from pathlib import Path
+
+# pdfplumber는 외부 의존이라 CI/테스트 안전하게 가드.
+# 운영에선 requirements.txt + Dockerfile로 보장. 부재면 첫 PDF 호출 시점에 명확한 메시지.
+try:
+    import pdfplumber  # type: ignore
+except ImportError as error:
+    print(f"[parser] pdfplumber unavailable: {error}")
+    pdfplumber = None
+
+
+PDF_EXTS = {".pdf"}
+HWP_EXTS = {".hwp", ".hwpx"}
+TEXT_EXTS = {".txt", ".md"}
+IMG_EXTS = {".jpg", ".jpeg", ".png", ".webp"}
+ALLOWED_EXTS = PDF_EXTS | HWP_EXTS | TEXT_EXTS | IMG_EXTS
+
+# LibreOffice 변환 타임아웃 (초). 큰 HWP는 ENV로 오버라이드 가능.
+LIBREOFFICE_TIMEOUT_SECONDS = int(os.environ.get("PARSER_LIBREOFFICE_TIMEOUT", "300"))
+
+
+class ParserError(RuntimeError):
+    """변환 실패 시 호출부가 잡을 수 있는 단일 예외."""
+
+
+def normalize(text: str) -> str:
+    """null 제거 + 한 줄 안 다중 공백만 정리. 줄바꿈 보존, 연속 빈 줄은 1개로."""
+    text = text.replace("\x00", " ")
+    out_lines: list[str] = []
+    prev_empty = False
+    for line in text.split("\n"):
+        line = re.sub(r"[ \t]+", " ", line).strip()
+        if not line:
+            if not prev_empty:
+                out_lines.append(line)
+            prev_empty = True
+        else:
+            out_lines.append(line)
+            prev_empty = False
+    return "\n".join(out_lines).strip()
+
+
+def _pdf_to_text(pdf_path: Path) -> str:
+    """본문 텍스트(표 영역 제외) + 표(행 단위 정리) 분리."""
+    if pdfplumber is None:
+        raise ParserError(
+            "pdfplumber 미설치. backend 컨테이너 재빌드(docker compose build backend) "
+            "또는 pip install pdfplumber 필요."
+        )
+
+    body_pages: list[str] = []
+    table_blocks: list[str] = []
+
+    with pdfplumber.open(pdf_path) as pdf:
+        for page in pdf.pages:
+            tables = page.extract_tables() or []
+            for tbl in tables:
+                rows: list[str] = []
+                for row in tbl:
+                    cells = [(c or "").replace("\n", " ").strip() for c in row]
+                    if any(cells):
+                        rows.append(" | ".join(cells))
+                if rows:
+                    table_blocks.append("\n".join(rows))
+
+            table_bboxes = [t.bbox for t in (page.find_tables() or [])]
+            if table_bboxes:
+                def outside_tables(obj):
+                    if obj.get("object_type") != "char":
+                        return True
+                    cx = (obj["x0"] + obj["x1"]) / 2
+                    cy = (obj["top"] + obj["bottom"]) / 2
+                    for bbox in table_bboxes:
+                        x0, top, x1, bottom = bbox
+                        if x0 <= cx <= x1 and top <= cy <= bottom:
+                            return False
+                    return True
+                page_view = page.filter(outside_tables)
+                body = page_view.extract_text() or ""
+            else:
+                body = page.extract_text() or ""
+
+            if body:
+                body_pages.append(body)
+
+    parts: list[str] = []
+    if body_pages:
+        parts.append("\n\n".join(body_pages))
+    if table_blocks:
+        parts.append("[표]\n" + "\n\n".join(table_blocks))
+    return "\n\n".join(parts)
+
+
+def _image_to_text(img_path: Path) -> str:
+    """카메라 사진(.jpg/.png) → 텍스트. Tesseract 한국어 OCR.
+
+    전체 이미지 1차 OCR → 한국어 문자 외 노이즈 정리.
+    표 영역 재처리(2차 OCR)는 별도 로직으로 확장 가능.
+    """
+    try:
+        import pytesseract
+        from PIL import Image
+    except ImportError as e:
+        raise ParserError(f"OCR 의존 미설치: {e}. Docker 재빌드 필요.")
+
+    try:
+        img = Image.open(img_path).convert("RGB")
+    except Exception as e:
+        raise ParserError(f"이미지 열기 실패: {e}")
+
+    try:
+        # psm 3: 자동 레이아웃 감지 (표·단락 혼재 가정통신문에 적합)
+        text = pytesseract.image_to_string(img, lang="kor", config="--psm 3 --oem 1")
+    except Exception as e:
+        raise ParserError(f"Tesseract OCR 실패: {e}")
+
+    return text
+
+
+# ODT content.xml 네임스페이스
+_ODT_TEXT_NS = "{urn:oasis:names:tc:opendocument:xmlns:text:1.0}"
+_ODT_TABLE_NS = "{urn:oasis:names:tc:opendocument:xmlns:table:1.0}"
+_ODT_DRAW_NS = "{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}"
+
+
+def _hwp_to_odt(hwp_path: Path, out_dir: Path) -> Path:
+    """LibreOffice headless로 HWP → ODT.
+
+    HWP→PDF 경로의 doubled-char 문제 회피. ODT는 zip 구조라 본문/표가
+    단일 트리에 한 번만 들어감. 타임아웃: PARSER_LIBREOFFICE_TIMEOUT.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        result = subprocess.run(
+            [
+                "libreoffice", "--headless",
+                "--convert-to", "odt",
+                "--outdir", str(out_dir),
+                str(hwp_path),
+            ],
+            capture_output=True, text=True,
+            timeout=LIBREOFFICE_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        raise ParserError(
+            f"LibreOffice 변환 타임아웃 ({LIBREOFFICE_TIMEOUT_SECONDS}초 초과). "
+            "큰 HWP면 PARSER_LIBREOFFICE_TIMEOUT 환경변수로 늘릴 수 있음."
+        )
+    odt_path = out_dir / f"{hwp_path.stem}.odt"
+    # H2Orestart가 ODT 변환 후 종료 시점에 종종 Signal 11 (cleanup 버그)을 내지만
+    # 출력 파일은 정상. 파일 존재 여부를 성공 기준으로 — returncode/stderr는 참고만.
+    if not odt_path.exists():
+        raise ParserError(
+            f"LibreOffice ODT 변환 실패 (출력 파일 없음). "
+            f"returncode={result.returncode}, stderr={result.stderr.strip()[:200]}"
+        )
+    return odt_path
+
+
+def _odt_to_text(odt_path: Path, mark_header: bool = False) -> str:
+    """ODT(zip) content.xml → 본문 + 표 영역 평면 텍스트.
+
+    표 안 paragraph는 본문 처리에서 제외(중복 방지). 표는 셀 단위 공백 합치고
+    행 단위 줄바꿈으로 평면화 — `|` 구분자 X, `[표]` 마커 X.
+    윤정님 split_sentences가 헤더 키워드 lookahead("운영시간"/"운영방법"/...)로
+    행 안에서 의미 단위 자연 분리하므로 셀 구분자 불필요.
+
+    mark_header=True: 각 표의 첫 번째 행 앞에 "[헤더] " 마킹 + 셀을 " | " 구분.
+    기본값 False — 기존 호출부(parse_bytes_to_text, batch_convert.py) 변경 없음.
+    """
+    with zipfile.ZipFile(odt_path) as z:
+        with z.open("content.xml") as f:
+            tree = ET.parse(f)
+
+    # 표/draw:frame 안 element id 모음 → 본문 처리에서 제외
+    # draw:frame: 텍스트 상자/이미지 프레임 — 본문과 같은 텍스트가 중복 저장돼
+    # 3배 이상 반복되는 아티팩트 원인. 표 inner 제외와 동일 방식.
+    table_inner_ids: set[int] = set()
+    for table in tree.iter(_ODT_TABLE_NS + "table"):
+        for elem in table.iter():
+            table_inner_ids.add(id(elem))
+    for frame in tree.iter(_ODT_DRAW_NS + "frame"):
+        for elem in frame.iter():
+            table_inner_ids.add(id(elem))
+
+    body_parts: list[str] = []
+    for elem in tree.iter():
+        tag = elem.tag
+        if tag in (_ODT_TEXT_NS + "p", _ODT_TEXT_NS + "h"):
+            if id(elem) in table_inner_ids:
+                continue
+            text = "".join(elem.itertext()).strip()
+            if text:
+                body_parts.append(text)
+
+    table_blocks: list[str] = []
+    for table in tree.iter(_ODT_TABLE_NS + "table"):
+        rows: list[str] = []
+        for row_idx, row in enumerate(table.iter(_ODT_TABLE_NS + "table-row")):
+            cells: list[str] = []
+            for cell in row.iter(_ODT_TABLE_NS + "table-cell"):
+                cell_text = "".join(cell.itertext()).strip()
+                if cell_text:
+                    cells.append(cell_text)
+            if cells:
+                if mark_header and row_idx == 0:
+                    rows.append("[헤더] " + " | ".join(cells))
+                else:
+                    rows.append(" ".join(cells))
+        if rows:
+            table_blocks.append("\n".join(rows))
+
+    parts: list[str] = []
+    if body_parts:
+        parts.append("\n".join(body_parts))
+    if table_blocks:
+        parts.append("\n\n".join(table_blocks))
+    return "\n\n".join(parts)
+
+
+def parse_bytes_to_text(data: bytes, filename: str) -> str:
+    """업로드된 bytes + 파일명 → 정규화된 clean_text.
+
+    호출부(라우터)는 파일 확장자 분기 신경 안 쓰고 이 함수만 부르면 됨.
+    """
+    if not data:
+        return ""
+
+    suffix = Path(filename).suffix.lower()
+
+    # 화이트리스트 검사: 알 수 없는 suffix는 일찍 거부.
+    # (subprocess는 어차피 list-form이라 명령 주입은 불가능하지만 표면을 줄임)
+    if suffix and suffix not in ALLOWED_EXTS:
+        raise ParserError(f"지원하지 않는 파일 형식: {suffix}")
+
+    if suffix in TEXT_EXTS or suffix == "":
+        return normalize(data.decode("utf-8", errors="replace"))
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        # 디스크 경로는 항상 tempdir 안의 고정 이름. 원본 filename은 어디에도 안 들어감.
+        src_path = tmp_dir / f"input{suffix}"
+        src_path.write_bytes(data)
+
+        if suffix in PDF_EXTS:
+            raw = _pdf_to_text(src_path)
+            return normalize(raw)
+
+        if suffix in HWP_EXTS:
+            odt_path = _hwp_to_odt(src_path, tmp_dir)
+            raw = _odt_to_text(odt_path)
+            return normalize(raw)
+
+        if suffix in IMG_EXTS:
+            raw = _image_to_text(src_path)
+            return normalize(raw)
+
+    raise ParserError(f"지원하지 않는 파일 형식: {suffix}")

backend/app/services/slot_extractor.py

@@ -0,0 +1,364 @@
+"""정규식 + i18n 포매터 기반 슬롯 추출기.
+
+강사 처방(2026-04-28) 대응:
+  - 날짜·시간·금액 같은 명확한 수치 데이터는 정규식으로 1차 안전 추출
+  - LLM 추론에 100% 의존하지 않고 지정된 위치(슬롯)에 매핑
+  - NLLB/glossary 거치지 않고 i18n 룰만으로 대상 언어 변환
+
+설계:
+  extract_dates/extract_times/extract_amounts → 구조화된 dict 리스트
+  format_date/format_time/format_amount → 대상 언어 문자열
+  extract_summary_regex_slots → 위 둘을 묶어 SlotEntry 호환 dict 반환
+"""
+from __future__ import annotations
+
+import re
+
+# ── 정규식 ────────────────────────────────────────────────────────
+_DATE_FULL = re.compile(
+    r"(?P<year>\d{4})\s*년\s*(?P<month>\d{1,2})\s*월\s*(?P<day>\d{1,2})\s*일"
+    r"(?:\s*\((?P<wday>[월화수목금토일])\))?"
+)
+_DATE_MD = re.compile(
+    r"(?P<month>\d{1,2})\s*월\s*(?P<day>\d{1,2})\s*일"
+    r"(?:\s*\((?P<wday>[월화수목금토일])\))?"
+)
+_DATE_SLASH = re.compile(r"\b(?P<month>\d{1,2})\s*[/.]\s*(?P<day>\d{1,2})\b")
+# 점 표기 ("2026. 4. 18.(토)" / "5. 16.(토)") — 요일 필수로 시간·금액 오탐 회피
+_DATE_DOT = re.compile(
+    r"(?:(?P<year>\d{4})\s*\.\s*)?"
+    r"(?P<month>\d{1,2})\s*\.\s*"
+    r"(?P<day>\d{1,2})\s*\.?"
+    r"\s*\((?P<wday>[월화수목금토일])\)"
+)
+_DATE_RELATIVE = ["내일", "모레", "오늘", "다음 주", "다음주", "이번 주", "이번주"]
+
+_TIME_AMPM = re.compile(
+    r"(?P<ampm>오전|오후)\s*(?P<hour>\d{1,2})\s*시(?:\s*(?P<minute>\d{1,2})\s*분)?"
+)
+_TIME_24H = re.compile(r"(?<!\d)(?P<hour>\d{1,2}):(?P<minute>\d{2})(?!\d)")
+
+_AMOUNT_KRW = re.compile(r"(?P<num>\d{1,3}(?:,\d{3})+|\d+)\s*원")
+_AMOUNT_KO = re.compile(r"(?P<num>\d+)\s*(?P<unit>만|천|억)\s*원")
+
+# URL: http(s)://… 또는 www.…  — NLLB가 토큰화하면서 깨먹는 패턴 방지용 슬롯
+_URL = re.compile(r"\bhttps?://[^\s<>\"'()]+|\bwww\.[^\s<>\"'()]+", re.IGNORECASE)
+# 전화번호: 02-xxx-xxxx, 02-xxxx-xxxx, 010-xxxx-xxxx, 1588-0260, 849-7003 등
+# 시작·끝에 숫자 인접 금지 (15,000원 같은 금액 부분 매칭 회피)
+_PHONE = re.compile(
+    r"(?<![\d-])"
+    r"(?:\d{2,4}-\d{3,4}-\d{4}|\d{4}-\d{4}|\d{3,4}-\d{4})"
+    r"(?!\d)"
+)
+
+# 까지 마감 표현: "5월 9일까지", "내일까지", "5월 9일(금)까지 ... 제출"
+# 콤마는 negation에서 제외 — "15,000원 (...까지...)" 같이 숫자 콤마에서 잘리는 버그 회피
+# 한글 프로 마커(❍❏|※)도 종결자 — pdfplumber 본문이 한 줄로 들어와도 항목 단위로 끊김
+_DEADLINE_PHRASE = re.compile(r"([^.\n❍❏|※]*?까지[^.\n❍❏|※]*?)(?=[.\n❍❏|※]|$)")
+
+# 안내문 줄머리 장식 마크업 (■ ▶ ▸ etc.) — items/슬롯 추출 전 strip
+_MARKER_STRIP = re.compile(r"^[\s■▶▸◆●○*\-•]+")
+
+
+def strip_markers(text: str) -> str:
+    """줄머리 장식 마크업 제거. UI 표시·TTS 양쪽 노이즈 방지."""
+    return _MARKER_STRIP.sub("", text).strip()
+
+
+# ── 추출기 ────────────────────────────────────────────────────────
+def extract_dates(text: str) -> list[dict]:
+    """텍스트에서 날짜 후보를 모두 뽑는다. 중복은 표면형 기준으로 제거."""
+    out: list[dict] = []
+    seen: set[str] = set()
+
+    for m in _DATE_FULL.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append({
+            "ko": ko,
+            "year": int(m.group("year")),
+            "month": int(m.group("month")),
+            "day": int(m.group("day")),
+            "weekday": m.group("wday"),
+        })
+
+    for m in _DATE_MD.finditer(text):
+        # 이미 _DATE_FULL이 잡은 영역과 겹치면 스킵
+        if any(s in text and m.start() >= text.find(s) and m.end() <= text.find(s) + len(s) for s in seen):
+            continue
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append({
+            "ko": ko,
+            "year": None,
+            "month": int(m.group("month")),
+            "day": int(m.group("day")),
+            "weekday": m.group("wday"),
+        })
+
+    for m in _DATE_DOT.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append({
+            "ko": ko,
+            "year": int(m.group("year")) if m.group("year") else None,
+            "month": int(m.group("month")),
+            "day": int(m.group("day")),
+            "weekday": m.group("wday"),
+        })
+
+    for word in _DATE_RELATIVE:
+        if word in text and word not in seen:
+            seen.add(word)
+            out.append({"ko": word, "year": None, "month": None, "day": None,
+                        "weekday": None, "relative": word})
+
+    return out
+
+
+def extract_times(text: str) -> list[dict]:
+    out: list[dict] = []
+    seen: set[str] = set()
+    for m in _TIME_AMPM.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append({
+            "ko": ko,
+            "hour": int(m.group("hour")),
+            "minute": int(m.group("minute")) if m.group("minute") else 0,
+            "ampm": m.group("ampm"),
+        })
+    for m in _TIME_24H.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append({
+            "ko": ko,
+            "hour": int(m.group("hour")),
+            "minute": int(m.group("minute")),
+            "ampm": None,
+        })
+    return out
+
+
+def extract_amounts(text: str) -> list[dict]:
+    """원화 금액을 정규화된 정수와 함께 반환."""
+    out: list[dict] = []
+    seen: set[str] = set()
+
+    for m in _AMOUNT_KRW.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        num = int(m.group("num").replace(",", ""))
+        out.append({"ko": ko, "value": num, "currency": "KRW"})
+
+    for m in _AMOUNT_KO.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        n = int(m.group("num"))
+        unit = m.group("unit")
+        mul = {"천": 1_000, "만": 10_000, "억": 100_000_000}[unit]
+        out.append({"ko": ko, "value": n * mul, "currency": "KRW"})
+
+    return out
+
+
+def extract_deadline_phrases(text: str) -> list[str]:
+    """'까지'가 들어간 어구를 한 문장 단위로 추출.
+
+    URL 안 마침표(`.do`/`.kr` 등)에서 phrase가 잘려 무의미하게 길어지는 것 회피 —
+    매칭 전 URL을 placeholder로 마스킹 후 매칭.
+    """
+    masked = _URL.sub(lambda m: "⟦U" + ("_" * (len(m.group(0)) - 3)) + "⟧", text)
+    return [m.group(1).strip() for m in _DEADLINE_PHRASE.finditer(masked)]
+
+
+def extract_urls(text: str) -> list[str]:
+    """URL 표면형 그대로. NLLB로 보내지 말고 슬롯으로 격리."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for m in _URL.finditer(text):
+        ko = m.group(0).strip().rstrip(".,)]")
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append(ko)
+    return out
+
+
+def extract_phones(text: str) -> list[str]:
+    """전화번호 표면형. 같은 이유로 슬롯 격리."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for m in _PHONE.finditer(text):
+        ko = m.group(0).strip()
+        if ko in seen:
+            continue
+        seen.add(ko)
+        out.append(ko)
+    return out
+
+
+# ── 다국어 포매터 ─────────────────────────────────────────────────
+# 베트남어가 1차 시연 타깃이라 가장 정교하게. 나머지 언어는 안전한 디폴트.
+_WEEKDAY_VI = {"월": "Thứ Hai", "화": "Thứ Ba", "수": "Thứ Tư", "목": "Thứ Năm",
+               "금": "Thứ Sáu", "토": "Thứ Bảy", "일": "Chủ Nhật"}
+_WEEKDAY_EN = {"월": "Mon", "화": "Tue", "수": "Wed", "목": "Thu",
+               "금": "Fri", "토": "Sat", "일": "Sun"}
+_RELATIVE_MAP = {
+    "vi": {"내일": "Ngày mai", "모레": "Ngày kia", "오늘": "Hôm nay",
+           "다음 주": "Tuần sau", "다음주": "Tuần sau",
+           "이번 주": "Tuần này", "이번주": "Tuần này"},
+    "en": {"내일": "Tomorrow", "모레": "Day after tomorrow", "오늘": "Today",
+           "다음 주": "Next week", "다음주": "Next week",
+           "이번 주": "This week", "이번주": "This week"},
+}
+
+
+def format_date(d: dict, target_lang: str) -> str:
+    if d.get("relative"):
+        return _RELATIVE_MAP.get(target_lang, {}).get(d["relative"], d["ko"])
+    y, m, day, w = d.get("year"), d.get("month"), d.get("day"), d.get("weekday")
+    if not (m and day):
+        return d["ko"]
+    if target_lang == "vi":
+        s = f"Ngày {day}/{m}" + (f"/{y}" if y else "")
+        if w:
+            s += f" ({_WEEKDAY_VI[w]})"
+        return s
+    if target_lang == "en":
+        months = ["", "January", "February", "March", "April", "May", "June",
+                  "July", "August", "September", "October", "November", "December"]
+        s = f"{months[m]} {day}" + (f", {y}" if y else "")
+        if w:
+            s += f" ({_WEEKDAY_EN[w]})"
+        return s
+    if target_lang in ("zh", "ja"):
+        return f"{m}月{day}日" + (f" ({w})" if w else "")
+    if target_lang == "ko_easy":
+        return d["ko"]  # 그대로
+    # ru / ms / th / mn 등은 일단 안전한 숫자 포맷
+    return f"{day}/{m}" + (f"/{y}" if y else "")
+
+
+def format_time(t: dict, target_lang: str) -> str:
+    h, mm, ampm = t.get("hour"), t.get("minute") or 0, t.get("ampm")
+    if h is None:
+        return t["ko"]
+    if target_lang == "vi":
+        suffix = ""
+        if ampm == "오전":
+            suffix = " sáng"
+        elif ampm == "오후":
+            suffix = " chiều"
+        return f"{h} giờ{(' ' + str(mm)) if mm else ''}{suffix}".strip()
+    if target_lang == "en":
+        ap = "AM" if ampm == "오전" else "PM" if ampm == "오후" else ""
+        return f"{h}:{mm:02d} {ap}".strip() if ap else f"{h}:{mm:02d}"
+    if target_lang in ("zh", "ja"):
+        prefix = "上午" if ampm == "오전" else "下午" if ampm == "오후" else ""
+        if target_lang == "ja":
+            prefix = "午前" if ampm == "오전" else "午後" if ampm == "오후" else ""
+        body = f"{h}時{mm:02d}分" if target_lang == "ja" else f"{h}时{mm:02d}分"
+        return f"{prefix}{body}"
+    if target_lang == "ko_easy":
+        return t["ko"]
+    return f"{h}:{mm:02d}"
+
+
+def format_amount(a: dict, target_lang: str) -> str:
+    n = a["value"]
+    # 천단위 콤마. (베트남식 점 표기는 _post_process_vi와 충돌하므로 콤마로 통일)
+    formatted = f"{n:,}"
+    suffix = {
+        "vi": " won", "en": " won", "ms": " won", "ru": " вон", "mn": " вон",
+        "th": " วอน", "zh": "韩元", "ja": "ウォン", "ko_easy": "원",
+    }.get(target_lang, " won")
+    return f"{formatted}{suffix}"
+
+
+# ── 통합 진입점 ──────────────────────────────────────────────────
+def extract_summary_regex_slots(text: str, target_lang: str) -> dict[str, list[dict]]:
+    """summary 슬롯 중 정규식으로 채울 수 있는 항목들을 SlotEntry-ready dict로.
+
+    urls/phones는 번역 안 거치고 ko 그대로 노출 (NLLB가 깨먹는 패턴 방어).
+    """
+    out: dict[str, list[dict]] = {
+        "dates": [], "times": [], "amounts": [], "urls": [], "phones": [],
+    }
+    for d in extract_dates(text):
+        out["dates"].append({
+            "ko": d["ko"],
+            "translated": format_date(d, target_lang),
+            "source": "regex",
+        })
+    for t in extract_times(text):
+        out["times"].append({
+            "ko": t["ko"],
+            "translated": format_time(t, target_lang),
+            "source": "regex",
+        })
+    for a in extract_amounts(text):
+        out["amounts"].append({
+            "ko": a["ko"],
+            "translated": format_amount(a, target_lang),
+            "source": "regex",
+        })
+    for url in extract_urls(text):
+        out["urls"].append({"ko": url, "translated": url, "source": "regex"})
+    for phone in extract_phones(text):
+        out["phones"].append({"ko": phone, "translated": phone, "source": "regex"})
+    return out
+
+
+def find_when_in_text(text: str, target_lang: str) -> str | None:
+    """item.when 용 — 텍스트에서 첫 날짜 + 시간 조합."""
+    dates = extract_dates(text)
+    times = extract_times(text)
+    parts: list[str] = []
+    if dates:
+        parts.append(format_date(dates[0], target_lang))
+    if times:
+        parts.append(format_time(times[0], target_lang))
+    return " ".join(parts) if parts else None
+
+
+def find_amount_in_text(text: str, target_lang: str) -> str | None:
+    """item.amount 용 — 텍스트의 첫 금액(원문 ko 그대로 반환, 안드 표시는 summary 통해 i18n)."""
+    amounts = extract_amounts(text)
+    return amounts[0]["ko"] if amounts else None
+
+
+def find_deadline_in_text(text: str) -> str | None:
+    """item.deadline 용 — '까지'가 들어간 첫 어구의 ko 표면형."""
+    phrases = extract_deadline_phrases(text)
+    return phrases[0] if phrases else None
+
+
+# ── 준비물 리스트 분해 ────────────────────────────────────────────
+# "도시락, 물통, 돗자리, 편한 운동화, 여벌 옷" → 5개 토큰
+_LIST_SEP = re.compile(r"[,，、]\s*|\s*(?:과|와|및)\s+")
+
+
+def split_supply_tokens(text: str) -> list[str]:
+    """카테고리=준비물 todo의 텍스트에서 항목 토큰 분리.
+
+    안내 문구('준비물:', '준비해 주세요' 등)는 제거 후 분리.
+    """
+    cleaned = re.sub(r"준비물\s*[:：]?\s*", "", text)
+    cleaned = re.sub(r"(을|를)?\s*(준비해|챙겨|가져).*$", "", cleaned)
+    tokens = [t.strip() for t in _LIST_SEP.split(cleaned) if t and t.strip()]
+    return [t for t in tokens if 1 < len(t) < 30]

backend/app/services/translator.py

@@ -0,0 +1,299 @@
+"""세종님 NLLB 번역 + 용어 검수 wrapper.
+
+run_mvp_pipeline.py의 가벼운 함수들(easy_korean, glossary)은 직접 호출.
+NLLB 번역은 매번 모델 새로 로드하지 않게 캐싱.
+
+URL/전화는 NLLB가 토큰화하면서 깨먹는 패턴이라 placeholder 치환 + 복원으로 보호.
+세종님 요청(2026-04-29).
+"""
+import re
+import sys
+from pathlib import Path
+
+import torch
+from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+from app.services.slot_extractor import _PHONE, _URL
+
+_TRANSLATION_DIR = Path("/app/external_model/translation_tts")
+if str(_TRANSLATION_DIR) not in sys.path:
+    sys.path.insert(0, str(_TRANSLATION_DIR))
+
+# 외부 마운트가 없는 환경(CI/테스트)에서도 모듈 로드는 성공해야 한다.
+try:
+    import run_mvp_pipeline as _sejong  # noqa: E402
+except ImportError as error:
+    print(f"[translator] run_mvp_pipeline unavailable: {error}")
+    _sejong = None
+
+NLLB_MODEL_NAME = "facebook/nllb-200-distilled-600M"
+SOURCE_LANG = "kor_Hang"
+MAX_TRANSLATE_CHARS = 100
+
+# 안드 언어 코드 → NLLB FLORES-200 코드
+LANG_TO_NLLB = {
+    "vi": "vie_Latn",
+    "en": "eng_Latn",
+    "ru": "rus_Cyrl",
+    "ms": "zsm_Latn",
+    "mn": "khk_Cyrl",
+    "zh": "zho_Hans",
+    "th": "tha_Thai",
+    "ja": "jpn_Jpan",
+}
+
+_tokenizer = None
+_model = None
+# 사전 raw rows 단일 캐시. 언어별 분기는 find_glossary_hits 호출 시 target_lang 인자로 처리.
+_glossary_rows: list | None = None
+
+
+def _get_translator():
+    global _tokenizer, _model
+    if _model is None:
+        _tokenizer = AutoTokenizer.from_pretrained(NLLB_MODEL_NAME, src_lang=SOURCE_LANG)
+        _model = AutoModelForSeq2SeqLM.from_pretrained(NLLB_MODEL_NAME)
+        _model.eval()
+    return _tokenizer, _model
+
+
+def _get_glossary():
+    """raw 사전 rows를 1회 로드. 언어별 컬럼 선택은 find_glossary_hits에서 처리."""
+    global _glossary_rows
+    if _glossary_rows is None:
+        if _sejong is None:
+            _glossary_rows = []
+            return _glossary_rows
+        try:
+            _glossary_rows = _sejong.read_glossary(_TRANSLATION_DIR / "term_glossary.csv")
+        except Exception as error:
+            print(f"[translator] glossary load failed: {error}")
+            _glossary_rows = []
+    return _glossary_rows
+
+
+def _translate(text: str, target_nllb: str = "vie_Latn", max_length: int = 512) -> str:
+    tokenizer, model = _get_translator()
+    target_id = tokenizer.convert_tokens_to_ids(target_nllb)
+    inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=max_length)
+    with torch.no_grad():
+        out = model.generate(
+            **inputs,
+            forced_bos_token_id=target_id,
+            max_length=max_length,
+            num_beams=4,
+            no_repeat_ngram_size=3,
+            repetition_penalty=1.3,
+            early_stopping=True,
+        )
+    return tokenizer.batch_decode(out, skip_special_tokens=True)[0]
+
+
+# 한국어 원문 → 베트남어 번역 결과의 명백한 오번역 강제 치환.
+# NLLB가 학교 도메인을 못 배워서 발생하는 시각적 결함을 시연 전에 막는 안전망.
+_CURRENCY_PATTERNS = [
+    re.compile(r"\bđô\s*la\b", re.IGNORECASE),
+    re.compile(r"\bdollars?\b", re.IGNORECASE),
+    re.compile(r"\bUSD\b"),
+]
+# 천단위 점(40.000) → 콤마(40,000). 베트남식 표기지만 한국 학부모는 "40원"으로 오인할 수 있음.
+_THOUSAND_DOT = re.compile(r"(\d{1,3}(?:\.\d{3})+)")
+_KRW_AMOUNT = re.compile(r"\d[\d,]*\s*원")
+
+
+def _normalize_thousand_separator(text: str) -> str:
+    def repl(m):
+        return m.group(1).replace(".", ",")
+    return _THOUSAND_DOT.sub(repl, text)
+
+
+def _post_process_vi(easy_ko: str, vi_text: str) -> str:
+    if not vi_text:
+        return vi_text
+    if _KRW_AMOUNT.search(easy_ko):
+        for pat in _CURRENCY_PATTERNS:
+            vi_text = pat.sub("won", vi_text)
+        vi_text = _normalize_thousand_separator(vi_text)
+    return vi_text
+
+
+# OCR 변환 과정에서 생기는 특수문자 제거. HWP 체크박스/불릿이 □·▣ 등으로 깨지는 패턴.
+_OCR_NOISE = re.compile(r"[□■▣▷◆◇▶◀►◄■-◿`]+")
+_MULTI_SPACE = re.compile(r"[ \t]{2,}")
+
+
+def _clean_for_translation(text: str) -> str:
+    """NLLB 입력 전 OCR 잔여 특수문자를 제거한다."""
+    text = _OCR_NOISE.sub(" ", text)
+    text = _MULTI_SPACE.sub(" ", text)
+    return text.strip()
+
+
+# URL/전화 보호 — NLLB가 깨먹는 패턴 방어. 한국어 입력에 안 등장하는 unicode bracket으로
+# 치환하고 번역 후 복원. ⟦…⟧는 NLLB가 분해하지 않는 안전 토큰.
+_PROTECT_TOKEN = re.compile(r"⟦P(\d+)⟧")
+
+
+def _mask_protected_entities(text: str) -> tuple[str, list[str]]:
+    """URL/전화 → ⟦P0⟧ 등 토큰. (masked, originals) 반환."""
+    placeholders: list[str] = []
+
+    def stash(match: re.Match) -> str:
+        placeholders.append(match.group(0))
+        return f"⟦P{len(placeholders) - 1}⟧"
+
+    masked = _URL.sub(stash, text)
+    masked = _PHONE.sub(stash, masked)
+    return masked, placeholders
+
+
+def _restore_protected_entities(text: str, placeholders: list[str]) -> str:
+    if not placeholders:
+        return text
+
+    def restore(match: re.Match) -> str:
+        idx = int(match.group(1))
+        return placeholders[idx] if idx < len(placeholders) else match.group(0)
+
+    return _PROTECT_TOKEN.sub(restore, text)
+
+
+def _is_url_or_phone(text: str) -> bool:
+    """슬롯 단위 번역 시 URL/전화면 NLLB 안 거치고 ko 그대로 반환하기 위한 가드."""
+    s = text.strip()
+    return bool(_URL.fullmatch(s) or _PHONE.fullmatch(s))
+
+
+def translate_term(text: str, target_lang: str) -> str:
+    """glossary 직접 치환 (summary 슬롯용 — places, supplies, deadlines).
+
+    exact match 우선. 없으면 한국어 원문 그대로 반환 (빈 문자열 금지).
+    고유명사("서울숲 생태체험관")처럼 사전에 없으면 한국어 노출이 NLLB 오역보다 낫다.
+    URL/전화는 어떤 언어든 ko 그대로 (방어적 가드).
+    """
+    if not text or not text.strip():
+        return text
+    if target_lang == "ko_easy" or _is_url_or_phone(text):
+        return text
+
+    glossary = _get_glossary()
+    term = text.strip()
+    for row in glossary:
+        if row.get("korean", "").strip() == term:
+            translated = row.get(f"preferred_{target_lang}", "").strip()
+            if translated:
+                return translated
+    return text  # Korean passthrough
+
+
+def translate_short_sentence(text: str, target_lang: str) -> str:
+    """짧은 문장 NLLB 번역 (items[].title_translated용).
+
+    URL/전화 보호 → glossary injection → NLLB → 보호 토큰 복원 → vi post-process.
+    실패 시 빈 문자열 반환 (호출부가 fallback 처리).
+    """
+    if not text or not text.strip():
+        return ""
+    if target_lang == "ko_easy":
+        return text
+    text = _clean_for_translation(text)[:MAX_TRANSLATE_CHARS]
+
+    # 1) URL/전화 placeholder 치환 — NLLB가 깨먹지 못하게 격리
+    masked, placeholders = _mask_protected_entities(text)
+
+    # 2) glossary injection (긴 용어 먼저 치환해야 부분 치환 충돌 방지)
+    glossary = _get_glossary()
+    hits = _sejong.find_glossary_hits(masked, glossary, target_lang) if _sejong else []
+    injected = masked
+    for hit in sorted(hits, key=lambda h: len(h["korean"]), reverse=True):
+        injected = injected.replace(
+            hit["korean"], f"{hit['korean']}({hit['preferred_term']})"
+        )
+
+    target_nllb = LANG_TO_NLLB.get(target_lang, "vie_Latn")
+    try:
+        translated = _translate(injected, target_nllb=target_nllb)
+        if target_lang == "vi":
+            translated = _post_process_vi(text, translated)
+    except Exception as error:
+        print(f"[translator] translate_short_sentence failed: {error}")
+        return ""
+
+    # 3) 보호 토큰 복원
+    return _restore_protected_entities(translated, placeholders)
+
+
+# DEPRECATED: 아래 함수는 단일 blob 번역 구조. 새 API(translate_term / translate_short_sentence)로 전환 후 제거 예정.
+def translate_and_review(notice_text: str, target_lang: str = "vi") -> dict:
+    """[DEPRECATED] 가정통신문 → easy_ko + 다국어 번역 + 용어 검수 결과.
+
+    슬롯 기반 응답(summary + items)으로 전환 후 호출부 없음. 다음 PR에서 제거 예정.
+    신규 호출은 translate_term / translate_short_sentence 사용.
+    """
+    empty = {
+        "easy_ko_text": "",
+        "translation": "",
+        "target_language": target_lang,
+        "vi_text": "",
+        "quality_note": "",
+        "review_needed": "",
+    }
+    if not notice_text or not notice_text.strip():
+        return empty
+
+    source = {"easy_ko_text": "", "easy_korean": "", "original_text": notice_text}
+    baseline = {"original_text": notice_text}
+
+    try:
+        easy_ko_text = _sejong.prepare_easy_ko_text(
+            _sejong.build_easy_korean(source, baseline)
+        )
+    except Exception as error:
+        print(f"[translator] easy_ko failed: {error}")
+        easy_ko_text = notice_text
+
+    if not easy_ko_text:
+        return empty
+
+    # ko_easy는 한국어 자체라 사전 검수 무의미 → 빈 hits
+    if target_lang == "ko_easy":
+        glossary_hits = []
+    else:
+        glossary = _get_glossary()
+        glossary_hits = _sejong.find_glossary_hits(easy_ko_text, glossary, target_lang)
+
+    # ko_easy: 번역 없이 easy_ko_text를 그대로 사용
+    if target_lang == "ko_easy":
+        rows = _sejong.build_glossary_check_rows(easy_ko_text, "", glossary_hits)
+        label, note = _sejong.summarize_quality(rows)
+        return {
+            "easy_ko_text": easy_ko_text,
+            "translation": "",
+            "target_language": "ko_easy",
+            "vi_text": "",
+            "quality_note": note if note else f"ok ({label})",
+            "review_needed": note if label == "review_needed" else "",
+        }
+
+    target_nllb = LANG_TO_NLLB.get(target_lang, "vie_Latn")
+    try:
+        translated = _translate(easy_ko_text, target_nllb=target_nllb)
+        if target_lang == "vi":
+            translated = _post_process_vi(easy_ko_text, translated)
+    except Exception as error:
+        print(f"[translator] translate failed: {error}")
+        translated = ""
+
+    rows = _sejong.build_glossary_check_rows(easy_ko_text, translated, glossary_hits)
+    label, note = _sejong.summarize_quality(rows)
+
+    return {
+        "easy_ko_text": easy_ko_text,
+        "translation": translated,
+        "target_language": target_lang,
+        # 호환: vi_text는 vi 선택 시만 채움 (안드 기존 fallback 동작)
+        "vi_text": translated if target_lang == "vi" else "",
+        "quality_note": note if note else f"ok ({label})",
+        "review_needed": note if label == "review_needed" else "",
+    }
+

backend/app/services/tts.py

@@ -0,0 +1,38 @@
+import uuid
+from pathlib import Path
+
+import edge_tts
+
+# 안드 언어 코드 → Edge-TTS voice
+LANG_TO_VOICE = {
+    "vi": "vi-VN-HoaiMyNeural",
+    "en": "en-US-JennyNeural",
+    "ru": "ru-RU-SvetlanaNeural",
+    "ms": "ms-MY-YasminNeural",
+    "mn": "mn-MN-YesuiNeural",
+    "zh": "zh-CN-XiaoxiaoNeural",
+    "th": "th-TH-PremwadeeNeural",
+    "ja": "ja-JP-NanamiNeural",
+    "ko_easy": "ko-KR-SunHiNeural",
+}
+
+STATIC_DIR = Path("/app/static/tts")
+STATIC_DIR.mkdir(parents=True, exist_ok=True)
+
+
+async def generate_tts_file(text: str, target_lang: str = "vi") -> str:
+    """선택 언어의 텍스트 → mp3 파일 생성. 안드가 BASE_URL과 합쳐 재생할 상대 경로 반환."""
+    if not text or not text.strip():
+        return ""
+    voice = LANG_TO_VOICE.get(target_lang)
+    if not voice:
+        print(f"[tts] no voice for lang={target_lang}")
+        return ""
+    filename = f"{uuid.uuid4()}.mp3"
+    out_path = STATIC_DIR / filename
+    try:
+        await edge_tts.Communicate(text=text, voice=voice).save(str(out_path))
+    except Exception as error:
+        print(f"[tts] generation failed for lang={target_lang}: {error}")
+        return ""
+    return f"/static/tts/{filename}"

backend/requirements-dev.txt

@@ -0,0 +1,5 @@
+# 개발/테스트 전용 의존성. 운영 컨테이너에는 설치 안 함.
+# 사용: docker compose exec backend pip install -r requirements-dev.txt
+# 또는 GitHub Actions에서 별도 install
+pytest>=8.0
+httpx>=0.27

backend/requirements.txt

@@ -0,0 +1,22 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+fastapi==0.111.0
+uvicorn[standard]==0.29.0
+pydantic==2.7.1
+edge-tts>=7.0.0
+torch==2.3.1+cpu
+transformers==4.44.2
+huggingface-hub==0.24.7
+sentencepiece==0.2.0
+numpy==2.0.2
+pandas==2.2.2
+
+# 파일 입력 변환 ([1] 텍스트 변환)
+pdfplumber==0.11.9
+python-multipart==0.0.20
+
+# 이미지 OCR ([1] 카메라 사진 입력 — 세종)
+pytesseract>=0.3.10
+pillow>=10.0.0
+
+# 경이 분류기 ([4] 단계 — TF-IDF + LogReg simple, KcELECTRA는 transformers 사용)
+scikit-learn==1.5.2

backend/static/tts/.gitkeep

@@ -0,0 +1 @@
+

backend/tests/README.md

@@ -0,0 +1,31 @@
+# 백엔드 단위테스트
+
+> 강사 피드백(2026-04-28) 대응: *"단위테스트 끝나고 통합테스트 할 때 합의된 기준/절차에 의해 merge"*  
+> → PR이 권한 검증·다국어 사전 로딩을 깨지 않는다는 자동 증빙 레이어.
+
+## 구성
+
+| 파일 | 검증 대상 |
+| --- | --- |
+| `test_auth_routes.py` | X-User-Id 헤더 인증, 역할(teacher/parent) 권한, 발송→수신 통합 흐름 |
+| `test_glossary.py` | 다국어 용어사전(8개) 컬럼 동적 로딩, find_glossary_hits 언어별 동작 |
+
+## 실행
+
+### 도커 컨테이너에서
+
+```bash
+docker compose exec backend pip install -r /app/../backend/requirements-dev.txt
+# 또는: docker compose exec backend pip install pytest httpx
+docker compose exec backend pytest /app/../backend/tests -v
+```
+
+### CI (GitHub Actions)에서
+
+PR 시 자동 실행 — `.github/workflows/backend-tests.yml` 참조.
+
+## 추가 테스트 가이드
+
+- 모델 호출(KoELECTRA / NLLB / Edge-TTS)은 무거우므로 직접 호출 X. 필요 시 monkey-patch로 가짜 응답 사용.
+- 새 라우트 추가 시 권한 검증 케이스(teacher/parent/anonymous) 3종 모두 작성.
+- 테스트는 빠르게 (총 실행시간 30초 이내 목표).

backend/tests/conftest.py

@@ -0,0 +1,36 @@
+"""백엔드 테스트 공통 픽스처.
+
+모델(KoELECTRA / NLLB / Edge-TTS) 호출은 무거우므로
+auth/route 흐름 테스트에서는 monkey-patch로 가짜 응답을 사용한다.
+"""
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+@pytest.fixture
+def client():
+    """lifespan(seed_demo_users) 트리거를 위해 with 블록 안에서 사용."""
+    with TestClient(app) as c:
+        yield c
+
+
+@pytest.fixture
+def teacher_headers():
+    return {"X-User-Id": "teacher_001"}
+
+
+@pytest.fixture
+def teacher2_headers():
+    return {"X-User-Id": "teacher_002"}
+
+
+@pytest.fixture
+def parent_headers():
+    return {"X-User-Id": "parent_001"}
+
+
+@pytest.fixture
+def parent2_headers():
+    return {"X-User-Id": "parent_002"}

backend/tests/test_analyze_routes.py

@@ -0,0 +1,326 @@
+"""`/notice/analyze` + `/notice/inbox` DELETE 권한 검증 + 슬롯 응답 shape 테스트.
+
+핵심 라우트 권한 분리 + 강사 처방(2026-04-28) 슬롯 응답이 자동 게이트로 잡혀야 한다.
+모델 호출(KoELECTRA + NLLB + Edge-TTS)은 무거우므로 monkeypatch로 우회.
+"""
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def reset_notices():
+    """각 테스트 전 모듈 상태(_notices) 초기화로 순서 의존성 제거."""
+    from app.routers import notice
+    notice._notices.clear()
+    yield
+    notice._notices.clear()
+
+
+# ─────────────────────────────────────────
+#  공통 헬퍼: parent_001 앞으로 통신문 1건 발송
+# ─────────────────────────────────────────
+def _seed_notice(client, teacher_id="teacher_001", parent_id="parent_001",
+                 text="테스트 통신문") -> str:
+    payload = {"teacher_id": teacher_id, "parent_id": parent_id, "text": text}
+    headers = {"X-User-Id": teacher_id}
+    r = client.post("/notice/send", json=payload, headers=headers)
+    assert r.status_code == 200, r.text
+    return r.json()["data"]["notice_id"]
+
+
+def _patch_models(monkeypatch, *, todos=None, category=None,
+                  tts_url="/static/tts/fake.mp3"):
+    """모델 호출 4종(추출/분류/번역2)을 한 번에 mock. 각 테스트가 인자만 바꿔쓰게."""
+    from app.models.schemas import Category
+    default_category = category or Category.other
+    monkeypatch.setattr("app.routers.notice.extract_todos", lambda text: todos or [])
+    monkeypatch.setattr("app.routers.notice.classify_category",
+                        lambda text: default_category)
+    monkeypatch.setattr("app.routers.notice.translate_short_sentence",
+                        lambda text, target_lang: f"[VI]{text}")
+    monkeypatch.setattr("app.routers.notice.translate_term",
+                        lambda text, target_lang: f"[T]{text}")
+
+    async def fake_tts(text, target_lang="vi"):
+        return tts_url
+    monkeypatch.setattr("app.routers.notice.generate_tts_file", fake_tts)
+
+
+# ─────────────────────────────────────────
+#  ANALYZE — 권한 게이트
+# ─────────────────────────────────────────
+_VI_BODY = {"target_language": "vi"}
+
+
+def test_analyze_unknown_notice(client, parent_headers):
+    r = client.post("/notice/analyze/ghost-id-xxx", json=_VI_BODY, headers=parent_headers)
+    assert r.status_code == 404
+    assert "찾을 수 없습니다" in r.json()["detail"]
+
+
+def test_analyze_other_parent_blocked(client, teacher_headers, parent_headers, parent2_headers):
+    notice_id = _seed_notice(client)
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent2_headers)
+    assert r.status_code == 403
+    assert "본인의 가정통신문" in r.json()["detail"]
+
+
+def test_analyze_teacher_role_blocked(client, teacher_headers):
+    notice_id = _seed_notice(client)
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=teacher_headers)
+    assert r.status_code == 403
+
+
+def test_analyze_missing_target_language_rejected(client, teacher_headers, parent_headers):
+    """body에 target_language 없이 호출 → 422 (FastAPI body 검증)."""
+    notice_id = _seed_notice(client)
+    r = client.post(f"/notice/analyze/{notice_id}", json={}, headers=parent_headers)
+    assert r.status_code == 422
+
+
+# ─────────────────────────────────────────
+#  ANALYZE — 슬롯 응답 shape (강사 처방)
+# ─────────────────────────────────────────
+def test_analyze_returns_slot_shape(client, parent_headers, monkeypatch):
+    """응답이 summary + items 슬롯 구조 — translation 한 덩어리 필드 사라짐."""
+    notice_id = _seed_notice(client, text="내일 도시락을 가져와 주세요.")
+    _patch_models(monkeypatch)
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    assert r.status_code == 200
+    data = r.json()["data"]
+
+    assert data["notice_id"] == notice_id
+    assert data["target_language"] == "vi"
+
+    # summary 8슬롯 모두 존재 (urls/phones는 NLLB 보호용)
+    summary = data["summary"]
+    for key in ("dates", "times", "places", "supplies", "amounts",
+                "deadlines", "urls", "phones"):
+        assert key in summary, f"summary 슬롯 누락: {key}"
+        assert isinstance(summary[key], list)
+
+    # items 리스트 + 각 item 필수 필드
+    assert isinstance(data["items"], list)
+    for item in data["items"]:
+        for key in ("category", "action_hint", "title_ko", "title_translated",
+                    "when", "where", "what", "amount", "deadline", "importance"):
+            assert key in item, f"item 필드 누락: {key}"
+
+    # 구버전 한 덩어리 필드는 빠져있어야 함 (안드 마이그레이션 확인용)
+    assert "translation" not in data
+    assert "vi_text" not in data
+    assert "easy_ko_text" not in data
+    assert "todos" not in data
+
+    assert data["tts_url"] == "/static/tts/fake.mp3"
+
+
+def test_analyze_regex_slots_filled_from_raw_text(client, parent_headers, monkeypatch):
+    """원문에 날짜·시간·금액이 있으면 정규식 추출이 summary에 채워진다 (LLM 비의존 데이터)."""
+    text = "5월 14일(수) 오전 9시 출발. 참가비 15,000원."
+    notice_id = _seed_notice(client, text=text)
+    _patch_models(monkeypatch)
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    summary = r.json()["data"]["summary"]
+
+    # 정규식 hit 3종 모두 잡혀야 함
+    assert any(d["ko"] == "5월 14일(수)" for d in summary["dates"])
+    assert any(t["ko"] == "오전 9시" for t in summary["times"])
+    assert any(a["ko"] == "15,000원" for a in summary["amounts"])
+
+    # source: "regex" 명시 — 강사 처방 "정규식 + 모델 하이브리드" 가시화
+    assert all(d["source"] == "regex" for d in summary["dates"])
+    assert all(t["source"] == "regex" for t in summary["times"])
+    assert all(a["source"] == "regex" for a in summary["amounts"])
+
+
+def test_analyze_urls_phones_passthrough(client, parent_headers, monkeypatch):
+    """원문에 URL/전화가 있으면 summary.urls / phones에 ko 그대로 노출 (번역 X)."""
+    text = "신청 https://apply.school.kr, 문의 02-2649-7232 / 1588-0260"
+    notice_id = _seed_notice(client, text=text)
+    _patch_models(monkeypatch)
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    summary = r.json()["data"]["summary"]
+
+    assert any(u["ko"] == "https://apply.school.kr" for u in summary["urls"])
+    assert any(p["ko"] == "02-2649-7232" for p in summary["phones"])
+    assert any(p["ko"] == "1588-0260" for p in summary["phones"])
+
+    # translated가 ko와 동일 = 번역 안 거침
+    for u in summary["urls"]:
+        assert u["translated"] == u["ko"]
+    for p in summary["phones"]:
+        assert p["translated"] == p["ko"]
+
+
+def test_analyze_returns_cards_shape(client, parent_headers, monkeypatch):
+    """신규 cards 필드 구조 검증 — 슬롯 카드 재설계 (Phase 1)."""
+    from app.models.schemas import Category, YunjeongTodo
+    todos = [YunjeongTodo(
+        text="운영시간 오전 10:00 ~ 12:00 (2시간)",
+        confidence=0.85,
+        action_hint="참여",
+    )]
+    notice_id = _seed_notice(client, text="운영시간 오전 10:00 ~ 12:00 (2시간)")
+    _patch_models(monkeypatch, todos=todos, category=Category.schedule)
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    assert r.status_code == 200
+    data = r.json()["data"]
+
+    # cards 필드 존재 + 리스트
+    assert "cards" in data
+    assert isinstance(data["cards"], list)
+    assert len(data["cards"]) >= 1
+
+    # 카드 필수 필드
+    for card in data["cards"]:
+        for key in ("header_ko", "header_translated", "value_ko",
+                    "value_easy_ko", "value_translated", "chip", "importance"):
+            assert key in card, f"card 필드 누락: {key}"
+
+    # 헤더 분해 — "운영시간" 헤더 추출됐는지
+    headers = [c["header_ko"] for c in data["cards"]]
+    assert "운영시간" in headers, f"운영시간 헤더 누락: {headers}"
+
+    # tts_url_easy_ko 필드 존재 (세종님 별도 버튼)
+    assert "tts_url_easy_ko" in data
+
+
+def test_analyze_cards_regex_url_card(client, parent_headers, monkeypatch):
+    """todo로 못 잡힌 URL이 regex 보강으로 '신청 URL' 카드에 들어가야 한다."""
+    text = "신청 안내. http://apply.school.kr 에서 접수."
+    notice_id = _seed_notice(client, text=text)
+    _patch_models(monkeypatch)  # todos 빈 채로
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    cards = r.json()["data"]["cards"]
+    headers = [c["header_ko"] for c in cards]
+    assert "신청 URL" in headers, f"URL 카드 누락: {headers}"
+    url_card = next(c for c in cards if c["header_ko"] == "신청 URL")
+    assert "http://apply.school.kr" in url_card["value_ko"]
+
+
+def test_analyze_supplies_aggregated_from_items(client, parent_headers, monkeypatch):
+    """경이님 분류가 supplies로 잡힌 todo의 토큰이 summary.supplies로 집계 (강사 강조: 누락 금지)."""
+    from app.models.schemas import Category, YunjeongTodo
+    todos = [YunjeongTodo(
+        text="도시락, 물통, 돗자리를 준비해 주세요",
+        confidence=0.9,
+        action_hint="준비",
+    )]
+    notice_id = _seed_notice(client, text="도시락, 물통, 돗자리를 준비해 주세요")
+    _patch_models(monkeypatch, todos=todos, category=Category.supplies)
+
+    r = client.post(f"/notice/analyze/{notice_id}", json=_VI_BODY, headers=parent_headers)
+    supplies = r.json()["data"]["summary"]["supplies"]
+    ko_tokens = [s["ko"] for s in supplies]
+    assert "도시락" in ko_tokens
+    assert "물통" in ko_tokens
+    assert "돗자리" in ko_tokens
+
+
+# ─────────────────────────────────────────
+#  UPLOAD — multipart 파일 입력
+# ─────────────────────────────────────────
+def _patch_parser(monkeypatch, *, text="파싱 결과 텍스트", error=None):
+    """parser.parse_bytes_to_text를 mock해서 LibreOffice 의존 없이 검증."""
+    from app.services.parser import ParserError
+
+    def fake(data, filename):
+        if error:
+            raise ParserError(error)
+        return text
+
+    monkeypatch.setattr("app.routers.notice.parse_bytes_to_text", fake)
+
+
+def test_upload_text_creates_notice(client, teacher_headers, monkeypatch):
+    """평문 .txt 업로드 → notice 생성. 응답에 notice_id + char_count."""
+    _patch_parser(monkeypatch, text="텍스트 통신문 본문")
+    files = {"file": ("hello.txt", b"abc", "text/plain")}
+    data = {"teacher_id": "teacher_001", "parent_id": "parent_001"}
+
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+
+    assert r.status_code == 200, r.text
+    body = r.json()["data"]
+    assert "notice_id" in body
+    assert body["char_count"] == len("텍스트 통신문 본문")
+
+
+def test_upload_other_teacher_blocked(client, teacher_headers):
+    """본인 ID와 다른 teacher_id로 업로드 → 403."""
+    files = {"file": ("hello.txt", b"abc", "text/plain")}
+    data = {"teacher_id": "teacher_002", "parent_id": "parent_001"}
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+    assert r.status_code == 403
+
+
+def test_upload_unknown_parent_blocked(client, teacher_headers, monkeypatch):
+    """존재하지 않는 parent_id → 404."""
+    _patch_parser(monkeypatch)
+    files = {"file": ("x.txt", b"abc", "text/plain")}
+    data = {"teacher_id": "teacher_001", "parent_id": "ghost"}
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+    assert r.status_code == 404
+
+
+def test_upload_parser_failure_returns_400(client, teacher_headers, monkeypatch):
+    _patch_parser(monkeypatch, error="LibreOffice 변환 실패")
+    files = {"file": ("broken.hwp", b"x", "application/x-hwp")}
+    data = {"teacher_id": "teacher_001", "parent_id": "parent_001"}
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+    assert r.status_code == 400
+    assert "변환 실패" in r.json()["detail"]
+
+
+def test_upload_empty_text_returns_400(client, teacher_headers, monkeypatch):
+    """파서가 빈 문자열 반환 → 400."""
+    _patch_parser(monkeypatch, text="")
+    files = {"file": ("empty.txt", b"", "text/plain")}
+    data = {"teacher_id": "teacher_001", "parent_id": "parent_001"}
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+    assert r.status_code == 400
+
+
+def test_upload_then_inbox_round_trip(client, teacher_headers, parent_headers, monkeypatch):
+    """업로드 → 학부모 inbox에서 같은 텍스트 보임."""
+    _patch_parser(monkeypatch, text="upload→inbox 통신문")
+    files = {"file": ("doc.pdf", b"%PDF-fake", "application/pdf")}
+    data = {"teacher_id": "teacher_001", "parent_id": "parent_001"}
+    r = client.post("/notice/upload", data=data, files=files, headers=teacher_headers)
+    notice_id = r.json()["data"]["notice_id"]
+
+    inbox = client.get("/notice/inbox/parent_001", headers=parent_headers).json()["data"]
+    assert any(n["notice_id"] == notice_id and n["text"] == "upload→inbox 통신문"
+               for n in inbox)
+
+
+# ─────────────────────────────────────────
+#  DELETE INBOX — 본인만 허용
+# ─────────────────────────────────────────
+def test_delete_inbox_self_only(client, teacher_headers, parent_headers, parent2_headers):
+    notice_id = _seed_notice(client)
+    r = client.delete("/notice/inbox/parent_001", headers=parent2_headers)
+    assert r.status_code == 403
+
+    r2 = client.get("/notice/inbox/parent_001", headers=parent_headers)
+    assert r2.status_code == 200
+    assert any(n["notice_id"] == notice_id for n in r2.json()["data"])
+
+
+def test_delete_inbox_self_succeeds(client, teacher_headers, parent_headers):
+    _seed_notice(client)
+    _seed_notice(client, text="두 번째 통신문")
+
+    r1 = client.get("/notice/inbox/parent_001", headers=parent_headers)
+    assert len(r1.json()["data"]) >= 2
+
+    r2 = client.delete("/notice/inbox/parent_001", headers=parent_headers)
+    assert r2.status_code == 200
+
+    r3 = client.get("/notice/inbox/parent_001", headers=parent_headers)
+    assert r3.json()["data"] == []

backend/tests/test_auth_routes.py

@@ -0,0 +1,72 @@
+"""권한 분리 라우트 테스트.
+
+강사 피드백(2026-04-28): "단위테스트 끝나고 통합테스트 할 때 합의된 기준/절차에 의해 merge"
+→ 운영 PR이 권한 검증을 깨지 않는다는 자동 증빙.
+"""
+
+
+def test_health_ok(client):
+    """기본 헬스체크 — 모델 로드 없이 즉시 응답."""
+    r = client.get("/health")
+    assert r.status_code == 200
+    assert r.json()["status"] == "ok"
+
+
+def test_send_notice_requires_teacher_role(client, parent_headers):
+    """학부모 ID로 발송 시도 → 403."""
+    payload = {"teacher_id": "teacher_001", "parent_id": "parent_001", "text": "테스트"}
+    r = client.post("/notice/send", json=payload, headers=parent_headers)
+    assert r.status_code == 403
+    assert "선생님 권한" in r.json()["detail"]
+
+
+def test_send_notice_teacher_id_must_match_header(client, teacher_headers):
+    """헤더(teacher_001) ≠ body.teacher_id(teacher_002) → 403."""
+    payload = {"teacher_id": "teacher_002", "parent_id": "parent_001", "text": "테스트"}
+    r = client.post("/notice/send", json=payload, headers=teacher_headers)
+    assert r.status_code == 403
+    assert "본인 선생님 ID" in r.json()["detail"]
+
+
+def test_send_notice_unknown_parent(client, teacher_headers):
+    """존재하지 않는 학부모로 발송 → 404."""
+    payload = {"teacher_id": "teacher_001", "parent_id": "parent_999", "text": "테스트"}
+    r = client.post("/notice/send", json=payload, headers=teacher_headers)
+    assert r.status_code == 404
+    assert "학부모 계정을 찾을 수 없습니다" in r.json()["detail"]
+
+
+def test_inbox_self_only(client, parent_headers, parent2_headers):
+    """parent_001은 본인 수신함 OK, parent_002의 수신함 조회는 403."""
+    r1 = client.get("/notice/inbox/parent_001", headers=parent_headers)
+    assert r1.status_code == 200
+
+    r2 = client.get("/notice/inbox/parent_001", headers=parent2_headers)
+    assert r2.status_code == 403
+
+
+def test_inbox_requires_user_header(client):
+    """X-User-Id 헤더 없으면 422 (FastAPI Header 필수 검증)."""
+    r = client.get("/notice/inbox/parent_001")
+    assert r.status_code == 422
+
+
+def test_unknown_user_id_rejected(client):
+    """등록 안 된 ID로 헤더 → 401."""
+    r = client.get("/notice/inbox/parent_001", headers={"X-User-Id": "ghost_999"})
+    assert r.status_code == 401
+    assert "등록되지 않은 사용자" in r.json()["detail"]
+
+
+def test_send_then_receive_flow(client, teacher_headers, parent_headers):
+    """발송 후 학부모 수신함에 보임 (권한 흐름 통합 검증)."""
+    payload = {"teacher_id": "teacher_001", "parent_id": "parent_001", "text": "단위테스트 통신문"}
+    r1 = client.post("/notice/send", json=payload, headers=teacher_headers)
+    assert r1.status_code == 200
+    notice_id = r1.json()["data"]["notice_id"]
+    assert notice_id
+
+    r2 = client.get("/notice/inbox/parent_001", headers=parent_headers)
+    assert r2.status_code == 200
+    inbox = r2.json()["data"]
+    assert any(n["notice_id"] == notice_id for n in inbox)

backend/tests/test_card_builder.py

@@ -0,0 +1,57 @@
+"""card_builder 슬롯 카드 빌드 + dedup 단위 테스트."""
+from app.models.schemas import SlotCard
+from app.services.card_builder import _dedup_cards
+
+
+def _card(header: str, value: str, importance: float = 0.5) -> SlotCard:
+    return SlotCard(
+        header_ko=header,
+        header_translated=header,
+        value_ko=value,
+        value_easy_ko=value,
+        value_translated=value,
+        chip=None,
+        importance=importance,
+    )
+
+
+def test_dedup_removes_substring_within_same_header():
+    """같은 헤더 안에서 짧은 value가 긴 value 안에 들어있으면 짧은 것 제거 — 본문/표 영역 중복 흡수."""
+    cards = [
+        _card("운영방법", "온라인 사전예약 100명 선착순 5가지 체험 안전 복장", 0.99),
+        _card("운영방법", "온라인 사전예약 100명 선착순", 0.53),  # substring
+    ]
+    out = _dedup_cards(cards)
+    assert len(out) == 1
+    assert out[0].importance == 0.99  # 긴 쪽이 살아남음
+
+
+def test_dedup_keeps_different_headers():
+    """헤더가 다르면 손대지 않음 — 운영방법과 일시는 별개 슬롯."""
+    cards = [
+        _card("운영방법", "온라인 사전예약", 0.9),
+        _card("일시", "2026. 4. 18.(토)", 0.7),
+        _card("신청 URL", "http://example.com", 0.7),
+    ]
+    out = _dedup_cards(cards)
+    assert len(out) == 3
+
+
+def test_dedup_normalizes_pipe_and_colon_separators():
+    """`|`/`:` 구분자 차이로 substring 매칭 놓치는 것 방지 — 윤정님 기호 정제 전후 둘 다 호환."""
+    cards = [
+        _card("운영방법", "온라인 사전예약 100명 선착순", 0.99),
+        _card("운영방법", "온라인 | 사전예약 | 100명 선착순", 0.50),  # `|` 구분자만 다름
+    ]
+    out = _dedup_cards(cards)
+    assert len(out) == 1
+
+
+def test_dedup_keeps_distinct_values_under_same_header():
+    """같은 헤더라도 substring 관계 아니면 둘 다 유지 — 정보 손실 방지."""
+    cards = [
+        _card("기타", "물 지참", 0.8),
+        _card("기타", "음식물 반입 금지", 0.6),
+    ]
+    out = _dedup_cards(cards)
+    assert len(out) == 2

backend/tests/test_glossary.py

@@ -0,0 +1,74 @@
+"""다국어 용어사전 로딩 단위 테스트.
+
+세종 PR 리팩토링 반영(2026-04-28):
+- read_glossary(path)는 raw rows 반환 (target_lang 파라미터 제거)
+- 언어별 분기는 find_glossary_hits(text, glossary, lang)에서 처리
+- 반환 dict 키: preferred_vi → preferred_term (generic)
+"""
+import sys
+from pathlib import Path
+
+import pytest
+
+# run_mvp_pipeline.py 직접 import
+_TRANSLATION_DIR = Path("/app/external_model/translation_tts")
+if str(_TRANSLATION_DIR) not in sys.path:
+    sys.path.insert(0, str(_TRANSLATION_DIR))
+import run_mvp_pipeline as _sj  # noqa: E402
+
+GLOSSARY_PATH = _TRANSLATION_DIR / "term_glossary.csv"
+
+
+def test_glossary_loads_raw_rows():
+    """read_glossary(path)는 최소 144행 이상 raw rows를 반환한다."""
+    rows = _sj.read_glossary(GLOSSARY_PATH)
+    assert len(rows) >= 144
+    # 한국어 컬럼은 비어있지 않음
+    assert rows[0]["korean"]
+
+
+@pytest.mark.parametrize("lang", ["vi", "en", "zh", "th", "ja", "ru", "ms", "mn"])
+def test_glossary_each_language_column_filled(lang):
+    """각 언어 preferred_{lang} 컬럼이 모든 행에 채워져있다."""
+    rows = _sj.read_glossary(GLOSSARY_PATH)
+    column = f"preferred_{lang}"
+    filled = [r for r in rows if r.get(column, "").strip()]
+    assert len(filled) == len(rows), f"{lang}: {len(rows) - len(filled)}건 누락"
+
+
+def test_glossary_dosirak_mapping():
+    """대표 학교 도메인 단어 '도시락'이 언어별로 다른 권장어로 매핑된다."""
+    expected = {"vi": "cơm hộp", "en": "Lunch box", "zh": "便当", "ja": "お弁당"}
+    rows = _sj.read_glossary(GLOSSARY_PATH)
+    dosirak = next((r for r in rows if r["korean"] == "도시락"), None)
+    assert dosirak is not None, "'도시락' 누락"
+    for lang, want in expected.items():
+        # Note: ja 'お弁당' 표기 차이로 일본어는 startswith 비교
+        actual = dosirak.get(f"preferred_{lang}", "").strip()
+        if lang == "ja":
+            assert actual.startswith("お弁") or actual.startswith("弁当"), f"ja: {actual!r}"
+        else:
+            assert actual == want, f"{lang}: expected {want!r}, got {actual!r}"
+
+
+def test_find_glossary_hits_returns_target_language():
+    """find_glossary_hits이 target_lang 권장어를 preferred_term 키로 반환한다."""
+    glossary = _sj.read_glossary(GLOSSARY_PATH)
+    text = "아이는 도시락과 물병을 가져와 주세요."
+
+    en_hits = _sj.find_glossary_hits(text, glossary, "en")
+    en_dosirak = next((h for h in en_hits if h["korean"] == "도시락"), None)
+    assert en_dosirak is not None
+    assert en_dosirak["preferred_term"].lower() == "lunch box"
+
+    vi_hits = _sj.find_glossary_hits(text, glossary, "vi")
+    vi_dosirak = next((h for h in vi_hits if h["korean"] == "도시락"), None)
+    assert vi_dosirak is not None
+    assert vi_dosirak["preferred_term"] == "cơm hộp"
+
+
+def test_find_glossary_hits_empty_text():
+    """본문에 사전 용어가 없으면 빈 리스트 반환."""
+    glossary = _sj.read_glossary(GLOSSARY_PATH)
+    hits = _sj.find_glossary_hits("아무 학교 용어 없음", glossary, "vi")
+    assert hits == []

backend/tests/test_parser.py

@@ -0,0 +1,171 @@
+"""파서 단위 테스트.
+
+LibreOffice 호출은 mocking. PDF 추출은 pdfplumber에 의존하므로
+실 PDF 한 장은 monkeypatch 없이 검증해도 됨 (가벼움).
+"""
+from pathlib import Path
+
+import pytest
+
+from app.services.parser import (
+    ParserError,
+    normalize,
+    parse_bytes_to_text,
+)
+
+
+# ── normalize ─────────────────────────────────────────────────
+def test_normalize_strips_null_bytes():
+    assert "\x00" not in normalize("a\x00b\x00c")
+
+
+def test_normalize_collapses_inline_whitespace_but_keeps_newlines():
+    out = normalize("foo   bar\n\n\nbaz")
+    # 한 줄 안 다중 공백은 1개로
+    assert out == "foo bar\n\nbaz"
+
+
+def test_normalize_preserves_paragraph_breaks():
+    """줄바꿈은 보존 (윤정님 요구: '줄바꿈만 살리고')."""
+    src = "안녕하세요\n학부모님께\n\n알려드립니다"
+    assert normalize(src) == "안녕하세요\n학부모님께\n\n알려드립니다"
+
+
+def test_normalize_empty_returns_empty():
+    assert normalize("") == ""
+    assert normalize("   \n\n  ") == ""
+
+
+# ── parse_bytes_to_text — 평문 ────────────────────────────────
+def test_parse_text_passthrough():
+    raw = "통신문 본문\n\n오늘 안내드립니다".encode("utf-8")
+    assert parse_bytes_to_text(raw, "notice.txt") == "통신문 본문\n\n오늘 안내드립니다"
+
+
+def test_parse_no_extension_treated_as_text():
+    raw = "그냥 텍스트".encode("utf-8")
+    assert parse_bytes_to_text(raw, "noext") == "그냥 텍스트"
+
+
+def test_parse_empty_bytes_returns_empty():
+    assert parse_bytes_to_text(b"", "anything.txt") == ""
+
+
+def test_parse_unsupported_extension_raises():
+    with pytest.raises(ParserError):
+        parse_bytes_to_text(b"x", "image.heic")
+
+
+def test_parse_unknown_extension_rejected():
+    """알 수 없는 suffix는 화이트리스트(ALLOWED_EXTS)에서 거부."""
+    with pytest.raises(ParserError):
+        parse_bytes_to_text(b"x", "../../etc/passwd.exe")
+    with pytest.raises(ParserError):
+        parse_bytes_to_text(b"x", "weird.bin")
+
+
+def test_parse_filename_metachars_safe(monkeypatch):
+    """쉘 메타문자가 들어간 .hwp 파일명도 LibreOffice 호출에 안전.
+
+    원본 filename은 어떤 경로/명령에도 들어가지 않고 tempdir/input.hwp로만 저장.
+    subprocess 호출 시 list 인자 형태라 명령 주입 표면 자체가 없음.
+    """
+    captured_args = {}
+
+    def fake_run(cmd, **kwargs):
+        captured_args["cmd"] = cmd
+        # 메타문자 흔적이 cmd 어디에도 안 보임을 검증
+        for arg in cmd:
+            assert "rm" not in arg
+            assert ";" not in arg
+            assert "$(" not in arg
+        # 가짜 ODT 만들어서 변환 성공처럼
+        out_dir = Path(cmd[cmd.index("--outdir") + 1])
+        (out_dir / "input.odt").write_bytes(b"PK-fake-odt")
+
+        class Result:
+            returncode = 0
+            stderr = ""
+        return Result()
+
+    monkeypatch.setattr("app.services.parser.subprocess.run", fake_run)
+    monkeypatch.setattr(
+        "app.services.parser._odt_to_text",
+        lambda p: "ok",
+    )
+
+    parse_bytes_to_text(b"HWP-data", "$(rm -rf /).hwp")
+    # 명령 주입은커녕 원본 filename이 cmd에 등장조차 안 함
+    assert all("$(rm" not in arg for arg in captured_args["cmd"])
+
+
+def test_parse_libreoffice_timeout_raises_with_message(monkeypatch):
+    """타임아웃 발생 시 ParserError + 환경변수 안내 메시지."""
+    import subprocess as sp
+
+    def boom(*args, **kwargs):
+        raise sp.TimeoutExpired(cmd=args[0], timeout=kwargs.get("timeout", 0))
+
+    monkeypatch.setattr("app.services.parser.subprocess.run", boom)
+    with pytest.raises(ParserError) as exc:
+        parse_bytes_to_text(b"HWP", "x.hwp")
+    assert "타임아웃" in str(exc.value)
+    assert "PARSER_LIBREOFFICE_TIMEOUT" in str(exc.value)
+
+
+# ── parse_bytes_to_text — HWP (LibreOffice 모킹) ──────────────
+def test_parse_hwp_calls_libreoffice_and_odt_extractor(monkeypatch, tmp_path):
+    """HWP 입력 → LibreOffice ODT 변환 호출 + content.xml 추출 호출 확인."""
+    called = {}
+
+    def fake_hwp_to_odt(hwp_path: Path, out_dir: Path) -> Path:
+        called["hwp_path"] = hwp_path
+        called["out_dir"] = out_dir
+        fake_odt = out_dir / "fake.odt"
+        fake_odt.write_bytes(b"PK-fake-odt")
+        return fake_odt
+
+    def fake_odt_to_text(odt_path: Path) -> str:
+        called["odt_path"] = odt_path
+        return "본문 추출 결과"
+
+    monkeypatch.setattr("app.services.parser._hwp_to_odt", fake_hwp_to_odt)
+    monkeypatch.setattr("app.services.parser._odt_to_text", fake_odt_to_text)
+
+    out = parse_bytes_to_text(b"HWP-bytes", "안내.hwp")
+
+    assert out == "본문 추출 결과"
+    assert called["hwp_path"].suffix == ".hwp"
+    assert called["odt_path"].suffix == ".odt"
+
+
+def test_parse_pdf_calls_pdfplumber_only(monkeypatch):
+    """PDF 입력 → LibreOffice 우회, pdfplumber만 호출."""
+    called = {"hwp": False, "pdf": False}
+
+    def fake_hwp_to_odt(*args, **kwargs):
+        called["hwp"] = True
+        raise AssertionError("PDF 입력에선 LibreOffice가 호출되면 안 됨")
+
+    def fake_pdf_to_text(pdf_path: Path) -> str:
+        called["pdf"] = True
+        return "PDF 추출 결과"
+
+    monkeypatch.setattr("app.services.parser._hwp_to_odt", fake_hwp_to_odt)
+    monkeypatch.setattr("app.services.parser._pdf_to_text", fake_pdf_to_text)
+
+    out = parse_bytes_to_text(b"%PDF-1.4 fake", "doc.pdf")
+
+    assert out == "PDF 추출 결과"
+    assert called["pdf"] is True
+    assert called["hwp"] is False
+
+
+def test_parse_libreoffice_failure_raises_parser_error(monkeypatch):
+    def boom(*args, **kwargs):
+        raise ParserError("LibreOffice 변환 실패")
+
+    monkeypatch.setattr("app.services.parser._hwp_to_odt", boom)
+
+    with pytest.raises(ParserError):
+        parse_bytes_to_text(b"HWP", "x.hwp")

backend/tests/test_slot_extractor.py

@@ -0,0 +1,232 @@
+"""슬롯 추출기 단위 테스트.
+
+강사 처방(2026-04-28): 날짜·시간·금액은 정규식으로 1차 안전 추출.
+이 테스트가 통과한다는 건 LLM 없이도 핵심 수치 데이터가 확보된다는 자동 증명.
+"""
+from app.services.slot_extractor import (
+    extract_amounts,
+    extract_dates,
+    extract_phones,
+    extract_summary_regex_slots,
+    extract_times,
+    extract_urls,
+    find_amount_in_text,
+    find_deadline_in_text,
+    find_when_in_text,
+    format_amount,
+    format_date,
+    format_time,
+    split_supply_tokens,
+    strip_markers,
+)
+
+
+# ── 날짜 ─────────────────────────────────────────────────────────
+def test_extract_dates_full_with_year_and_weekday():
+    result = extract_dates("2026년 5월 14일(수) 출발")
+    assert len(result) == 1
+    d = result[0]
+    assert d["year"] == 2026
+    assert d["month"] == 5
+    assert d["day"] == 14
+    assert d["weekday"] == "수"
+
+
+def test_extract_dates_md_only():
+    result = extract_dates("5월 9일(금)까지 제출")
+    assert len(result) == 1
+    d = result[0]
+    assert d["year"] is None
+    assert d["month"] == 5
+    assert d["day"] == 9
+    assert d["weekday"] == "금"
+
+
+def test_extract_dates_relative_words():
+    result = extract_dates("내일까지 동의서를 제출하세요")
+    assert any(d.get("relative") == "내일" for d in result)
+
+
+def test_extract_dates_dedups_surface():
+    result = extract_dates("5월 9일(금)까지 납부, 5월 9일(금)까지 제출")
+    # 동일 표면형은 1개로
+    surfaces = [d["ko"] for d in result]
+    assert surfaces.count("5월 9일(금)") == 1
+
+
+# ── 시간 ─────────────────────────────────────────────────────────
+def test_extract_times_ampm():
+    result = extract_times("오전 9시 출발")
+    assert len(result) == 1
+    assert result[0]["hour"] == 9
+    assert result[0]["ampm"] == "오전"
+
+
+def test_extract_times_with_minute():
+    result = extract_times("오후 2시 30분")
+    assert result[0]["hour"] == 2
+    assert result[0]["minute"] == 30
+
+
+def test_extract_times_24h():
+    result = extract_times("회의 14:30 시작")
+    assert result[0]["hour"] == 14
+    assert result[0]["minute"] == 30
+
+
+# ── 금액 ─────────────────────────────────────────────────────────
+def test_extract_amounts_with_comma():
+    result = extract_amounts("참가비 15,000원")
+    assert result[0]["value"] == 15000
+    assert result[0]["ko"] == "15,000원"
+
+
+def test_extract_amounts_korean_unit():
+    result = extract_amounts("5천원만 가져오세요")
+    assert any(a["value"] == 5000 for a in result)
+
+
+def test_extract_amounts_no_match():
+    assert extract_amounts("그냥 평범한 통신문") == []
+
+
+# ── 베트남어 포매터 ──────────────────────────────────────────────
+def test_format_date_vi_with_year_weekday():
+    d = {"ko": "2026년 5월 14일(수)", "year": 2026, "month": 5, "day": 14, "weekday": "수"}
+    assert format_date(d, "vi") == "Ngày 14/5/2026 (Thứ Tư)"
+
+
+def test_format_date_vi_md_only():
+    d = {"ko": "5월 9일(금)", "year": None, "month": 5, "day": 9, "weekday": "금"}
+    assert format_date(d, "vi") == "Ngày 9/5 (Thứ Sáu)"
+
+
+def test_format_date_vi_relative():
+    d = {"ko": "내일", "year": None, "month": None, "day": None,
+         "weekday": None, "relative": "내일"}
+    assert format_date(d, "vi") == "Ngày mai"
+
+
+def test_format_time_vi_morning():
+    t = {"ko": "오전 9시", "hour": 9, "minute": 0, "ampm": "오전"}
+    assert format_time(t, "vi") == "9 giờ sáng"
+
+
+def test_format_amount_vi():
+    a = {"ko": "15,000원", "value": 15000, "currency": "KRW"}
+    assert format_amount(a, "vi") == "15,000 won"
+
+
+# ── 영어 포매터 (보조 시연용) ────────────────────────────────────
+def test_format_date_en():
+    d = {"ko": "5월 14일(수)", "year": None, "month": 5, "day": 14, "weekday": "수"}
+    assert format_date(d, "en") == "May 14 (Wed)"
+
+
+# ── URL / 전화 ───────────────────────────────────────────────────
+def test_extract_urls_http_https_www():
+    text = "신청은 https://example.kr/apply 에서, 자세한 내용은 www.school.go.kr 참조."
+    urls = extract_urls(text)
+    assert "https://example.kr/apply" in urls
+    assert "www.school.go.kr" in urls
+
+
+def test_extract_urls_dedupes():
+    text = "http://a.com 안내 http://a.com 재공지"
+    urls = extract_urls(text)
+    assert urls.count("http://a.com") == 1
+
+
+def test_extract_phones_dash_formats():
+    text = "교무실 02-2649-7232, 학교 849-7003, 신고 1588-0260, 휴대폰 010-1234-5678"
+    phones = extract_phones(text)
+    assert "02-2649-7232" in phones
+    assert "849-7003" in phones
+    assert "1588-0260" in phones
+    assert "010-1234-5678" in phones
+
+
+def test_extract_phones_does_not_match_amount_with_comma():
+    """'15,000원' 같은 숫자에서 전화번호가 잘못 잡히면 안 됨."""
+    text = "참가비 15,000원, 문의 02-1234-5678"
+    phones = extract_phones(text)
+    assert "02-1234-5678" in phones
+    assert not any(p.startswith("15") or p.startswith("000") for p in phones)
+
+
+# ── 통합 진입점 ──────────────────────────────────────────────────
+def test_extract_summary_regex_slots_full_flow():
+    text = "5월 14일(수) 오전 9시 출발. 참가비 15,000원."
+    out = extract_summary_regex_slots(text, "vi")
+    assert any(d["ko"] == "5월 14일(수)" for d in out["dates"])
+    assert all(d["source"] == "regex" for d in out["dates"])
+    assert any(t["ko"] == "오전 9시" for t in out["times"])
+    assert any(a["ko"] == "15,000원" for a in out["amounts"])
+
+
+def test_extract_summary_regex_slots_includes_urls_and_phones():
+    """summary 슬롯에 urls/phones가 ko 그대로 통과 (NLLB 안 거침)."""
+    text = "신청 https://apply.school.kr 문의 02-2649-7232"
+    out = extract_summary_regex_slots(text, "vi")
+    assert any(u["ko"] == "https://apply.school.kr" for u in out["urls"])
+    assert any(p["ko"] == "02-2649-7232" for p in out["phones"])
+    # 보호: translated가 ko와 동일해야 한다
+    for slot in out["urls"] + out["phones"]:
+        assert slot["translated"] == slot["ko"]
+        assert slot["source"] == "regex"
+
+
+def test_find_when_combines_date_and_time():
+    when = find_when_in_text("5월 14일(수) 오전 9시 출발", "vi")
+    assert "Ngày 14/5" in when
+    assert "9 giờ sáng" in when
+
+
+def test_find_amount_returns_korean_surface():
+    assert find_amount_in_text("참가비 15,000원", "vi") == "15,000원"
+
+
+def test_find_deadline_phrase_with_까지():
+    assert "5월 9일(금)까지" in find_deadline_in_text("5월 9일(금)까지 제출")
+
+
+def test_find_deadline_not_broken_by_number_comma():
+    """`15,000원 (...까지...)` 의 콤마에서 잘려서 '000원...'만 잡히던 회귀 방지."""
+    text = "참가비: 15,000원 (5월 9일(금)까지 스쿨뱅킹으로 납부)"
+    result = find_deadline_in_text(text)
+    assert result is not None
+    assert "5월 9일" in result
+    assert not result.lstrip().startswith("000")
+
+
+# ── 마크업 strip ────────────────────────────────────────────────
+def test_strip_markers_leading_bullet():
+    assert strip_markers("■ 준비물: 도시락") == "준비물: 도시락"
+
+
+def test_strip_markers_multiple_chars():
+    assert strip_markers("▶▸ 안내사항") == "안내사항"
+
+
+def test_strip_markers_preserves_inside():
+    """문장 내부의 기호는 보존 (시작 부분만 제거)."""
+    assert strip_markers("■ 5월 14일 - 출발") == "5월 14일 - 출발"
+
+
+def test_strip_markers_no_op_when_clean():
+    assert strip_markers("도시락을 준비하세요") == "도시락을 준비하세요"
+
+
+# ── 준비물 토큰 분해 ─────────────────────────────────────────────
+def test_split_supply_tokens_comma_separated():
+    tokens = split_supply_tokens("도시락, 물통, 돗자리, 편한 운동화, 여벌 옷")
+    assert "도시락" in tokens
+    assert "물통" in tokens
+    assert "돗자리" in tokens
+    assert "편한 운동화" in tokens
+
+
+def test_split_supply_tokens_strips_prefix():
+    tokens = split_supply_tokens("준비물: 도시락, 물병을 준비해 주세요")
+    assert "도시락" in tokens
+    assert "물병" in tokens

backend/tests/test_translator_protection.py

@@ -0,0 +1,119 @@
+"""URL/전화 placeholder 보호 단위 테스트.
+
+NLLB 호출 자체는 모킹해서 마스킹 → 번역 → 복원 사이클만 검증.
+실제 NLLB 모델은 무거우므로 _translate를 monkeypatch.
+"""
+import pytest
+
+from app.services.translator import (
+    _is_url_or_phone,
+    _mask_protected_entities,
+    _restore_protected_entities,
+    translate_short_sentence,
+    translate_term,
+)
+
+
+# ── 마스킹 / 복원 단위 ─────────────────────────────────────────
+def test_mask_url_replaces_with_token():
+    masked, holders = _mask_protected_entities("신청은 https://apply.kr 에서")
+    assert "https://apply.kr" not in masked
+    assert "⟦P0⟧" in masked
+    assert holders == ["https://apply.kr"]
+
+
+def test_mask_phone_replaces_with_token():
+    masked, holders = _mask_protected_entities("문의 02-2649-7232")
+    assert "02-2649-7232" not in masked
+    assert "⟦P0⟧" in masked
+    assert holders == ["02-2649-7232"]
+
+
+def test_mask_url_and_phone_separate_tokens():
+    masked, holders = _mask_protected_entities(
+        "https://a.com 문의 02-1234-5678"
+    )
+    # 두 엔티티 각각 다른 인덱스
+    assert "⟦P0⟧" in masked and "⟦P1⟧" in masked
+    assert set(holders) == {"https://a.com", "02-1234-5678"}
+
+
+def test_mask_no_entities_returns_text_unchanged():
+    masked, holders = _mask_protected_entities("그냥 평범한 통신문")
+    assert masked == "그냥 평범한 통신문"
+    assert holders == []
+
+
+def test_restore_returns_original_entities():
+    masked, holders = _mask_protected_entities("문의 02-2649-7232")
+    restored = _restore_protected_entities(masked, holders)
+    assert restored == "문의 02-2649-7232"
+
+
+def test_restore_with_translated_token_intact():
+    """NLLB 번역 결과에도 토큰이 살아남으면 복원 가능."""
+    holders = ["02-2649-7232"]
+    fake_translated = "Liên hệ ⟦P0⟧"
+    assert _restore_protected_entities(fake_translated, holders) == "Liên hệ 02-2649-7232"
+
+
+# ── 슬롯 단위 가드 ────────────────────────────────────────────
+def test_is_url_or_phone_true_for_url():
+    assert _is_url_or_phone("https://example.kr/path")
+    assert _is_url_or_phone("www.school.go.kr")
+
+
+def test_is_url_or_phone_true_for_phone():
+    assert _is_url_or_phone("02-2649-7232")
+    assert _is_url_or_phone("1588-0260")
+
+
+def test_is_url_or_phone_false_for_normal_text():
+    assert not _is_url_or_phone("도시락")
+    assert not _is_url_or_phone("5월 14일")
+
+
+def test_translate_term_passthrough_for_url_phone(monkeypatch):
+    """URL/전화는 어떤 언어든 번역 안 거치고 ko 그대로."""
+    # glossary 호출이 일어나면 안 됨 (URL/전화 가드가 그 위에서 차단)
+    called = []
+    monkeypatch.setattr(
+        "app.services.translator._get_glossary",
+        lambda: called.append("glossary") or [],
+    )
+    assert translate_term("https://apply.kr", "vi") == "https://apply.kr"
+    assert translate_term("02-2649-7232", "en") == "02-2649-7232"
+    assert called == []
+
+
+# ── translate_short_sentence E2E (NLLB 모킹) ──────────────────
+def test_translate_short_sentence_protects_url_through_nllb(monkeypatch):
+    """URL이 NLLB 호출 후에도 원래 문자열로 복원돼야 한다."""
+    captured_input = []
+
+    def fake_translate(text, target_nllb="vie_Latn", max_length=512):
+        captured_input.append(text)
+        # NLLB는 마스킹된 토큰을 그대로 통과시킨다고 가정 (실제로도 ⟦…⟧ 안 깸)
+        return text.replace("문의", "Liên hệ").replace("신청은", "Đăng ký")
+
+    monkeypatch.setattr("app.services.translator._translate", fake_translate)
+    monkeypatch.setattr("app.services.translator._get_glossary", lambda: [])
+    monkeypatch.setattr(
+        "app.services.translator._sejong.find_glossary_hits",
+        lambda text, glossary, lang: [],
+    )
+
+    out = translate_short_sentence(
+        "신청은 https://apply.kr 에서, 문의 02-2649-7232",
+        "vi",
+    )
+
+    # 1) NLLB에 들어간 입력엔 URL/전화가 토큰으로 마스킹됨
+    assert "https://apply.kr" not in captured_input[0]
+    assert "02-2649-7232" not in captured_input[0]
+    assert "⟦P0⟧" in captured_input[0]
+
+    # 2) 최종 출력엔 URL/전화가 원래 문자열로 복원됨
+    assert "https://apply.kr" in out
+    assert "02-2649-7232" in out
+    assert "⟦P" not in out

docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./backend:/app
+      - ./scripts:/app/scripts
+      - ./data:/app/external_data
+      - ./model:/app/external_model
+      - hf_cache:/root/.cache/huggingface
+    env_file:
+      - ./backend/.env
+    dns:
+      - 8.8.8.8
+      - 1.1.1.1
+    # LibreOffice ODT 변환 후 H2Orestart cleanup 버그로 segfault 발생.
+    # 코어 덤프 비활성화 (RLIMIT_CORE=0) — wsl-crashes 누적 → 디스크 마비 방지.
+    ulimits:
+      core: 0
+    restart: unless-stopped
+
+volumes:
+  hf_cache:

model/classification/README.md

@@ -0,0 +1,213 @@
+전체 파이프라인 (확정 버전)
+
+┌──────────────────────────────────────────────────────────────────┐
+│ 호스트 앱 → POST /notice/analyze                                  │
+│   body: HWP/PDF (multipart) or text (json)                        │
+└──────────────────────────────────────────────────────────────────┘
+            ↓
+[1] 텍스트 변환  (services/parser.py — 신설)
+    · text     → passthrough
+    · PDF      → pdfplumber + table 분리
+    · HWP/HWPX → LibreOffice + pdfplumber
+    · 이미지   → 세종님 OCR (연휴 후 합류)
+    → output: clean_text (str)
+
+            ↓
+[2] 정규식 슬롯 추출  (services/slot_extractor.py — 이미 구현)
+    · dates / times / amounts (이미 있음)
+    · urls / phones (NEW — 추가 필요)
+    · 통신문 전체 단위. summary용 재료.
+    → output: regex_slots (dict)
+
+            ↓
+[3] 할일 추출  (services/extractor.py — 윤정님 v2 wrapper)
+    입력:  clean_text
+    내부:  문장분리 → binary 분류(0.5컷) → 정규식(due_date/amount/action_hint)
+    출력:  list[YunjeongTodo]
+           각 항목: { text, source, due_date, amount,
+                     confidence, action_hint }
+    빈 리스트면 items 없음.
+
+            ↓
+[4] 카테고리 분류  (services/classifier.py — 경이님 6-class wrapper)
+    입력:  각 todo.text
+    출력:  category ∈ {일정, 준비물, 제출, 비용, 건강·안전, 기타}
+
+            ↓
+[5] 번역  (services/translator.py — 이미 구현, 보강 필요)
+    슬롯 단위:
+      · dates/times/amounts → i18n formatter (deterministic, NLLB 안 거침)
+      · urls/phones        → ko 그대로 (NEW)
+      · places/supplies    → glossary lookup → 없으면 NLLB
+    본문 단위 (todo.text):
+      · URL/전화 ⟦P0⟧ 토큰 치환 → NLLB → 토큰 복원 (NEW, 보호)
+      · glossary injection → NLLB
+
+            ↓
+[6] 응답 빌드  (routers/notice.py)
+    summary = SummarySlots(
+        dates, times, amounts, urls, phones,    # 정규식
+        places, supplies, deadlines              # items에서 집계
+    )
+    items = [
+        AnalyzeItem(
+            text_ko        = todo.text,
+            title_translated = ...번역...,
+            category       = 경이(todo.text),    # 주제 (6-class)
+            action_hint    = todo.action_hint,   # 행동 (신청/제출/...)
+            due_date       = todo.due_date,
+            amount         = todo.amount,
+            importance     = todo.confidence,
+            ...
+        )
+        for todo in yunjeong_todos
+    ]
+
+            ↓
+[7] TTS  (services/tts.py — 이미 구현)
+    슬롯 + 할일 합쳐 문장별 mp3 생성.
+    importance 내림차순 정렬.
+
+            ↓
+JSON 응답 → 호스트 앱
+{
+    "summary": SummarySlots,
+    "items":   [AnalyzeItem, ...],
+    "tts_url": "...",
+    ...
+}
+
+
+### 카테고리 분류-경이님
+
+`일정`, `준비물`, `제출`, `비용`, `건강·안전`, `기타`
+
+
+# 가장 중요한 핵심과제: 모델 성능 비교 (베이스라인 VS. 파인튜닝)
+1. 조건: 베이스라인 모델, 파인튜닝한 모델에 들어가는 input data가 동일한 데이터셋 및 동일한 조건에서 두 모델의 성능을 비교. 다시 말해서, 기존에 있던 모델을 가지고 동일한 조건을 맞춰서 일정, 준비물, 제출, 비용, 건강·안전, 기타에 대한 분류 성능 점수가 나와야하고 파인튜닝한 모델을 동일한 조건으로 6가지 분류 성능 점수가 나와야 비교가 가능. 그래서 파인튜닝된 모델이 베이스라인모델보다 성능이 좋다라는 지표가 나와야 성능의 우수함을 입증할 수 있음. 근거 자료를 만들어야 함. 
+
+2. 두 모델(베이스라인 모델, 파인튜닝한 모델)에 들어가는 데이터는 답안지가 없기 때문에 accuracy가 아닌 그 모델의 맞는 평가 방식 및 성능 지표를 뽑아야 함. 사용하고자 하는 모델들의 기능을 자세한 설명 듣기.
+
+예시로, Precision이라고 하면 10개 단어 중에 2개 단어만 맞췄다. 그래서 그 모델로 해서 모든 텍스트 데이터 돌아서 몇 프로 맞췄으니까 얘는 성능이 얼마다 라고 얘기하는 것도 있다.
+
+==> 파인튜닝의 성능이 베이스라인 성능보다 좋은 쪽으로 모델이 나와야하고 그 모델에 맞는 평가 지표가 나와야 한다. 글씨로 정리하는 것 뿐만아니라 시각적인 도구를 활용해서 그래프 혹은 직선 사용 등으로 제시할 근거 자료가 필요.
+
+
+# 윤정님 데이터 정보들
+
+-원본 데이터 : \data\galsan_txt 
+-전처리 파일 : file/preprocess_txt_to_jsonl.py
+-���처리 후 데이터 : data/v2.1_notices_galsan.jsonl
+
+-윤정님이 전처리 후 데이터로 모델 학습 시켰고 실 서비스에서
+데이터 넣고 나오는 아웃풋을 보려면 predict.py를 돌려봐야
+하고 그 predict.py의 아웃풋이 경이님 모델로 들어감. 
+
+-predict.py를 경이님 모델의 인풋으로 해서 넣어야 함.
+results.append({
+            "text":        sentence,
+            "source":      source,
+            "due_date":    extract_due_date(sentence),
+            "amount":      extract_amount(sentence),
+            "confidence":  round(confidence, 4),
+            "action_hint": extract_action_hint(sentence),
+        })
+[
+  {
+    "text": "모국어를 사용하는 강사가 단계별로 친절히 가르치는 동영상 강의(VOD)를 PC나 모바일 기기로 접속하여 언제든지 원하는 장소에서 편리하게 학습할 수 있는 좋은 기회이오니, 한국어 학습이 필요한 다문화가정 학생 및 학부모(보호자) 모두 기한 내 신청하여 주시기 바랍니다.",
+    "source": "sample_pdfplumber.txt",
+    "due_date": null,
+    "amount": null,
+    "confidence": 0.9946,
+    "action_hint": "신청"
+  }
+]
+
+# 추천된 모델 및 기술 스택
+
+추천1. KcELECTRA fine-tune
+
+이유:
+1. 데이터 양 충분 (700~1400 sentence) — KcELECTRA fine-tune 권장 sweet spot
+2. 학교 도메인 어휘 OOV 문제 해결 (subword tokenization)
+3. 윤정님 base 모델과 같은 koelectra-small ─ backbone 공유 가능
+   → 백엔드 RAM 중복 로드 회피 (둘 다 base는 같고 head만 다름)
+4. CPU 추론 가능 (small 변형이라 ~50ms/문장)
+5. 윤정님이 이미 같은 모델로 학습 환경 셋업 완료 — 학습 코드 재활용
+메모리 효율 트릭
+
+두 모델이 같은 backbone 공유하면 RAM 중복 0
+shared_encoder = AutoModel.from_pretrained("monologg/koelectra-small-v3-discriminator")
+
+윤정_head = BinaryHead(shared_encoder)        # 할일 추출 (binary)
+경이_head = MulticlassHead(shared_encoder, 6)  # 카테고리 (6-class)
+이렇게 짜면 경이 모델 추가에 따른 RAM 증가가 head만큼(~수MB)으로 줄어듦. 이상적.
+
+단계적 권장안
+
+1주차: 경이님이 KcELECTRA fine-tune 시도
+   
+데이터: notice_sample_v3.csv + notices_galsan.jsonl 라벨 부분
+GPU: Colab T4 무료로 충분 (~20분 학습)
+검증: 갈산초 holdout F1 + cross-validation
+
+2주차: 정확도 비교
+   
+simple (현재) vs KcELECTRA fine-tune
+5%+ F1 향상 → KcELECTRA 채택, 그 미만 → simple 유지
+simple은 항상 fallback으로 유지
+
+3주차: 시연 통합
+   
+더 좋은 쪽으로 교체
+선생님께 학습 코드/모델 공유로 재현성 보장
+주의
+시연 4주 임박이라 무리하면 안 됨:
+
+KcELECTRA fine-tune 학습 자체는 빠르지만 검증 + 디버깅 시간 필요
+simple v1이 이미 75% 정확도라 시연 박살 안 남
+실패하면 simple 그대로 — 백업 명확히
+경이님 부담:
+
+학습 환경 셋업 (윤정님 코드 빌려쓰기로 부담 경감)
+라벨 데이터 정제 (현재 v3.csv 라벨 품질 확인)
+검증셋 분리 (갈산초 holdout)
+한 줄 요약
+데이터 충분 → KcELECTRA fine-tune 시도가 정답. 다만 simple v1을 fallback으로 항상 유지. 윤정님 backbone 공유하면 RAM 효율 + 학습 환경 재활용 가능.
+
+경이님이 비교 실험 의지 있는 건 좋음. 다만 제대로 비교해야 가치 있고, 시연 4주 안 압박도 있으니 셋업이 중요.
+
+# 비교 실험 설계 가이드
+1. 후보 모델 선정 (3~4개가 최대)
+모델                              카테고리           학습 시간       강점               
+TF-IDF + LogReg                베이스라인 (필수)       수초          빠름              
+SBERT + LightGBM                임베딩 ML             분         의미 유사도           
+KcELECTRA-small fine-tune      한국어 BERT          20~30분      도메인 학습          
+KoBERT fine-tune               한국어 BERT          20~30분      한국어 특화  
+
+→ 3개 권장: TF-IDF (baseline) + SBERT + KcELECTRA. 4개는 시간 박살.
+
+2. 공정 비교를 위한 절대 규칙
+(a) 동일 train/val/test 분할 강제
+
+scripts/split_dataset.py 만들어서 ONE TIME 실행:
+random.seed(42)  # 무조건 고정
+labels = stratified_split(data, train=0.8, val=0.1, test=0.1)
+
+split_v1.csv 라는 단일 파일로 저장 → 모든 모델이 같은 분할 사용
+
+(b) Metric 통일
+
+Macro F1 (메인) — 클래스 불균형 대비
+Per-class F1 — "비용은 잘 잡는데 건강·안전은 못 잡는다" 같은 진단
+Confusion matrix — 어디서 헷갈리는지 시각화
+
+(c) Seed 고정 — numpy, torch, random 모두 42
+
+추천2.  모델: klue/roberta-base
+
+KoELECTRA(A단계)와 겹치지 않고, KLUE 벤치마크에서 한국어 분류 SOTA. 
+파인튜닝이 안정적이고 허깅페이스에서 바로 쓸 수 있음.
+
+
+

model/classification/README2.md

@@ -0,0 +1,284 @@
+# 카테고리 분류 모델 — 경이님 작업 가이드
+
+> 이 문서는 경이님이 작업 내용을 빠르게 이해하고 바로 실행할 수 있도록 작성되었습니다.  
+> 코드가 **왜** 이렇게 짜여졌는지, **무엇**을 하는지 중심으로 설명합니다.
+
+---
+
+## 전체 구조 한눈에 보기
+
+```
+model/classification/
+├── data/
+│   ├── notice_sample_v3.csv        ← 경이님이 라벨링한 학습 데이터 (150개)
+│   └── split_v1.csv                ← train/val/test 분할 (scripts 실행 후 생성됨)
+├── src/
+│   ├── predict.py                  ← 백엔드 진입점 (이게 핵심!)
+│   ├── classifier_simple.py        ← 베이스라인 모델 (TF-IDF + LogReg)
+│   └── classifier_kcelectra.py     ← KcELECTRA 추론 모듈
+├── scripts/
+│   ├── split_dataset.py            ← 데이터 분할 (딱 한 번만 실행)
+│   └── evaluate_compare.py         ← 두 모델 성능 비교
+├── notebooks/
+│   ├── 01_train_kcelectra.ipynb    ← GPU 학습 (Colab에서 실행)
+│   └── 02_evaluate_compare.ipynb   ← 성능 비교 시각화
+├── checkpoints/
+│   ├── simple_tfidf_logreg.pkl     ← 베이스라인 모델 저장 파일 (학습 후 생성)
+│   └── kcelectra-category/         ← KcELECTRA 파인튜닝 결과 (Colab 후 복사)
+└── README2.md                      ← 지금 이 파일
+```
+
+---
+
+## 파이프라인에서 경이님 역할
+
+전체 가정통신문 분석 시스템에서 경이님 모델은 **[4]번 단계**를 담당합니다.
+
+```
+[3] 윤정님 모델 (할일 추출)
+        ↓
+       text: "체험학습 비용 20,000원을 납부해 주세요."
+             ↓
+[4] 경이님 모델 (카테고리 분류)  ← 여기!
+        ↓
+    category: "비용"
+        ↓
+[5] 번역 → [6] 응답 빌드 → [7] TTS
+```
+
+**윤정님이 추출한 문장들이 경이님 모델로 들어오고**, 경이님 모델이 각 문장을 6개 카테고리 중 하나로 분류합니다.
+
+---
+
+## 6가지 카테고리 설명
+
+| 카테고리 | 의미 | 예시 |
+|--------|------|------|
+| **일정** | 날짜·시간·행사 관련 | "운동회는 10월 5일 오전 9시에..." |
+| **준비물** | 챙겨야 할 물건 | "도시락과 물을 준비해 주세요." |
+| **제출** | 서류·동의서 제출 | "동의서를 담임선생님께 제출해 주세요." |
+| **비용** | 금액·납부 관련 | "급식비 65,000원을 납부해 주세요." |
+| **건강·안전** | 건강·안전 지침 | "발열 증상 시 등교를 자제해 주세요." |
+| **기타** | 위에 해당 없음 | "궁금한 사항은 담임선생님께 문의..." |
+
+---
+
+## 백엔드 연결 구조 이해하기
+
+백엔드 `backend/app/services/classifier.py`가 이렇게 호출합니다:
+
+```python
+from src.predict import predict_one
+result = predict_one("납부할 급식비는 6만 5천원입니다.", model="simple")
+# → {"category": "비용", "confidence": 0.87, "model_used": "simple"}
+```
+
+`predict.py`의 `predict_one()`이 **모든 모델의 단일 창구**입니다.  
+`model="simple"` → TF-IDF+LogReg 사용  
+`model="kcelectra"` → KcELECTRA 파인튜닝 모델 사용  
+`model="auto"` → KcELECTRA 체크포인트 있으면 사용, 없으면 simple로 자동 전환
+
+---
+
+## 파일별 역할 상세 설명
+
+### `data/notice_sample_v3.csv`
+학습 데이터 파일입니다. 컬럼 2개 (`text`, `category`).
+
+- 150개의 문장이 미리 라벨링 되어 있습니다
+- 각 카테고리당 약 20~25개씩 균등하게 구성
+- **더 많은 데이터를 추가할수록 모델 성능이 향상됩니다**
+  - 형식: `문장,카테고리` (맨 아래에 행 추가)
+  - 카테고리는 반드시 `일정`, `준비물`, `제출`, `비용`, `건강·안전`, `기타` 중 하나
+
+### `src/classifier_simple.py` — 베이스라인 (TF-IDF + Logistic Regression)
+
+**왜 TF-IDF인가?**
+- TF-IDF는 각 단어가 문서에서 얼마나 중요한지 숫자로 나타냅니다
+- "납부", "입금", "원" 같은 단어가 **비용** 카테고리에서 많이 나오면 높은 점수를 받음
+- GPU 없이 CPU에서 수십 ms만에 실행 — 백엔드 서버 부담 없음
+
+**왜 char_wb n-gram인가?**
+- 한국어는 "납부해" "납부하여" "납부하시기" 등 동사 변형이 많음
+- 글자 단위 2~4글자 조합(`ngram_range=(2,4)`)으로 형태소 변형 문제 해결
+- 예: "납부" → "납부", "부하", "부해", "납부하" 등으로 분해해 학습
+
+**사용법:**
+```bash
+cd model/classification
+python src/classifier_simple.py          # 학습 + 저장
+python src/classifier_simple.py --eval   # 테스트 평가
+```
+
+### `src/classifier_kcelectra.py` — KcELECTRA 추론 모듈
+
+**왜 KcELECTRA인가?**
+- 한국어 특화 사전학습 모델 (윤정님 모델과 동일한 backbone!)
+- ELECTRA 구조: BERT보다 학습 효율이 2~3배 좋음
+- `koelectra-small`: 메��리 사용량 적어 CPU 서버에서도 동작
+
+**중요:** 이 파일은 **추론만** 합니다. 학습은 `notebooks/01_train_kcelectra.ipynb`에서.
+
+학습이 끝나면 `checkpoints/kcelectra-category/` 폴더가 생깁니다.
+이 폴더가 없으면 `is_ready()` 함수가 False를 반환하여 simple로 자동 전환됩니다.
+
+### `src/predict.py` — 백엔드 진입점
+
+**왜 이 파일이 중요한가?**
+- 백엔드가 `from src.predict import predict_one`으로 이 함수를 호출
+- 내부에서 어떤 모델을 쓸지 결정하는 로직 포함
+- `model="auto"`로 설정하면 체크포인트 유무에 따라 자동 선택
+
+**반환 형식:**
+```python
+{
+    "text":       "납부할 급식비는 6만 5천원입니다.",
+    "category":   "비용",       # 최종 분류 결과
+    "confidence": 0.87,         # 얼마나 확신하는지 (0~1)
+    "model_used": "simple",     # 실제 사용된 모델
+    "probs": {                  # explain=True일 때만 포함
+        "일정": 0.02,
+        "비용": 0.87,
+        ...
+    }
+}
+```
+
+### `scripts/split_dataset.py` — 데이터 분할
+
+**왜 딱 한 번만 실행해야 하는가?**
+- 베이스라인과 KcELECTRA가 **완전히 동일한** 데이터로 학습/평가해야 공정한 비교 가능
+- 한 번 분할하면 `split_v1.csv`에 고정 저장
+- 랜덤 시드 42로 고정 → 언제 실행해도 같은 결과
+
+```bash
+python scripts/split_dataset.py         # 최초 1회 실행
+python scripts/split_dataset.py --force # 강제 재생성 (비추천)
+```
+
+분할 비율: **Train 80% / Val 10% / Test 10%**  
+Stratified Split: 각 카테고리에서 균등하게 뽑음
+
+### `scripts/evaluate_compare.py` — 성능 비교
+
+두 모델을 같은 test 데이터로 평가하고 결과를 저장합니다.
+
+```bash
+python scripts/evaluate_compare.py
+```
+
+생성 파일:
+- `data/eval_results_simple.json` — 베이스라인 상세 결과
+- `data/eval_results_kcelectra.json` — KcELECTRA 상세 결과
+- `data/eval_comparison_summary.csv` — 두 모델 비교 요약
+
+---
+
+## 실행 순서 (처음부터 전부 하려면)
+
+### Step 1. 데이터 분할 (딱 한 번)
+```bash
+cd c:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification
+python scripts/split_dataset.py
+```
+
+### Step 2. 베이스라인 학습
+```bash
+python src/classifier_simple.py
+```
+`checkpoints/simple_tfidf_logreg.pkl` 파일이 생성됩니다.
+
+### Step 3. KcELECTRA 파인튜닝 (Colab GPU 필요)
+1. Google Colab 접속 → 런타임 → 런타임 유형 변경 → **GPU**
+2. `notebooks/01_train_kcelectra.ipynb` 업로드
+3. `data/notice_sample_v3.csv`와 `data/split_v1.csv` 업로드
+4. 모든 셀 순서대로 실행 (~20분)
+5. `checkpoints/kcelectra-category/` 폴더 다운로드
+6. 로컬 `checkpoints/kcelectra-category/`에 붙여넣기
+
+### Step 4. 성능 비교
+```bash
+python scripts/evaluate_compare.py
+```
+
+### Step 5. 시각화 확인
+Jupyter에서 `notebooks/02_evaluate_compare.ipynb` 열어서 실행.
+
+---
+
+## 평가 지표 설명
+
+### Macro F1 (메인 지표)
+- 6개 카테고리 각각의 F1을 구한 뒤 **평균**
+- 클래스 불균형에 강함 (특정 클래스가 많아도 편향 없음)
+- **0.8 이상이면 좋은 성능**
+
+### F1 Score = 2 × (Precision × Recall) / (Precision + Recall)
+- **Precision (정밀도):** "비용이라고 예측한 것 중 실제로 비용인 비율"
+- **Recall (재현율):** "실제 비용인 것 중 비용이라고 맞춘 비율"
+- F1은 이 둘의 균형
+
+### Confusion Matrix
+행 = 실제 카테고리, 열 = 예측 카테고리  
+대각선이 클수록 좋음 (맞게 분류한 것들)
+
+---
+
+## KcELECTRA 채택 기준
+
+> Simple 대비 **Macro F1이 5% 이상 향상**되면 KcELECTRA 채택
+
+- ΔF1 ≥ +0.05 → KcELECTRA 채택, predict_one에서 `model="kcelectra"`로 변경
+- ΔF1 < 0.05 → Simple 유지 (안정성 우선)
+- Simple은 항상 fallback으로 유지
+
+---
+
+## 자주 묻는 질문
+
+**Q. 베이스라인 학습이 안 되고 파일을 못 찾는다고 에러가 난다면?**  
+→ `cd model/classification` 후 실행하세요. 경로 기준이 `model/classification/`입니다.
+
+**Q. 데이터를 더 추가하고 싶은데 어떻게 하나요?**  
+→ `data/notice_sample_v3.csv` 맨 아래에 `문장,카테고리` 형식으로 행 추가.  
+단, split_v1.csv가 없는 상태라면 추가 후 `split_dataset.py` 실행.  
+이미 split_v1.csv가 있다면 `--force`로 재분할.
+
+**Q. KcELECTRA 학습이 CUDA OOM 에러가 난다면?**  
+→ `01_train_kcelectra.ipynb`의 `BATCH_SIZE = 16`을 `8`로 줄이세요.
+
+**Q. predict_one이 항상 "기타"만 반환한다면?**  
+→ 베이스라인 모델(pkl 파일)이 없는 것. `python src/classifier_simple.py` 먼저 실행.
+
+##4월30일##작업 완료 — feature/kyeongyi-classification 브랜치
+model/classification/ 폴더에 다음 구조가 완성됐습니다:
+
+
+model/classification/
+├── data/
+│   ├── notice_sample_v3.csv         ← 새로 만든 학습 데이터 (150개, 6카테고리 균등)
+│   ├── notices_labeled_v2.csv       ← 기존 라벨 데이터 복원 (병합 학습에 사용)
+│   └── notices_labeled_v2.jsonl     ← 기존 원본 데이터 복원
+├── src/
+│   ├── predict.py                   ← 백엔드 진입점 (predict_one 함수)
+│   ├── classifier_simple.py         ← 베이스라인: TF-IDF + LogReg (CPU)
+│   └── classifier_kcelectra.py      ← KcELECTRA 추론 모듈
+├── scripts/
+│   ├── split_dataset.py             ← 데이터 공정 분할 (딱 한 번 실행)
+│   └── evaluate_compare.py          ← 두 모델 성능 비교
+├── notebooks/
+│   ├── 01_train_kcelectra.ipynb     ← GPU 학습 (Colab T4, ~20분)
+│   └── 02_evaluate_compare.ipynb    ← 성능 비교 시각화
+├── checkpoints/                     ← 학습 후 모델 파일 저장 위치
+├── docs/
+│   └── devlog_2026-04-30.md         ← 오늘 개발일지
+└── README2.md                       ← 상세 가이드
+
+# 지금 바로 실행할 순서:
+
+python scripts/split_dataset.py → 데이터 분할
+python src/classifier_simple.py → 베이스라인 학습
+Colab에서 notebooks/01_train_kcelectra.ipynb → KcELECTRA 파인튜닝 (GPU)
+python scripts/evaluate_compare.py → 두 모델 성능 비교
+notebooks/02_evaluate_compare.ipynb → 시각화 차트 생성 (발표 근거 자료)
+백엔드가 호출하는 predict_one() 인터페이스는 기존과 완전히 호환되며, model="simple" / "kcelectra" / "auto" 세 가지 모드를 지원합니다. 자세한 설명은 README2.md와 devlog_2026-04-30.md를 참고.

model/classification/README3.md

@@ -0,0 +1,38 @@
+# 윤정님(2026년 05월 04일):
+
+-새로운 데이터 추가
+model/extraction/data/train/test_data.jsonl    모델 통과 전 — {text, is_todo} 5,560행
+data/processed/predict_output_testset.jsonl    모델 통과 후 — {text, source, due_date, amount, confidence, action_hint, true_is_todo} 5,330행 (정규식 필터 제외 230행)
+
+# 로컬에서 비교 평가 실행
+
+(ai_env) C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification>python scripts/evaluate_compare_v2_20260504.py
+평가 시작 — split: test, 데이터: v4_20260504
+
+[Simple] 분류 리포트
+              precision    recall  f1-score   support
+
+          일정       0.79      0.85      0.81        13
+         준비물       0.86      0.75      0.80         8
+          제출       0.69      0.69      0.69        13
+          비용       1.00      0.90      0.95        10
+       건강·안전       0.75      0.82      0.78        11
+          기타       0.71      0.71      0.71        14
+
+    accuracy                           0.78        69
+   macro avg       0.80      0.79      0.79        69
+weighted avg       0.79      0.78      0.78        69
+
+[kcelectra] 기존 JSON 재활용: eval_results_kcelectra_20260504.json
+
+[저장] eval_results_simple_20260504.json
+[저장] eval_results_kcelectra_20260504.json
+[저장] eval_comparison_summary_20260504.csv
+
+==================================================
+  성능 비교 결과
+==================================================
+  Simple    Macro F1 : 0.7919
+  KcELECTRA Macro F1 : 0.6938
+  Delta              : -0.0981
+  >> Simple 유지 권장

model/classification/README4.md

@@ -0,0 +1,50 @@
+# README.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\README.md
+
+전체 파이프라인 (확정 버전)
+[4] 카테고리 분류  (services/classifier.py — 경이님 6-class wrapper)
+입력:  각 todo.text
+출력:  category ∈ {일정, 준비물, 제출, 비용, 건강·안전, 기타}
+
+- 카테고리 분류-경이님
+
+`일정`, `준비물`, `제출`, `비용`, `건강·안전`, `기타`
+
+
+- 가장 중요한 핵심과제: 모델 성능 비교 (베이스라인 VS. 파인튜닝)
+1. 조건: 베이스라인 모델, 파인튜닝한 모델에 들어가는 input data가 동일한 데이터셋 및 동일한 조건에서 두 모델의 성능을 비교. 다시 말해서, 기존에 있던 모델을 가지고 동일한 조건을 맞춰서 일정, 준비물, 제출, 비용, 건강·안전, 기타에 대한 분류 성능 점수가 나와야하고 파인튜닝한 모델을 동일한 조건으로 6가지 분류 성능 점수가 나와야 비교가 가능. 그래서 파인튜닝된 모델이 베이스라인모델보다 성능이 좋다라는 지표가 나와야 성능의 우수함을 입증할 수 있음. 근거 자료를 만들어야 함. 
+
+2. 두 모델(베이스라인 모델, 파인튜닝한 모델)에 들어가는 기존의 데이터는 답안지가 없기 때문에 accuracy가 아닌 그 모델의 맞는 평가 방식 및 성능 지표를 뽑아야 함. 그래서 자동라벨링(C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\scripts\auto_label_from_new_data_20260504.py)을 해서 notice_sample_v4_20260504.csv (C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\data\20260504\notice_sample_v4_20260504.csv) 696행 학습 데이터를 만들었다. 그러나 2026년 05월 05일에 받은 새로운 학습 데이터 notice_sample_v5_clean_full_20260504.csv (C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\data\notice_sample_v5_clean_full_20260504.csv) 5001행은 이미 라벨링이 존재함. 그래서 사용하고 있는 모델들의 적절한 평가 및 성능 지표가 나와야 함. 사용하고자 하는 모델 기능들의 자세한 설명 보기.
+
+예시로, Precision이라고 하면 10개 단어 중에 2개 단어만 맞췄다. 그래서 그 모델로 해서 모든 텍스트 데이터 돌아서 몇 프로 맞췄으니까 얘는 성능이 얼마다 라고 얘기하는 것도 있다.
+
+==> 파인튜닝의 성능이 베이스라인 성능보다 좋은 쪽으로 모델이 나와야하고 그 모델에 맞는 평가 지표가 나와야 한다. 글씨로 정리하는 것 뿐만아니라 시각적인 도구를 활용해서 그래프 혹은 직선 사용 등으로 제시할 근거 자료가 필요.
+
+# README2.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\README2.md
+
+# README3.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\README3.md
+
+# docs 개발일지
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\docs\devlog_2026-04-30.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\docs\devlog_2026-04-30_실행결과.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\docs\devlog_2026-05-02.md
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\docs\devlog_2026-05-04_자동라벨링.md
+
+# data
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\data
+-중요: 새로운 학습 데이터 C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\data\notice_sample_v5_clean_full_20260504.csv --> 주어진 5001행 데이터를 가지고 학습 시켜야 함.
+
+나머지는 기존 데이터
+
+# scripts
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\scripts
+
+# src
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\src
+
+# notebooks
+C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\notebooks
+-가상환경 설치 권장: tensorflow, torch
+-C:\Users\kysop\Team_Project_Multiculture\multicultural-ai\model\classification\notebooks\03_train_kcelectra_v2_20260504 (1).ipynb 파일처럼 Colab GPU로 돌릴 수 있는 것은 주피터 노트북 형성해야 한다.

model/classification/scripts/auto_label_from_new_data_20260504.py

@@ -0,0 +1,575 @@
+"""
+auto_label_from_new_data_20260504.py
+=====================================
+담당: 경이 (kyeongyi)
+작성일: 2026-05-04
+브랜치: feature/kyeongyi-classification
+
+목적:
+    윤정님이 새로 추가한 대용량 데이터(5,560행)에는 'is_todo' 정보만 있고
+    '일정/준비물/제출/비용/건강·안전/기타' 라벨이 없다.
+    이 스크립트는 키워드 규칙과 슬롯(amount, due_date, action_hint)을 이용해
+    자동으로 카테고리를 부여하고, 기존 v3.csv와 합쳐 v4 학습 데이터를 생성한다.
+
+왜 '자동 라벨링'을 썼나?
+    1. 새 데이터 5,560행을 사람이 수작업으로 라벨링하면 수십 시간 걸림.
+    2. 기존 라벨 데이터(v3.csv, 142행)만으로는 KcELECTRA 파인튜닝이 부족
+       (BERT 계열은 최소 클래스당 50~100개, 전체 300~1000개 이상 필요).
+    3. 키워드 기반 자동 라벨링 → 대량 데이터 확보 → KcELECTRA 재학습 → 성능 역전.
+
+검증 방법:
+    - 기존 라벨이 있는 v3.csv를 이 규칙으로 다시 분류 → 규칙 정확도 확인.
+    - 규칙 정확도가 75% 이상이면 자동 라벨 데이터를 신뢰할 수 있다고 판단.
+
+실행:
+    cd model/classification
+    python scripts/auto_label_from_new_data_20260504.py
+"""
+
+import json
+import re
+import csv
+import random
+from pathlib import Path
+from collections import Counter
+
+random.seed(42)   # 재현성 보장 — 누가 실행해도 동일한 분할·샘플 순서
+
+
+# ──────────────────────────────────────────────────────────────────
+# 1. 경로 설정
+# ──────────────────────────────────────────────────────────────────
+# 이 파일의 위치: model/classification/scripts/
+# _BASE → model/classification/
+_BASE = Path(__file__).parent.parent
+
+DATA_DIR     = _BASE / "data"
+EXTRACT_BASE = _BASE.parent.parent / "model" / "extraction"  # 윤정님 모델 폴더
+
+# 입력 파일 (윤정님이 추가한 새 데이터)
+SRC_TEST_DATA   = EXTRACT_BASE / "data" / "train" / "test_data.jsonl"
+SRC_PREDICT_OUT = EXTRACT_BASE / "data" / "processed" / "predict_output_testset.jsonl"
+
+# 기존 경이님 라벨 데이터
+SRC_V3_CSV = DATA_DIR / "notice_sample_v3.csv"
+
+# 출력 파일
+OUT_CSV = DATA_DIR / "notice_sample_v4_20260504.csv"
+
+# 6가지 분류 카테고리
+LABELS = ["일정", "준비물", "제출", "비용", "건강·안전", "기타"]
+
+
+# ──────────────────────────────────────────────────────────────────
+# 2. 카테고리별 키워드 규칙
+# ──────────────────────────────────────────────────────────────────
+# 설계 원칙:
+#   (a) 우선순위 순서로 검사 — 먼저 매칭된 카테고리를 반환하고 중단.
+#   (b) 각 카테고리에서 가장 '강한' 신호(오탐 없는 단어)를 선택.
+#   (c) 한국어는 조사·어미 변형이 많으므로 어근만 사용 (예: "납부" → "납부해", "납부하여" 모두 포함).
+#   (d) 숫자 패턴은 정규표현식 사용 (예: "20,000원", "3만원" 등 다양한 금액 표현).
+#
+# 왜 이 순서인가?
+#   비용 > 준비물 > 제출 > 건강·안전 > 일정 > 기타
+#   → "3만 원을 5월 15일까지 납부" 같은 문장은 '비용'이 더 강한 신호.
+#   → '일정'은 날짜 표현이 많아 오탐 위험이 있어 후순위.
+#   → '기타'는 규칙 없이 나머지를 다 받는 쓰레기통 역할.
+
+RULES: list[tuple[str, list[str]]] = [
+    # ── 비용 ──
+    # 금액·납부 관련 표현이 명확하게 있는 경우.
+    # r"\d[\d,]*\s*원" : "65,000원", "3만원"은 이 정규식으로 포착.
+    ("비용", [
+        "납부",            # "납부해 주세요", "납부하여"
+        "입금",            # "계좌로 입금"
+        "계좌이체",        # "계좌이체해 주세요"
+        "급식비",
+        "참가비",
+        "수강료",
+        "교재비",
+        "버스비",
+        "이용료",
+        "수업료",
+        "구입비",
+        "지원금",
+        "면제",            # "급식비 면제 신청"
+        "선납",            # "선납해 주세요"
+        r"\d[\d,]*\s*원",  # 숫자+원 (20,000원, 3만원 등)
+    ]),
+
+    # ── 준비물 ──
+    # 챙겨야 할 물건·복장 관련.
+    # "마스크를" 처럼 뒤에 조사가 붙는 경우도 어근으로 포착.
+    ("준비물", [
+        "지참",            # "지참하시기 바랍니다"
+        "챙겨",            # "챙겨주시기 바랍니다"
+        "챙기",            # "챙기���기 바랍니다"
+        "준비해",          # "준비해 주세요"
+        "준비물",          # "학습 준비물"
+        "가져오",          # "가져오세요"
+        "착용",            # "착용하여 등교"
+        "신고 오",         # "운동화를 신고 오세요"
+        "복장",
+        "도시락",
+        "우산",
+        "수영복",
+        "실내화",
+        "방한",            # "방한용품"
+        "앞치마",
+        "고무장갑",
+        "배낭",
+        "여벌",            # "여벌 옷"
+        "스케치북",
+        "색연필",
+    ]),
+
+    # ── 제출 ──
+    # 서류·동의서·설문 등 무언가를 학교에 내야 하는 경우.
+    ("제출", [
+        "제출",            # "제출해 주세요", "제출하여"
+        "동의서",          # "현장체험학습 동의서"
+        "신청서",          # "급식 신청서"
+        "설문",            # "온라인 설문에 응답"
+        "서류를",
+        "작성하여",        # "작성하여 제출"
+        "응답해",          # "설문에 응답해 주세요"
+        "기재",            # "기재해 주세요"
+        "접수",
+        "첨부",
+        "등록",            # "회원 등록"
+        "신청해",          # "신청해 주세요"
+        "기한 내 신청",
+        "아이 편에",       # "아이 편에 보내주시기"
+        "담임선생님께 보내",
+    ]),
+
+    # ── 건강·안전 ──
+    # 신체 관련, 안전사고 예방, 감염병 관련.
+    ("건강·안전", [
+        "발열",
+        "기침",
+        "증상",
+        "예방접종",
+        "백신",
+        "감염",
+        "방역",
+        "소독",
+        "위생",
+        "자가진단",
+        "결석",
+        "질병",
+        "코로나",
+        "독감",
+        "알레르기",
+        "안전사고",
+        "교통안전",
+        "헬멧",
+        "안전벨트",
+        "온열",            # "온열 질환"
+        "응급",
+        "선별진료",
+        "PCR",
+        "진단키트",
+        "확진",
+        "수분 보충",
+    ]),
+
+    # ── 일정 ──
+    # 날짜·시간·행사 관련. 비용/준비물/제출 보다 후순위인 이유:
+    #   "3만 원을 5월 15일까지 납부" → 날짜가 있어도 '비용'이 정답.
+    #   날짜 패턴은 오탐이 많아 '강한' 단어와 함께 쓸 때만 신뢰.
+    ("일정", [
+        r"\d+월\s*\d+일",      # "5월 20일", "3 월 7 일"
+        r"\d{4}\.\s*\d+\.\s*\d+",  # "2025.05.20"
+        r"\d+\.\s*\d+\.\s*\([월화수목금토일]\)",  # "5.20.(화)"
+        "오전",                # "오전 9시"
+        "오후",
+        "~까지",               # "3월 20일~까지"
+        "부터 ",               # "3월부터 "
+        "기간",
+        "주간",
+        "방학",
+        "개학",
+        "졸업식",
+        "입학식",
+        "운동회",
+        "수학여행",
+        "체험학습",
+        "현장학습",
+        "학부모 총회",
+        "공개수업",
+        "학예발표",
+        "체육대회",
+        "생태체험",
+        "시작합니다",
+        "출발합니다",
+        "진행됩니다",
+        "실시됩니다",
+        "열립니다",
+        "개최됩니다",
+    ]),
+]
+# RULES에 없는 문장 → "기타"로 분류
+
+
+# ──────────────────────────────────────────────────────────────────
+# 3. 정규표현식 여부 판별 헬퍼
+# ──────────────────────────────────────────────────────────────────
+def _is_regex(pattern: str) -> bool:
+    """문자열 안에 정규표현식 특수문자가 있으면 True."""
+    # \d, ^, $, |, ?, *, +, (, ), [, ], {, } 중 하나라도 있으면 regex
+    regex_chars = r"\d^$.|?*+()[]{}".replace(".", r"\.")
+    return bool(re.search(r"[\\^$.|?*+()\[\]{}]|\\d", pattern))
+
+
+# ──────────────────────────────────────────────────────────────────
+# 4. 핵심 분류 함수 (규칙 기반)
+# ──────────────────────────────────────────────────────────────────
+def label_by_keywords(text: str) -> str | None:
+    """
+    텍스트에 키워드·패턴이 포함되면 해당 카테고리를 반환.
+    RULES 리스트 순서대로 검사 — 첫 매칭에서 즉시 반환.
+    없으면 None 반환 (→ 슬롯 기반 분류로 넘어감).
+    """
+    for category, patterns in RULES:
+        for pat in patterns:
+            if _is_regex(pat):
+                if re.search(pat, text):
+                    return category
+            else:
+                if pat in text:
+                    return category
+    return None
+
+
+def label_by_slots(
+    action_hint: str | None,
+    amount: str | None,
+    due_date: str | None,
+) -> str | None:
+    """
+    윤정님 추출 모델이 뽑은 슬롯 정보를 이용한 보조 분류.
+    키워드 규칙이 None을 반환했을 때만 호출.
+
+    논리:
+      - amount 있음  → 비용 관련 문장일 가능성이 높다
+      - action_hint = "제출"/"신청" → 제출 카테고리
+      - action_hint = "준비"/"지참" → 준비물 카테고리
+      - due_date 있음 + 비용/제출 키워드 없음 → 일정 관련
+    """
+    if amount:
+        return "비용"
+    if action_hint in ("제출", "신청", "작성"):
+        return "제출"
+    if action_hint in ("준비", "지참", "착용"):
+        return "준비물"
+    if due_date:
+        # 날짜가 있으나 다른 강한 신호가 없으면 일정
+        return "일정"
+    return None
+
+
+def classify(
+    text: str,
+    action_hint: str | None = None,
+    amount: str | None = None,
+    due_date: str | None = None,
+) -> str | None:
+    """
+    최종 분류 함수.
+    1단계: 키워드 규칙 (빠르고 명확)
+    2단계: 슬롯 기반 (윤정님 추출 정보 활용)
+    모두 실패하면 None → 이 문장은 학습 데이터에서 제외 (노이즈 방지).
+
+    '기타'를 일부러 규칙에 넣지 않은 이유:
+      규칙으로 잡히지 않는 문장이 전부 기타가 되면 기타 데이터가
+      너무 많아지고, 오탐(실제론 일정인데 기타로 잡힌 것)도 섞임.
+      → 기타는 별도 limit을 두지 않고 "나머지"로만 수집.
+    """
+    label = label_by_keywords(text)
+    if label:
+        return label
+    label = label_by_slots(action_hint, amount, due_date)
+    if label:
+        return label
+    return None   # 애매한 문장은 버린다
+
+
+# ──────────────────────────────────────────────────────────────────
+# 5. 데이터 로드 함수
+# ──────────────────────────────────────────────────────────────────
+def load_test_data() -> list[dict]:
+    """
+    test_data.jsonl : {text, is_todo}
+    is_todo = True인 행만 사용.
+    이유: False인 행은 학교 공지 중 '할 일이 없는' 순수 안내 문장.
+    분류 모델의 목적(학부모가 해야 할 행동 분류)에 맞지 않아 제외.
+    """
+    rows = []
+    with open(SRC_TEST_DATA, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            d = json.loads(line)
+            if d.get("is_todo") is True:
+                rows.append({
+                    "text":        d["text"],
+                    "action_hint": None,   # 이 파일엔 슬롯 정보 없음
+                    "amount":      None,
+                    "due_date":    None,
+                })
+    return rows
+
+
+def load_predict_output() -> list[dict]:
+    """
+    predict_output_testset.jsonl : {text, source, due_date, amount,
+                                     confidence, action_hint, true_is_todo}
+
+    필터 기준:
+      - true_is_todo = True  : 명확하게 할 일인 문장
+      - confidence >= 0.7    : 윤정님 모델이 확신하는 문장
+    이 두 조건 중 하나라도 만족하면 사용.
+    슬롯(amount, due_date, action_hint)은 자동 라벨링 2단계(label_by_slots)에 활용.
+    """
+    rows = []
+    with open(SRC_PREDICT_OUT, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            d = json.loads(line)
+            is_todo   = d.get("true_is_todo") is True
+            high_conf = d.get("confidence", 0) >= 0.7
+            if is_todo or high_conf:
+                rows.append({
+                    "text":        d["text"],
+                    "action_hint": d.get("action_hint"),
+                    "amount":      d.get("amount"),
+                    "due_date":    d.get("due_date"),
+                })
+    return rows
+
+
+def load_v3_csv() -> list[tuple[str, str]]:
+    """
+    기존에 경이님이 직접 라벨링한 notice_sample_v3.csv 로드.
+    컬럼: text, category
+    """
+    rows = []
+    with open(SRC_V3_CSV, encoding="utf-8-sig", newline="") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            text = row.get("text", "").strip()
+            cat  = row.get("category", "").strip()
+            if text and cat in LABELS:
+                rows.append((text, cat))
+    return rows
+
+
+# ─────────────────────────────────────────────────────��────────────
+# 6. 규칙 검증 함수 — 기존 라벨 데이터로 규칙 정확도 측정
+# ──────────────────────────────────────────────────────────────────
+def validate_rules(v3_rows: list[tuple[str, str]]) -> float:
+    """
+    v3.csv는 경이님이 직접 라벨링한 '정답 데이터'다.
+    이 정답 데이터에 자동 라벨링 규칙을 적용해 몇 %나 맞히는지 확인.
+
+    목표: 75% 이상 → 자동 라벨 데이터를 신뢰할 수 있다고 판단.
+    낮으면 규칙을 수정해야 함.
+    """
+    correct = 0
+    total   = 0
+    errors  = []
+
+    for text, true_cat in v3_rows:
+        pred = classify(text)
+        if pred is None:
+            pred = "기타"   # 규칙 미매칭 → 기타로 간주
+        total += 1
+        if pred == true_cat:
+            correct += 1
+        else:
+            errors.append((text[:40], true_cat, pred))
+
+    accuracy = correct / total if total > 0 else 0.0
+
+    print("\n[규칙 검증] v3.csv 기준 자동 라벨링 정확도")
+    print(f"  정답: {correct}/{total} = {accuracy:.1%}")
+
+    if errors:
+        print(f"  오분류 예시 (상위 10개):")
+        for txt, true, pred in errors[:10]:
+            print(f"    [{true}→{pred}] {txt}")
+
+    if accuracy >= 0.75:
+        print("  [OK] 규칙 신뢰도 충분 (75% 이상) -> 자동 라벨 데이터 채택")
+    else:
+        print("  [경고] 규칙 신뢰도 부족 -- 규칙을 추가/수정할 것을 권장")
+
+    return accuracy
+
+
+# ──────────────────────────────────────────────────────────────────
+# 7. 라벨링 + 필터링
+# ──────────────────────────────────────────────────────────────────
+MIN_TEXT_LEN = 10   # 10글자 미만 단편 문장은 노이즈 가능성이 높아 제외
+
+
+def label_all(rows: list[dict]) -> list[tuple[str, str]]:
+    """
+    rows 각각에 classify()를 적용해 (text, category) 쌍 반환.
+    - MIN_TEXT_LEN 미만 → 제외
+    - classify() 결과가 None → 제외 (애매한 문장)
+    """
+    labeled: list[tuple[str, str]] = []
+    for r in rows:
+        text = r["text"].strip()
+        if len(text) < MIN_TEXT_LEN:
+            continue
+        cat = classify(text, r.get("action_hint"), r.get("amount"), r.get("due_date"))
+        if cat:
+            labeled.append((text, cat))
+        else:
+            # 규칙·슬롯 미매칭 문장은 '기타'로 넣되, 별도 카운터로 제한
+            labeled.append((text, "기타"))
+    return labeled
+
+
+MAX_NEW_PER_LABEL = 120   # 새 데이터에서 카테고리당 최대 수집 수
+# 이유: 너무 많으면 노이즈가 늘어나고, 클래스 불균형도 발생.
+# 기존 v3(약 25/카테고리) + 신규(최대 120/카테고리) → 전체 약 900개 목표.
+
+
+def balance_new_data(
+    labeled: list[tuple[str, str]],
+    max_per: int,
+) -> list[tuple[str, str]]:
+    """
+    카테고리별로 max_per 개까지만 샘플링.
+    random.shuffle(seed=42)로 무작위 선택 → 재현 가능.
+
+    왜 균형이 필요한가?
+      KcELECTRA 파인튜닝 시 특정 클래스 데이터가 너무 많으면
+      모델이 그 클래스로 편향됨 (기존 문제와 동일한 class collapse 현상).
+    """
+    buckets: dict[str, list[str]] = {l: [] for l in LABELS}
+    for text, cat in labeled:
+        if cat in buckets:
+            buckets[cat].append(text)
+
+    result: list[tuple[str, str]] = []
+    for cat, texts in buckets.items():
+        random.shuffle(texts)
+        for t in texts[:max_per]:
+            result.append((t, cat))
+    return result
+
+
+# ──────────────────────────────────────────────────────────────────
+# 8. 중복 제거
+# ──────────────────────────────────────────────────────────────────
+def remove_duplicates(rows: list[tuple[str, str]]) -> list[tuple[str, str]]:
+    """
+    동일 텍스트가 두 번 이상 나타나면 첫 번째만 유지.
+    왜 필요한가?
+      test_data.jsonl과 predict_output_testset.jsonl이 같은 원본에서
+      파생됐기 때문에 중복 문장이 존재할 수 있음.
+      중복이 있으면 test 세트에도 같은 문장이 들어가 평가가 부풀려짐.
+    """
+    seen: set[str] = set()
+    out: list[tuple[str, str]] = []
+    for text, cat in rows:
+        if text not in seen:
+            seen.add(text)
+            out.append((text, cat))
+    return out
+
+
+# ���─────────────────────────────────────────────────────────────────
+# 9. 저장
+# ──────────────────────────────────────────────────────────────────
+def save_csv(rows: list[tuple[str, str]], path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8-sig", newline="") as f:
+        # quoting=QUOTE_ALL : 쉼표·줄바꿈 포함 텍스트도 안전하게 저장
+        writer = csv.writer(f, quoting=csv.QUOTE_ALL)
+        writer.writerow(["text", "category"])
+        for text, cat in rows:
+            writer.writerow([text, cat])
+    print(f"\n[저장] {path}  ({len(rows)}행)")
+
+
+# ──────────────────────────────────────────────────────────────────
+# 10. 메인 실행
+# ──────────────────────────────────────────────────────────────────
+def main() -> None:
+    print("=" * 60)
+    print("  자동 라벨링 파이프라인 시작  (2026-05-04)")
+    print("=" * 60)
+
+    # Step A: 기존 라벨 데이터 로드
+    v3_rows = load_v3_csv()
+    print(f"\n[A] 기존 v3.csv: {len(v3_rows)}개")
+    cnt_v3 = Counter(cat for _, cat in v3_rows)
+    for l in LABELS:
+        print(f"     {l}: {cnt_v3.get(l, 0)}개")
+
+    # Step B: 규칙 검증 (v3.csv 기준)
+    rule_acc = validate_rules(v3_rows)
+
+    # Step C: 새 데이터 로드
+    print("\n[C] 새 데이터 로드")
+    test_rows    = load_test_data()
+    predict_rows = load_predict_output()
+    print(f"  test_data.jsonl  (is_todo=True): {len(test_rows):,}개")
+    print(f"  predict_output   (필터 후):       {len(predict_rows):,}개")
+
+    # Step D: 자동 라벨링
+    print("\n[D] 자동 라벨링 중...")
+    labeled_test    = label_all(test_rows)
+    labeled_predict = label_all(predict_rows)
+    all_new = labeled_test + labeled_predict
+    print(f"  라벨링 완료: {len(all_new):,}개")
+    cnt_new = Counter(cat for _, cat in all_new)
+    for l in LABELS:
+        print(f"  {l}: {cnt_new.get(l, 0)}개")
+
+    # Step E: 균형 조정 (카테고리당 최대 MAX_NEW_PER_LABEL개)
+    balanced = balance_new_data(all_new, MAX_NEW_PER_LABEL)
+    print(f"\n[E] 균형 조정 후: {len(balanced)}개")
+    cnt_bal = Counter(cat for _, cat in balanced)
+    for l in LABELS:
+        print(f"  {l}: {cnt_bal.get(l, 0)}개")
+
+    # Step F: 기존 v3 + 새 데이터 병합 → 중복 제거
+    combined = v3_rows + balanced
+    combined = remove_duplicates(combined)
+    random.shuffle(combined)   # 파일 내 순서 무작위화
+    print(f"\n[F] 최종 병합 (중복 제거 후): {len(combined)}개")
+    cnt_final = Counter(cat for _, cat in combined)
+    for l in LABELS:
+        print(f"  {l}: {cnt_final.get(l, 0)}개")
+
+    # Step G: 저장
+    save_csv(combined, OUT_CSV)
+
+    # 최종 요약
+    print("\n" + "=" * 60)
+    print("  완료 요약")
+    print("=" * 60)
+    print(f"  기존 v3.csv:          {len(v3_rows):>4}개")
+    print(f"  새 데이터 (균형 후):  {len(balanced):>4}개")
+    print(f"  최종 v4 (중복 제거):  {len(combined):>4}개")
+    print(f"  규칙 정확도:          {rule_acc:.1%}")
+    print(f"  출력: {OUT_CSV}")
+    print()
+    print("다음 단계:")
+    print("  python scripts/split_dataset.py --data v4_20260504 --force")
+    print("  python src/classifier_simple.py   (베이스라인 재학습)")
+    print("  Colab에서 notebooks/03_train_kcelectra_v2_20260504.ipynb 실행")
+
+
+if __name__ == "__main__":
+    main()

model/classification/scripts/evaluate_compare.py

@@ -0,0 +1,203 @@
+"""
+베이스라인 vs KcELECTRA 성능 비교 스크립트
+===========================================
+담당: 경이
+목적: 동일한 test 데이터로 두 모델의 성능을 비교하여 CSV·JSON으로 저장.
+      결과는 02_evaluate_compare.ipynb에서 시각화.
+
+실행:
+    python scripts/evaluate_compare.py              # test split 평가
+    python scripts/evaluate_compare.py --split val  # val split 평가
+
+결과 파일:
+    data/eval_results_simple.json
+    data/eval_results_kcelectra.json
+    data/eval_comparison_summary.csv
+
+평가 지표:
+    - Macro F1  : 클래스 불균형 무관 전체 성능 (메인 지표)
+    - Per-class F1, Precision, Recall
+    - Confusion Matrix
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import pandas as pd
+from sklearn.metrics import (
+    classification_report,
+    confusion_matrix,
+    f1_score,
+    precision_score,
+    recall_score,
+)
+
+_BASE = Path(__file__).parent.parent
+sys.path.insert(0, str(_BASE))
+
+from src.classifier_simple import load_pipeline, load_data
+from src.classifier_kcelectra import predict_kcelectra, is_ready as kcelectra_ready
+
+LABELS = ["일정", "준비물", "제출", "비용", "건강·안전", "기타"]
+OUT_DIR = _BASE / "data"
+
+
+def _fill_per_class_from_cm(res: dict) -> dict:
+    """Colab 저장 JSON에 per_class가 없을 때 confusion_matrix에서 보완."""
+    if res.get("per_class"):
+        return res
+    cm = res.get("confusion_matrix")
+    labels = res.get("labels", LABELS)
+    if not cm:
+        return res
+    per_class = {}
+    for i, label in enumerate(labels):
+        tp = cm[i][i]
+        fp = sum(cm[r][i] for r in range(len(cm))) - tp
+        fn = sum(cm[i]) - tp
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        recall    = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        f1        = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+        per_class[label] = {
+            "precision": round(precision, 4),
+            "recall":    round(recall, 4),
+            "f1":        round(f1, 4),
+            "support":   sum(cm[i]),
+        }
+    res["per_class"] = per_class
+    return res
+
+
+def evaluate_simple(split: str = "test") -> dict:
+    texts, true_labels = load_data(split)
+    if not texts:
+        texts, true_labels = load_data("all")
+
+    pipe = load_pipeline()
+    pred_labels = pipe.predict(texts)
+
+    return _make_result("simple", true_labels, list(pred_labels))
+
+
+def evaluate_kcelectra(split: str = "test") -> dict:
+    # Colab에서 이미 평가한 JSON이 있으면 재활용 (torch 없는 환경에서도 비교 가능)
+    cached_json = OUT_DIR / "eval_results_kcelectra.json"
+    if cached_json.exists() and not kcelectra_ready():
+        print(f"[compare] Colab 결과 파일 사용: {cached_json.name}")
+        with open(cached_json, encoding="utf-8") as f:
+            result = json.load(f)
+        result = _fill_per_class_from_cm(result)
+        # per_class 보완된 내용을 다시 저장
+        with open(cached_json, "w", encoding="utf-8") as f:
+            json.dump(result, f, ensure_ascii=False, indent=2)
+        return result
+
+    if not kcelectra_ready():
+        print("[compare] KcELECTRA 체크포인트 없음. 01_train_kcelectra.ipynb 먼저 실행하세요.")
+        return {}
+
+    texts, true_labels = load_data(split)
+    if not texts:
+        texts, true_labels = load_data("all")
+
+    pred_labels = [predict_kcelectra(t)["category"] for t in texts]
+    return _make_result("kcelectra", true_labels, pred_labels)
+
+
+def _make_result(model_name: str, true: list, pred: list) -> dict:
+    macro_f1  = f1_score(true, pred, labels=LABELS, average="macro",  zero_division=0)
+    macro_pre = precision_score(true, pred, labels=LABELS, average="macro", zero_division=0)
+    macro_rec = recall_score(true, pred, labels=LABELS, average="macro", zero_division=0)
+
+    report = classification_report(
+        true, pred, labels=LABELS, output_dict=True, zero_division=0
+    )
+    cm = confusion_matrix(true, pred, labels=LABELS)
+
+    print(f"\n{'='*50}")
+    print(f"[{model_name}] 분류 리포트")
+    print(classification_report(true, pred, labels=LABELS, zero_division=0))
+    print(f"[{model_name}] Macro F1={macro_f1:.4f}  Pre={macro_pre:.4f}  Rec={macro_rec:.4f}")
+    print(f"[{model_name}] Confusion Matrix:\n{cm}")
+
+    return {
+        "model":          model_name,
+        "macro_f1":       round(macro_f1, 4),
+        "macro_precision":round(macro_pre, 4),
+        "macro_recall":   round(macro_rec, 4),
+        "per_class":      {
+            label: {
+                "precision": round(report[label]["precision"], 4),
+                "recall":    round(report[label]["recall"], 4),
+                "f1":        round(report[label]["f1-score"], 4),
+                "support":   report[label]["support"],
+            }
+            for label in LABELS if label in report
+        },
+        "confusion_matrix": cm.tolist(),
+        "labels":           LABELS,
+    }
+
+
+def save_and_compare(simple_res: dict, kcelectra_res: dict) -> None:
+    ts = datetime.now().strftime("%Y%m%d")
+
+    def _write_json(data: dict, canonical: str) -> None:
+        with open(OUT_DIR / canonical, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        stem = canonical.replace(".json", "")
+        with open(OUT_DIR / f"{stem}_{ts}.json", "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    _write_json(simple_res, "eval_results_simple.json")
+    if kcelectra_res:
+        _write_json(kcelectra_res, "eval_results_kcelectra.json")
+
+    rows = []
+    for res in [simple_res, kcelectra_res]:
+        if not res:
+            continue
+        row = {
+            "model":          res["model"],
+            "macro_f1":       res["macro_f1"],
+            "macro_precision":res["macro_precision"],
+            "macro_recall":   res["macro_recall"],
+        }
+        for label in LABELS:
+            if label in res.get("per_class", {}):
+                row[f"{label}_f1"] = res["per_class"][label]["f1"]
+        rows.append(row)
+
+    summary_df = pd.DataFrame(rows)
+    summary_df.to_csv(OUT_DIR / "eval_comparison_summary.csv", index=False, encoding="utf-8-sig")
+    summary_df.to_csv(OUT_DIR / f"eval_comparison_summary_{ts}.csv", index=False, encoding="utf-8-sig")
+    print(f"\n[compare] 결과 저장 완료 → {OUT_DIR}")
+    print("\n── 성능 요약 ──")
+    print(summary_df[["model", "macro_f1", "macro_precision", "macro_recall"]].to_string(index=False))
+
+    if kcelectra_res:
+        delta = kcelectra_res["macro_f1"] - simple_res["macro_f1"]
+        print(f"\n KcELECTRA vs Simple  ΔMacro F1 = {delta:+.4f}")
+        if delta >= 0.05:
+            print("  → KcELECTRA 5%+ 향상: 채택 권장!")
+        else:
+            print("  → 5% 미만 향상: Simple 유지 고려")
+
+
+def main(split: str = "test") -> None:
+    print(f"[compare] 평가 split: {split}")
+
+    simple_res     = evaluate_simple(split)
+    kcelectra_res  = evaluate_kcelectra(split)
+
+    save_and_compare(simple_res, kcelectra_res)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--split", default="test", choices=["train", "val", "test", "all"])
+    args = parser.parse_args()
+    main(split=args.split)

model/classification/scripts/evaluate_compare_ensemble_20260505.py

@@ -0,0 +1,409 @@
+"""
+evaluate_compare_ensemble_20260505.py
+======================================
+담당: 경이 (kyeongyi)
+작성일: 2026-05-05
+
+목적:
+    Simple + KcELECTRA 소프트 투표 앙상블 평가.
+    KcELECTRA 단독(v3, Macro F1 0.8545)이 목표 +5%에 0.71%p 미달하여
+    devlog 우선순위 3에 따라 앙상블 시도.
+
+    [비교 모델]
+      1. Simple   : TF-IDF + Logistic Regression  (baseline 0.8116)
+      2. KcELECTRA: v3 파인튜닝 단독              (0.8545)
+      3. Ensemble : KcELECTRA×0.7 + Simple×0.3   (목표: 0.8616+)
+
+    [앙상블 방식]
+      소프트 투표(Soft Voting) — 두 모델의 확률을 가중 합산 후 argmax
+      combined[i] = weight_kc × kc_prob[i] + (1-weight_kc) × s_prob[i]
+
+    [출력 파일 - data/20260505/]
+      eval_results_ensemble_20260505.json
+      eval_comparison_summary_ensemble_20260505.csv
+
+실행:
+    cd model/classification
+    python scripts/evaluate_compare_ensemble_20260505.py
+    python scripts/evaluate_compare_ensemble_20260505.py --weight_kc 0.6
+    python scripts/evaluate_compare_ensemble_20260505.py --search_weights
+"""
+
+import argparse
+import json
+import pickle
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from sklearn.metrics import classification_report, confusion_matrix, f1_score
+from sklearn.pipeline import Pipeline
+
+_BASE = Path(__file__).parent.parent
+sys.path.insert(0, str(_BASE / "src"))
+
+SPLIT_CSV      = _BASE / "data" / "split_v5_20260505.csv"
+SIMPLE_PKL     = _BASE / "checkpoints" / "simple_tfidf_logreg_v3_20260505.pkl"
+KCELECTRA_CKPT = _BASE / "checkpoints" / "kcelectra-category-v3"
+OUT_DIR        = _BASE / "data" / "20260505"
+
+# HF Hub fallback (로컬 체크포인트 없을 때)
+_HF_REPO      = "kysophia/kcelectra-category"
+_HF_SUBFOLDER = "kcelectra-category-v3"
+
+LABELS = ["일정", "준비물", "제출", "비용", "건강·안전", "기타"]
+_LABEL_TO_COL = {lbl: i for i, lbl in enumerate(LABELS)}
+
+
+# ──────────────────────────────────────────────────────────────────
+# 데이터 로드
+# ──────────────────────────────────────────────────────────────────
+def load_split(split: str = "test") -> tuple[list[str], list[str]]:
+    if not SPLIT_CSV.exists():
+        raise FileNotFoundError(f"{SPLIT_CSV} 없음")
+    df = pd.read_csv(SPLIT_CSV, encoding="utf-8-sig")
+    df = df[df["split"] == split]
+    df = df[df["category"].isin(LABELS)]
+    return df["text"].tolist(), df["category"].tolist()
+
+
+# ──────────────────────────────────────────────────────────────────
+# Simple 확률 행렬 (N, 6)
+# ──────────────────────────────────────────────────────────────────
+def _load_simple() -> Pipeline:
+    if not SIMPLE_PKL.exists():
+        raise FileNotFoundError(
+            f"{SIMPLE_PKL.name} 없음.\n"
+            "  먼저 실행: python scripts/evaluate_compare_v3_20260505.py"
+        )
+    with open(SIMPLE_PKL, "rb") as f:
+        return pickle.load(f)
+
+
+def get_simple_proba(texts: list[str]) -> np.ndarray:
+    """Simple predict_proba → LABELS 순서로 열 정렬한 (N, 6) 행렬."""
+    pipe = _load_simple()
+    raw = pipe.predict_proba(texts)          # (N, K), pipe.classes_ 순서
+    classes = list(pipe.classes_)
+    out = np.zeros((len(texts), len(LABELS)))
+    for j, lbl in enumerate(LABELS):
+        if lbl in classes:
+            out[:, j] = raw[:, classes.index(lbl)]
+    return out
+
+
+# ──────────────────────────────────────────────────────────────────
+# KcELECTRA 확률 행렬 (N, 6)
+# ──────────────────────────────────────────────────────────────────
+def _load_kcelectra_model():
+    """(device, tokenizer, model, id2label) 반환. 로컬 우선, HF Hub fallback."""
+    try:
+        import torch
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+    except ImportError:
+        raise ImportError("pip install torch transformers")
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+
+    local_ready = (
+        KCELECTRA_CKPT.exists()
+        and (KCELECTRA_CKPT / "config.json").exists()
+        and any(
+            (KCELECTRA_CKPT / f).exists()
+            for f in ("pytorch_model.bin", "model.safetensors")
+        )
+    )
+
+    if local_ready:
+        tokenizer = AutoTokenizer.from_pretrained(str(KCELECTRA_CKPT))
+        model = AutoModelForSequenceClassification.from_pretrained(
+            str(KCELECTRA_CKPT), num_labels=len(LABELS), ignore_mismatched_sizes=True
+        )
+        src = str(KCELECTRA_CKPT)
+    else:
+        print(f"[kcelectra] 로컬 없음 → HF Hub 다운로드: {_HF_REPO}/{_HF_SUBFOLDER}")
+        tokenizer = AutoTokenizer.from_pretrained(_HF_REPO, subfolder=_HF_SUBFOLDER)
+        model = AutoModelForSequenceClassification.from_pretrained(
+            _HF_REPO, subfolder=_HF_SUBFOLDER, num_labels=len(LABELS)
+        )
+        src = f"{_HF_REPO}/{_HF_SUBFOLDER}"
+
+    model.to(device).eval()
+    print(f"[kcelectra] 모델 로드: {src} → device={device}")
+
+    labels_file = KCELECTRA_CKPT / "label2id.json"
+    if local_ready and labels_file.exists():
+        with open(labels_file, encoding="utf-8") as f:
+            label2id: dict[str, int] = json.load(f)
+        id2label = {v: k for k, v in label2id.items()}
+    else:
+        id2label = {i: lbl for i, lbl in enumerate(LABELS)}
+
+    return device, tokenizer, model, id2label
+
+
+def get_kcelectra_proba(texts: list[str], batch_size: int = 32) -> np.ndarray:
+    """KcELECTRA softmax → LABELS 순서로 열 정렬한 (N, 6) 행렬. 배치 처리."""
+    import torch
+
+    device, tokenizer, model, id2label = _load_kcelectra_model()
+    out = np.zeros((len(texts), len(LABELS)))
+
+    with torch.no_grad():
+        for start in range(0, len(texts), batch_size):
+            batch = texts[start : start + batch_size]
+            enc = tokenizer(
+                batch,
+                return_tensors="pt",
+                truncation=True,
+                padding=True,
+                max_length=128,
+            ).to(device)
+            probs = torch.softmax(model(**enc).logits, dim=-1).cpu().numpy()
+            for b_i, prob_row in enumerate(probs):
+                for k_i, p in enumerate(prob_row):
+                    lbl = id2label.get(k_i, "기타")
+                    col = _LABEL_TO_COL.get(lbl, _LABEL_TO_COL["기타"])
+                    out[start + b_i, col] = p
+
+    return out
+
+
+# ──────────────────────────────────────────────────────────────────
+# 앙상블 평가
+# ──────────────────────────────────────────────────────────────────
+def evaluate_ensemble(
+    split: str,
+    weight_kc: float,
+    s_proba: np.ndarray,
+    kc_proba: np.ndarray,
+    true_labels: list[str],
+) -> dict:
+    """소프트 투표. s_proba / kc_proba를 받아 가중 합산 → 분류 리포트 반환."""
+    combined = weight_kc * kc_proba + (1.0 - weight_kc) * s_proba
+    pred_idx = combined.argmax(axis=1)
+    pred_labels = [LABELS[i] for i in pred_idx]
+
+    report = classification_report(
+        true_labels, pred_labels,
+        labels=LABELS, output_dict=True, zero_division=0,
+    )
+    cm = confusion_matrix(true_labels, pred_labels, labels=LABELS)
+    macro_f1 = f1_score(true_labels, pred_labels, labels=LABELS,
+                        average="macro", zero_division=0)
+
+    return {
+        "model":            "ensemble",
+        "version":          f"kc{weight_kc:.1f}+s{1-weight_kc:.1f}",
+        "weight_kc":        weight_kc,
+        "macro_f1":         round(macro_f1, 4),
+        "macro_precision":  round(report["macro avg"]["precision"], 4),
+        "macro_recall":     round(report["macro avg"]["recall"], 4),
+        "per_class": {
+            lbl: {
+                "precision": round(report[lbl]["precision"], 4),
+                "recall":    round(report[lbl]["recall"], 4),
+                "f1":        round(report[lbl]["f1-score"], 4),
+                "support":   report[lbl]["support"],
+            }
+            for lbl in LABELS
+        },
+        "confusion_matrix": cm.tolist(),
+        "labels":           LABELS,
+        "split_used":       split,
+        "data_version":     "v5_20260505",
+    }
+
+
+# ──────────────────────────────────────────────────────────────────
+# val 세트 가중치 그리드 탐색
+# ──────────────────────────────────────────────────────────────────
+def search_best_weight() -> float:
+    """val 세트에서 weight_kc 0.4~0.9 탐색 → 최적 weight 반환."""
+    print("\n[weight 탐색] val 세트 기준 KcELECTRA 가중치 최적화")
+
+    val_texts, val_labels = load_split("val")
+    print(f"  val {len(val_texts)}건 확률 계산 중...")
+    val_s  = get_simple_proba(val_texts)
+    val_kc = get_kcelectra_proba(val_texts)
+
+    print(f"\n  {'weight_kc':>10s}  {'val Macro F1':>14s}")
+    print("  " + "-" * 28)
+
+    best_w, best_f1 = 0.7, 0.0
+    for w in [0.4, 0.5, 0.6, 0.7, 0.8, 0.9]:
+        res = evaluate_ensemble("val", w, val_s, val_kc, val_labels)
+        mark = " ← best" if res["macro_f1"] > best_f1 else ""
+        print(f"  {w:>10.1f}  {res['macro_f1']:>14.4f}{mark}")
+        if res["macro_f1"] > best_f1:
+            best_f1, best_w = res["macro_f1"], w
+
+    print(f"\n  최적 weight_kc = {best_w}  (val Macro F1 = {best_f1:.4f})")
+    return best_w
+
+
+# ──────────────────────────────────────────────────────────────────
+# 저장 + 비교 출력
+# ──────────────────────────────────────────────────────────────────
+def _summary_row(res: dict) -> dict:
+    row = {
+        "macro_f1":        res.get("macro_f1", "-"),
+        "macro_precision": res.get("macro_precision", "-"),
+        "macro_recall":    res.get("macro_recall", "-"),
+    }
+    for lbl in LABELS:
+        row[f"f1_{lbl}"] = res.get("per_class", {}).get(lbl, {}).get("f1", "-")
+    return row
+
+
+def _build_result_from_proba(
+    proba: np.ndarray,
+    true_labels: list[str],
+    model_name: str,
+    split: str,
+) -> dict:
+    """확률 행렬 → 분류 리포트 dict (JSON 없을 때 fallback)."""
+    pred_labels = [LABELS[i] for i in proba.argmax(axis=1)]
+    report = classification_report(true_labels, pred_labels,
+                                   labels=LABELS, output_dict=True, zero_division=0)
+    macro_f1 = f1_score(true_labels, pred_labels, labels=LABELS,
+                        average="macro", zero_division=0)
+    cm = confusion_matrix(true_labels, pred_labels, labels=LABELS)
+    return {
+        "model":            model_name,
+        "version":          "v3",
+        "macro_f1":         round(macro_f1, 4),
+        "macro_precision":  round(report["macro avg"]["precision"], 4),
+        "macro_recall":     round(report["macro avg"]["recall"], 4),
+        "per_class": {
+            lbl: {
+                "precision": round(report[lbl]["precision"], 4),
+                "recall":    round(report[lbl]["recall"], 4),
+                "f1":        round(report[lbl]["f1-score"], 4),
+                "support":   report[lbl]["support"],
+            }
+            for lbl in LABELS
+        },
+        "confusion_matrix": cm.tolist(),
+        "labels":           LABELS,
+        "split_used":       split,
+        "data_version":     "v5_20260505",
+    }
+
+
+def save_and_compare(simple_res: dict, kc_res: dict, ens_res: dict) -> None:
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    ens_path = OUT_DIR / "eval_results_ensemble_20260505.json"
+    with open(ens_path, "w", encoding="utf-8") as f:
+        json.dump(ens_res, f, ensure_ascii=False, indent=2)
+    print(f"\n[저장] {ens_path.name}")
+
+    label_e = f"Ensemble(kc{ens_res['weight_kc']:.1f}+s{1-ens_res['weight_kc']:.1f})"
+    rows = [
+        {"model": "Simple (TF-IDF+LR)",      **_summary_row(simple_res)},
+        {"model": "KcELECTRA v3 (단독)",      **_summary_row(kc_res)},
+        {"model": label_e,                    **_summary_row(ens_res)},
+    ]
+    summary_path = OUT_DIR / "eval_comparison_summary_ensemble_20260505.csv"
+    pd.DataFrame(rows).to_csv(summary_path, index=False, encoding="utf-8-sig")
+    print(f"[저장] {summary_path.name}")
+
+    s_f1  = simple_res["macro_f1"]
+    kc_f1 = kc_res["macro_f1"]
+    e_f1  = ens_res["macro_f1"]
+
+    print("\n" + "=" * 60)
+    print("  앙상블 성능 비교 (v5 데이터 - 4992행)")
+    print("=" * 60)
+    print(f"  Simple      Macro F1 : {s_f1:.4f}  (baseline)")
+    print(f"  KcELECTRA   Macro F1 : {kc_f1:.4f}  (Delta vs Simple: {kc_f1-s_f1:+.4f})")
+    print(f"  Ensemble    Macro F1 : {e_f1:.4f}  (Delta vs Simple: {e_f1-s_f1:+.4f})")
+    print()
+
+    delta = e_f1 - s_f1
+    if delta >= 0.05:
+        print("  ★ 앙상블 5%+ 향상 달성! 채택 확정")
+    elif delta > 0:
+        print(f"  ~ 앙상블 소폭 향상 ({delta:+.4f}) — --search_weights 또는 추가 튜닝 권장")
+    else:
+        print("  ✗ 앙상블이 Simple 미달 — weight_kc 조정 필요")
+
+    print("\n  [카테고리별 F1 비교]")
+    print(f"  {'카테고리':10s} {'Simple':>8s} {'KcELEC':>8s} {'Ensemble':>10s}")
+    print("  " + "-" * 42)
+    for lbl in LABELS:
+        s = simple_res["per_class"].get(lbl, {}).get("f1", 0.0)
+        k = kc_res["per_class"].get(lbl, {}).get("f1", 0.0)
+        e = ens_res["per_class"].get(lbl, {}).get("f1", 0.0)
+        best = " ★" if e > max(s, k) else ("  " if e >= max(s, k) else "  ")
+        print(f"  {lbl:10s} {s:>8.4f} {k:>8.4f} {e:>10.4f}{best}")
+
+    print(f"\n[출력 폴더] {OUT_DIR}")
+
+
+# ──────────────────────────────────────────��───────────────────────
+# CLI
+# ──────────────────────────────────────────────────────────────────
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="KcELECTRA + Simple 소프트 투표 앙상블 평가"
+    )
+    parser.add_argument("--split", default="test",
+                        choices=["train", "val", "test"])
+    parser.add_argument("--weight_kc", type=float, default=0.7,
+                        help="KcELECTRA 가중치 (0.0~1.0). 기본값 0.7")
+    parser.add_argument("--search_weights", action="store_true",
+                        help="val 세트에서 0.4~0.9 그리드 탐색 후 최적값으로 test 평가")
+    args = parser.parse_args()
+
+    print(f"앙상블 평가 시작 — split: {args.split}, weight_kc: {args.weight_kc}")
+
+    # ① val 세트 가중치 탐색 (--search_weights)
+    weight_kc = args.weight_kc
+    if args.search_weights:
+        weight_kc = search_best_weight()
+        print(f"\n[test 평가] 최적 weight_kc={weight_kc} 적용")
+
+    # ② test 확률 행렬
+    texts, true_labels = load_split(args.split)
+    print(f"\n[데이터] {args.split} 세트 {len(texts)}건")
+
+    print("\n[Simple] 확률 행렬 계산 중...")
+    s_proba = get_simple_proba(texts)
+
+    print("[KcELECTRA] 확률 행렬 계산 중... (CPU면 수 분 소요)")
+    kc_proba = get_kcelectra_proba(texts)
+
+    # ③ 앙상블 평가
+    ens_res = evaluate_ensemble(args.split, weight_kc, s_proba, kc_proba, true_labels)
+
+    # ④ 단독 결과 — 기존 JSON 재활용, 없으면 확률 행렬에서 직접 계산
+    simple_json = OUT_DIR / "eval_results_simple_v3_20260505.json"
+    kc_json     = OUT_DIR / "eval_results_kcelectra_v3_20260505.json"
+
+    if simple_json.exists():
+        with open(simple_json, encoding="utf-8") as f:
+            simple_res = json.load(f)
+        print(f"[simple] 기존 JSON 재활용: {simple_json.name}")
+    else:
+        simple_res = _build_result_from_proba(s_proba, true_labels, "simple", args.split)
+
+    if kc_json.exists():
+        with open(kc_json, encoding="utf-8") as f:
+            kc_res = json.load(f)
+        print(f"[kcelectra] 기존 JSON 재활용: {kc_json.name}")
+    else:
+        kc_res = _build_result_from_proba(kc_proba, true_labels, "kcelectra", args.split)
+
+    # ⑤ 저장 + 비교 출력
+    print("\n[앙상블] 분류 리포트")
+    pred_labels = [LABELS[i] for i in (weight_kc * kc_proba + (1 - weight_kc) * s_proba).argmax(axis=1)]
+    print(classification_report(true_labels, pred_labels, labels=LABELS, zero_division=0))
+
+    save_and_compare(simple_res, kc_res, ens_res)
+
+
+if __name__ == "__main__":
+    main()

model/classification/scripts/evaluate_compare_v2_20260504.py

@@ -0,0 +1,355 @@
+"""
+evaluate_compare_v2_20260504.py
+================================
+담당: 경이 (kyeongyi)
+작성일: 2026-05-04
+
+목적:
+    split_v2_20260504.csv (695개 확장 데이터) 기준으로
+    두 모델의 성능을 비교·저장한다.
+
+    [비교 모델]
+      1. Simple   : TF-IDF + Logistic Regression (베이스라인)
+      2. KcELECTRA: 파인튜닝 모델 (03_train_kcelectra_v2_20260504.ipynb 실행 후 사용 가능)
+
+    [공정 비교 원칙]
+      - 두 모델 모두 split_v2_20260504.csv의 동일한 test 세트(69개)로 평가
+      - 학습 데이터도 동일한 train 세트(556개) 사용
+
+    [출력 파일 — 타임스탬프 포함]
+      data/eval_results_simple_20260504.json
+      data/eval_results_kcelectra_20260504.json   (KcELECTRA 준비 후 생성)
+      data/eval_comparison_summary_20260504.csv
+
+실행:
+    cd model/classification
+    python scripts/evaluate_compare_v2_20260504.py
+    python scripts/evaluate_compare_v2_20260504.py --split val   # val 세트로 평가
+"""
+
+import argparse
+import json
+import pickle
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import pandas as pd
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import (
+    classification_report,
+    confusion_matrix,
+    f1_score,
+)
+from sklearn.pipeline import Pipeline
+
+_BASE = Path(__file__).parent.parent
+sys.path.insert(0, str(_BASE / "src"))
+
+SPLIT_CSV    = _BASE / "data" / "split_v2_20260504.csv"
+SIMPLE_PKL   = _BASE / "checkpoints" / "simple_tfidf_logreg_v2_20260504.pkl"
+KCELECTRA_CKPT = _BASE / "checkpoints" / "kcelectra-category-v2"
+
+DATA_DIR = _BASE / "data"
+TS       = "20260504"  # 타임스탬프
+
+LABELS = ["일정", "준비물", "제출", "비용", "건강·안전", "기타"]
+
+
+# ──────────────────────────────────────────────────────────────────
+# 데이터 로드
+# ──────────────────────────────────────────────────────────────────
+def load_split(split: str = "test") -> tuple[list[str], list[str]]:
+    """
+    split_v2_20260504.csv에서 지정한 split의 text와 category를 반환.
+    split: "train" | "val" | "test"
+    """
+    if not SPLIT_CSV.exists():
+        raise FileNotFoundError(
+            f"{SPLIT_CSV} 없음 — split_dataset_v2_20260504.py 먼저 실행하세요."
+        )
+    df = pd.read_csv(SPLIT_CSV, encoding="utf-8-sig")
+    df = df[df["split"] == split]
+    df = df[df["category"].isin(LABELS)]
+    return df["text"].tolist(), df["category"].tolist()
+
+
+# ──────────────────────────────────────────────────────────────────
+# Simple 모델 (TF-IDF + LogReg)
+# ──────────────────────────────────────────────────────────────────
+def train_simple() -> Pipeline:
+    """
+    v2 train 데이터로 베이스라인 재학습.
+
+    왜 재학습이 필요한가?
+      기존 simple_tfidf_logreg.pkl은 v1 데이터(244개) 기준으로 학습됨.
+      v2 데이터(556개 train)로 재학습해야 동일 조건의 비교가 가능.
+    """
+    texts, labels = load_split("train")
+    print(f"[simple] train 데이터: {len(texts)}개")
+
+    pipe = Pipeline([
+        ("tfidf", TfidfVectorizer(
+            analyzer="char_wb",
+            ngram_range=(2, 4),
+            max_features=30_000,
+            sublinear_tf=True,
+        )),
+        ("clf", LogisticRegression(
+            C=1.0,
+            max_iter=1000,
+            class_weight="balanced",
+            random_state=42,
+            solver="lbfgs",
+        )),
+    ])
+    pipe.fit(texts, labels)
+
+    SIMPLE_PKL.parent.mkdir(parents=True, exist_ok=True)
+    with open(SIMPLE_PKL, "wb") as f:
+        pickle.dump(pipe, f)
+    print(f"[simple] 모델 저장: {SIMPLE_PKL.name}")
+    return pipe
+
+
+def _load_simple() -> Pipeline:
+    if SIMPLE_PKL.exists():
+        with open(SIMPLE_PKL, "rb") as f:
+            return pickle.load(f)
+    return train_simple()
+
+
+def evaluate_simple(split: str = "test") -> dict:
+    """Simple 모델 평가 → 결과 dict 반환."""
+    texts, true_labels = load_split(split)
+    pipe = _load_simple()
+    pred_labels = pipe.predict(texts)
+
+    report = classification_report(
+        true_labels, pred_labels,
+        labels=LABELS,
+        output_dict=True,
+        zero_division=0,
+    )
+    cm = confusion_matrix(true_labels, pred_labels, labels=LABELS)
+    macro_f1 = f1_score(true_labels, pred_labels, labels=LABELS,
+                        average="macro", zero_division=0)
+
+    print("\n[Simple] 분류 리포트")
+    print(classification_report(true_labels, pred_labels, labels=LABELS, zero_division=0))
+
+    # 결과 구조 — 노트북 시각화와 호환되는 형식
+    result = {
+        "model":          "simple",
+        "macro_f1":       round(macro_f1, 4),
+        "macro_precision": round(report["macro avg"]["precision"], 4),
+        "macro_recall":   round(report["macro avg"]["recall"], 4),
+        "per_class": {
+            lbl: {
+                "precision": round(report[lbl]["precision"], 4),
+                "recall":    round(report[lbl]["recall"], 4),
+                "f1":        round(report[lbl]["f1-score"], 4),
+                "support":   report[lbl]["support"],
+            }
+            for lbl in LABELS
+        },
+        "confusion_matrix": cm.tolist(),
+        "labels":           LABELS,
+        "split_used":       split,
+        "data_version":     "v4_20260504",
+        "train_size":       len(load_split("train")[0]),
+        "test_size":        len(texts),
+    }
+    return result
+
+
+# ──────────────────────────────────────────────────────────────────
+# KcELECTRA 모델
+# ──────────────────────────────────────────────────────────────────
+def _kcelectra_ready() -> bool:
+    """
+    03_train_kcelectra_v2_20260504.ipynb 실행 후 생성되는 체크포인트 확인.
+    체크포인트 없으면 평가 스킵 — 에러 없이 진행.
+    """
+    try:
+        import torch  # noqa: F401
+        from transformers import AutoTokenizer  # noqa: F401
+    except ImportError:
+        print("[kcelectra] torch/transformers 미설치 — KcELECTRA 평가 스킵")
+        return False
+
+    required = [
+        KCELECTRA_CKPT / "config.json",
+        KCELECTRA_CKPT / "label2id.json",
+    ]
+    model_file = (
+        (KCELECTRA_CKPT / "model.safetensors").exists()
+        or (KCELECTRA_CKPT / "pytorch_model.bin").exists()
+    )
+    return all(f.exists() for f in required) and model_file
+
+
+def evaluate_kcelectra(split: str = "test") -> dict:
+    """
+    KcELECTRA 평가.
+    체크포인트 없거나 torch 미설치 → 빈 dict 반환 (스킵).
+
+    eval_results_kcelectra_20260504.json이 이미 있으면 재사용.
+    (Colab에서 학습 후 JSON만 복사해도 동작)
+    """
+    json_path = DATA_DIR / f"eval_results_kcelectra_{TS}.json"
+
+    # JSON 재활용 (Colab에서 다운로드해서 data/ 에 넣은 경우)
+    if json_path.exists():
+        print(f"[kcelectra] 기존 JSON 재활용: {json_path.name}")
+        with open(json_path, encoding="utf-8") as f:
+            return json.load(f)
+
+    if not _kcelectra_ready():
+        print("[kcelectra] 체크포인트 없음 — 03_train_kcelectra_v2_20260504.ipynb 실행 후 재시도")
+        return {}
+
+    # 체크포인트가 있을 때만 실행
+    import torch
+    from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+    texts, true_labels = load_split(split)
+
+    with open(KCELECTRA_CKPT / "label2id.json", encoding="utf-8") as f:
+        label2id: dict[str, int] = json.load(f)
+    id2label = {v: k for k, v in label2id.items()}
+
+    device    = "cuda" if torch.cuda.is_available() else "cpu"
+    tokenizer = AutoTokenizer.from_pretrained(str(KCELECTRA_CKPT))
+    model     = AutoModelForSequenceClassification.from_pretrained(
+        str(KCELECTRA_CKPT), num_labels=len(LABELS), ignore_mismatched_sizes=True
+    ).to(device)
+    model.eval()
+
+    pred_labels = []
+    with torch.no_grad():
+        for text in texts:
+            enc = tokenizer(text, return_tensors="pt",
+                            truncation=True, padding=True, max_length=128).to(device)
+            logits = model(**enc).logits
+            idx    = int(logits.argmax(dim=-1).item())
+            pred_labels.append(id2label.get(idx, "기타"))
+
+    report = classification_report(
+        true_labels, pred_labels,
+        labels=LABELS,
+        output_dict=True,
+        zero_division=0,
+    )
+    cm = confusion_matrix(true_labels, pred_labels, labels=LABELS)
+    macro_f1 = f1_score(true_labels, pred_labels, labels=LABELS,
+                        average="macro", zero_division=0)
+
+    print("\n[KcELECTRA] 분류 리포트")
+    print(classification_report(true_labels, pred_labels, labels=LABELS, zero_division=0))
+
+    result = {
+        "model":          "kcelectra",
+        "macro_f1":       round(macro_f1, 4),
+        "macro_precision": round(report["macro avg"]["precision"], 4),
+        "macro_recall":   round(report["macro avg"]["recall"], 4),
+        "per_class": {
+            lbl: {
+                "precision": round(report[lbl]["precision"], 4),
+                "recall":    round(report[lbl]["recall"], 4),
+                "f1":        round(report[lbl]["f1-score"], 4),
+                "support":   report[lbl]["support"],
+            }
+            for lbl in LABELS
+        },
+        "confusion_matrix": cm.tolist(),
+        "labels":           LABELS,
+        "split_used":       split,
+        "data_version":     "v4_20260504",
+    }
+    return result
+
+
+# ──────────────────────────────────────────────────────────────────
+# 저장 + 비교 출력
+# ──────────────────────────────────────────────────────────────────
+def save_and_compare(simple_res: dict, kcelectra_res: dict) -> None:
+    # Simple 결과 저장
+    simple_path = DATA_DIR / f"eval_results_simple_{TS}.json"
+    with open(simple_path, "w", encoding="utf-8") as f:
+        json.dump(simple_res, f, ensure_ascii=False, indent=2)
+    print(f"\n[저장] {simple_path.name}")
+
+    # KcELECTRA 결과 저장 (있을 때만)
+    kc_path = DATA_DIR / f"eval_results_kcelectra_{TS}.json"
+    if kcelectra_res:
+        with open(kc_path, "w", encoding="utf-8") as f:
+            json.dump(kcelectra_res, f, ensure_ascii=False, indent=2)
+        print(f"[저장] {kc_path.name}")
+
+    # 비교 요약 CSV
+    rows = [{"model": "Simple (TF-IDF + LR)", **_summary_row(simple_res)}]
+    if kcelectra_res:
+        rows.append({"model": "KcELECTRA (fine-tuned)", **_summary_row(kcelectra_res)})
+
+    summary_df = pd.DataFrame(rows)
+    summary_path = DATA_DIR / f"eval_comparison_summary_{TS}.csv"
+    summary_df.to_csv(summary_path, index=False, encoding="utf-8-sig")
+    print(f"[저장] {summary_path.name}")
+
+    # 채택 판정
+    print("\n" + "=" * 50)
+    print("  성능 비교 결과")
+    print("=" * 50)
+    print(f"  Simple    Macro F1 : {simple_res['macro_f1']:.4f}")
+    if kcelectra_res:
+        delta = kcelectra_res["macro_f1"] - simple_res["macro_f1"]
+        print(f"  KcELECTRA Macro F1 : {kcelectra_res['macro_f1']:.4f}")
+        print(f"  Delta              : {delta:+.4f}")
+        if delta >= 0.05:
+            print("  >> KcELECTRA 5%+ 향상: 채택 권장!")
+        elif delta >= 0:
+            print("  >> KcELECTRA 소폭 향상: 추가 데이터/튜닝 권장")
+        else:
+            print("  >> Simple 유지 권장")
+    else:
+        print("  KcELECTRA: 평가 미완료 (노트북 실행 후 재시도)")
+
+
+def _summary_row(res: dict) -> dict:
+    row = {
+        "macro_f1":        res.get("macro_f1", "-"),
+        "macro_precision": res.get("macro_precision", "-"),
+        "macro_recall":    res.get("macro_recall", "-"),
+    }
+    for lbl in LABELS:
+        row[f"f1_{lbl}"] = res.get("per_class", {}).get(lbl, {}).get("f1", "-")
+    return row
+
+
+# ──────────────────────────────────────────────────────────────────
+# CLI
+# ──────────────────────────────────────────────────────────────────
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--split", default="test", choices=["train", "val", "test"])
+    parser.add_argument("--retrain", action="store_true",
+                        help="Simple 모델 강제 재학습 (PKL 있어도 새로 학습)")
+    args = parser.parse_args()
+
+    print(f"평가 시작 — split: {args.split}, 데이터: v4_20260504")
+
+    # Simple 재학습 여부
+    if args.retrain and SIMPLE_PKL.exists():
+        SIMPLE_PKL.unlink()
+        print("[simple] 기존 PKL 삭제 → 재학습")
+
+    simple_res     = evaluate_simple(args.split)
+    kcelectra_res  = evaluate_kcelectra(args.split)
+
+    save_and_compare(simple_res, kcelectra_res)
+
+
+if __name__ == "__main__":
+    main()