# InsuWiki AI 노드 자동 연결 — 구현 계획서

**버전**: v1.1
**작성일**: 2026-03-22
**최종 상태 업데이트**: 2026-04-25
**근거 미팅**: `memory/meetings/2026-03-22-insuwiki-ai-auto-linking.md`
**프로젝트 경로**: `/home/jay/projects/insuwiki/`
**작업 레벨**: Lv.3

---

## 0. 진행 현황 (2026-04-25 기준)

| Phase | 상태 | 비고 |
|-------|------|------|
| Phase 0: 보안 기초 | ✅ 완료 | Firestore Rules + links 스키마 배포 |
| Phase 1-A: 정적 매칭 백엔드 | ✅ 완료 | `staticMatching.ts` (435줄) Firebase 배포 완료 |
| Phase 1-A: 프론트 UI | ✅ 완료 | `FloatingTermDetection.tsx` (531줄) — 플로팅바 추천 + 승인 UI |
| Go/No-Go 게이트 | ⏸ 미실시 | 50건 실측 미수행 |
| Phase 1-B: 임베딩 백엔드 | ✅ 완료 | `embeddingMatching.ts` (529줄) Firebase 배포 완료 |
| Phase 1-B: 프론트 UI | ⚠️ 미완 | 프론트에서 `method === 'static'`만 필터 — embedding 결과 미표시 |
| Phase 2: Claude 연동 | ❌ 미착수 | |
| Phase 3: 지식 그래프 | ❌ 미착수 | |

**핵심 구현 파일:**
- 백엔드: `functions/src/staticMatching.ts`, `functions/src/embeddingMatching.ts`
- 프론트: `nextapp/src/components/FloatingTermDetection.tsx`
- 트리거: `documents/{docId}` onWrite → 자동 실행
- 데이터: `ai_suggestions` 서브컬렉션에 결과 저장

**즉시 가능한 작업:**
1. FloatingTermDetection에서 embedding 결과도 표시 (필터 1줄 수정)
2. Go/No-Go 게이트: 50건 실측으로 정확도 확인

---

## 1. 목표

InsuWiki 문서 간 관련 노드를 AI로 자동 연결하여 지식 탐색 경험을 강화한다.
- B안: 기존 도구(Gemini embeddings, Firestore)로 가볍게 검증 → 검증된 로직만 InsuWiki에 이식
- AI 백엔드: 아누 서버(Claude) — Phase 2부터 활용

---

## 2. 범위

### 포함
- Firestore Rules 강화 + links 스키마 확장
- insurance_terms 기반 정적 매칭 (Phase 1-A)
- Gemini 임베딩 기반 유사도 추천 (Phase 1-B, Go/No-Go 이후)
- 아누 서버 Claude 의미 분석 연동 (Phase 2)
- 지식 그래프 자동 구축 + 시각화 (Phase 3)

### 제외
- 외부 AI API 직접 사용 (아누 서버를 통해서만)
- 한국어 형태소 분석기 도입 (ROI 부적합)
- 사용자 문서 외 외부 데이터 크롤링

---

## 3. 아키텍처

### 3.1 기술 스택
- **프론트**: Next.js (기존 InsuWiki)
- **백엔드**: Firebase Cloud Functions
- **DB**: Firestore (documents, links, insurance_terms, embeddings)
- **임베딩**: Gemini embedding API (768-dim)
- **벡터 검색**: Firestore Vector Search
- **AI 분석**: 아누 서버 Claude (Phase 2~)
- **인증**: HMAC-SHA256 (Phase 2~)

### 3.2 통신 구조
```
[사용자 문서 저장]
  → Firestore onWrite 트리거
  → Cloud Function (정적 매칭 즉시 실행)
  → ai_suggestions 서브컬렉션에 결과 저장

[Phase 2 추가]
  → Cloud Function → POST /api/v1/insuwiki/recommend (아누 서버)
  → HMAC-SHA256 서명
  → timeout 10초, 재시도 금지
  → 아누 다운 시: 정적 매칭만 반환 + aiStatus: "unavailable"
```

### 3.3 links 스키마 (Phase 0에서 확정)
```javascript
{
  sourceId: string,       // 출발 문서 ID
  targetId: string,       // 도착 문서 ID
  method: "manual" | "static" | "embedding" | "semantic",
  confidence: number,     // 0-100
  createdBy: "user" | "system" | "ai",
  status: "active" | "pending",  // AI 링크는 pending으로 시작
  explanation: string,    // Phase 2에서 Claude 설명
  createdAt: timestamp,
  updatedAt: timestamp
}
```

### 3.4 신뢰도 임계값 (config 외부화)
- 95%+: 자동 추천 표시 (승인 필요)
- 70-95%: 추천 표시 (승인 필요)
- <70%: 숨김
- 50건 실측 후 조정

---

## 4. Phase 구조

### Phase 0: 보안 기초 (0.5일) ✅ 완료
- Firestore Rules 강화 (links 컬렉션 write validation)
- links 스키마 확정 + validation rule (confidence 0-100, method 허용값)
- 기존 links 데이터에 method: "manual", createdBy: "user" 백필
- **산출물**: Firestore Rules 배포, 스키마 문서
- **완료 기준**: Rules 테스트 통과

### Phase 1-A: 정적 매칭 (2-3일) ✅ 완료
- insurance_terms 사전 기반 [[]] 자동 제안
- Cloud Function 내부 실행 (insurance_terms 메모리 캐싱 TTL 1h)
- 정규화 테이블 (공백/띄어쓰기 변형 처리, 50-100개)
- ~~사이드바 추천 UI 컴포넌트~~ → 플로팅바 추천 UI (`FloatingTermDetection.tsx`)
- confidence 산정: exact=100, alias=90, substring=70 (+ 공백제거=85)
- **산출물**: `staticMatching.ts` Cloud Function, 플로팅바 UI, 승인 UI
- **완료 기준**: 기존 문서 10건 대상 정확도 90%+
- **구현 task**: task-820.1 (정적 매칭), 별도 task (프론트 UI)

### ★ Go/No-Go 게이트 — ⏸ 미실시
- Phase 1-A 완료 후 50건 실측
- 정확도 80%+ → Phase 1-B 진행
- 정확도 60-80% → 정규화 테이블 보강 후 재측정
- 정확도 <60% → 접근법 재검토
- **참고**: Phase 1-B 백엔드는 Go/No-Go 전에 구현 완료됨 (프론트 미연결)

### Phase 1-B: 임베딩 유사도 추천 (3-4일) ⚠️ 백엔드만 완료
- Gemini 768-dim 임베딩 활용 (기존 embeddings 서브컬렉션)
- content_hash(SHA-256) 기반 변경 감지 + lazy 재생성
- Firestore Vector Search로 유사 문서 검색
- 정적 매칭과 공존 (method 필드로 구분)
- **산출물**: `embeddingMatching.ts` Cloud Function — Firebase 배포 완료
- **미완료**: 프론트에서 embedding 결과 표시 안 됨 (static만 필터링 중)
- **구현 task**: task-829.1
- **완료 기준**: precision@5 70%+ (수동 검증) — 미검증

### Phase 2: 아누 서버 Claude 연동 (3-4일)
- REST 엔드포인트: POST /api/v1/insuwiki/recommend
- HMAC-SHA256 인증 + Cloud Secret Manager (90일 로테이션)
- uid 기반 rate limit (분당 5건)
- 관계 환각 방어: 설명 강제 + 설명 품질 검증
- AI 링크 status: "pending" → 사용자 승인 → "active"
- graceful degradation (아누 다운 시 정적 매칭만)
- **산출물**: REST 엔드포인트, 보안 인프라, 승인 플로우
- **완료 기준**: 추천 품질 Phase 1-B 대비 향상 확인

### Phase 3: 지식 그래프 자동 구축 (4-5일)
- 전체 문서 관계망 시각화
- 고아 노드 감지 + 연결 제안
- 순환 참조 감지
- **산출물**: 그래프 뷰 UI
- **완료 기준**: 고아 노드 0, 순환 참조 감지 동작

---

## 5. 보안 설계

### Phase 0 (즉시)
- Firestore Rules: links 컬렉션 write validation
- 스키마 validation: confidence 범위, method 허용값

### Phase 2 (아누 연동 시)
- HMAC-SHA256 서명 (timestamp + body)
- Cloud Secret Manager로 키 관리 (90일 자동 로테이션)
- uid 기반 rate limit (분당 5건)
- 최소 데이터 원칙: Claude에 필요한 최소 정보만 전달
- AI 링크 pending 상태 관리 (자동 반영 금지)
- Firestore 주기적 export 백업 (대량 오염 롤백 대비)

### 감사 추적
- 모든 AI 추천/승인/거부 기록 보존
- createdBy + timestamp + explanation 필수

---

## 6. 위임 계획

### 1차 위임: Phase 0 + Phase 1-A ✅ 완료
- **팀**: 개발1팀 (헤르메스)
- **범위**: Firestore Rules + 정적 매칭 + 플로팅바 UI
- **task**: task-820.1 등

### 2차 위임: Phase 1-B ✅ 백엔드 완료 (프론트 미연결)
- **팀**: 개발1팀
- **범위**: 임베딩 유사도 추천 백엔드
- **task**: task-829.1

### 다음 위임: Phase 1-B 프론트 + Go/No-Go 검증
- **팀**: TBD
- **범위**: FloatingTermDetection에서 embedding 결과 표시 + 50건 정확도 실측
- **예상 기간**: 0.5~1일

### 이후 위임: Phase 2 (Go/No-Go 통과 시)
- **팀**: TBD
- **범위**: 아누 서버 Claude 연동 + 보안
- **예상 기간**: 3-4일

---

## 7. 검증 기준

- Phase 0: Firestore Rules 테스트 (잘못된 스키마 write 거부 확인)
- Phase 1-A: 기존 문서 10건 정확도 90%+, insurance_terms 매칭 동작
- Phase 1-B: precision@5 70%+ (수동 검증 50건)
- Phase 2: Claude 추천 품질 Phase 1-B 대비 향상, 관계 환각 0건
- Phase 3: 고아 노드 0, 순환 참조 감지 동작