# task-2252 완료 보고서

## SCQA

**S**: InsuRo 증권분석 기능이 Phase 2-1에서 분석 엔진까지 완성되었으나, 분석 결과가 user_id로만 관리되어 CRM 고객과 연결되지 않는 상태이다.

**C**: 동일 고객의 여러 증권분석 결과를 통합 조회할 수 없고, CRM 고객 상세에서 분석 이력을 볼 수 없어 실무 활용도가 낮다. 미등록 고객의 분석은 고아 데이터가 됨.

**Q**: policy_analyses에 customer_id FK를 추가하고, 고객 검색/선택 + 임시 등록 플로우를 구현하여 CRM-증권분석 연동을 완성할 수 있는가?

**A**: 마이그레이션 1건 + 백엔드 API 4개 + 프론트엔드 2개 파일 수정으로 완성. TSC exit 0, npm build 성공, 신규 API 3개 라우팅 확인.

---

## 작업 내용

### 1. DB 마이그레이션
- `supabase/migrations/20260427190000_policy_analyses_customer_id.sql`
- policy_analyses에 `customer_id uuid REFERENCES customers(id)` 컬럼 + 인덱스 추가

### 2. 백엔드 API (server/main.py)
- `POST /api/insuro/analyze-policy`: customer_id 파라미터 추가 (form-data)
- `POST /api/insuro/register-temporary-customer`: 임시 고객 등록 + 분석 연결
- `GET /api/insuro/customer-policy-analyses/{customer_id}`: 고객별 분석 이력 조회
- `GET /api/insuro/search-customers?q=`: CRM 고객 이름 검색

### 3. 프론트엔드 — PolicyAnalysis.tsx
- 기존 고객 검색/선택 UI (디바운스 300ms, 드롭다운 목록)
- 선택 시 고객명/생년월일 자동 입력 + customer_id 전달
- 분석 완료 후 미연결 시 "임시 고객 등록" 모달 표시

### 4. 프론트엔드 — CrmCustomerDetail.tsx
- "증권분석" 탭 추가 (10번째 탭)
- 고객별 분석 이력 시간순 표시 (완료/실패 뱃지, 보험사/상품명/보험료)

---

## 수정 파일 목록

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| supabase/migrations/20260427190000_policy_analyses_customer_id.sql | customer_id FK + index 마이그레이션 | grep "customer_id" OK | verified |
| server/main.py:4718 | analyze-policy에 customer_id 파라미터 추가 | grep "customer_id.*form.get" OK | verified |
| server/main.py:4789 | policy_analyses INSERT에 customer_id 포함 | grep '"customer_id": customer_id' OK | verified |
| server/main.py:4906 | register-temporary-customer 엔드포인트 | grep "register-temporary-customer" OK | verified |
| server/main.py:4945 | customer-policy-analyses 엔드포인트 | grep "customer-policy-analyses" OK | verified |
| server/main.py:4960 | search-customers 엔드포인트 | grep "search-customers" OK | verified |
| src/pages/PolicyAnalysis.tsx | 고객 검색/선택 UI + 임시 등록 모달 | grep "기존 고객 연결" OK | verified |
| src/pages/CrmCustomerDetail.tsx | 증권분석 이력 탭 추가 | grep "policy-analysis" OK | verified |

---

## 발견 이슈 및 해결

1. **pollStatus 정의 순서 문제 (TS2554)**: pollStatus에 3번째 인자(linkedCustomerId) 추가 후, startAnalysis보다 아래에 정의되어 TS 에러 발생 → pollStatus를 startAnalysis 위로 이동하여 해결
2. **customer_stage enum에 'temporary' 없음**: 별도 status 컬럼 추가 대신 tags 배열에 'temporary' 추가로 우회. 스키마 변경 최소화 + 기존 CRM 필터링 호환.
3. **기존 Pyright 경고 (main.py:908,920,922)**: ver_res.data/consent의 타입 관련 기존 이슈. 이번 작업 범위 밖 — 향후 별도 task로 처리 권장.

---

## L1 스모크테스트 결과
- 서버 재시작: 성공 (포트 8001, /api/status → 200)
- API 응답 확인:
  - `GET /api/insuro/search-customers?q=test` → 401 (인증 필수 확인)
  - `GET /api/insuro/customer-policy-analyses/test-id` → 401
  - `POST /api/insuro/register-temporary-customer` → 401
- TypeScript: `npx tsc --noEmit` → exit 0
- 빌드: `npm run build` → 성공 (12.02s, dist/ 생성)
- 스크린샷: L1 미통과 사유 — Supabase 환경 변수(VITE_SUPABASE_URL) 미설정으로 프론트엔드 렌더링 불가. 백엔드 API + 빌드 + TSC로 검증 대체.

---

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-2252-dev1
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-2252-dev1
- **커밋 수**: 5건
- **머지 의견**: TSC 통과, 빌드 성공, 신규 API 3개 라우팅 정상. 기존 코드 변경 최소화 (server/main.py에 71줄 추가). Gemini PR 리뷰 후 머지 권장.

---

## 모델 사용 기록
- 불칸(백엔드): sonnet — DB 마이그레이션 + API 4개 구현
- 이리스(프론트엔드): sonnet — PolicyAnalysis 고객선택 + CrmCustomerDetail 이력탭
- 헤르메스(팀장): opus — 설계/분배/검토/통합 + TS 에러 직접 수정 1건

## 세션 통계
- QC 결과: 8 PASS, 1 FAIL(git_evidence — 린팅 순환), 11 SKIP, 3 WARN
- 전체 테스트: 2521 passed (workspace), 7 passed (신규 API 테스트)
- TRUST 5차원: T✓ R✓ U✓ S✓ T✓


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


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


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