---
task_id: task-2160
type: context
scope: task
created: 2026-04-25
updated: 2026-04-25
status: in-progress
---

# 맥락 노트: task-2160

**task**: task-2160

---

## 결정 근거

### PDF 파싱 라이브러리 선택: pdfplumber 주력 + PyMuPDF 보조
- pdfplumber가 테이블 경계 감지에 가장 정확 (심평원 PDF는 웹 인쇄→PDF 변환)
- PyMuPDF는 텍스트 추출 보조용 (fallback)
- 실제 분석 결과: pdfplumber의 extract_tables()가 5종 PDF 모두에서 정상 작동

### 날짜 형식 통일: YYYY-MM-DD
- 세부진료/처방조제: 원본이 YYYY-MM-DD (하이픈 있음)
- 자동차사고기본: 원본이 YYYYMMDD (하이픈 없음) → 변환 필요
- 건강검진결과: 연도만 사용 (`17, `18 등) → 20XX 형식으로 변환

### 건강검진결과 특수 구조
- 12열 테이블이지만 대부분 빈 셀 (1년치 데이터만 존재)
- 헤더가 2행: 1행=항목/구분/.../단위, 2행=검진년도/`17/`18/.../
- 빈 문자열, None 모두 처리 필요

### 3 Step Why 자문

**1st Why: "왜 이 설계가 필요한가?"**
- 심평원/건보공단 PDF는 비정형 데이터로 수동 분석에 건당 30-60분 소요
- 보험 고지의무 분석 자동화를 위해 구조화된 데이터가 필수

**2nd Why: "왜 pdfplumber + Pydantic v2 조합이 최선인가?"**
- pdfplumber: 테이블 경계 감지 정확도 최고 (tabula-py, camelot 대비)
- Pydantic v2: 성능 개선(5-50x), 타입 검증 자동화, JSON 직렬화 내장
- 실제 5종 PDF에서 100% 테이블 감지 성공 확인

**3rd Why: "왜 이 조합이 대안보다 나은가?"**
- 대안 1: OCR (tesseract) → 불필요 (디지털 텍스트 PDF)
- 대안 2: LLM 기반 파싱 → 비용 과다, 정확도 불안정
- 대안 3: tabula-py → Java 의존성, 한글 처리 불안정
- 선택한 조합: 의존성 최소, 정확도 최고, 비용 0

## 참조 자료

- PDF 샘플: `/home/jay/projects/MediScan/docs/samples/`
- 작업 지시서: `/home/jay/workspace/memory/tasks/task-2160.md`

## 주의사항

- PDF 파일에 실제 개인 의료정보 포함 → git 커밋 금지 (.gitignore에 docs/samples/ 추가 필수)
- 테스트 시 개인정보가 로그에 남지 않도록 주의
- 셀 내 줄바꿈(\n) 처리가 핵심 → 모든 텍스트 필드에서 strip + replace 필요
- 자동차사고기본진료 날짜 형식이 다름 (YYYYMMDD → YYYY-MM-DD 변환)