# 체크리스트: InsuWiki LLM Wiki 패턴 흡수

**작성일**: 2026-04-11
**근거**: Agent Meeting 합의 (task-1641.1)

## Phase 1 사전 준비 (기존 Week 3에 추가)

### 스키마 예약
- [ ] documents 컬렉션에 suggestedEntities: string[] 필드 추가 (Optional)
- [ ] documents 컬렉션에 extractedEntities: string[] 필드 추가 (Optional)
- [ ] documents 컬렉션에 entityLinks: { entity: string, relatedDocIds: string[] }[] 필드 추가 (Optional)
- [ ] firestore.ts 타입 정의에 신규 필드 추가

## Phase 3: LLM Wiki 패턴 흡수 (22일)

### 보안 전제조건 (Phase 3 시작 전 반드시 완료)

#### PII 마스킹 레이어 (2일)
- [ ] PII 마스킹 유틸 함수 구현 (정규식 기반)
  - 주민번호: /\d{6}-?\d{7}/g → "[주민번호 마스킹]"
  - 전화번호: /01[016789]-?\d{3,4}-?\d{4}/g → "[전화번호 마스킹]"
  - 계좌번호: /\d{3,4}-?\d{2,6}-?\d{2,6}/g → "[계좌번호 마스킹]"
- [ ] 마스킹 실패 시 API 호출 차단 (fail-safe)
- [ ] PII 마스킹 단위 테스트 (경계값: 주민번호 하이픈 유무, 전화번호 010/011 등)

#### Prompt Injection 방어 (2일, /query와 병행)
- [ ] 검색어 입력 새니타이징 함수 구현
- [ ] system/user 역할 분리 (Claude API 호출 시)
- [ ] 응답 내 문서 ID에 대한 호출자 권한 사후 필터링
- [ ] query_cache 키에 tenant_id/userId 바인딩
- [ ] Injection 공격 벡터 10개 테스트 케이스

### 3-1. 보험 엔티티/컨셉 자동 추출 (7일)

#### Firestore 스키마
- [ ] entities 컬렉션 생성
  - name: string
  - aliases: string[]
  - category: 'product'|'concept'|'term'|'regulation'|'clause'
  - relatedEntityIds: string[]
  - documentIds: string[]
  - insurance_term_id?: string
  - createdAt, updatedAt
- [ ] entities 컬렉션 인덱스 설정 (category + name)

#### 추출 파이프라인
- [ ] 엔티티 추출 Cloud Function 구현 (비동기, Cloud Tasks 큐)
- [ ] 추출 프롬프트 템플릿 설계 (보험 도메인 특화)
  - 추출 대상: 상품명, 보장/특약명, 법규/조항 번호, 비교 컨셉, 실무 용어
- [ ] 추출 결과를 documents.suggestedEntities에 저장
- [ ] 3회 재시도 + pending 마킹 로직
- [ ] Claude API 비용 모니터링 (api_usage_daily 연계)

#### 사용자 승격 워크플로우
- [ ] 엔티티 확인/수정 UI 컴포넌트 (문서 편집 화면 하단 또는 사이드패널)
- [ ] suggestedEntities → entities 승격 API Route
- [ ] 미확인 엔티티는 검색에 활용하되 "미확인" 표시

#### 교차 연결 자동 생성
- [ ] 동일 엔티티 공유 문서 쌍 → links 컬렉션에 method: 'entity_match', status: 'pending' 생성
- [ ] confidence 산출: 공유 엔티티 수 / min(문서A 엔티티 수, 문서B 엔티티 수)

#### 기존 데이터 백필
- [ ] insurance_terms 1,192건 → entities 프로모션 스크립트 (배치, dry-run)
- [ ] 기존 documents 전체에 대한 엔티티 추출 배치 (Scheduled Function, 1회성)

#### 테스트
- [ ] 엔티티 추출 정확도 테스트 (20건, precision 80%+)
- [ ] PII 마스킹 통합 테스트 (PII 포함 문서 → 마스킹 → Claude → 추출)
- [ ] 승격 워크플로우 E2E 테스트
- [ ] links 자동 생성 테스트

### 3-2. /lint 위키 건강 검사 (6일)

#### 검사 항목 구현
- [ ] 중복 탐지: 제목 Levenshtein 유사도 + extractedEntities 교집합 비율 (임계값 0.8)
  - 규칙 기반 (LLM 불필요)
- [ ] 모순 감지: 동일 엔티티 문서 쌍 → Claude API 모순 판정 + confidence score
  - LLM 사용 (PII 마스킹 적용)
  - confidence 0.8 미만 → "검토 필요" 분류
- [ ] 고아 항목: extractedEntities 비어있거나 links 0개인 고립 문서
  - 규칙 기반 (Firestore 쿼리)
- [ ] 최신성: updatedAt 180일+ 경과 AND sourceType in (regulation, court_ruling)
  - 규칙 기반 (Firestore 쿼리)

#### 실행 인프라
- [ ] Scheduled Function (주 1회, 일요일 새벽)
- [ ] Admin API Route: POST /api/admin/lint (수동 트리거)
- [ ] lint_reports 컬렉션 스키마
  - runAt, trigger, findings[], summary

#### Admin 대시보드
- [ ] 최근 lint 리포트 요약 표시 (Admin 페이지)
- [ ] finding별 해당 문서 직접 이동 링크
- [ ] 이슈 해결 처리 (resolved 마킹)

#### 테스트
- [ ] 수동 생성 이슈 10건에서 탐지율 90%+ 확인
- [ ] 모순 감지 false positive율 30% 미만 확인
- [ ] Scheduled Function 실행 안정성 테스트

### 3-3. /query 검색 종합 정리 (9일)

#### API 구현
- [ ] /api/wiki/synthesize API Route 신설 (verifyMember)
- [ ] 검색어 → Firestore 키워드 검색 실행
- [ ] 검색 결과에서 extractedEntities 수집 → 관련 엔티티의 documentIds로 확장 검색
- [ ] 결과 문서를 authorityTier(+compositeReliabilityScore) 기준 정렬
- [ ] 상위 N개 문서 → PII 마스킹 → Claude API 종합 요약 생성
- [ ] 각 문장에 원문 docId+제목 인라인 인용
- [ ] query_cache 저장 (TTL 1시간, 원문 변경 시 무효화)

#### Prompt Injection 방어
- [ ] 검색어 새니타이징 (Section "보안 전제조건" 참조)
- [ ] system/user 메시지 분리
- [ ] 응답 내 문서 접근 권한 사후 필터링
- [ ] cache 키에 userId/tenant_id 바인딩

#### 프론트엔드
- [ ] "종합 정리 보기" 버튼 (검색 결과 3건 이상일 때 표시)
- [ ] 종합 정리 결과 표시 UI (원문 링크+하이라이트)
- [ ] 로딩 상태 표시 (LLM 응답 대기)
- [ ] 면책 표시 ("AI 생성 요약입니다. 원문을 확인하세요")

#### 기존 코드 통합
- [ ] useSemanticSearch.ts 확장 또는 useEntitySearch.ts 신설
- [ ] AISidepanel에 종합 정리 결과 표시 영역 추가

#### 테스트
- [ ] 종합 정리 응답 시간 5초 이내 확인
- [ ] 원문 링크 정확도 100% (인용된 docId 존재 확인)
- [ ] Prompt Injection 10개 공격 벡터 테스트
- [ ] cache 무효화 테스트 (원문 변경 후 cache 갱신)

## [미해결 - Phase 3 시작 전 결정]
- [ ] Claude API 키 관리 방식 (환경 변수 vs Secret Manager) — 결정 필요
- [ ] 엔티티 카테고리 분류 체계 상세 확정 — 5종(product/concept/term/regulation/clause) 외 추가 필요 여부
- [ ] 엔티티 추출 프롬프트 템플릿 설계 — 보험 도메인 전문가 피드백 필요
- [ ] PII 마스킹 패턴 범위 확장 검토 — 이메일 주소, 주소 등 추가 유형 (마아트 권고)