---
task_id: task-2359
type: context
scope: task
created: 2026-05-02
updated: 2026-05-02
status: completed
---

# 맥락 노트: task-2359 — Phase 3 CRM 자동 연동

**task**: task-2359

---

## 결정 근거

### 매칭 lookup 시점 — 캡처 직후 동기 처리
- POST /api/insuro/ohmy-capture가 INSERT 직후 customers를 (agent_id, customer_key_hash)로 조회
- match 발견 → confirm 대기 (customer_id 자동 매핑 X) — 회장 결정 #3 동명이인 안전장치
- match 미발견 → 즉시 upsert + history.customer_id UPDATE
- 대안 (별도 lookup endpoint) 기각 — 캡처 직후 사용자가 /composite-design 진입 시 dialog 자동 노출이 단순

### auto-link customers row 컬럼 채움 정책
- 평문 customers 흐름 호환 (Phase B 운영 마이그레이션 예정)
- name/birth_date 평문 + encrypted_name/encrypted_dob/customer_key_hash 신규 컬럼 dual-write
- stage='lead', tags=['temporary', 'auto_ohmy']
- 사유: Phase 3는 임시 통합. 본격 보안은 Phase B(메가 프로젝트)에서

### duplicate 분기 auto-link (마아트 권고 즉시 반영)
- 같은 capture_hash 재캡처 시 INSERT 23505 — 기존 capture row가 customer_id NULL이고 customers 매칭도 없으면 동일하게 auto-link
- 사유: 정상 INSERT 분기와 동작 일관성 보장

### CompositeDesign 매칭 dialog 자동 검출
- 별도 GET endpoint 없이 captureHistory list 내 customer_key_hash 그룹의 customer_id 있는 항목을 matchCandidate로 추출
- shownMatchDialogIds useRef Set으로 1회 표시 (사용자 "취소" 시 재표시 X)
- 사유: 백엔드 API 표면 최소화

### CRM 페이지 통합 — Dialog 기반
- CrmCustomerDetail 별도 페이지 없음 → CrmCustomers row 액션 버튼 → Dialog로 history 표시
- 사유: 기존 페이지 구조 보존, 라우팅 변경 최소

### POST /link 엔드포인트 분리 (캡처와 매칭 분리)
- ohmy-capture POST는 idempotent + match 정보만 반환
- 실제 customer_id 매핑은 사용자 confirm 후 POST /link로 분리
- 사유: 사용자 의사결정 후의 명시적 액션 + 동명이인 신규 등록 분기 가능

## 참조 자료

- 시스템 3문서: `memory/plans/insuro-composite-design/`
- 메가 프로젝트 3문서: `memory/plans/customer-mgmt-integration/`
- task-2354 Phase 1 보고서: `memory/reports/task-2354.md`
- task-2356 Phase 2 보고서: `memory/reports/task-2356.md`
- 보고서: `memory/reports/task-2359.md`
- 워크트리: `/home/jay/projects/InsuRo/.worktrees/task-2359-dev6` (브랜치 `task/task-2359-dev6`)

## 주의사항

- customers PII는 **여전히 평문** 컬럼 dual-write. Phase B에서 본격 마이그레이션
- 매칭 lookup이 실패하면 캡처 자체는 성공해야 함 (try/except로 감쌌음)
- Phase 3 → Phase 4 진행 전 회장 검증 필수: CRM 자동 등록 시범 + 동명이인 confirm UX
- vitest 3건 기존 환경변수 미설정 FAIL은 본 task와 무관 (Phase 3 신규 16건 전부 PASS)