# InsuWiki AI 노드 자동 연결 — 남은 Phase 전체 (한정승인)

## 개요
Phase 0 + Phase 1-A가 머지 완료되었다. 남은 Phase를 **끝까지 진행**하라.
각 Phase를 팀장이 자율적으로 순차 진행한다. Phase 완료마다 .done 통보.

## 참조 문서 (반드시 읽고 시작)
- 계획서: `/home/jay/workspace/memory/plans/insuwiki-ai-linking/plan.md`
- 체크리스트: `/home/jay/workspace/memory/plans/insuwiki-ai-linking/checklist.md`
- 맥락노트: `/home/jay/workspace/memory/plans/insuwiki-ai-linking/context-notes.md`
- 미팅 기록: `/home/jay/workspace/memory/meetings/2026-03-22-insuwiki-ai-auto-linking.md`

## 프로젝트 경로
- InsuWiki: `/home/jay/projects/insuwiki/`
- 현재 브랜치: master (Phase 0+1-A 머지 완료)

## Phase 1-A 구현 완료 내역 (참고)
- `functions/src/staticMatching.ts` — 4단계 매칭 Cloud Function
- `nextapp/src/components/RelatedDocsSidebar.tsx` — 추천 사이드바 UI
- `firestore.rules` — links validation 추가
- `nextapp/src/types/firestore.ts` — Link/AiSuggestion 타입
- config/aiLinking, config/normalizeMap — Firestore 설정 문서

---

## Phase 순서

### Phase 1: Go/No-Go 게이트 검증
Phase 1-A의 정적 매칭 품질을 검증한다.

1. InsuWiki 기존 문서 50건을 대상으로 정적 매칭 실행
2. 매칭 결과의 precision과 recall 측정
   - precision: 추천된 것 중 실제로 관련 있는 비율
   - recall: 관련 있는 것 중 추천된 비율
3. 검증 스크립트 작성 (`scripts/evaluate-static-matching.ts`)
4. 결과 보고서 작성

**판정 기준:**
- 정확도 80%+ → Phase 1-B 진행
- 정확도 60-80% → 정규화 테이블 보강 후 재측정
- 정확도 <60% → 보고 후 대기 (Phase 1-B 진행하지 말 것)

⚠️ 60% 미만이면 반드시 멈추고 보고만 할 것. 자의적 판단으로 진행 금지.

### Phase 1-B: 임베딩 유사도 추천 (Go/No-Go 통과 시)

1. **content_hash 필드 추가**
   - documents 컬렉션에 `contentHash` 필드 (SHA-256)
   - 문서 저장 시 title + content + tags 해시 생성
   - 기존 embeddings 서브컬렉션의 embedding_hash와 비교하여 stale 감지

2. **임베딩 lazy 재생성**
   - 추천 요청 시 contentHash 불일치 감지 → 이번 요청은 정적 매칭만 반환
   - 백그라운드에서 Gemini embedding API로 재생성
   - 다음 요청부터 임베딩 기반 추천 반영

3. **Firestore Vector Search 쿼리**
   - 기존 embeddings 서브컬렉션(768-dim Gemini) 활용
   - 유사 문서 Top-K 검색 (K = config.maxSuggestions)
   - 정적 매칭 결과와 병합 (method 필드로 구분)
   - 중복 제거: 같은 target 문서가 static + embedding으로 나오면 더 높은 confidence 유지

4. **UI 업데이트**
   - RelatedDocsSidebar에 method 뱃지 구분 ("용어 매칭" vs "AI 유사도")
   - 신뢰도 임계값 config에서 로드 (minConfidence, autoApproveThreshold)

5. **테스트**
   - 임베딩 매칭 단위 테스트
   - precision@5 70%+ 수동 검증 (50건)

**완료 기준**: precision@5 70%+ 확인

### Phase 2: 아누 서버 Claude 연동

1. **아누 서버 REST 엔드포인트**
   - `POST /api/v1/insuwiki/recommend`
   - 요청: `{ docId, title, content, type: "semantic", existingLinks: [...] }`
   - 응답: `{ suggestions: [{ targetId, confidence, explanation }], aiStatus: "ok" }`
   - 이 엔드포인트는 아누 서버 측 구현이 필요하므로, **InsuWiki Cloud Function 측 호출 코드만 구현**
   - 아누 서버 엔드포인트가 아직 없으면 mock으로 테스트

2. **HMAC-SHA256 인증**
   - Cloud Function에서 서명 생성 (timestamp + body)
   - 키는 Cloud Secret Manager 또는 Firebase Functions config로 관리
   - 키 값은 임시 placeholder 사용 (실제 키는 나중에 설정)

3. **Cloud Function 통합**
   - staticMatching에 semantic 분석 호출 추가
   - timeout 10초, 재시도 금지
   - 아누 다운 시 graceful degradation: 정적+임베딩 결과만 반환 + `aiStatus: "unavailable"`

4. **uid 기반 rate limit**
   - Firestore `rateLimits/{uid}` 문서로 분당 5건 제한
   - 초과 시 AI 추천 스킵 (정적+임베딩만 반환)

5. **관계 환각 방어**
   - AI 생성 링크는 status: "pending"으로 저장 (자동 반영 금지)
   - explanation 필드 필수 (설명 없는 추천 거부)
   - 사이드바에 AI 추천 설명 표시

6. **테스트**
   - HMAC 서명 검증 테스트
   - rate limit 테스트
   - graceful degradation 테스트
   - 추천 품질 Phase 1-B 대비 향상 확인

### Phase 3: 지식 그래프 자동 구축

1. **전체 문서 관계망 데이터**
   - links 컬렉션 전체를 읽어 그래프 구조 생성
   - 노드 = 문서, 엣지 = link (method/confidence 포함)

2. **그래프 시각화 UI**
   - D3.js 또는 react-force-graph 등 라이브러리 활용
   - 줌/팬/드래그 인터랙션
   - 노드 클릭 시 해당 문서로 이동
   - method별 엣지 색상 구분

3. **고아 노드 감지**
   - incomingLinkCount === 0이고 outgoingLinks가 없는 문서
   - 고아 노드에 연결 제안 (정적 매칭 + 임베딩)

4. **순환 참조 감지**
   - A→B→C→A 같은 순환 경로 탐지
   - 관리자에게 알림 (문제는 아니지만 인지 필요)

5. **테스트**
   - 그래프 렌더링 테스트
   - 고아 노드 감지 로직 테스트
   - 순환 참조 감지 테스트

---

## 공통 규칙

1. **각 Phase 완료 시 .done 통보** (task-timer end + .done 파일)
2. **Phase 간 순차 진행** — 이전 Phase 완료 + 머지 후 다음 Phase
3. Phase마다 별도 worktree 브랜치 사용
4. 기존 InsuWiki 기능 회귀 금지
5. Phase 1-A에서 구현한 코드/타입/컴포넌트를 최대한 활용 (중복 구현 금지)
6. 한국어 형태소 분석기 사용 금지
7. Go/No-Go 게이트에서 60% 미만이면 반드시 멈출 것

## 완료 후
- 각 Phase 보고서: `memory/reports/task-822.{N}.md` (N=1,2,3,4 순서대로)
- 전체 완료 후 통합 보고서: `memory/reports/task-822.final.md`