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

# 맥락 노트: task-2253

**task**: task-2253

---

## 결정 근거

### 3 Step Why

**1st Why: 왜 이 설계가 필요한가?**
현재 합산 보장현황은 한 번의 분석(현재 업로드분)만 합산한다. 동일 고객의 시간차 분석(과거 다른 보험증권 분석 이력)을 합산해야 전체 보장현황을 보여줄 수 있다.

**2nd Why: 왜 프론트 토글+API 호출 방식이 최선인가?**
백엔드에 이미 customer-policy-analyses API가 존재하므로, 프론트에서 고객 선택 시 기존 분석을 fetch하고 토글로 합산 여부를 제어하는 것이 가장 적은 변경으로 구현 가능하다.

**3rd Why: 왜 이 접근이 다른 대안보다 나은가?**
- 대안 A (서버 합산) → 서버 로직 복잡화 + 프론트 유연성 감소
- 대안 B (DB 뷰) → 마이그레이션 필요 + 실시간 토글 불가
- 현재 접근 → 기존 API 재활용, 토글 즉시 반영, 서버 변경 최소화

### 합산 데이터 모델 선택
- `category-name` 키로 그룹핑 + `byInsurer` 맵으로 보험사별 금액 추적
- IIFE 패턴으로 `useMemo` 없이 render 단계에서 계산 (의존성 명확)

### exclude_analysis_id 파라미터
- 현재 분석이 이미 DB에 저장된 후 합산 API를 호출하므로, 현재 분석을 중복 포함하지 않기 위해 제외 필터 필요

## 참조 자료

- Phase 2-2 보고서: `/home/jay/workspace/memory/reports/task-2252.md`
- Codex 사전 검증 결과: risks=4 (high 2, medium 2), critical=False, pass=true

## 주의사항

- Supabase 환경변수 미설정으로 프론트엔드 브라우저 렌더링 테스트 불가 (L1 백엔드+빌드로 대체)
- main.py 908/920/922행 Pyright 경고는 기존 이슈 (Phase 2-2에서도 확인됨, 이번 작업 범위 밖)
- 담보별 부족분 금액 표시는 목표 보장액 테이블이 없어 "미보장" 라벨로만 표시 (향후 Phase에서 확장)