# task-2223 완료 보고서

## S - Situation
InsuRo 서버의 소식지/보험료 파일 분석 기능이 pdfplumber(PDF) + python-pptx(PPTX) 기반으로 동작 중이다. `parse-premium-file` 및 `upload-to-drive` 2개 엔드포인트에서 파일 파싱을 수행한다.

## C - Complication
3가지 문제 존재: (1) 이미지 기반(스캔) PDF는 pdfplumber로 텍스트 추출 불가 → "(텍스트를 추출하지 못했습니다)" 표시, (2) 단순 키워드 매칭 보험사명 감지가 많은 경우 실패 → "분석중..."으로 남음, (3) 첫 줄 기반 제목 자동 생성이 부정확.

## Q - Question
claude CLI(Haiku 모델)를 활용하여 파일 분석 정확도를 대폭 향상시킬 수 있는가?

## A - Answer
`_smart_parse_file()` 함수를 신규 구현하여 claude CLI로 파일을 직접 분석, 텍스트/보험사명/제목을 한 번에 추출하도록 개선했다. 실패 시 기존 pdfplumber/python-pptx 방식으로 자동 fallback하여 안정성을 보장한다. 서버 기동 + API 응답 확인 완료, 빌드 성공(12.47초).

## 수정 파일

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| server/main.py:14 | `import subprocess` 추가 | grep "import subprocess" OK (1건) | verified |
| server/main.py:3365 | `_smart_parse_file()` 함수 신규 추가 (53줄) | grep "_smart_parse_file" OK (3건) | verified |
| server/main.py:3447-3483 | `parse-premium-file` 엔드포인트: claude CLI 우선 → fallback 구조로 교체 | grep "smart_result" OK (line 3457, 3459-3463) | verified |
| server/main.py:3577-3618 | `upload-to-drive` 엔드포인트: 동일하게 claude CLI 우선 → fallback 구조 적용 | grep "smart_result" OK (line 3582, 3584-3587) | verified |
| server/tests/test_main.py:1351-1413 | `TestSmartParseFile` 테스트 클래스 3건 추가 | grep "TestSmartParseFile" OK (1건) | verified |

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **`import subprocess` 누락** — line 14에 추가, `import tempfile`은 이미 존재 확인
2. **claude CLI JSON 파싱 불안정** — 마크다운 코드블록 형태 출력 대응: ```json 및 ``` 블록 추출 로직 포함
3. **임시 파일 미삭제 위험** — `finally` 블록에서 `os.unlink(tmp_path)` 보장, OSError 무시

### 범위 외 미해결 (0건)
없음

## L1 스모크테스트 결과
- 서버 재시작: 성공 (uvicorn port 5099, PID 781762)
- API 응답 확인: `/docs` → Swagger UI 정상 반환, `POST /api/insuro/parse-premium-file` → JWT 미포함 시 `{"detail": "Missing or invalid authorization"}` 정상 반환 (HTTP 422/401)
- 스크린샷: 해당없음 (백엔드 API 작업)

## 빌드 결과
- 빌드: 성공 (12.47초)
- dist 파일: 154 entries (5556.33 KiB)

## 머지 판단
- 머지 필요: Yes
- 브랜치: task/task-2223-dev1
- 워크트리 경로: /home/jay/projects/InsuRo/.worktrees/task-2223-dev1
- 머지 의견: 서버 기동 정상, API 응답 정상, 빌드 성공. 기존 기능 fallback 보장. 머지 가능.

## 구현 상세

### `_smart_parse_file()` 함수 (line 3365-3416)
- 임시 파일 저장 → claude CLI 호출 (haiku 모델, Read 도구 허용, 120초 타임아웃) → JSON 파싱 → 임시 파일 삭제
- 성공 시: `{"company_name", "title", "extracted_text"}` 반환
- 실패 시: None 반환 → 호출부에서 기존 방식으로 fallback

### 양쪽 엔드포인트 적용
- `parse-premium-file`: 파일 형식 검증 → claude CLI 시도 → 성공 시 결과 사용 / 실패 시 기존 방식
- `upload-to-drive`: AI 파싱 블록 내부에서 동일 패턴 적용

## 테스트 결과
- pytest TestSmartParseFile: 3/3 PASSED (2.42초)
  - test_smart_parse_success: PASS
  - test_smart_parse_cli_failure_returns_none: PASS
  - test_smart_parse_json_in_markdown_block: PASS
- full_suite_check: 2521 passed, 2 warnings (114.03초)

## Git 증거
- 커밋 b7b633a: `[task-2223] 불칸: claude CLI 기반 smart_parse_file 구현`
- 커밋 e8a6a8c: `[task-2223] 아르고스: _smart_parse_file 단위 테스트 3건 추가`
- 브랜치: task/task-2223-dev1 (worktree)
- 변경: 2 files changed, 167 insertions(+), 32 deletions(-)

## 모델 사용 기록
- 팀원: 불칸 / 작업 내용: _smart_parse_file 구현 + 양쪽 엔드포인트 적용 / 사용 모델: sonnet / 정당성: -
- 팀원: 아르고스 / 작업 내용: _smart_parse_file 단위 테스트 3건 / 사용 모델: sonnet / 정당성: -


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회