---
task_id: task-2235
type: context
scope: task
created: 2026-04-27
updated: 2026-04-27
status: completed
---

# 맥락 노트: task-2235

**task**: task-2235

---

## 결정 근거

### 3 Step Why

**1st Why**: "왜 이 설계가 필요한가?"
→ 보험 설계사가 고객의 기존 증권을 분석하여 보장 현황을 한눈에 파악하고, 구글시트 양식으로 내보내 업무에 활용할 수 있어야 한다.

**2nd Why**: "왜 AI 기반 증권 분석이 최선인가?"
→ 증권 PDF는 보험사마다 양식이 다르고, 담보 명칭도 비표준화. Claude의 PDF 읽기 + 표준 담보 리스트 매핑으로 정확하고 빠른 구조화 가능.

**3rd Why**: "왜 기존 생성 큐를 활용하되 파일 단위 구조로 설계하는가?"
→ Codex 리뷰에서 지적한 대로, 단일 레코드 구조로는 다중 증권 관리/부분 실패/재분석이 어렵다. 결과를 JSON 배열(파일별)로 저장하고 합산은 런타임 계산으로 분리.

### 기존 큐 시스템 활용 결정
- 기존 `generation_queue.py`의 세마포어 기반 큐를 그대로 활용
- 신규 큐 시스템 구축보다 기존 검증된 패턴 재사용이 안전
- 향후 큐 분리가 필요하면 별도 리팩토링

### Codex 리뷰 리스크 대응
- critical (코드 미존재): 구현 완료로 해소
- high (큐 패턴): 기존 generation_queue 활용으로 해소
- high (다중 PDF 스키마): result를 JSONB 배열로 저장, 합산은 프론트에서 계산
- high (AI 출력 계약): validate_analysis_result()로 필수 필드 검증 + 정규화
- medium (민감정보): PDF는 임시파일로만 처리 (저장 안 함), DB에는 분석 결과 JSON만 저장
- medium (설정 충돌): Phase 1에서는 기본 설정만 제공, 커스텀 CRUD는 기본 구현

## 참조 자료

- 프롬프트 v3.7: `/home/jay/workspace/memory/specs/insuro-policy-analysis-prompt-v3.7.md`
- 구글시트 양식: `https://docs.google.com/spreadsheets/d/1b2nFuQEwlNT6oIlSqBpXv88nNkO3iVt3ousCEja4lbQ/edit?gid=410241279`

## 주의사항

- Supabase 테이블(`policy_analyses`, `user_policy_settings`)은 별도 마이그레이션으로 생성 필요
- main.py의 line 1070/1103 pyright 에러는 기존 Supabase 타입 이슈 (이번 작업 범위 외)
- 서버 환경에서 `.env.keys`가 필요 (Supabase URL, JWT 시크릿 등)