# InsuWiki AI 노드 자동 연결 — 체크리스트

**버전**: v1.2
**작성일**: 2026-03-22
**갱신일**: 2026-03-23

---

## Phase 0: 보안 기초 ✅ (task-820.1 완료)

- [x] Firestore Rules 수정 — links 컬렉션 write validation
  - [x] confidence 범위 검증 (0-100)
  - [x] method 허용값 검증 ("manual"|"static"|"embedding"|"semantic")
  - [x] createdBy 필수 필드 검증
- [x] links 스키마 문서 작성
- [x] 기존 links 데이터 백필 스크립트 (`scripts/backfill-links-schema.ts`)
- [x] Rules 테스트 통과

---

## Phase 1-A: 정적 매칭 ✅ (task-820.1 완료)

- [x] Cloud Function `staticMatching.ts` — 4단계 매칭 로직
  - [x] insurance_terms 메모리 캐싱 (TTL 1h)
  - [x] exact match (100) / alias (90) / 공백제거 (85) / substring (70)
- [x] Firestore onWrite 트리거 구현
- [x] ai_suggestions 서브컬렉션 결과 저장
- [x] `RelatedDocsSidebar.tsx` — 추천 UI + 승인/거부
- [x] 테스트 43/43 통과 (BE 22 + FE 21)
- [x] config 시딩 스크립트 작성 (`seed-ai-linking-config.ts`, `seed-normalize-map.ts`)

---

## ★ 선행 작업 (BLOCKER) — ✅ 완료 (task-827.1)

### B1. insurance_terms 컬렉션 시딩 ✅
- [x] 보험 용어 사전 구축: 1,100개+ (12개 카테고리)
- [x] 시딩 스크립트 작성: `scripts/seedInsuranceTerms.ts`
- [x] Firestore 적재 완료: 1,192건 (upsert 후 유니크)

### B2. config 문서 시딩 ✅
- [x] config/aiLinking 생성 (기존+신규 필드 통합)
- [x] config/normalizeMap 생성 (616개 매핑)

### B3. 정규화 테이블 ✅
- [x] normalizeMap 자동 생성 (593 alias + 23 하드코딩)

### B4. 기존 데이터 백필
- [x] links 0건이므로 실행 불필요 확인

---

## ★ Go/No-Go 게이트 ✅ PASS (task-827.1)

- [x] 검증 스크립트 작성 (`scripts/evaluate-static-matching.ts`) — task-822.1
- [x] 검증 테스트 9/9 통과 — task-822.1
- [x] 선행 작업(B1~B3) 완료 후 재실행 — task-827.1
- [x] 50건 실측 완료: 965건 매칭
- [x] Precision: **100%** (965/965) — 80%+ 기준 초과 달성
- [x] **판정: Phase 1-B 진행 가능**

### ⚠️ 미해결 (TODO)
- [ ] **Recall 측정**: manual 링크(gold standard) 0건으로 recall 미산출
  - 해결: InsuWiki 문서 10~20개 선정 → 수동 gold standard 링크 생성 → recall 측정
  - 시점: Phase 1-B 진행 중 또는 이후 콘텐츠 큐레이션 시

---

## Phase 1-B: 임베딩 유사도 추천 ✅ (task-829.1 완료)

- [x] content_hash(SHA-256) 필드 추가 — computeContentHash() + onWrite 트리거
- [x] embedding_hash 불일치 감지 → lazy 재생성 로직 — shouldRegenerateEmbedding()
- [x] Firestore Vector Search 쿼리 구현 — findNearest(COSINE, distanceThreshold)
- [x] 정적 매칭 + 임베딩 결과 병합 (method 필드로 구분) — mergeResults()
- [x] 신뢰도 UI 업데이트 (config 외부화) — method별 SVG 아이콘 + getDoc config
- [x] precision@5 검증 실행 완료 (50건, task-832.1)
  - embeddingMatching.enabled → true 활성화 완료
  - Precision@5 (병합): 42.26% (71/168) — 70% 미달
  - 원인: 정적 매칭 termId ≠ documents ID (임베딩 매칭 유효성: 100%)
  - 임베딩 추가 발견률: 11.06% (120건)
  - 판정: 임베딩 매칭 자체는 정상 동작, precision 지표 재정의 필요
  - 발견 이슈: text-embedding-004 모델 deprecated → gemini-embedding-001 마이그레이션 필요
- [x] 임베딩 모델 마이그레이션: text-embedding-004 → gemini-embedding-001 (3072차원) (task-833.1)
- [x] Firestore vector index: embeddings 컬렉션 3072차원 index 설정 추가 (task-833.1)
- [x] Precision 지표 분리: 정적(insurance_terms 존재)/임베딩(documents 존재)/병합 별도 측정 (task-833.1)

---

## Phase 2: 아누 서버 Claude 연동 (Phase 1-B 검증 후)

- [ ] 아누 서버 REST 엔드포인트 구축
  - [ ] POST /api/v1/insuwiki/recommend
  - [ ] HMAC-SHA256 인증
  - [ ] Cloud Secret Manager 키 관리 (90일 로테이션)
- [ ] Cloud Function → 아누 서버 호출 구현
  - [ ] timeout 10초
  - [ ] graceful degradation (정적 매칭 fallback)
  - [ ] aiStatus 필드 반환
- [ ] uid 기반 rate limit (분당 5건)
- [ ] 관계 환각 방어
  - [ ] Claude에 설명 강제
  - [ ] 설명 품질 검증 로직
  - [ ] AI 링크 status: "pending" 관리
- [ ] Firestore 주기적 export 백업 설정
- [ ] 추천 품질 Phase 1-B 대비 향상 확인

---

## Phase 3: 지식 그래프 자동 구축 (Phase 2 완료 후)

- [ ] 전체 문서 관계망 데이터 구조 설계
- [ ] 그래프 시각화 UI
- [ ] 고아 노드 감지 + 연결 제안
- [ ] 순환 참조 감지
- [ ] 고아 노드 0 확인