# 계획서: InsuWiki 협업 검토 시스템 + 신뢰도 UX

**작성일**: 2026-04-11 (v3: PRD 검증 미팅 반영)
**근거**: Agent Meeting v2 합의 20건 + 제이회장님 피드백 6건 + PRD 검증 미팅 합의 22건
**프로젝트**: InsuWiki (/home/jay/projects/insuwiki/)
**검증 미팅**: /home/jay/workspace/memory/meetings/2026-04-11-insuwiki-review-trust-prd-verification.md

## 목표
1. 제이회장님 1인 승인 병목 해소 → 다중 검토자 시스템
2. 보험 콘텐츠 신뢰도 시각화 (authorityTier × verificationStatus)
3. 보안 기반 확립 (SEC-02 CRITICAL 해결 + 기존 인증 부재 패치)

## 범위

### 포함
- SEC-02 즉시 패치: index-wiki/search-wiki/invalidate-cache 인증 추가
- Custom Claims 도입 (request.auth.token.role)
- 4역할 체계 (admin/reviewer/member/guest) + permissions 배열
- 상태 머신 (draft→in_review→approved/rejected/revision_requested) — CF 서버 사이드
- Security Rules: 불변식만 (민감 필드 보호 + approved 직접 전이 차단)
- 이벤트 소싱 (Cloud Functions onCreate 트리거)
- 3계층 방어: Rules(불변식) → CF(비즈니스 로직) → API Routes(인증)
- 감사 로그 (CF only, append-only + Cloud Logging 이중화)
- TrustBadge 3단계 + VerificationTag 분리 (어댑터 패턴 마이그레이션)
- 정적 기본 필터("전체") + 미검증 문서 시각적 구분 + "검증만 보기" 토글
- 카테고리 칩 필터 + 신뢰도순 정렬
- 검토 UI (독립 화면 + 인라인 패널)
- reliabilityScores 인라인 필드 (compositeReliabilityScore)
- authorityTier 백필 (sourceType 기반, TIER_MAP 코드 기준)
- 승인 인원 차등: sourceType 기반 riskLevel + override 필드
- 검토 메모: review.comment 필드 (반려/수정요청 시 사유 필수)
- 경량 수정 면제: 7조건 AND, CF 서버사이드 판정
- contributorIds 기반 자기 검토 금지

### 추가 포함 (v3 PRD 검증 미팅 결과)
- UserRole 타입 단일 소스화 (중복 정의 제거)
- versions/revisions 서브컬렉션 통합
- useWikiFilter 커스텀 훅 캡슐화
- 검토 큐 diff 크기순 정렬 (Phase 3)
- LLM 응답에 원문 문서 링크 + 문단 하이라이트 필수 (Phase 3)

### 제외
- AI 사전 분류 (Phase 3 이후, aiSuggestedGrade 예약만)
- 게이미피케이션 (규모 15명+ 도달 시 재검토)
- 커뮤니티 투표 시스템 (사용자 확장 후 재검토)
- 검색 중심 IA 전환 (사용 데이터 수집 후)
- 검토 통계 대시보드 (상태 요약 한 줄로 대체)
- 검토자 전문성 매칭 (수동 선택으로 충분)
- 동적 기본 필터 (정적 기본 + 토글로 대체)
- 카테고리 × 신뢰도 교차 필터 (카테고리 칩 + 정렬로 대체, 30건+ 시 재검토)
- LLM-Native Knowledge Base 전환 (환각 리스크, Phase 3 축소 버전으로 점진 탐색)

### 변경 사항 (v2 → v3)
- SEC-01: 팬텀 위험으로 재정의 (API 미존재 확인). SEC-02로 실제 위험 추적
- Security Rules 상태 머신 → 서버 사이드 전환
- Big Bang 마이그레이션 → 점진적 마이그레이션
- TrustBadge 4단계 → 3단계 + VerificationTag 분리
- 동적 기본 필터 → 정적 기본 + 시각적 구분 + 토글
- 교차 필터 → 카테고리 칩 + 신뢰도순 정렬
- Phase 1: 2주 → 3주. Phase 2: 2주 → 2.5주 (2a+2b 분리)
- Custom Claims 도입 (get() 10회 제한 대응)
- TIER_MAP: 코드 기준 통일 (regulation=1.5, kakao_expert=3.5)

## Phase 분리

### Phase 1: 보안+핵심 로직 (3주)

**Week 1: 인증 + Claims**
- SEC-02 즉시 패치 (index-wiki, search-wiki, invalidate-cache)
- UserRole enum 확장 ('reviewer' 추가) + 타입 단일 소스화
- Custom Claims 세팅 (발급 CF + 기존 유저 백필)
- Security Rules 기본 불변식 배포
- Day 3 체크포인트: Claims 발급 CF 동작 확인

**Week 2: 상태 머신 + 검토 제도**
- CF 서버 사이드 상태 머신 구현
- reviews 서브컬렉션 스키마 + CRUD API
- 승인 차등 로직 (riskLevel 자동 판정 CF)
- 자기 검토 금지 (contributorIds)
- 검토자 배정 무작위화
- 감사 로그 (auditLogs 서브컬렉션)
- 경량 수정 면제 7조건 CF 로직

**Week 3: 백필 + 마이그레이션 + 테스트**
- authorityTier 백필 스크립트 (TIER_MAP 코드 기준)
- 점진적 마이그레이션 (기존 문서에 신규 필드 추가)
- versions/revisions 서브컬렉션 통합
- 통합 테스트 (Firebase Emulator)
- 역할별 접근 매트릭스 테스트 (4역할 × 12 API)

### Phase 2a: 시각적 전환 (1주)
- TrustBadge 3단계 컴포넌트 신규 생성
- VerificationTag 서브텍스트 컴포넌트
- SourceBadge → TrustBadge 어댑터 패턴 적용
- 미검증 콘텐츠 배너 (severity 분기)
- 접근성: aria-label, SVG 아이콘, 색상 대비 4.5:1+

### Phase 2b: 기능 추가 (1.5주)
- 카테고리 칩 필터 + 신뢰도순 정렬
- useWikiFilter 커스텀 훅 캡슐화
- URL 동기화 (useSearchParams)
- "검증만 보기" 세션 토글
- 검토 독립 화면 (앱바 아이콘 + 배지)
- InlineReviewPanel + ReviewActions
- useReviewPermission 훅 + 역할 조건부 렌더링
- Firestore onSnapshot (검토 대기열, limit 50, visibilitychange detach)
- 검토 큐 상태 요약 ("대기 N건, 최고 경과 X일")

### Phase 3: 확장 (TBD)
- reliabilityScores 계산 CF + 사전 캐싱
- 프로그레시브 디스클로저 (Layer 2 Popover + Layer 3 타임라인)
- 검토자 적체 모니터링 Scheduled Function (3단계 SLA)
- Push 알림 (FCM)
- AI 사전 분류 검토 (aiSuggestedGrade)
- 검색 종합 정리 (명시적 버튼 트리거, 캐시 TTL 1시간, 원문 링크+하이라이트)
- 오류 신고 (reports 서브컬렉션, Rate Limiting)
- 버전 비교 UI (jsdiff, unified/side-by-side 반응형)
- 교차 필터 재검토 (카테고리 내 30건+ 시)
- 검토 큐 diff 크기순 정렬
- 오프라인 UX (useNetworkStatus + ConnectionBanner)

## 위임 계획
- Phase 1 백엔드: 불칸(dev1 백엔드) — CF, Rules, Custom Claims, 마이그레이션
- Phase 2 프론트: 이리스(dev1 프론트) — TrustBadge, 검토 UI, 필터
- Phase 1/2 테스트: 아르고스(dev1 테스트) — 역할 매트릭스, 상태 전이, E2E
- UX 설계 검증: 아테나(dev1 UX) — 배지, 필터, 토글 UX 리뷰

## 검증 기준
- Security Rules 테스트: 4역할 × 12 API × 허용/거부 = 최소 60 케이스
- 상태 전이 테스트: 12 케이스 (합법/불법 전이)
- 동시성 테스트: Firebase Emulator Suite
- 경량 수정 판정 테스트: 7조건 각각의 경계값
- TrustBadge 접근성: WCAG 2.1 AA (색맹 시뮬레이션 + grayscale)
- reliabilityScores 정확성: 테스트 문서 10건 수동 검증

## 기술 스택
- Firebase Auth + Custom Claims + Firestore users/{uid}.role
- Firestore Security Rules v2 (불변식만)
- Cloud Functions (Node 20, Firebase Functions v2) — 상태 머신 주체
- Next.js API Routes (verifyIdToken, verifyMember, verifyReviewer)
- React (TrustBadge, VerificationTag, ReviewPanel, useWikiFilter)