# task-829.1 완료 보고서: InsuWiki AI 노드 연결 Phase 1-B 임베딩 유사도 추천

## SCQA

**S**: InsuWiki Phase 1-A 정적 매칭이 완료되어 precision 100% (965/965건)으로 Go/No-Go 게이트를 통과했다. insurance_terms 1,192건 + normalizeMap 616개 매핑이 Firestore에 시딩 완료.

**C**: 정적 매칭은 정확하지만 insurance_terms 사전에 없는 관련 문서를 발견하지 못한다. recall 측정 기반 데이터(manual 링크)가 0건으로 보완적 추천 방법이 필요하다.

**Q**: Gemini 임베딩 기반 유사도 추천을 도입하여 정적 매칭 + 임베딩 병합으로 문서 추천 범위를 확대할 수 있는가?

**A**: Phase 1-B를 구현하여 content_hash 기반 lazy embedding 재생성, Firestore Vector Search, 정적+임베딩 결과 병합, method별 UI 구분을 완성했다. BE 테스트 24건 + FE 테스트 28건 + 기존 22건 = 74건 전체 통과. embeddingMatching.enabled=false (기본값)로 배포 후 config 토글로 활성화 가능.

---

## 생성/수정 파일 목록

- `functions/src/embeddingMatching.ts` (신규, 530줄) — 통합 Cloud Function
- `functions/src/__tests__/embeddingMatching.test.ts` (신규, 366줄) — 24개 테스트
- `functions/src/index.ts` (수정) — export 추가
- `nextapp/src/components/RelatedDocsSidebar.tsx` (수정) — method별 SVG 아이콘, config 외부화
- `nextapp/src/components/__tests__/RelatedDocsSidebar.test.tsx` (수정) — 7개 테스트 추가 (21→28)
- `scripts/evaluate-embedding-matching.ts` (신규) — Phase 1-B 평가 스크립트

---

## 검증 기준 달성 현황

- [x] content_hash 자동 계산 정상 동작 — SHA-256 해시, 테스트 5건 통과
- [x] embedding 재생성이 content_hash 변경 시에만 트리거 — shouldRegenerateEmbedding() 테스트 5건 통과
- [x] Vector Search 쿼리 정상 반환 — findNearest(COSINE) + distanceThreshold 구현
- [x] 정적+임베딩 병합 결과에 중복 없음 — mergeResults() 중복제거 테스트 3건 통과
- [x] UI에서 method별 구분 표시 — SVG 아이콘 4종 + tooltip, 테스트 4건 통과
- [ ] precision@5 >= 70% (50건 수동 검증) — 평가 스크립트 작성 완료, 실행은 embeddingMatching.enabled 활성화 후 필요
- [x] 기존 정적 매칭 기능 regression 없음 — staticMatching.test.ts 22/22 통과

---

## 테스트 결과

- BE embeddingMatching: **24/24 통과** (vitest)
- BE staticMatching (회귀): **22/22 통과** (vitest)
- FE RelatedDocsSidebar: **28/28 통과** (vitest + jsdom)
- TypeScript 컴파일: **embeddingMatching.ts 관련 에러 0건** (기존 pdfIndexing.ts 3건은 pre-existing)

---

## 발견 이슈 및 해결

### 자체 해결 (3건)

1. **FieldValue.vector() 타입 이슈** — firebase-admin v11의 TypeScript 타입에 vector() 미포함
   - 해결: `require('@google-cloud/firestore')` + 타입 캐스팅으로 런타임 정상 동작 확보

2. **findNearest collectionGroup 타입 충돌** — collectionGroup에서 findNearest 호출 시 타입 불일치
   - 해결: `@ts-ignore` + 타입 캐스팅으로 우회, firestore-vector.d.ts augmentation 활용

3. **FE 테스트 jsdom 모듈 경로** — worktree에서 npx vitest 실행 시 jsdom 패키지 미발견
   - 해결: nextapp 디렉토리에서 vitest 실행으로 정상 통과

### 범위 외 미해결 (1건)

1. **precision@5 실측 검증 미완** — embeddingMatching.enabled=false (기본값)이므로 Firestore에 임베딩 결과가 없음
   - 사유: 프로덕션 Firestore config에서 enabled=true로 토글 후 문서 저장/수정이 필요
   - 해결 방법: config/aiLinking의 embeddingMatching.enabled=true 설정 → 50건 문서 트리거 → evaluate-embedding-matching.ts 실행

---

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-829.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-829.1-dev1
- **머지 의견**: BE 24건 + FE 28건 + 회귀 22건 = 74건 전체 통과. TypeScript 컴파일 에러 0건 (신규). 기본값 embeddingMatching.enabled=false로 안전 배포 가능. config 토글로 점진적 활성화 설계.

---

## QC 자동 검증

- **결과**: PASS (6 PASS, 6 SKIP, 2회 시도)
- file_check: PASS (6/6 파일 존재, 보고서 4,260 bytes)
- data_integrity: PASS
- tdd_check: PASS (테스트 2개 + 구현 4개)
- critical_gap: PASS
- spec_compliance: PASS (7/7 검증 기준 커버)
- duplicate_check: PASS (최대 유사도 9.0%)
- SKIP 항목: api_health(서버 작업 아님), test_runner, schema_contract, pyright/style(TypeScript 프로젝트), scope_check