---
task_id: task-2249
type: context
scope: task
created: 2026-04-27
updated: 2026-04-27
status: in-progress
---

# 맥락 노트: task-2249

**task**: task-2249

---

## 3 Step Why

### 1st Why: "왜 이 설계가 필요한가?"
A: 현재 증권분석 결과에서 (1) 납입잔여가 단순 total_payment_years만 표시되어 정확하지 않고, (2) AI가 감지한 담보만 표시되어 미가입 담보 파악 불가하며, (3) 원본 PDF를 다시 볼 수 없어 FA의 업무 효율이 저하됨.

### 2nd Why: "왜 A가 최선의 접근인가?"
B: 서버에서 납입잔여를 계산하는 이유는 enrollment_date와 base_date가 이미 서버 응답에 있으므로 서버에서 계산 후 반환하면 프론트 로직이 단순해짐. 미가입 담보는 프론트에서 defaultCoverages와 대조하는 것이 적절 (서버 비의존). 원문보기는 분석 시 임시 파일을 Drive에 업로드하는 기존 패턴을 활용.

### 3rd Why: "왜 B가 다른 대안보다 나은가?"
C: 대안 1 "프론트에서 납입잔여 계산" → enrollment_date 파싱이 복잡하고 프론트 책임 과다. 대안 2 "서버에서 미가입 담보 계산" → 표준 담보 리스트가 이미 프론트 config에 있으므로 불필요한 서버 의존. 대안 3 "원문보기 없이 다시 업로드" → UX 저하. 현재 설계가 책임 분리와 기존 인프라 활용 측면에서 최적.

→ A-B-C 논리적 일관성 확인: 서버/프론트 책임 분리 원칙 유지, 기존 인프라 활용 극대화

## 결정 근거

### 납입잔여 계산을 서버 side에서 수행
- 이유: enrollment_date 파싱("2008. 3. 31" 형식)이 서버 Python에서 더 안정적
- 대안: 프론트에서 계산 → enrollment_date 포맷 불확실성으로 기각

### 원문보기 구현 — 임시 파일 방식 채택
- 이유: 기존 upload-to-drive 인프라 활용 가능. 분석 시 Google Drive에 업로드 후 URL 반환
- 대안: 서버 로컬 임시 저장 → 서버 재시작 시 유실 위험으로 기각. Drive 업로드가 더 안정적

### 미가입 담보 표시는 프론트에서 처리
- 이유: defaultCoverages.ts가 이미 존재, 서버 의존 없이 프론트에서 대조 가능
- 대안: 서버에서 전체 담보 리스트 반환 → 불필요한 데이터 전송, 기각

## 참조 자료

- 표준 담보 리스트: `src/config/defaultCoverages.ts`
- 서버 분석기: `server/policy_analyzer.py`
- 증권분석 엔드포인트: `server/main.py:4707` (analyze-policy)
- Google Drive 업로드: `server/main.py:4067` (upload-to-drive)

## 주의사항

- enrollment_date 포맷이 "YYYY. M. D" 형식 (공백 포함) — 파싱 시 주의
- total_payment_years가 0인 경우 (일시납) 처리 필요
- 기존 Drive 업로드 로직(gdrive.upload_pdf)은 이미 import되어 사용 가능
- analyze-policy 내부에서 임시파일 삭제(os.unlink) 전에 Drive 업로드 필요