# 체크리스트: InsuWiki 협업 검토 시스템 + 신뢰도 UX

**작성일**: 2026-04-11 (v3: PRD 검증 미팅 반영)
**근거**: Agent Meeting v2 합의 + PRD 검증 미팅 (task-1639.1) 합의 22건

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

### Week 1: 인증 + Custom Claims

#### SEC-02 즉시 패치 (CRITICAL)
- [ ] /api/ai/search-wiki에 verifyMember 미들웨어 추가
- [ ] /api/ai/index-wiki에 verifyAdmin 미들웨어 추가
- [ ] /api/ai/invalidate-cache의 Bearer 존재 확인 → verifyIdToken()으로 교체

#### UserRole 확장 + 타입 단일 소스화
- [ ] shared/types/roles.ts 생성 (UserRole = 'admin' | 'reviewer' | 'member' | 'guest')
- [ ] firestore.ts의 UserRole 정의 → shared/types/roles.ts import로 교체
- [ ] AuthContext.tsx의 UserRole 정의 → shared/types/roles.ts import로 교체
- [ ] ROLE_HIERARCHY 상수 정의 (admin=3, reviewer=2, member=1, guest=0)
- [ ] permissions 배열 기반 확장 설계

#### Custom Claims 세팅
- [ ] Claims 발급 Cloud Function 작성 (setCustomClaims)
- [ ] 기존 유저 전원 Claims 백필 스크립트
- [ ] 프론트엔드 토큰 갱신 처리 (getIdToken(true) 호출 시점)
- [ ] **Day 3 체크포인트**: Claims 발급 CF 동작 확인

#### Security Rules 기본 불변식
- [ ] Rules에 reviewer 역할 인식 추가 (request.auth.token.role)
- [ ] documents 컬렉션: status/reliabilityScores/verificationStatus 필드 클라이언트 쓰기 차단
- [ ] documents 컬렉션: approved 상태로의 직접 전이 차단 (CF/Admin SDK만 가능)
- [ ] role/permissions 필드 클라이언트 쓰기 차단
- [ ] Rules 배포 전 에뮬레이터 테스트

### Week 2: 상태 머신 + 검토 제도

#### 상태 머신 (CF 서버 사이드)
- [ ] VALID_TRANSITIONS 테이블 정의 (TypeScript)
- [ ] CF: reviews onCreate 트리거 → 상태 전이 로직
- [ ] API Route: POST /api/wiki/entries/{id}/review (verifyReviewer)
- [ ] riskLevel 자동 판정 CF (sourceType/카테고리 기반)
- [ ] 고위험 → admin 최종 승인 필수 로직
- [ ] 승인 후 수정 → needs_re_review 자동 전환

#### 경량 수정 면제 로직 (CF)
- [ ] 7조건 판정 로직 구현:
  - 조건1: 변경 문자 수 ≤ 20자
  - 조건2: 숫자/금액/날짜/비율 변경 없음 (정규식)
  - 조건3: 부정어 추가/삭제 없음 (키워드 목록)
  - 조건4: 링크 URL 변경 없음
  - 조건5: 법규/약관 인용 번호 변경 없음 (정규식)
  - 조건6: 고위험 카테고리 아님
  - 조건7: 7일 내 경량 수정 누적 < 3회
- [ ] 7조건 경계값 테스트 (각 조건별 통과/실패 케이스)

#### 검토 제도
- [ ] reviews 서브컬렉션 스키마: documents/{docId}/reviews/{reviewId}
- [ ] 자기 검토 금지: contributorIds 배열 기반 검증 (CF)
- [ ] 검토자 배정 무작위화 로직 (라운드 로빈 + 연속 배정 제한)
- [ ] 리뷰어 풀 최소 3명 체크 + admin 경고
- [ ] 승인 인원 차등: 저위험=reviewer 1명, 고위험=reviewer+admin 2단계
- [ ] review.comment 필드: 반려/수정요청 시 사유 필수 입력 검증
- [ ] collectionGroup('reviews') 인덱스 추가 (reviewerId + createdAt)

#### 감사 로그 (Week 3로 이월 가능 — DA-01)
- [ ] documents/{docId}/auditLogs 서브컬렉션 스키마
- [ ] CF에서만 쓰기 (Security Rules deny all client writes)
- [ ] Cloud Logging 이중화 (structured log)

### Week 3: 백필 + 마이그레이션 + 테스트

#### authorityTier 백필
- [ ] TIER_MAP 코드 기준 확정 (regulation=1.5, court_ruling=2, kakao_expert=3.5 등)
- [ ] 백필 스크립트 작성 (500건 배치, dry-run 모드)
- [ ] sourceType null 문서 처리 (기본값 6 + 수동 분류 목록)
- [ ] 백필 완료 확인 (전체 vs 백필 수 비교)

#### 점진적 마이그레이션
- [ ] 기존 documents에 status 필드 추가 (기본값: 'published')
- [ ] reliabilityScores 필드 스키마 추가 (Optional)
- [ ] riskLevel 필드 추가 (CF 자동 판정)
- [ ] versions/revisions 서브컬렉션 통합 (revisions deprecated)
- [ ] extractedEntities 필드 예약 추가 (Optional, Phase 3 엔티티 추출 준비)
- [ ] entityLinks 필드 예약 추가 (Optional, Phase 3 교차 연결 준비)
- [ ] 마이그레이션 스크립트 dry-run + 실행
- [ ] Python 크롤링 스크립트에 status 기본값 가드 추가

#### 테스트
- [ ] 역할별 접근 매트릭스 테스트 (4역할 × 12 API = 60+ 케이스)
- [ ] 상태 전이 테스트 (12 케이스: 합법+불법 전이)
- [ ] 동시성 테스트 (Firebase Emulator)
- [ ] 자기 검토 금지 테스트 (contributorIds)
- [ ] 감사 로그 무결성 테스트
- [ ] Custom Claims 발급/갱신 테스트
- [ ] 경량 수정 7조건 판정 테스트

## Phase 2a: 시각적 전환 (1주)

### TrustBadge 3단계
- [ ] getTrustLevel(authorityTier, sourceType) 매핑 함수 구현
- [ ] TrustBadge 컴포넌트 (아이콘+색상+텍스트 3중 인코딩)
- [ ] 3단계: 공식확인(녹색,방패SVG) / 전문가검증(파랑,체크SVG) / 참고정보(회색,infoSVG)
- [ ] 반응형 크기 (sm/md/lg)
- [ ] 접근성: aria-label, aria-hidden(아이콘), role="status"
- [ ] SVG 아이콘 (이모지 아이콘 교체)
- [ ] 색상 대비 WCAG 2.1 AA (4.5:1+)
- [ ] grayscale 테스트 통과

### VerificationTag
- [ ] VerificationTag 서브텍스트 컴포넌트
- [ ] 4상태: pending(회색) / in_review(주황) / verified(녹색체크) / rejected(적색)
- [ ] TrustBadge와 조합 렌더링

### SourceBadge 마이그레이션
- [ ] SourceBadge → TrustBadge 어댑터 래퍼 생성
- [ ] page.tsx 카드뷰/리스트뷰: 어댑터 적용
- [ ] DocumentClient.tsx 상세 페이지: 어댑터 적용
- [ ] 기존 SourceBadge 테스트 업데이트

### 미검증 콘텐츠 배너
- [ ] UnverifiedBanner 컴포넌트 (severity: info/caution)
- [ ] 미검증 문서 시각적 구분 (bg-amber-50 + border-l-4 border-amber-300)
- [ ] severity 자동 판정 (practice + user_submitted → caution)

## Phase 2b: 기능 추가 (1.5주)

### 필터 + 정렬
- [ ] useWikiFilter 커스텀 훅 생성 (필터 로직 캡슐화)
- [ ] 카테고리 칩 필터 (단일 선택: 전체/법규/판례/정책/전문가/커뮤니티)
- [ ] 신뢰도순 정렬 옵션 (authorityTier DESC)
- [ ] "검증만 보기" 세션 토글 (sessionStorage 유지)
- [ ] URL 동기화 (useSearchParams)
- [ ] Firestore 복합 인덱스 3개 추가

### 검토 UI
- [ ] 검토 독립 화면 (앱바 우측 아이콘 + 배지)
- [ ] ReviewQueue 대기열 리스트
- [ ] 검토 큐 상태 요약 한 줄 ("대기 N건, 최고 경과 X일")
- [ ] InlineReviewPanel (문서 상세 하단)
- [ ] ReviewActions (승인/거절/수정요청)
- [ ] 근거 유형 필수 선택 + 출처 첨부 UI

### 역할 기반 렌더링
- [ ] useReviewPermission 훅 구현
- [ ] 역할 기반 UI 조건부 렌더링

### Firestore 실시간 리스너
- [ ] 검토 대기열 onSnapshot (limit 50)
- [ ] 문서 상세 검토 상태 리스너
- [ ] visibilitychange 기반 탭 백그라운드 detach
- [ ] iOS Safari 폴백 (pagehide/pageshow)

## Phase 3: 확장 (TBD)

### reliabilityScores 계산
- [ ] CF: compositeReliabilityScore 계산 (6가중치: verification 0.30, authority 0.20, source 0.15, review 0.15, freshness 0.10, sourceRef 0.10)
- [ ] 결격 조건(knockout) + 가중 평균 하이브리드
- [ ] freshness 이산 구간 + 일일 배치 재계산 (Scheduled Function)
- [ ] 가중치 설정 파일 외부화

### 프로그레시브 디스클로저
- [ ] Layer 2: Popover (검토자, 일시, 사유 요약, "이력 보기" 링크 자리)
- [ ] Layer 3: 타임라인 (전체 검토 이력)

### 운영 기능
- [ ] 검토자 적체 모니터링 (6시간 주기 Scheduled Function)
- [ ] 3단계 SLA: WARNING(10건/48h), CRITICAL(20건/96h), ESCALATION(168h)
- [ ] Push 알림 (FCM 토큰 관리, Service Worker 연동)

### 검색 종합 정리
- [ ] "종합 정리 보기" 버튼 (결과 3건 이상일 때만 표시)
- [ ] LLM 요약 생성 (기존 RAG 파이프라인 확장)
- [ ] 캐시 전략: 쿼리별 TTL 1시간, 원문 변경 시 캐시 무효화
- [ ] Prompt Injection 방어 3중 (입력 새니타이징 + 출력 검증 + 면책 표시)
- [ ] LLM 응답에 원문 문서 링크 + 문단 하이라이트 필수

### 오류 신고
- [ ] documents/{docId}/reports/{reportId} 서브컬렉션
- [ ] API: POST /api/wiki/entries/{id}/report (verifyMember)
- [ ] 선택형 사유 4개 + 선택적 메모 1줄
- [ ] Rate limit: 동일 유저×문서 1회/24h, 전체 10건/일
- [ ] 신고 → 자동 상태 변경 없음, admin/reviewer 큐에만 표시
- [ ] 신고자 실명 표시 (검토자에게만)

### 버전 관리 UI
- [ ] 버전 비교 diff (jsdiff, unified/side-by-side 반응형)
- [ ] 규정 변경 시 기존 승인 항목 "재검토 필요" 자동 전환
- [ ] 버전 히스토리 접근 권한 분리 (reviewer 이상)
- [ ] 버전 보존 정책 (최대 N개 또는 M일)

### LLM Wiki 흡수 기능 (task-1641.1 합의, +22일)
- [ ] 엔티티 자동 추출: suggestedEntities → 사용자 확인 → entities 승격
- [ ] entities 컬렉션 + documents.extractedEntities 이중 구조
- [ ] 명시적 "엔티티 추출" 버튼 (CF 자동 트리거 아님)
- [ ] PII 마스킹 레이어 (주민번호/전화번호/계좌번호 정규식)
- [ ] Claude API 비동기 큐 (3회 재시도 + pending 마킹)
- [ ] /lint 위키 건강 검사: 중복/고아/최신성=규칙 기반, 모순=LLM(confidence 0.8+)
- [ ] lint_reports 컬렉션 + Scheduled Function 주 1회
- [ ] /query 종합 정리: 엔티티 기반 확장 검색 + "종합 정리 보기" 버튼
- [ ] Prompt Injection 방어 3중 (system/user 분리 + 사후 권한 필터 + tenant_id cache)
- [ ] query_cache TTL 1시간 + 원문 변경 시 캐시 무효화

### 기타
- [ ] 교차 필터 재검토 (카테고리 내 30건+ 트리거)
- [ ] 검토 큐 diff 크기순 정렬 옵션
- [ ] 오프라인 UX (useNetworkStatus + ConnectionBanner)
- [ ] AI 사전 분류 검토 (aiSuggestedGrade)

## [결정 완료] 제이회장님 확정 사항 (2026-04-11)
- [x] 승인 인원: 저위험=reviewer 1명, 고위험=reviewer+admin 2단계
- [x] 검토자 전문성 매칭: 불필요 (reviewer 수동 선택으로 충분)
- [x] 검토 통계 대시보드: 불필요 (상태 요약 한 줄로 대체)
- [x] 만료/갱신: 버전 관리에서 커버

## [결정 완료] PRD 검증 미팅 확정 사항 (2026-04-11, task-1639.1)
- [x] SEC-01: 팬텀 위험. 향후 생성 시 인증 필수
- [x] SEC-02: CRITICAL. AI 엔드포인트 3종 즉시 인증 추가
- [x] reviews: 서브컬렉션 documents/{docId}/reviews/{reviewId}
- [x] documentScores: reliabilityScores 인라인 필드
- [x] "자기" 판별: contributorIds 배열 (기여자 전원)
- [x] 위험도 판단: sourceType 기반 + riskLevel override + CF 자동 판정
- [x] 오류 신고: 선택형 사유 + Rate Limit + 자동 상태변경 금지
- [x] 검색 종합 LLM: 명시적 버튼 + 캐시 TTL 1시간 + 원문 링크 필수

## [미해결] 항목
없음 (v3에서 7건 전부 확정)